Initial commit: 智能项目定价模型

2026-01-31 21:33:06 +08:00
commit ef0824303f
174 changed files with 31705 additions and 0 deletions
--- a/规划文档/05_API接口设计.md
+++ b/规划文档/05_API接口设计.md
@@ -0,0 +1,990 @@
+# 智能项目定价模型 - API 接口设计
+
+> **版本**：v1.0  
+> **创建日期**：2026-01-19  
+> **最后更新**：2026-01-19  
+> **负责人**：待定
+
+---
+
+## 1. 接口规范
+
+### 1.1 基础规范
+
+| 项目 | 规范 |
+|------|------|
+| **协议** | HTTPS |
+| **基础路径** | `/api/v1` |
+| **数据格式** | JSON (UTF-8) |
+| **时间格式** | ISO 8601 (`YYYY-MM-DDTHH:mm:ss`) |
+| **时区** | Asia/Shanghai (UTC+8) |
+| **认证方式** | Bearer Token (OAuth) |
+
+### 1.2 请求头
+
+```http
+Content-Type: application/json
+Authorization: Bearer <access_token>
+Accept: application/json
+```
+
+### 1.3 响应格式
+
+**成功响应**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... }
+}
+```
+
+**失败响应**
+
+```json
+{
+  "code": 10001,
+  "message": "参数错误：project_name 不能为空",
+  "data": null
+}
+```
+
+**分页响应**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [ ... ],
+    "total": 100,
+    "page": 1,
+    "page_size": 20,
+    "total_pages": 5
+  }
+}
+```
+
+### 1.4 错误码定义
+
+| 错误码 | 说明 |
+|--------|------|
+| 0 | 成功 |
+| 10001 | 参数错误 |
+| 10002 | 数据不存在 |
+| 10003 | 数据已存在 |
+| 10004 | 操作不允许 |
+| 20001 | 认证失败 |
+| 20002 | 权限不足 |
+| 20003 | Token 过期 |
+| 30001 | 系统内部错误 |
+| 30002 | 服务暂不可用 |
+| 40001 | AI 服务调用失败 |
+| 40002 | AI 服务超时 |
+
+### 1.5 通用参数
+
+**分页参数**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| page | int | 否 | 1 | 页码 |
+| page_size | int | 否 | 20 | 每页数量（最大100）|
+
+**排序参数**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| sort_by | string | 否 | created_at | 排序字段 |
+| sort_order | string | 否 | desc | 排序方向：asc/desc |
+
+---
+
+## 2. 接口列表概览
+
+### 2.1 基础数据管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/categories` | 获取项目分类列表 |
+| POST | `/categories` | 创建项目分类 |
+| PUT | `/categories/{id}` | 更新项目分类 |
+| DELETE | `/categories/{id}` | 删除项目分类 |
+| GET | `/materials` | 获取耗材列表 |
+| POST | `/materials` | 创建耗材 |
+| PUT | `/materials/{id}` | 更新耗材 |
+| DELETE | `/materials/{id}` | 删除耗材 |
+| POST | `/materials/import` | 批量导入耗材 |
+| GET | `/equipments` | 获取设备列表 |
+| POST | `/equipments` | 创建设备 |
+| PUT | `/equipments/{id}` | 更新设备 |
+| DELETE | `/equipments/{id}` | 删除设备 |
+| GET | `/staff-levels` | 获取人员级别列表 |
+| POST | `/staff-levels` | 创建人员级别 |
+| PUT | `/staff-levels/{id}` | 更新人员级别 |
+| DELETE | `/staff-levels/{id}` | 删除人员级别 |
+| GET | `/fixed-costs` | 获取固定成本列表 |
+| POST | `/fixed-costs` | 创建固定成本 |
+| PUT | `/fixed-costs/{id}` | 更新固定成本 |
+| DELETE | `/fixed-costs/{id}` | 删除固定成本 |
+
+### 2.2 成本核算模块
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/projects` | 获取服务项目列表 |
+| POST | `/projects` | 创建服务项目 |
+| GET | `/projects/{id}` | 获取项目详情 |
+| PUT | `/projects/{id}` | 更新项目 |
+| DELETE | `/projects/{id}` | 删除项目 |
+| GET | `/projects/{id}/cost-items` | 获取项目成本明细 |
+| POST | `/projects/{id}/cost-items` | 添加成本明细 |
+| PUT | `/projects/{id}/cost-items/{item_id}` | 更新成本明细 |
+| DELETE | `/projects/{id}/cost-items/{item_id}` | 删除成本明细 |
+| GET | `/projects/{id}/labor-costs` | 获取项目人工成本 |
+| POST | `/projects/{id}/labor-costs` | 添加人工成本 |
+| PUT | `/projects/{id}/labor-costs/{item_id}` | 更新人工成本 |
+| DELETE | `/projects/{id}/labor-costs/{item_id}` | 删除人工成本 |
+| POST | `/projects/{id}/calculate-cost` | 计算项目总成本 |
+| GET | `/projects/{id}/cost-summary` | 获取成本汇总 |
+
+### 2.3 市场行情模块
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/competitors` | 获取竞品机构列表 |
+| POST | `/competitors` | 创建竞品机构 |
+| GET | `/competitors/{id}` | 获取竞品详情 |
+| PUT | `/competitors/{id}` | 更新竞品机构 |
+| DELETE | `/competitors/{id}` | 删除竞品机构 |
+| GET | `/competitors/{id}/prices` | 获取竞品价格列表 |
+| POST | `/competitors/{id}/prices` | 添加竞品价格 |
+| PUT | `/competitor-prices/{id}` | 更新竞品价格 |
+| DELETE | `/competitor-prices/{id}` | 删除竞品价格 |
+| GET | `/benchmark-prices` | 获取标杆价格列表 |
+| POST | `/benchmark-prices` | 创建标杆价格 |
+| PUT | `/benchmark-prices/{id}` | 更新标杆价格 |
+| DELETE | `/benchmark-prices/{id}` | 删除标杆价格 |
+| POST | `/projects/{id}/market-analysis` | 执行市场分析 |
+| GET | `/projects/{id}/market-analysis` | 获取市场分析结果 |
+
+### 2.4 智能定价模块
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/pricing-plans` | 获取定价方案列表 |
+| POST | `/pricing-plans` | 创建定价方案 |
+| GET | `/pricing-plans/{id}` | 获取定价方案详情 |
+| PUT | `/pricing-plans/{id}` | 更新定价方案 |
+| DELETE | `/pricing-plans/{id}` | 删除定价方案 |
+| POST | `/projects/{id}/generate-pricing` | AI 生成定价建议 |
+| POST | `/projects/{id}/simulate-strategy` | 模拟定价策略 |
+| GET | `/pricing-plans/{id}/export` | 导出定价报告 |
+
+### 2.5 利润模拟模块
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/profit-simulations` | 获取利润模拟列表 |
+| POST | `/profit-simulations` | 创建利润模拟 |
+| GET | `/profit-simulations/{id}` | 获取模拟详情 |
+| DELETE | `/profit-simulations/{id}` | 删除模拟记录 |
+| POST | `/pricing-plans/{id}/simulate-profit` | 执行利润模拟 |
+| POST | `/profit-simulations/{id}/sensitivity` | 敏感性分析 |
+| GET | `/profit-simulations/{id}/sensitivity` | 获取敏感性分析结果 |
+| GET | `/pricing-plans/{id}/breakeven` | 获取盈亏平衡分析 |
+
+### 2.6 仪表盘与统计
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/dashboard/summary` | 仪表盘概览数据 |
+| GET | `/dashboard/cost-trend` | 成本趋势 |
+| GET | `/dashboard/market-trend` | 市场价格趋势 |
+| GET | `/statistics/ai-usage` | AI 使用统计 |
+
+### 2.7 系统接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 健康检查 |
+| GET | `/me` | 当前用户信息 |
+
+---
+
+## 3. 接口详细设计
+
+### 3.1 健康检查
+
+#### GET `/health`
+
+**描述**：检查服务健康状态
+
+**认证**：不需要
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "status": "healthy",
+    "version": "1.0.0",
+    "database": "connected",
+    "timestamp": "2026-01-19T10:00:00"
+  }
+}
+```
+
+---
+
+### 3.2 服务项目
+
+#### GET `/projects`
+
+**描述**：获取服务项目列表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| page | int | 否 | 页码，默认 1 |
+| page_size | int | 否 | 每页数量，默认 20 |
+| category_id | int | 否 | 分类筛选 |
+| keyword | string | 否 | 关键词搜索（名称/编码）|
+| is_active | bool | 否 | 是否启用 |
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": 1,
+        "project_code": "PRJ001",
+        "project_name": "光子嫩肤",
+        "category_id": 3,
+        "category_name": "光电类",
+        "description": "IPL 光子嫩肤项目",
+        "duration_minutes": 60,
+        "is_active": true,
+        "cost_summary": {
+          "total_cost": 280.50,
+          "material_cost": 120.00,
+          "equipment_cost": 50.50,
+          "labor_cost": 80.00,
+          "fixed_cost_allocation": 30.00
+        },
+        "created_at": "2026-01-15T10:00:00",
+        "updated_at": "2026-01-15T10:00:00"
+      }
+    ],
+    "total": 50,
+    "page": 1,
+    "page_size": 20,
+    "total_pages": 3
+  }
+}
+```
+
+#### POST `/projects`
+
+**描述**：创建服务项目
+
+**请求体**：
+
+```json
+{
+  "project_code": "PRJ002",
+  "project_name": "水光针",
+  "category_id": 2,
+  "description": "水光针注射项目",
+  "duration_minutes": 45,
+  "is_active": true
+}
+```
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "创建成功",
+  "data": {
+    "id": 2,
+    "project_code": "PRJ002",
+    "project_name": "水光针",
+    "category_id": 2,
+    "description": "水光针注射项目",
+    "duration_minutes": 45,
+    "is_active": true,
+    "created_at": "2026-01-19T10:00:00"
+  }
+}
+```
+
+#### GET `/projects/{id}`
+
+**描述**：获取项目详情（含成本明细）
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "project_code": "PRJ001",
+    "project_name": "光子嫩肤",
+    "category_id": 3,
+    "category_name": "光电类",
+    "description": "IPL 光子嫩肤项目",
+    "duration_minutes": 60,
+    "is_active": true,
+    "cost_items": [
+      {
+        "id": 1,
+        "item_type": "material",
+        "item_id": 5,
+        "item_name": "冷凝胶",
+        "quantity": 20,
+        "unit": "ml",
+        "unit_cost": 2.00,
+        "total_cost": 40.00
+      },
+      {
+        "id": 2,
+        "item_type": "equipment",
+        "item_id": 1,
+        "item_name": "光子仪",
+        "quantity": 1,
+        "unit": "次",
+        "unit_cost": 50.50,
+        "total_cost": 50.50
+      }
+    ],
+    "labor_costs": [
+      {
+        "id": 1,
+        "staff_level_id": 2,
+        "level_name": "中级美容师",
+        "duration_minutes": 60,
+        "hourly_rate": 50.00,
+        "labor_cost": 50.00
+      }
+    ],
+    "cost_summary": {
+      "material_cost": 120.00,
+      "equipment_cost": 50.50,
+      "labor_cost": 80.00,
+      "fixed_cost_allocation": 30.00,
+      "total_cost": 280.50,
+      "calculated_at": "2026-01-19T09:00:00"
+    },
+    "created_at": "2026-01-15T10:00:00",
+    "updated_at": "2026-01-15T10:00:00"
+  }
+}
+```
+
+---
+
+### 3.3 成本计算
+
+#### POST `/projects/{id}/calculate-cost`
+
+**描述**：计算并保存项目总成本
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| fixed_cost_allocation_method | string | 否 | 分摊方式：count/revenue/duration，默认 count |
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "计算完成",
+  "data": {
+    "project_id": 1,
+    "project_name": "光子嫩肤",
+    "cost_breakdown": {
+      "material_cost": {
+        "items": [
+          {"name": "冷凝胶", "quantity": 20, "unit_cost": 2.00, "total": 40.00},
+          {"name": "一次性床单", "quantity": 1, "unit_cost": 5.00, "total": 5.00}
+        ],
+        "subtotal": 120.00
+      },
+      "equipment_cost": {
+        "items": [
+          {"name": "光子仪", "depreciation_per_use": 50.50, "total": 50.50}
+        ],
+        "subtotal": 50.50
+      },
+      "labor_cost": {
+        "items": [
+          {"level": "中级美容师", "duration_minutes": 60, "hourly_rate": 50.00, "total": 50.00},
+          {"level": "高级美容师", "duration_minutes": 30, "hourly_rate": 80.00, "total": 40.00}
+        ],
+        "subtotal": 80.00
+      },
+      "fixed_cost_allocation": {
+        "method": "count",
+        "total_fixed_cost": 30000.00,
+        "project_count": 1000,
+        "allocation": 30.00
+      }
+    },
+    "total_cost": 280.50,
+    "min_price_suggestion": 280.50,
+    "calculated_at": "2026-01-19T10:30:00"
+  }
+}
+```
+
+---
+
+### 3.4 市场分析
+
+#### POST `/projects/{id}/market-analysis`
+
+**描述**：执行市场价格分析
+
+**请求体**：
+
+```json
+{
+  "competitor_ids": [1, 2, 3],
+  "include_benchmark": true
+}
+```
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "分析完成",
+  "data": {
+    "project_id": 1,
+    "project_name": "光子嫩肤",
+    "analysis_date": "2026-01-19",
+    "competitor_count": 5,
+    "price_statistics": {
+      "min_price": 380.00,
+      "max_price": 1280.00,
+      "avg_price": 680.00,
+      "median_price": 580.00,
+      "std_deviation": 220.50
+    },
+    "price_distribution": {
+      "low": {"range": "300-500", "count": 2, "percentage": 40},
+      "medium": {"range": "500-800", "count": 2, "percentage": 40},
+      "high": {"range": "800-1500", "count": 1, "percentage": 20}
+    },
+    "competitor_prices": [
+      {
+        "competitor_name": "美丽人生",
+        "positioning": "medium",
+        "original_price": 680.00,
+        "promo_price": 480.00,
+        "collected_at": "2026-01-15"
+      }
+    ],
+    "benchmark_reference": {
+      "tier": "medium",
+      "min_price": 400.00,
+      "max_price": 800.00,
+      "avg_price": 600.00
+    },
+    "suggested_range": {
+      "min": 480.00,
+      "max": 780.00,
+      "recommended": 580.00
+    }
+  }
+}
+```
+
+---
+
+### 3.5 智能定价建议
+
+#### POST `/projects/{id}/generate-pricing`
+
+**描述**：调用 AI 生成定价建议
+
+**请求体**：
+
+```json
+{
+  "target_margin": 50,
+  "strategies": ["traffic", "profit", "premium"],
+  "stream": true
+}
+```
+
+**请求参数说明**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| target_margin | float | 否 | 目标毛利率(%)，默认 50 |
+| strategies | array | 否 | 策略类型，默认全部 |
+| stream | bool | 否 | 是否流式返回，默认 false |
+
+**非流式响应**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "project_id": 1,
+    "project_name": "光子嫩肤",
+    "cost_base": 280.50,
+    "market_reference": {
+      "min": 380.00,
+      "max": 1280.00,
+      "avg": 680.00
+    },
+    "pricing_suggestions": {
+      "traffic": {
+        "strategy": "引流款",
+        "suggested_price": 388.00,
+        "margin": 27.7,
+        "description": "低于市场均价，适合引流获客"
+      },
+      "profit": {
+        "strategy": "利润款",
+        "suggested_price": 580.00,
+        "margin": 51.6,
+        "description": "接近市场均价，平衡利润与竞争力"
+      },
+      "premium": {
+        "strategy": "高端款",
+        "suggested_price": 880.00,
+        "margin": 68.1,
+        "description": "定位高端，需配套优质服务"
+      }
+    },
+    "ai_advice": {
+      "summary": "建议采用利润款定价策略...",
+      "cost_analysis": "成本结构合理，耗材成本占比...",
+      "market_analysis": "市场价格区间较大...",
+      "risk_notes": "注意竞品促销活动的影响...",
+      "recommendations": [
+        "常规定价建议 580 元",
+        "新客首单可设置 388 元引流价",
+        "VIP 会员可享 520 元优惠价"
+      ]
+    },
+    "ai_usage": {
+      "provider": "4sapi",
+      "model": "gemini-3-flash-preview",
+      "tokens": 1250,
+      "latency_ms": 2300
+    }
+  }
+}
+```
+
+**流式响应（SSE）**：
+
+```
+event: message
+data: {"type": "chunk", "content": "根据您提供的成本数据..."}
+
+event: message
+data: {"type": "chunk", "content": "建议采用以下定价策略..."}
+
+event: message
+data: {"type": "done", "summary": {...}}
+```
+
+---
+
+### 3.6 利润模拟
+
+#### POST `/pricing-plans/{id}/simulate-profit`
+
+**描述**：执行利润模拟测算
+
+**请求体**：
+
+```json
+{
+  "price": 580.00,
+  "estimated_volume": 100,
+  "period_type": "monthly"
+}
+```
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "simulation_id": 1,
+    "pricing_plan_id": 5,
+    "project_name": "光子嫩肤",
+    "input": {
+      "price": 580.00,
+      "cost_per_unit": 280.50,
+      "estimated_volume": 100,
+      "period_type": "monthly"
+    },
+    "result": {
+      "estimated_revenue": 58000.00,
+      "estimated_cost": 28050.00,
+      "estimated_profit": 29950.00,
+      "profit_margin": 51.64,
+      "profit_per_unit": 299.50
+    },
+    "breakeven_analysis": {
+      "breakeven_volume": 48,
+      "current_volume": 100,
+      "safety_margin": 52,
+      "safety_margin_percentage": 52.0
+    },
+    "created_at": "2026-01-19T11:00:00"
+  }
+}
+```
+
+#### POST `/profit-simulations/{id}/sensitivity`
+
+**描述**：执行敏感性分析
+
+**请求体**：
+
+```json
+{
+  "price_change_rates": [-20, -15, -10, -5, 0, 5, 10, 15, 20]
+}
+```
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "simulation_id": 1,
+    "base_price": 580.00,
+    "base_profit": 29950.00,
+    "sensitivity_results": [
+      {
+        "price_change_rate": -20,
+        "adjusted_price": 464.00,
+        "adjusted_profit": 18350.00,
+        "profit_change_rate": -38.73
+      },
+      {
+        "price_change_rate": -10,
+        "adjusted_price": 522.00,
+        "adjusted_profit": 24150.00,
+        "profit_change_rate": -19.37
+      },
+      {
+        "price_change_rate": 0,
+        "adjusted_price": 580.00,
+        "adjusted_profit": 29950.00,
+        "profit_change_rate": 0
+      },
+      {
+        "price_change_rate": 10,
+        "adjusted_price": 638.00,
+        "adjusted_profit": 35750.00,
+        "profit_change_rate": 19.37
+      },
+      {
+        "price_change_rate": 20,
+        "adjusted_price": 696.00,
+        "adjusted_profit": 41550.00,
+        "profit_change_rate": 38.73
+      }
+    ],
+    "insights": {
+      "price_elasticity": "价格每变动1%，利润变动约1.94%",
+      "risk_level": "中等",
+      "recommendation": "价格下降20%仍可盈利，但利润空间大幅收窄"
+    }
+  }
+}
+```
+
+---
+
+### 3.7 仪表盘
+
+#### GET `/dashboard/summary`
+
+**描述**：获取仪表盘概览数据
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "project_overview": {
+      "total_projects": 50,
+      "active_projects": 45,
+      "projects_with_pricing": 30
+    },
+    "cost_overview": {
+      "avg_project_cost": 320.50,
+      "highest_cost_project": {
+        "id": 12,
+        "name": "热玛吉",
+        "cost": 1500.00
+      },
+      "lowest_cost_project": {
+        "id": 5,
+        "name": "基础清洁",
+        "cost": 45.00
+      }
+    },
+    "market_overview": {
+      "competitors_tracked": 15,
+      "price_records_this_month": 120,
+      "avg_market_price": 680.00
+    },
+    "pricing_overview": {
+      "pricing_plans_count": 85,
+      "avg_target_margin": 48.5,
+      "strategies_distribution": {
+        "traffic": 20,
+        "profit": 50,
+        "premium": 15
+      }
+    },
+    "ai_usage_this_month": {
+      "total_calls": 150,
+      "total_tokens": 185000,
+      "total_cost_usd": 2.35,
+      "provider_distribution": {
+        "4sapi": 140,
+        "openrouter": 10
+      }
+    },
+    "recent_activities": [
+      {
+        "type": "pricing_created",
+        "project_name": "水光针",
+        "user": "张三",
+        "time": "2026-01-19T10:30:00"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 4. 耗材管理
+
+### POST `/materials/import`
+
+**描述**：批量导入耗材
+
+**请求**：`multipart/form-data`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file | file | 是 | Excel 文件 (.xlsx) |
+| update_existing | bool | 否 | 是否更新已存在数据，默认 false |
+
+**Excel 模板格式**：
+
+| 耗材编码 | 耗材名称 | 单位 | 单价 | 供应商 | 类型 |
+|----------|----------|------|------|--------|------|
+| MAT001 | 冷凝胶 | ml | 2.00 | 供应商A | consumable |
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "导入完成",
+  "data": {
+    "total": 50,
+    "success": 48,
+    "failed": 2,
+    "errors": [
+      {"row": 15, "error": "耗材编码 MAT015 已存在"},
+      {"row": 23, "error": "单价格式错误"}
+    ]
+  }
+}
+```
+
+---
+
+## 5. 竞品管理
+
+### GET `/competitors`
+
+**描述**：获取竞品机构列表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| page | int | 否 | 页码 |
+| page_size | int | 否 | 每页数量 |
+| positioning | string | 否 | 定位筛选：high/medium/budget |
+| is_key_competitor | bool | 否 | 是否重点关注 |
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": 1,
+        "competitor_name": "美丽人生医美",
+        "address": "XX市XX路100号",
+        "distance_km": 2.5,
+        "positioning": "medium",
+        "is_key_competitor": true,
+        "price_count": 25,
+        "last_price_update": "2026-01-15",
+        "created_at": "2026-01-01T10:00:00"
+      }
+    ],
+    "total": 15,
+    "page": 1,
+    "page_size": 20
+  }
+}
+```
+
+### POST `/competitors/{id}/prices`
+
+**描述**：添加竞品价格记录
+
+**请求体**：
+
+```json
+{
+  "project_id": 1,
+  "project_name": "光子嫩肤",
+  "original_price": 680.00,
+  "promo_price": 480.00,
+  "member_price": 580.00,
+  "price_source": "meituan",
+  "collected_at": "2026-01-19",
+  "remark": "美团活动价"
+}
+```
+
+---
+
+## 6. 定价方案
+
+### GET `/pricing-plans`
+
+**描述**：获取定价方案列表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | int | 否 | 项目筛选 |
+| strategy_type | string | 否 | 策略类型筛选 |
+| is_active | bool | 否 | 是否启用 |
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": 1,
+        "project_id": 1,
+        "project_name": "光子嫩肤",
+        "plan_name": "2026年Q1定价",
+        "strategy_type": "profit",
+        "base_cost": 280.50,
+        "target_margin": 50.00,
+        "suggested_price": 561.00,
+        "final_price": 580.00,
+        "is_active": true,
+        "created_at": "2026-01-15T10:00:00",
+        "created_by_name": "张三"
+      }
+    ],
+    "total": 30,
+    "page": 1,
+    "page_size": 20
+  }
+}
+```
+
+### GET `/pricing-plans/{id}/export`
+
+**描述**：导出定价报告
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| format | string | 否 | 导出格式：pdf/excel，默认 pdf |
+
+**响应**：文件下载
+
+---
+
+## 7. 附录
+
+### 7.1 数据类型说明
+
+| 字段类型 | JSON 类型 | 示例 |
+|----------|-----------|------|
+| id | number | 1 |
+| 金额 | number | 280.50 |
+| 百分比 | number | 50.00 (表示 50%) |
+| 日期时间 | string | "2026-01-19T10:00:00" |
+| 日期 | string | "2026-01-19" |
+| 布尔值 | boolean | true/false |
+
+### 7.2 AI 接口说明
+
+AI 相关接口（如 `/generate-pricing`）遵循《瑞小美 AI 接入规范》：
+
+- 通过 `shared_backend.AIService` 调用
+- 支持流式输出（SSE）
+- 自动降级：4sapi.com → OpenRouter.ai
+- 调用日志记录到 `ai_call_logs` 表
+- 使用 `prompt_name` 参数用于统计
+
+### 7.3 接口版本管理
+
+- 当前版本：v1
+- 接口路径包含版本号：`/api/v1/...`
+- 重大变更时发布新版本（v2）
+- 旧版本保持兼容至少 6 个月
+
+---
+
+*瑞小美技术团队 · 2026-01-19*