kuzma/smart-project-pricing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ef0824303f5934702e77d112803f8c3d238d833c
smart-project-pricing/规划文档/05_API接口设计.md
kuzma ef0824303f Initial commit: 智能项目定价模型
2026-01-31 21:33:06 +08:00

991 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 智能项目定价模型 - 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*
Reference in New Issue View Git Blame Copy Permalink