SBrainCO/docs/20260812-1/API.md

后端 API 完整列表

路由挂载（server/src/index.ts）

前缀	路由文件	说明
/api/auth	auth.ts	认证
/api/admin	admin.ts	平台管理（租户管理）
/api	data.ts	核心数据（overview/stores/cost/risk等）
/api/tasks	tasks.ts	任务管理+本体查询
/api/cost-analysis	cost-analysis.ts	成本分析
/api/store-expense	store-expense.ts	门店费用
/api/smart-scheduling	smart-scheduling.ts	智能排班
/api/situational-awareness	situational-awareness.ts	态势感知
/api/analytics-enhanced	analytics-enhanced.ts	增强分析
/api/tts	tts.ts	语音合成
/api/target	target.ts	目标管理
/api/scheduler	scheduler.ts	调度管理
/api/alert	alert.ts	预警管理
/api/store-grade	store-grade.ts	门店分级
/api/product	product.ts	产品管理
/api/enterprise	enterprise.ts	企业管理
/api/intelligence	intelligence.ts	智能分析
/api/promotion	promotion.ts	促销分析

---

1. 认证 /api/auth

方法	路径	说明
POST	/auth/login	用户登录
GET	/auth/me	获取当前用户信息

2. 平台管理 /api/admin

方法	路径	说明
POST	/admin/login	平台管理员登录
GET	/admin/tenants	获取所有租户
GET	/admin/tenants/:tenantId	获取单个租户详情
POST	/admin/tenants	创建租户
PUT	/admin/tenants/:tenantId	更新租户

3. 核心数据 /api

方法	路径	说明	数据源
GET	/overview	经营总览	mv_overview_monthly + bill_fact
GET	/overview/daily	日度总览	v_overview_daily
GET	/overview/profit-waterfall	利润瀑布	mv_store_risk_rating_monthly + mv_store_operating_expense_monthly + bill_fact
GET	/overview/store-profit-ranking	门店利润排名	mv_store_operating_expense_monthly
GET	/overview/profit-opportunity	利润机会池	mv_store_risk_rating_monthly + mv_store_operating_expense_monthly + mv_dish_sku_abc_monthly
GET	/overview/yoy	同比分析	mv_overview_monthly
GET	/overview/mom	环比分析	mv_overview_monthly
GET	/overview/trend	趋势分析	mv_overview_monthly
GET	/overview/profit-trend	利润趋势	mv_store_operating_expense_monthly
GET	/overview/period	时段分析	v_hourly_summary
GET	/stores	门店列表	mv_store_risk_rating_monthly
GET	/stores/risk	门店风险	mv_store_risk_rating_monthly
GET	/stores/priority	门店优先级	mv_store_action_priority_deep_monthly
GET	/stores/quadrant	门店象限	mv_store_risk_rating_monthly
GET	/stores/:code	门店详情	bill_records (直接查原始表)
GET	/stores/:code/daily	门店日度	bill_records (直接查原始表)
GET	/stores/:code/meal-period	门店餐段	bill_records (直接查原始表)
GET	/stores/:code/category-mix	门店品类结构	mv_store_category_mix_monthly
GET	/stores/:code/cost	门店成本	mv_store_theoretical_actual_cost_monthly
GET	/stores/:code/member	门店会员	v_store_member_monthly_activity
GET	/stores/:code/anomalies	门店异常	v_anomaly_bills
GET	/stores/:code/staffing	门店人效	attendance_records + bill_records
GET	/cost/comparison	成本对比	mv_store_theoretical_actual_cost_monthly
GET	/cost/category-benchmark	品类成本基准	mv_inventory_cost_classified_monthly
GET	/cost/inventory	库存成本	inventory_cost_records
GET	/platform/economics	平台经济	mv_store_platform_economics_monthly
GET	/member/comparison	会员对比	v_member_comparison
GET	/member/repeat	会员复购	v_member_repeat_summary_monthly
GET	/sku/abc	SKU ABC分类	mv_dish_sku_abc_monthly
GET	/sku/category	SKU品类	mv_dish_sku_summary_monthly
GET	/sku/attach	SKU关联	mv_dish_basket_monthly
GET	/risk/anomaly	异常风险	v_anomaly_summary
GET	/risk/zero-received	零实收风险	v_zero_received_store_summary
GET	/risk/cashier	收银风险	v_cashier_risk
GET	/marketing/plans	营销计划	v_marketing_plan_summary
GET	/benchmark/composite	综合基准	mv_store_benchmark_composite_monthly
GET	/time/weekday	星期分析	v_weekday_summary
GET	/time/hourly	小时分析	v_hourly_summary
GET	/channel	渠道分析	v_channel_daily
GET	/data-quality	数据质量	v_data_quality_check
GET	/region/summary	区域汇总	v_region_summary
GET	/site-selection/profile	选址画像	mv_store_site_profile_monthly
GET	/site-selection/segment-benchmark	分段基准	mv_site_segment_benchmark_monthly
GET	/site-selection/replication	选址复制	mv_store_site_replication_monthly
GET	/site-selection/overlap-risk	重叠风险	mv_store_overlap_risk_monthly
GET	/site-selection/district-benchmark	区域基准	mv_district_site_benchmark_monthly
GET	/revenue/channel	渠道营收	v_channel_daily
GET	/revenue/meal-period	餐段营收	v_meal_period_daily
GET	/revenue/store-ranking	门店营收排名	mv_store_risk_rating_monthly
GET	/revenue/daily-summary	日度营收汇总	mv_daily_revenue
GET	/bank/report	银行报表	mv_store_risk_rating_monthly + mv_store_operating_expense_monthly + bill_fact
GET	/central-kitchen/dashboard	中央厨房总览	central_kitchen_* 系列表
GET	/central-kitchen/bom-penetration	BOM穿透	central_kitchen_* 系列表
GET	/distribution/reconciliation	配送对账	distribution_detail_records
GET	/sales-driven/production-plan	销售驱动生产计划	bill_fact + fact_recipe_bom

4. 任务管理 /api/tasks

方法	路径	说明
GET	/tasks	任务列表
POST	/tasks	创建任务
POST	/tasks/auto-generate	自动生成任务
GET	/tasks/weekly-check	周度检查
GET	/tasks/monthly-review	月度复盘
GET	/tasks/monthly-review/completion	月度复盘完成度
GET	/tasks/monthly-review/activity-list	月度复盘活动列表
GET	/tasks/monthly-review/sku-governance	SKU治理
GET	/tasks/monthly-review/indicator-effectiveness	指标有效性
GET	/tasks/followup	跟进任务
GET	/tasks/grade-change	分级变更
GET	/tasks/practices	最佳实践列表
POST	/tasks/practices	创建最佳实践
GET	/tasks/practices/:id/replication-result	实践复制结果
POST	/tasks/practices/:id/replicate	复制实践
POST	/tasks/practices/:id/promote	推广实践
GET	/tasks/indicators	指标列表
POST	/tasks/indicators	创建指标
PUT	/tasks/indicators/:id/threshold	更新指标阈值
GET	/tasks/loop-health	闭环健康度
POST	/tasks/notifications/dispatch	通知派发
GET	/tasks/stores/:code/daily-card	门店日度卡片
GET	/tasks/:id	任务详情
PUT	/tasks/:id	更新任务
PUT	/tasks/:id/execute	执行任务
PUT	/tasks/:id/weekly-check	周度检查
PUT	/tasks/:id/verify	验证任务
POST	/tasks/:id/rollback	回滚任务
GET	/tasks/ontology/overview	本体总览
GET	/tasks/ontology/dim/:table	维度表查询
GET	/tasks/ontology/fact/:table	事实表查询
GET	/tasks/ontology/enum/:table	枚举表查询
GET	/tasks/ontology/metrics	指标查询

5. 成本分析 /api/cost-analysis

方法	路径	说明	数据源
GET	/cost-analysis/overview	成本总览	dish_cost_analysis_summary
GET	/cost-analysis/category-comparison	品类成本对比	dish_cost_analysis_summary
GET	/cost-analysis/margin-deviation	毛利率偏差	dish_cost_analysis_summary
GET	/cost-analysis/variance-top	成本差异TOP	dish_cost_analysis_summary
GET	/cost-analysis/menu-engineering	菜单工程	dish_cost_analysis_summary
GET	/cost-analysis/profitability	盈利能力	dish_cost_analysis_summary
GET	/cost-analysis/pricing	定价分析	dish_cost_analysis_summary
GET	/cost-analysis/material-variance	原料差异	dish_cost_analysis_material_detail
GET	/cost-analysis/loss-distribution	损耗分布	dish_cost_analysis_material_detail
GET	/cost-analysis/material-loss-top	原料损耗TOP	dish_cost_analysis_material_detail
GET	/cost-analysis/material-type-loss	原料类型损耗	dish_cost_analysis_material_detail
GET	/cost-analysis/bom-overview	BOM总览	fact_recipe_bom
GET	/cost-analysis/bom-complexity	BOM复杂度	fact_recipe_bom
GET	/cost-analysis/bom-high-loss	BOM高损耗	fact_recipe_bom
GET	/cost-analysis/bom-missing	BOM缺失	dish_cost_analysis_summary
GET	/cost-analysis/bom-composition	BOM组成	fact_recipe_bom
GET	/cost-analysis/material-sharing	原料共享	fact_recipe_bom
GET	/cost-analysis/unique-material-risk	独有原料风险	fact_recipe_bom
POST	/cost-analysis/sku-simplify-simulate	SKU精简模拟	fact_recipe_bom
GET	/cost-analysis/material-demand	原料需求	fact_recipe_bom
GET	/cost-analysis/packaging-overview	包装总览	dish_cost_analysis_summary
GET	/cost-analysis/packaging-detail	包装明细	dish_cost_analysis_material_detail
GET	/cost-analysis/data-quality	数据质量	dish_cost_analysis_summary
GET	/cost-analysis/unmatched-dishes	未匹配菜品	dish_cost_analysis_summary
GET	/cost-analysis/unmatched-materials	未匹配原料	dish_cost_analysis_material_detail
GET	/cost-analysis/store-overview	门店成本总览	mv_store_theoretical_actual_cost_monthly
GET	/cost-analysis/store-map	门店成本地图	mv_store_theoretical_actual_cost_monthly
GET	/cost-analysis/store-ranking	门店成本排名	mv_store_theoretical_actual_cost_monthly
GET	/cost-analysis/scatter	散点图数据	mv_store_theoretical_actual_cost_monthly
POST	/cost-analysis/diagnosis/generate	生成诊断	mv_store_theoretical_actual_cost_monthly
GET	/cost-analysis/diagnosis	诊断列表	dish_diagnosis_snapshot
GET	/cost-analysis/adjustment	调整列表	dish_adjustment_log
POST	/cost-analysis/adjustment	创建调整	dish_adjustment_log
PUT	/cost-analysis/adjustment/:id	更新调整	dish_adjustment_log
GET	/cost-analysis/adjustment/:id/verify	验证调整	dish_adjustment_result
POST	/cost-analysis/adjustment/:id/result	调整结果	dish_adjustment_result

6. 门店费用 /api/store-expense

方法	路径	说明	数据源
GET	/store-expense/overview	费用总览	mv_store_operating_expense_monthly
GET	/store-expense/expense-structure	费用结构	v_operating_expense_account_monthly
GET	/store-expense/store-ranking	门店费用排名	mv_store_operating_expense_monthly
GET	/store-expense/store-contribution	门店贡献利润	mv_store_operating_expense_monthly
GET	/store-expense/rent-risk	房租风险	mv_store_operating_expense_monthly
GET	/store-expense/delivery-commission	外卖佣金	mv_store_operating_expense_monthly
GET	/store-expense/efficiency	人效坪效	mv_store_operating_expense_monthly
GET	/store-expense/fixed-variable	固定/变动费用	mv_store_operating_expense_monthly
GET	/store-expense/break-even	盈亏平衡	mv_store_operating_expense_monthly
GET	/store-expense/loss-diagnosis	亏损诊断	mv_store_operating_expense_monthly
GET	/store-expense/store-evaluation	门店评估	mv_store_operating_expense_monthly
GET	/store-expense/data-quality	费用数据质量	v_operating_expense_data_quality

7. 智能排班 /api/smart-scheduling

方法	路径	说明	数据源
GET	/smart-scheduling/traffic-heatmap	流量热力图	bill_records
GET	/smart-scheduling/meal-period-traffic	餐段流量	bill_records
GET	/smart-scheduling/traffic-heatmap-staffing	流量+排班	bill_records + attendance_records
GET	/smart-scheduling/dow-traffic	星期流量	bill_records
GET	/smart-scheduling/traffic-overview	流量总览	bill_records
GET	/smart-scheduling/staffing-match	排班匹配	bill_records + attendance_records
GET	/smart-scheduling/stores	门店列表	bill_records
GET	/smart-scheduling/efficiency-ranking	人效排名	bill_records + attendance_records
GET	/smart-scheduling/position-distribution	岗位分布	attendance_records
GET	/smart-scheduling/scheduling-suggestion	排班建议	bill_records + attendance_records
GET	/smart-scheduling/attendance-alert	考勤预警	attendance_records
GET	/smart-scheduling/attendance-summary	考勤汇总	attendance_records
GET	/smart-scheduling/employee-analysis	员工分析	attendance_records
GET	/smart-scheduling/position-salary-compare	岗位薪资对比	salary_detail_records
GET	/smart-scheduling/turnover-stats	流失率统计	attendance_records
GET	/smart-scheduling/overall-analysis	综合分析	bill_records + attendance_records
GET	/smart-scheduling/staffing-forecast	排班预测	bill_records + attendance_records

8. 态势感知 /api/situational-awareness

方法	路径	说明
GET	/situational-awareness/health-score	健康度评分
GET	/situational-awareness/alerts	预警列表
GET	/situational-awareness/correlation	关联分析
GET	/situational-awareness/forecast	预测分析

9. 增强分析 /api/analytics-enhanced

方法	路径	说明
GET	/analytics-enhanced/member/ltv	会员LTV
GET	/analytics-enhanced/menu-engineering/actions	菜单工程行动
GET	/analytics-enhanced/dish-pair/recommendations	菜品搭配推荐
GET	/analytics-enhanced/region/comparison	区域对比
GET	/analytics-enhanced/region/kpi-forecast	区域KPI预测
GET	/analytics-enhanced/store/daily-target	门店日度目标
GET	/analytics-enhanced/store/member-activity	门店会员活动
GET	/analytics-enhanced/employee/performance	员工绩效
GET	/analytics-enhanced/inventory/turnover	库存周转
GET	/analytics-enhanced/inventory/near-expiry	临期库存
GET	/analytics-enhanced/marketing/roi	营销ROI
GET	/analytics-enhanced/region/inspection-plan	区域巡检计划
GET	/analytics-enhanced/kpi	KPI达成率

10. 语音合成 /api/tts

方法	路径	说明
POST	/tts	文本转语音

11. 目标管理 /api/target

方法	路径	说明
GET	/target/annual	年度目标
POST	/target/annual	创建年度目标
DELETE	/target/annual/:id	删除年度目标
GET	/target/regional	区域目标
POST	/target/regional	创建区域目标
GET	/target/store-monthly	门店月度目标
POST	/target/store-monthly	创建门店月度目标
GET	/target/daily	日度目标
GET	/target/personal-tasks	个人任务
POST	/target/decompose/annual-to-store	年度目标分解到门店
POST	/target/decompose/monthly-to-daily	月度目标分解到日
GET	/target/achievement	目标达成率

12. 调度管理 /api/scheduler

方法	路径	说明
GET	/scheduler	调度列表
PATCH	/scheduler/:id	更新调度
POST	/scheduler/:id/trigger	手动触发

13. 预警管理 /api/alert

方法	路径	说明
GET	/alert/rules	预警规则列表
POST	/alert/rules	创建预警规则
PATCH	/alert/rules/:id	更新预警规则
DELETE	/alert/rules/:id	删除预警规则
GET	/alert/logs	预警日志
PATCH	/alert/logs/:id	更新预警日志
GET	/alert/overview	预警总览

14. 门店分级 /api/store-grade

方法	路径	说明
POST	/store-grade/auto-grade	自动分级
GET	/store-grade/grades	分级列表
GET	/store-grade/traffic-light	红黄绿灯
GET	/store-grade/closure-analysis	关停测算

15. 产品管理 /api/product

方法	路径	说明
GET	/product/products	产品列表
POST	/product/products	创建产品
POST	/product/products/:id/track	跟踪产品
GET	/product/reviews	评价列表
POST	/product/reviews	创建评价
GET	/product/reviews/overview	评价总览
GET	/product/import-logs	导入日志
POST	/product/import/trigger	触发导入
GET	/product/quality-rules	质量规则
GET	/product/inventory-snapshot	库存快照
GET	/product/reports	报告
POST	/product/reports/generate	生成报告
GET	/product/variance	差异
POST	/product/variance/generate	生成差异
GET	/product/budget-locks	预算锁
POST	/product/budget-locks	创建预算锁
PATCH	/product/budget-locks/:id/approve	审批预算锁

16. 企业管理 /api/enterprise

方法	路径	说明
GET	/enterprise/suppliers	供应商列表
POST	/enterprise/suppliers	创建供应商
POST	/enterprise/suppliers/:code/score	供应商评分
GET	/enterprise/purchase-orders	采购订单
POST	/enterprise/purchase-orders	创建采购订单
GET	/enterprise/price-comparison	价格对比
GET	/enterprise/approvals	审批列表
POST	/enterprise/approvals	创建审批
POST	/enterprise/approvals/:id/approve	审批通过
GET	/enterprise/approvals/:id/steps	审批步骤
GET	/enterprise/notifications	通知列表
PATCH	/enterprise/notifications/:id/read	标记已读
POST	/enterprise/notifications	创建通知
GET	/enterprise/hr/attendance	考勤
GET	/enterprise/hr/talent-matrix	人才矩阵
GET	/enterprise/training/courses	培训课程
POST	/enterprise/training/courses	创建课程
GET	/enterprise/training/records	培训记录
POST	/enterprise/training/records	创建记录
GET	/enterprise/campaigns	活动列表
POST	/enterprise/campaigns	创建活动
GET	/enterprise/coupons	优惠券
POST	/enterprise/coupons	创建优惠券
GET	/enterprise/budgets	预算
POST	/enterprise/budgets	创建预算
POST	/enterprise/scan/production	扫描生产
POST	/enterprise/scan/receiving	扫描收货
POST	/enterprise/scan/inspection	扫描巡检
GET	/enterprise/loop-verification	闭环验证
POST	/enterprise/loop-verification/check	闭环检查
GET	/enterprise/audit-logs	审计日志
POST	/enterprise/audit-logs	创建审计
POST	/enterprise/pii/mask	PII脱敏
GET	/enterprise/anonymous-ranking	匿名排名
GET	/enterprise/supplier-benchmark	供应商基准
GET	/enterprise/supplier-benchmark/:skuCode	供应商基准详情

17. 智能分析 /api/intelligence

方法	路径	说明
GET	/intelligence/iot/devices	IoT设备
POST	/intelligence/iot/devices	创建IoT设备
POST	/intelligence/iot/reading	IoT读数
GET	/intelligence/iot/temperature-history	温度历史
POST	/intelligence/ai/adjust-target	AI目标调整
GET	/intelligence/ai/forecasts	AI预测
POST	/intelligence/ai/forecast	创建预测
POST	/intelligence/ai/quarterly-report	季报生成
GET	/intelligence/chain/production-sales	产销分析
POST	/intelligence/chain/mrp	MRP计算
GET	/intelligence/realtime/dashboard	实时看板
GET	/intelligence/strategy/roi	ROI分析
POST	/intelligence/strategy/roi/calculate	ROI计算
GET	/intelligence/strategy/brand-assets	品牌资产
POST	/intelligence/strategy/brand-assets	创建品牌资产
POST	/intelligence/training/lock-scheduling	培训锁定排班

18. 促销分析 /api/promotion

方法	路径	说明
GET	/promotion/overview	促销总览
GET	/promotion/by-plan	按方案对比
GET	/promotion/by-store	按门店效果
GET	/promotion/daily-trend	促销日趋势

---

API 统计

路由文件	端点数
data.ts	57
tasks.ts	31
cost-analysis.ts	35
store-expense.ts	12
smart-scheduling.ts	17
situational-awareness.ts	4
analytics-enhanced.ts	13
enterprise.ts	35
product.ts	15
intelligence.ts	16
promotion.ts	4
target.ts	12
alert.ts	7
store-grade.ts	4
admin.ts	5
auth.ts	2
tts.ts	1
scheduler.ts	3
合计	~273