# 教育部驾驶舱接口清单

> **编制说明**：对标 `科技部驾驶舱接口清单.md`，为教育部看板（二期）列 API 与页面模块。  
> **业务口径**：组织归属 **教育一部/二部**（`lq_md_target.F_EducationDepartment`）；业绩品项 **`F_ItemCategory = '生美'`**（`lq_xmzl.qt2 = '生美'`）。  
> **参考文档**：`客户需求梳理-一期收尾与二期规划.md` §2.1 教育部看板

---

## 〇、与科技部差异摘要

| 维度 | 科技部 | 教育部 |
|------|--------|--------|
| 组织字段 | `F_TechDepartment` | `F_EducationDepartment` |
| 品项 | 科美 | **生美** |
| 老师 | 科技部老师 `kjbls` | 教育部老师 `jybls`（`lq_ycsd_mdlbjhsxx`、`F_EducationTeacherId`） |
| 特有模块 | 溯源/Cell、股份 | **单品项统计**（生命之波等）、**品项占比**、**单客户频次**、**服务日志** |
| 会员标识 | — | `lq_khxx.F_IsEducationMember` |

---

## 一、服务与路由约定

- **Service 类名（建议）**：`LqEducationDepartmentDashboardService`
- **路由前缀**：`POST /api/Extend/LqEducationDepartmentDashboard/{Action}`
- **基础入参类**：`EducationDepartmentDashboardStatisticsInput`

### 1.1 基础入参

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `educationDepartmentId` | string | 与 storeIds 二选一 | 教育部组织 ID |
| `storeIds` | List\<string\> | 与 educationDepartmentId 二选一 | 门店列表 |
| `statisticsMonth` | string | 是 | `YYYYMM` |

**门店解析**：

```sql
SELECT DISTINCT F_StoreId
FROM lq_md_target
WHERE F_EducationDepartment = @educationDepartmentId
  AND F_Month = @statisticsMonth
```

### 1.2 单品项配置（建议）

二期需统计 **生命之波、水氧MG、slk** 等，建议新增配置表或枚举：

| 方案 | 说明 |
|------|------|
| A（推荐） | `lq_education_dashboard_featured_item`：`F_ItemId` / `F_DisplayName` / `F_Sort`，后台可维护 |
| B | 硬编码 `lq_xmzl.xmbh` 列表，首期快但难维护 |

接口 `GetFeaturedItemStatistics` 读取该配置列表逐项汇总。

---

## 二、接口清单

### 2.1 核心业务指标

#### ⏳ 1. GetStatistics — 核心 KPI

| 输出字段 | 说明 | 数据来源 |
|----------|------|----------|
| `billingAmount` | 生美开单金额 | `lq_kd_jksyj`，`F_ItemCategory='生美'` |
| `refundAmount` | 生美退卡 | `lq_hytk_jksyj` / `lq_hytk_mx`（生美行） |
| `netBillingAmount` | 实收 | 开单 − 退卡 |
| `deductAmount` | 生美储扣 | `lq_kd_deductinfo` + 生美品项 |
| `consumeAmount` | 生美消耗 | `lq_xh_pxmx` + `qt2='生美'` |
| `managedStoreCount` | 管辖门店数 | `lq_md_target` |
| `activeStoreCount` | 有生美开单或耗卡门店数 | 去重 |
| `targetAmount` | 教育部月度目标 | `F_EducationDepartmentTarget` 汇总 |
| `targetCompletionRate` | 目标完成率 % | 计算 |
| `educationMemberCount` | 教育部会员数 | `F_IsEducationMember=1` |
| `newEducationMemberCount` | 当月新增 | `F_EducationMemberTime` |
| `billingMemberCount` | 开单人数（去重） | `lq_kd_kdjlb` |
| `consumeMemberCount` | 耗卡人数（去重） | `lq_xh_hyhk` |
| `serviceLogCount` | 当月服务日志条数 | `lq_xh_feedback`（门店在范围内） |

---

#### ⏳ 2. GetFeaturedItemStatistics — 重点单品项（教育部特有）

**说明**：生命之波、水氧MG、slk 等单独卡片 + 表格。

| 输出（每项） | 说明 |
|--------------|------|
| `itemId` / `itemName` | 品项 |
| `billingAmount` | 开单金额 |
| `billingCount` | 开单次数 |
| `consumeAmount` | 消耗金额 |
| `consumeCount` | 消耗次数 |
| `mom` / `yoy` | 环比、同比（可选） |

---

#### ⏳ 3. GetItemShareStatistics — 生美品项开单占比

**输出**：品项名、开单金额、占比 %、开单次数。  
**范围**：当月全部生美品项或 Top20。

---

#### ⏳ 4. GetCustomerFrequencyStatistics — 单品项单客户消费频次

**说明**：如「生命之波」平均每客耗卡次数。

| 输出 | 说明 |
|------|------|
| `itemId` / `itemName` | 品项 |
| `customerCount` | 消费客户数 |
| `totalConsumeCount` | 总耗卡次数 |
| `avgFrequency` | 人均频次 |

---

### 2.2 趋势与对比

#### ⏳ 5. GetPerformanceTrend

`monthCount`：3/6/12  
序列：实收、消耗、储扣、目标完成率。

#### ⏳ 6. GetComparisonAnalysis

环比、同比、近三年同月（对齐二期文档）。

---

### 2.3 排行与分布

#### ⏳ 7. GetStoreRanking

门店实收、消耗、占比。

#### ⏳ 8. GetStoreDistribution

饼图数据。

#### ⏳ 9. GetItemRanking

生美品项开单排行（与 GetItemShareStatistics 可合并或分层：一个 Top 榜一个全量占比）。

#### ⏳ 10. GetTeacherRanking — 教育部老师排行（可选）

**数据来源**：`lq_ycsd_mdlbjhsxx.jybls` 关联当月门店生美业绩；若无老师子表，可按门店归属老师汇总开单。

---

### 2.4 客户维度（二期重点）

#### ⏳ 11. GetCustomerDimensionStatistics — 客户汇总指标

| 字段 | 说明 |
|------|------|
| `billingCount` | 开单数（笔） |
| `consumeCount` | 耗卡数 |
| `refundCount` | 退卡数 |
| `totalBillingAmount` | 开单总金额 |

可按 **会员** 聚合后做分布（人均开单等）。

#### ⏳ 12. GetCustomerDetailList — 客户明细分页

字段：会员、门店、开单数、耗卡数、退卡数、开单总金额、最近耗卡日。

---

### 2.5 服务日志（教育部特有）

#### ⏳ 13. GetServiceLogStatistics

按门店/老师统计 `lq_xh_feedback` 条数；权限：老师仅看自己创建（`F_CreateUser`）。

#### ⏳ 14. GetServiceLogList — 服务日志分页

| 字段 | 说明 |
|------|------|
| `storeName` | 门店 |
| `teacherName` | 老师（创建人） |
| `remark` | 备注 `F_Remark` / `F_KjbRemark` |
| `createTime` | 时间 |
| `attachments` | 附件（若有） |

---

### 2.6 运营与明细

#### ⏳ 15. GetOperationStatistics

开单 / 消耗 / 退卡分析（同科技部结构）。

#### ⏳ 16. GetStoreDetailList

#### ⏳ 17. GetBillingDetailList — 生美开单明细

#### ⏳ 18. GetConsumeDetailList — 生美耗卡明细

#### ⏳ 19. GetRefundDetailList — 生美退卡明细

#### ⏳ 20. ExportStoreDetailList / ExportCustomerDetailList

导出记 `lq_business_operation_log`（模块：教育部看板，动作：导出）。

---

## 三、页面模块结构（管理后台）

**建议路径**：`antis-ncc-admin/src/views/extend/educationDepartmentDashboard/index.vue`  
**API 模块**：`antis-ncc-admin/src/api/extend/educationDepartmentDashboard.js`

| 区块 | 接口 | 说明 |
|------|------|------|
| **顶栏** | — | 月份 + 教育部（一部/二部）+ 刷新 |
| **KPI 行** | `GetStatistics` | 实收、消耗、目标完成率、活跃门店、教育部会员、服务日志数 |
| **重点单品项** | `GetFeaturedItemStatistics` | 横向卡片（生命之波、水氧MG、slk…） |
| **业绩趋势** | `GetPerformanceTrend` | 折线 3/6/12 月 |
| **品项占比** | `GetItemShareStatistics` | 饼图 + 表格双呈现（战略全景舱同款） |
| **消费频次** | `GetCustomerFrequencyStatistics` | 条形图（单品项人均耗卡） |
| **环比同比** | `GetComparisonAnalysis` | 数字卡片 |
| **门店排行** | `GetStoreRanking` | 表格，点击穿透 |
| **老师排行** | `GetTeacherRanking` | 可选 |
| **运营分析** | `GetOperationStatistics` | 三列指标 |
| **服务日志** | `GetServiceLogStatistics` + `GetServiceLogList` | 统计 + 列表 Tab |
| **明细 Tab** | 门店 / 开单 / 耗卡 / 退卡 / 客户 | `NCC-table` 分页 |
| **截图导出** | 前端 + 导出接口 | 二期 |

**配置页（一期收尾已有 CRUD 可链入）**  
- 教育部门店归属：`lq_md_target`、`LqMdTargetService`（`organizationType=教育部`）  
- 老师归属：`lq_ycsd_mdlbjhsxx`、`LqMdMajorProjectTeacherAssignmentService`  
- 重点单品项配置（若采用方案 A）：新菜单「教育部看板品项配置」

---

## 四、可复用现有接口

| 接口 | 用途 |
|------|------|
| `POST /api/Extend/LqDailyReport/get-tianwang-group-performance-completion` | 教育部=生美，口径校验 |
| `POST /api/Extend/LqStatistics/OtherDepartmentStatistics` | 教育部门子部门流水 |
| `POST /api/Extend/LqXmzl/GetItemStatistics` | 按品项 ID 批量统计 |
| `POST /api/Extend/LqStoreDashboard/GetStatistics` | `LifeBeautyPerformance` 分项 |
| `GET /api/Extend/LqMdTarget/...` | 按教育部查管辖门店 |

---

## 五、实现优先级

**第一批（MVP）**  
1. `GetStatistics`  
2. `GetPerformanceTrend`  
3. `GetStoreRanking`  
4. `GetFeaturedItemStatistics`（硬编码 3 个品项可先上线）  
5. `GetStoreDetailList`  
6. 页面：顶栏 + KPI + 趋势 + 重点品项 + 门店排行  

**第二批**  
7. `GetItemShareStatistics`  
8. `GetCustomerFrequencyStatistics`  
9. `GetOperationStatistics`  
10. 开单/耗卡/退卡明细  

**第三批**  
11. `GetCustomerDimensionStatistics` + `GetCustomerDetailList`  
12. `GetServiceLogStatistics` + `GetServiceLogList`  
13. 单品项后台配置、导出、截图、小程序  

---

## 六、后端文件清单（建议新建）

```
netcore/src/Modularity/Extend/NCC.Extend/LqEducationDepartmentDashboardService.cs
netcore/src/Modularity/Extend/NCC.Extend.Entitys/Dto/LqEducationDepartmentDashboard/*.cs
antis-ncc-admin/src/views/extend/educationDepartmentDashboard/index.vue
antis-ncc-admin/src/api/extend/educationDepartmentDashboard.js
```

**权限**：菜单「教育部看板」；门店范围 `F_EducationDepartment` + `F_Month`。

---

## 七、待产品确认项

1. 生命之波 / 水氧MG / slk 的 `xmbh` 或 `F_ItemId` 正式清单  
2. 服务日志是否仅 `lq_xh_feedback`，是否合并 `lq_xh_hyhk` 备注  
3. 教育部老师业绩是否单独子表，还是仅健康师 `lq_kd_jksyj` 生美汇总  
4. 客户维度「开单数」按主单还是按品项行  

---

## 八、科技部看板二期增强（对照，非本文件实现范围）

教育部/医美新建时，科技部同步项见 `客户需求梳理`：

- 门店战略决策 **科技部 → 门店穿透**（复用 `GetStoreDetailList`）  
- **冰美人** 从溯源拆分统计  
- 老师数据与「科技部营销数据」**实时**一致