antissoft / lvqianmeiye_ERP

  # 教育部驾驶舱接口清单
  
  > **编制说明**：对标 `科技部驾驶舱接口清单.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`）  
  - **冰美人** 从溯源拆分统计  
  - 老师数据与「科技部营销数据」**实时**一致