kuzma/smart-project-pricing

Fork 0

Files

kuzma ef0824303f Initial commit: 智能项目定价模型

2026-01-31 21:33:06 +08:00

22 KiB

Raw Blame History

智能项目定价模型 - 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 请求头

Content-Type: application/json
Authorization: Bearer <access_token>
Accept: application/json

1.3 响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

失败响应

{
  "code": 10001,
  "message": "参数错误：project_name 不能为空",
  "data": null
}

分页响应

{
  "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`

描述：检查服务健康状态

认证：不需要

响应示例：

{
  "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	否	是否启用

响应示例：

{
  "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`

描述：创建服务项目

请求体：

{
  "project_code": "PRJ002",
  "project_name": "水光针",
  "category_id": 2,
  "description": "水光针注射项目",
  "duration_minutes": 45,
  "is_active": true
}

响应示例：

{
  "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}`

描述：获取项目详情（含成本明细）

响应示例：

{
  "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

响应示例：

{
  "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`

描述：执行市场价格分析

请求体：

{
  "competitor_ids": [1, 2, 3],
  "include_benchmark": true
}

响应示例：

{
  "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 生成定价建议

请求体：

{
  "target_margin": 50,
  "strategies": ["traffic", "profit", "premium"],
  "stream": true
}

请求参数说明：

参数	类型	必填	说明
target_margin	float	否	目标毛利率(%)，默认 50
strategies	array	否	策略类型，默认全部
stream	bool	否	是否流式返回，默认 false

非流式响应：

{
  "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`

描述：执行利润模拟测算

请求体：

{
  "price": 580.00,
  "estimated_volume": 100,
  "period_type": "monthly"
}

响应示例：

{
  "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`

描述：执行敏感性分析

请求体：

{
  "price_change_rates": [-20, -15, -10, -5, 0, 5, 10, 15, 20]
}

响应示例：

{
  "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`

描述：获取仪表盘概览数据

响应示例：

{
  "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

响应示例：

{
  "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	否	是否重点关注

响应示例：

{
  "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`

描述：添加竞品价格记录

请求体：

{
  "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	否	是否启用

响应示例：

{
  "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

22 KiB Raw Blame History Unescape Escape

智能项目定价模型 - API 接口设计

1. 接口规范

1.1 基础规范

1.2 请求头

1.3 响应格式

1.4 错误码定义

1.5 通用参数

2. 接口列表概览

2.1 基础数据管理

2.2 成本核算模块

2.3 市场行情模块

2.4 智能定价模块

2.5 利润模拟模块

2.6 仪表盘与统计

2.7 系统接口

3. 接口详细设计

3.1 健康检查

GET /health

3.2 服务项目

GET /projects

POST /projects

GET /projects/{id}

3.3 成本计算

POST /projects/{id}/calculate-cost

3.4 市场分析

POST /projects/{id}/market-analysis

3.5 智能定价建议

POST /projects/{id}/generate-pricing

3.6 利润模拟

POST /pricing-plans/{id}/simulate-profit

POST /profit-simulations/{id}/sensitivity

3.7 仪表盘

GET /dashboard/summary

4. 耗材管理

POST /materials/import

5. 竞品管理

GET /competitors

POST /competitors/{id}/prices

6. 定价方案

GET /pricing-plans

GET /pricing-plans/{id}/export

7. 附录

7.1 数据类型说明

7.2 AI 接口说明

7.3 接口版本管理

22 KiB

Raw Blame History

GET `/health`

GET `/projects`

POST `/projects`

GET `/projects/{id}`

POST `/projects/{id}/calculate-cost`

POST `/projects/{id}/market-analysis`

POST `/projects/{id}/generate-pricing`

POST `/pricing-plans/{id}/simulate-profit`

POST `/profit-simulations/{id}/sensitivity`

GET `/dashboard/summary`

POST `/materials/import`

GET `/competitors`

POST `/competitors/{id}/prices`

GET `/pricing-plans`

GET `/pricing-plans/{id}/export`