# 智能项目定价模型 - 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*