# 事业部驾驶舱接口清单

根据 `事业部驾驶舱数据分析梳理.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**：扩展功能，可以后续实现