antissoft / lvqianmeiye_ERP

  # 事业部驾驶舱接口清单
  
  根据 `事业部驾驶舱数据分析梳理.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）：基础功能
  **目标**：完成最核心的统计数据，支撑驾驶舱主页面展示
  
  1. **GetStatistics**（P0）
     - 核心业务指标统计
     - 包含所有关键指标
     - 预估代码量：300-400行
  
  2. **GetPerformanceTrend**（P1）
     - 业绩趋势分析
     - 支持多时间维度
     - 预估代码量：200-300行
  
  3. **GetStoreRanking**（P1）
     - 门店业绩排行
     - 支持多种排序方式
     - 预估代码量：200-250行
  
  4. **GetOperationStatistics**（P1）
     - 运营分析数据
     - 包含开单、消耗、退卡分析
     - 预估代码量：200-250行
  
  5. **GetStoreDetailList**（P1）
     - 门店明细列表
     - 支持分页和排序
     - 预估代码量：150-200行
  
  **第一批总计**：约1050-1400行代码
  
  ---
  
  ### 第二批（分析接口 - P1/P2）：分析功能
  **目标**：完成分析和对比功能
  
  6. **GetManagerRanking**（P1）
     - 总经理/经理业绩排行
     - 关联工资数据
     - 预估代码量：250-300行
  
  7. **GetComparisonAnalysis**（P2）
     - 对比分析数据
     - 环比、同比、部门对比
     - 预估代码量：250-300行
  
  8. **GetStoreDistribution**（P2）
     - 门店业绩分布
     - 饼图和柱状图数据
     - 预估代码量：150-200行
  
  **第二批总计**：约650-800行代码
  
  ---
  
  ### 第三批（扩展接口 - P2）：扩展功能
  **目标**：完成人员分析和明细功能
  
  9. **GetManagerDistribution**（P2）
     - 总经理/经理业绩分布
     - 预估代码量：100-150行
  
  10. **GetManagerTrend**（P2）
      - 总经理/经理业绩趋势
      - 预估代码量：150-200行
  
  11. **GetStoreManagerRanking**（P2）
      - 店长业绩排行
      - 预估代码量：150-200行
  
  12. **GetHealthCoachRanking**（P2）
      - 健康师业绩排行
      - 预估代码量：150-200行
  
  13. **GetManagerDetailList**（P2）
      - 总经理/经理明细列表
      - 预估代码量：150-200行
  
  14. **GetStoreManagerDetailList**（P2）
      - 店长明细列表
      - 预估代码量：100-150行
  
  15. **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类（第一批）
  1. 创建趋势分析相关DTO
  2. 创建门店排行相关DTO
  3. 创建运营分析相关DTO
  4. 创建门店明细列表相关DTO
  
  ### 第二步：创建服务类基础结构
  1. 创建 `LqBusinessUnitDashboardService.cs`
  2. 实现辅助方法：
     - `GetStoreIdsAsync` - 获取门店列表
     - `GetStoreIdsForMonthAsync` - 获取指定月份的门店列表
     - `CalculatePerformanceByCategory` - 计算品项分类业绩
  
  ### 第三步：实现第一批接口
  1. 实现 `GetStatistics` - 核心指标
  2. 实现 `GetPerformanceTrend` - 趋势分析
  3. 实现 `GetStoreRanking` - 门店排行
  4. 实现 `GetOperationStatistics` - 运营分析
  5. 实现 `GetStoreDetailList` - 门店明细列表
  
  ### 第四步：测试第一批接口
  1. 编写测试脚本
  2. 测试所有接口
  3. 验证数据准确性
  
  ### 第五步：实现第二批接口
  1. 创建第二批DTO类
  2. 实现 `GetManagerRanking`
  3. 实现 `GetComparisonAnalysis`
  4. 实现 `GetStoreDistribution`
  
  ### 第六步：实现第三批接口
  1. 创建第三批DTO类
  2. 实现剩余接口
  
  ---
  
  ## ⚠️ 注意事项
  
  1. **月份维度**：所有统计数据必须按月份统计，每个月份独立计算门店归属
  2. **门店归属**：必须使用 `lq_md_target` 表的 `F_BusinessUnit` 字段获取指定月份的门店归属
  3. **数据一致性**：统计接口与明细列表接口使用相同的过滤条件
  4. **性能优化**：使用批量查询，避免N+1查询
  5. **分页支持**：明细列表接口必须支持分页
  6. **参数验证**：所有接口都需要进行参数验证
  7. **错误处理**：统一异常处理，返回友好错误信息
  8. **日志记录**：关键步骤记录日志
  
  ---
  
  ## 📊 预估工作量
  
  - **总接口数**：15个
  - **总DTO类**：约25-30个
  - **总代码量**：约2600-3450行
  - **预估开发时间**：
    - 第一批：2-3天
    - 第二批：1-2天
    - 第三批：2-3天
    - 总计：5-8天
  
  ---
  
  ## 🎯 实现优先级说明
  
  - **P0**：核心功能，必须首先实现
  - **P1**：重要功能，第一批或第二批实现
  - **P2**：扩展功能，可以后续实现