事业部驾驶舱接口清单.md 11.4 KB

Edit Raw Blame History


事业部驾驶舱接口清单
根据 事业部驾驶舱数据分析梳理.md 文档，需要实现的接口清单：
一、核心业务指标接口
⏳ 1. GetStatistics（待实现）

功能：获取事业部驾驶舱核心指标
返回指标：


整体业绩：开单业绩、消耗业绩、退卡金额、净业绩、目标业绩、完成率
门店指标：管理的门店数、活跃门店数
运营指标：开单次数、消耗次数、退卡次数、平均开单金额、平均消耗金额
客户指标：人头数、人次、项目数、消耗率、退卡率
品项分类业绩：生美业绩、科美业绩、医美业绩、产品业绩

优先级：P0（最高优先级）


二、趋势分析接口
⏳ 2. GetPerformanceTrend（待实现）

功能：获取业绩趋势数据
返回数据：


开单业绩趋势（近12个月、近6个月、近3个月、当月）
消耗业绩趋势
净业绩趋势
开单与消耗对比趋势
品项分类业绩趋势（生美/科美/医美/产品）

优先级：P1


三、门店分析接口
⏳ 3. GetStoreRanking（待实现）

功能：获取门店业绩排行
返回数据：


门店开单业绩排行
门店消耗业绩排行
门店完成率排行

支持参数：排序方式、排行榜数量（Top N）
优先级：P1

⏳ 4. GetStoreDistribution（待实现）

功能：获取门店业绩分布
返回数据：


门店业绩分布（饼图数据）
门店业绩对比（柱状图数据）

优先级：P2


四、人员分析接口
⏳ 5. GetManagerRanking（待实现）

功能：获取总经理/经理业绩排行
返回数据：


总经理/经理姓名
管理的门店数、管理的门店名称列表
管理的门店总业绩（开单-退卡）
管理的门店总消耗业绩
管理的门店总毛利
底薪、提成、应发工资

优先级：P1

⏳ 6. GetManagerDistribution（待实现）

功能：获取总经理/经理业绩分布
返回数据：各总经理/经理的业绩占比（饼图数据）
优先级：P2

⏳ 7. GetManagerTrend（待实现）

功能：获取指定总经理/经理的业绩趋势
返回数据：近12个月业绩趋势
支持功能：多总经理/经理选择对比
优先级：P2

⏳ 8. GetStoreManagerRanking（待实现）

功能：获取店长业绩排行
返回数据：


店长姓名、所属门店
门店开单业绩、门店消耗业绩、门店退卡业绩
门店净业绩、门店完成率

优先级：P2

⏳ 9. GetHealthCoachRanking（待实现）

功能：获取健康师业绩排行
返回数据：


健康师姓名、所属门店
开单业绩、消耗业绩、退卡业绩
总业绩、项目数

优先级：P2


五、运营分析接口
⏳ 10. GetOperationStatistics（待实现）

功能：获取运营分析数据
返回数据：


开单分析：开单次数、平均开单金额、开单门店分布
消耗分析：消耗次数、消耗金额、消耗率
退卡分析：退卡次数、退卡金额、退卡率

优先级：P1


六、对比分析接口
⏳ 11. GetComparisonAnalysis（待实现）

功能：获取对比分析数据
返回数据：


时间对比：环比对比、同比对比（开单业绩、消耗业绩、净业绩、完成率）
部门对比：各事业部的业绩对比（柱状图或折线图数据）
门店类型对比：按门店类型分组统计

优先级：P2


七、明细数据列表接口
⏳ 12. GetStoreDetailList（待实现）

功能：获取门店业绩明细列表
返回数据：门店列表，包含业绩相关所有字段
支持功能：分页、排序、筛选（按月份、门店）
优先级：P1

⏳ 13. GetManagerDetailList（待实现）

功能：获取总经理/经理明细列表
返回数据：总经理/经理列表，包含管理门店和业绩信息
支持功能：分页、排序、筛选
优先级：P2

⏳ 14. GetStoreManagerDetailList（待实现）

功能：获取店长明细列表
返回数据：店长列表，包含门店业绩信息
支持功能：分页、排序、筛选
优先级：P2

⏳ 15. GetHealthCoachDetailList（待实现）

功能：获取健康师明细列表
返回数据：健康师列表，包含业绩信息
支持功能：分页、排序、筛选
优先级：P2


📋 接口实现计划
第一批（核心接口 - P0/P1）：基础功能
目标：完成最核心的统计数据，支撑驾驶舱主页面展示


GetStatistics（P0）


核心业务指标统计
包含所有关键指标
预估代码量：300-400行

GetPerformanceTrend（P1）


业绩趋势分析
支持多时间维度
预估代码量：200-300行

GetStoreRanking（P1）


门店业绩排行
支持多种排序方式
预估代码量：200-250行

GetOperationStatistics（P1）


运营分析数据
包含开单、消耗、退卡分析
预估代码量：200-250行

GetStoreDetailList（P1）


门店明细列表
支持分页和排序
预估代码量：150-200行


第一批总计：约1050-1400行代码


第二批（分析接口 - P1/P2）：分析功能
目标：完成分析和对比功能


GetManagerRanking（P1）


总经理/经理业绩排行
关联工资数据
预估代码量：250-300行

GetComparisonAnalysis（P2）


对比分析数据
环比、同比、部门对比
预估代码量：250-300行

GetStoreDistribution（P2）


门店业绩分布
饼图和柱状图数据
预估代码量：150-200行


第二批总计：约650-800行代码


第三批（扩展接口 - P2）：扩展功能
目标：完成人员分析和明细功能


GetManagerDistribution（P2）


总经理/经理业绩分布
预估代码量：100-150行

GetManagerTrend（P2）


总经理/经理业绩趋势
预估代码量：150-200行

GetStoreManagerRanking（P2）


店长业绩排行
预估代码量：150-200行

GetHealthCoachRanking（P2）


健康师业绩排行
预估代码量：150-200行

GetManagerDetailList（P2）


总经理/经理明细列表
预估代码量：150-200行

GetStoreManagerDetailList（P2）


店长明细列表
预估代码量：100-150行

GetHealthCoachDetailList（P2）


健康师明细列表
预估代码量：100-150行


第三批总计：约900-1250行代码


📦 DTO类清单
已创建

✅ BusinessUnitDashboardStatisticsInput.cs
✅ BusinessUnitDashboardStatisticsOutput.cs

需要创建（第一批）
趋势分析相关

⏳ BusinessUnitDashboardPerformanceTrendInput.cs
⏳ BusinessUnitDashboardPerformanceTrendOutput.cs
⏳ PerformanceTrendItem.cs（趋势数据项）

门店排行相关

⏳ BusinessUnitDashboardStoreRankingInput.cs
⏳ BusinessUnitDashboardStoreRankingOutput.cs
⏳ StoreRankingItem.cs（门店排行项）

运营分析相关

⏳ BusinessUnitDashboardOperationStatisticsInput.cs（复用StatisticsInput）
⏳ BusinessUnitDashboardOperationStatisticsOutput.cs
⏳ BillingAnalysis.cs（开单分析）
⏳ ConsumeAnalysis.cs（消耗分析）
⏳ RefundAnalysis.cs（退卡分析）

门店明细列表相关

⏳ BusinessUnitDashboardStoreDetailListInput.cs
⏳ BusinessUnitDashboardStoreDetailListOutput.cs
⏳ StoreDetailItem.cs（门店明细项）

需要创建（第二批）
总经理/经理排行相关

⏳ BusinessUnitDashboardManagerRankingInput.cs
⏳ BusinessUnitDashboardManagerRankingOutput.cs
⏳ ManagerRankingItem.cs（总经理/经理排行项）

对比分析相关

⏳ BusinessUnitDashboardComparisonAnalysisInput.cs
⏳ BusinessUnitDashboardComparisonAnalysisOutput.cs
⏳ TimeComparisonData.cs（时间对比数据）
⏳ DepartmentComparisonData.cs（部门对比数据）

门店分布相关

⏳ BusinessUnitDashboardStoreDistributionInput.cs（复用StatisticsInput）
⏳ BusinessUnitDashboardStoreDistributionOutput.cs
⏳ StoreDistributionItem.cs（门店分布项）


🔧 接口参数规范
基础输入参数
所有接口都使用 BusinessUnitDashboardStatisticsInput 或其扩展作为基础输入参数：


BusinessUnitId（可选）：事业部ID（BASE_ORGANIZE表的组织ID）
StoreIds（可选）：门店ID列表
StatisticsMonth（必填）：统计月份（YYYYMM格式）


重要规则：BusinessUnitId 或 StoreIds 两者必填其一，不能同时为空，也不能同时传入
扩展输入参数
部分接口需要额外参数：


趋势分析接口：MonthCount（月份数量，默认12）
排行接口：TopCount（排行数量，默认10）、SortType（排序类型）
明细列表接口：CurrentPage（当前页，默认1）、PageSize（每页数量，默认10）、SortField（排序字段）、SortOrder（排序方向）


📝 实现步骤
第一步：创建DTO类（第一批）

创建趋势分析相关DTO
创建门店排行相关DTO
创建运营分析相关DTO
创建门店明细列表相关DTO

第二步：创建服务类基础结构

创建 LqBusinessUnitDashboardService.cs
实现辅助方法：


GetStoreIdsAsync - 获取门店列表
GetStoreIdsForMonthAsync - 获取指定月份的门店列表
CalculatePerformanceByCategory - 计算品项分类业绩


第三步：实现第一批接口

实现 GetStatistics - 核心指标
实现 GetPerformanceTrend - 趋势分析
实现 GetStoreRanking - 门店排行
实现 GetOperationStatistics - 运营分析
实现 GetStoreDetailList - 门店明细列表

第四步：测试第一批接口

编写测试脚本
测试所有接口
验证数据准确性

第五步：实现第二批接口

创建第二批DTO类
实现 GetManagerRanking
实现 GetComparisonAnalysis
实现 GetStoreDistribution

第六步：实现第三批接口

创建第三批DTO类
实现剩余接口


⚠️ 注意事项

月份维度：所有统计数据必须按月份统计，每个月份独立计算门店归属
门店归属：必须使用 lq_md_target 表的 F_BusinessUnit 字段获取指定月份的门店归属
数据一致性：统计接口与明细列表接口使用相同的过滤条件
性能优化：使用批量查询，避免N+1查询
分页支持：明细列表接口必须支持分页
参数验证：所有接口都需要进行参数验证
错误处理：统一异常处理，返回友好错误信息
日志记录：关键步骤记录日志


📊 预估工作量

总接口数：15个
总DTO类：约25-30个
总代码量：约2600-3450行
预估开发时间：


第一批：2-3天
第二批：1-2天
第三批：2-3天
总计：5-8天


🎯 实现优先级说明

P0：核心功能，必须首先实现
P1：重要功能，第一批或第二批实现
P2：扩展功能，可以后续实现