antissoft / lvqianmeiye_ERP

  # 医美驾驶舱接口清单
  
  > **编制说明**：对标 `科技部驾驶舱接口清单.md` 与 `LqTechDepartmentDashboardService`，为医美看板（二期）列 API 与页面模块。  
  > **业务口径**：组织归属 **大项目部**（`lq_md_target.F_MajorProjectDepartment`）；业绩品项 **`F_ItemCategory = '医美'`**（或 `lq_xmzl.qt2 = '医美'`）。  
  > **参考文档**：`客户需求梳理-一期收尾与二期规划.md` §2.1 医美看板、`科技部驾驶舱数据分析梳理.md`
  
  ---
  
  ## 〇、与科技部差异摘要
  
  | 维度 | 科技部驾驶舱 | 医美驾驶舱 |
  |------|--------------|------------|
  | 组织筛选字段 | `F_TechDepartment` | `F_MajorProjectDepartment` |
  | 品项类型 | 科美（溯源/Cell） | 医美 |
  | 老师业绩 | `lq_kd_kjbsyj` 科技部老师 | 大项目部老师（`lq_md_major_project_teacher_assignment`）+ 健康师医美业绩 `lq_kd_jksyj` |
  | 股份模块 | 有（`lq_share_statistics_tech_dept`） | **无独立股份表**，一期不做股份趋势（或二期对接大项目部薪酬） |
  | 特有模块 | 溯源/Cell 拆分 | **客户活跃、未消耗权益、医美会员、品项/客户排名** |
  
  ---
  
  ## 一、服务与路由约定
  
  - **Service 类名（建议）**：`LqMedicalBeautyDashboardService`
  - **路由前缀**：`POST /api/Extend/LqMedicalBeautyDashboard/{Action}`
  - **基础入参类**：`MedicalBeautyDashboardStatisticsInput`
  
  ### 1.1 基础入参 `MedicalBeautyDashboardStatisticsInput`
  
  | 字段 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | `majorProjectDepartmentId` | string | 与 storeIds 二选一 | 大项目部组织 ID（`BASE_ORGANIZE.F_Id`） |
  | `storeIds` | List\<string\> | 与 majorProjectDepartmentId 二选一 | 直接指定门店列表 |
  | `statisticsMonth` | string | 是 | 统计月 `YYYYMM` |
  
  **门店解析规则**（与科技部一致）：
  
  ```sql
  SELECT DISTINCT F_StoreId
  FROM lq_md_target
  WHERE F_MajorProjectDepartment = @majorProjectDepartmentId
    AND F_Month = @statisticsMonth
  ```
  
  ### 1.2 月份与落月口径
  
  | 业务 | 落月字段 | 表 |
  |------|----------|-----|
  | 开单实收 | 单据 `kdrq` 或子表 `yjsj`（与天王日报/大项目部一致，实现时二选一并写清） | `lq_kd_kdjlb` + `lq_kd_jksyj` / `lq_kd_pxmx` |
  | 退卡 | 主表 `tksj` | `lq_hytk_hytk` + `lq_hytk_jksyj` / `lq_hytk_mx`（仅医美明细） |
  | 耗卡 | `hksj` | `lq_xh_hyhk` + `lq_xh_pxmx` |
  | 储扣 | 关联开单 `kdrq` | `lq_kd_deductinfo` + 品项 `qt2='医美'` |
  
  ---
  
  ## 二、接口清单
  
  ### 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` | 大项目部月度目标 | `lq_md_target.F_MajorProjectDepartmentTarget` 汇总 |
  | `targetCompletionRate` | 目标完成率 % | `netBillingAmount / targetAmount` |
  | `medicalMemberCount` | 医美会员数（期末） | `lq_khxx.F_IsMedicalMember=1` 且门店在范围内 |
  | `newMedicalMemberCount` | 当月新增医美会员 | `F_MedicalMemberTime` 落月 |
  | `billingMemberCount` | 当月医美开单人数（去重） | `lq_kd_kdjlb.kdhy` |
  | `consumeMemberCount` | 当月医美耗卡人数（去重） | `lq_xh_hyhk` |
  | `avgOrderAmount` | 客单价 | `netBillingAmount / billingMemberCount` |
  
  ---
  
  #### ⏳ 2. GetCustomerActivityStatistics — 客户活跃与结构
  
  **说明**：对应二期「客户活跃度、老客/新客/复购」。
  
  | 输出字段 | 说明 |
  |----------|------|
  | `newCustomerCount` | 新客（口径待确认：首单医美 / 首到店） |
  | `oldCustomerCount` | 老客 |
  | `repurchaseCustomerCount` | 复购客户数（当月≥2 次医美开单或耗卡） |
  | `activeCustomerCount` | 活跃客户（当月有开单或耗卡） |
  | `inactiveCustomerCount` | 沉睡客户（管辖门店会员中当月无医美行为） |
  | `unusedRightsCustomerCount` | 有医美权益未消耗客户数 |
  | `unusedRightsAmount` | 未消耗权益金额合计 | `lq_khxx.F_RemainingRightsAmount` 等，需结合医美品项剩余 |
  
  > **待产品确认**：新客/老客判定规则写入 `医美驾驶舱数据分析梳理.md` 定稿后再实现。
  
  ---
  
  #### ⏳ 3. GetUnusedRightsStatistics — 未消耗客户明细（Top + 分页）
  
  **入参**：基础入参 + `PageInput`  
  **输出**：会员、门店、剩余权益金额、最近开单/耗卡日期。
  
  ---
  
  ### 2.2 趋势分析
  
  #### ⏳ 4. GetPerformanceTrend
  
  **入参**：`MedicalBeautyDashboardPerformanceTrendInput`（继承基础入参 + `monthCount`：3/6/12）
  
  | 序列 | 说明 |
  |------|------|
  | `netBillingTrend` | 实收趋势 |
  | `consumeTrend` | 消耗趋势 |
  | `deductTrend` | 储扣趋势 |
  | `targetCompletionTrend` | 目标完成率趋势 |
  
  ---
  
  #### ⏳ 5. GetComparisonAnalysis — 环比 / 同比
  
  | 输出 | 说明 |
  |------|------|
  | `mom` | 环比上月（实收、消耗、人数） |
  | `yoy` | 同比去年同月 |
  | `yoyThreeYear` | 近三年同月对比（二期「环比三年」） |
  
  ---
  
  ### 2.3 排行与分布
  
  #### ⏳ 6. GetStoreRanking — 门店排行
  
  | 字段 | 说明 |
  |------|------|
  | `storeId` / `storeName` | 门店 |
  | `netBillingAmount` | 实收 |
  | `consumeAmount` | 消耗 |
  | `percentage` | 占部门总额 % |
  
  ---
  
  #### ⏳ 7. GetStoreDistribution — 门店业绩分布（饼图）
  
  ---
  
  #### ⏳ 8. GetItemRanking — 品项排行
  
  **数据来源**：`lq_kd_pxmx` + `lq_xmzl`，`qt2='医美'`  
  **字段**：品项名、开单金额、开单次数、占比。
  
  ---
  
  #### ⏳ 9. GetCustomerRanking — 客户排行（Top N）
  
  **字段**：客户名、门店、开单金额、耗卡次数、最近到店。
  
  ---
  
  ### 2.4 运营分析
  
  #### ⏳ 10. GetOperationStatistics
  
  | 模块 | 指标 |
  |------|------|
  | 开单 | 次数、均单、门店分布 |
  | 消耗 | 次数、金额、消耗率（消耗/开单） |
  | 退卡 | 次数、金额、退卡率 |
  
  ---
  
  ### 2.5 明细列表（分页）
  
  #### ⏳ 11. GetStoreDetailList
  
  门店维度：实收、消耗、目标、完成率、开单人数。
  
  #### ⏳ 12. GetBillingDetailList
  
  医美开单明细：`lq_kd_kdjlb` + `lq_kd_pxmx` / `lq_kd_jksyj`。
  
  #### ⏳ 13. GetConsumeDetailList
  
  医美耗卡明细：`lq_xh_hyhk` + `lq_xh_pxmx`。
  
  #### ⏳ 14. GetRefundDetailList
  
  医美退卡明细：`lq_hytk_hytk` + 医美品项行。
  
  #### ⏳ 15. GetCustomerDetailList — 医美客户列表（二期「展示所有医美客户」）
  
  **筛选**：门店、是否会员、是否有未消耗、关键词（姓名/手机）。
  
  #### ⏳ 16. ExportCustomerDetailList — 导出 / 截图数据源
  
  复用列表查询，支持导出 Excel（记业务日志）。
  
  ---
  
  ## 三、页面模块结构（管理后台）
  
  **建议路径**：`antis-ncc-admin/src/views/extend/medicalBeautyDashboard/index.vue`  
  **API 模块**：`antis-ncc-admin/src/api/extend/medicalBeautyDashboard.js`  
  **小程序（可选二期）**：`绿纤uni-app/pagesA/medical-beauty-dashboard/`
  
  | 区块 | 对应接口 | UI 组件（对标科技部） |
  |------|----------|------------------------|
  | **顶栏筛选** | — | 月份 + 大项目部下拉 + 刷新 |
  | **KPI 第一行** | `GetStatistics` | 6~8 张卡片：实收、消耗、储扣、退卡、目标完成率、活跃门店 |
  | **KPI 第二行** | `GetStatistics` + `GetCustomerActivityStatistics` | 医美会员、新客、复购、客单价、未消耗金额 |
  | **业绩趋势** | `GetPerformanceTrend` | 折线图，3/6/12 月切换 |
  | **门店分布** | `GetStoreDistribution` | 饼图 |
  | **环比同比** | `GetComparisonAnalysis` | 数字卡片 + 迷你柱图 |
  | **门店排行** | `GetStoreRanking` | 表格 Top10，点击穿透门店明细 |
  | **品项排行** | `GetItemRanking` | 表格 / 条形图 |
  | **客户排行** | `GetCustomerRanking` | 表格 Top10 |
  | **运营分析** | `GetOperationStatistics` | 开单/消耗/退卡三列指标 |
  | **明细 Tab** | `GetStoreDetailList` / `GetBillingDetailList` / `GetConsumeDetailList` / `GetCustomerDetailList` | `NCC-table` 分页，支持导出 |
  | **未消耗专区** | `GetUnusedRightsStatistics` | 可折叠表格 |
  | **截图** | 前端 `html2canvas` 或区域导出 | 二期需求 |
  
  **工作台入口（可选）**：`workbench/widgets/medical-beauty-dashboard-entry.vue`、`medical-beauty-kpi.vue`
  
  ---
  
  ## 四、可复用现有接口（开发前可先拼装 Mock）
  
  | 接口 | 用途 |
  |------|------|
  | `POST /api/Extend/LqStoreDashboard/GetStatistics` | 门店维度医美分项 |
  | `POST /api/Extend/LqStoreDashboard/GetCategoryMonthlyPerformance` | 月度医美消耗 |
  | `POST /api/Extend/LqBusinessUnitDashboard/GetStatistics` | 事业部医美占比 |
  | `POST /api/Extend/LqDailyReport/get-tianwang-group-performance-completion` | 大项目部=医美日报口径校验 |
  | `POST /api/Extend/LqXmzl/GetItemStatistics` | `itemCategory: "医美"` |
  | `POST /api/Extend/LqStatistics/get-member-upgrade-statistics-list` | 升医美人数 |
  
  ---
  
  ## 五、实现优先级
  
  **第一批（可上线 MVP）**  
  1. `GetStatistics`  
  2. `GetPerformanceTrend`  
  3. `GetStoreRanking`  
  4. `GetStoreDetailList`  
  5. 管理后台页面：顶栏 + KPI + 趋势 + 门店排行 + 门店明细  
  
  **第二批**  
  6. `GetOperationStatistics`  
  7. `GetItemRanking`  
  8. `GetComparisonAnalysis`  
  9. `GetBillingDetailList` / `GetConsumeDetailList` / `GetRefundDetailList`  
  
  **第三批（二期完整）**  
  10. `GetCustomerActivityStatistics`  
  11. `GetCustomerRanking` / `GetCustomerDetailList`  
  12. `GetUnusedRightsStatistics`  
  13. 导出、截图、小程序页  
  
  ---
  
  ## 六、后端文件清单（建议新建）
  
  ```
  netcore/src/Modularity/Extend/NCC.Extend/LqMedicalBeautyDashboardService.cs
  netcore/src/Modularity/Extend/NCC.Extend.Entitys/Dto/LqMedicalBeautyDashboard/*.cs
  antis-ncc-admin/src/api/extend/medicalBeautyDashboard.js
  antis-ncc-admin/src/views/extend/medicalBeautyDashboard/index.vue
  ```
  
  **权限**：菜单「医美看板」；数据范围按大项目部组织 + `lq_md_target` 月份门店（与科技部 `app科技部数据开关按钮` 类似，可加「大项目部数据开关」）。
  
  ---
  
  ## 七、待产品确认项（实现前）
  
  1. 新客 / 老客 / 复购的精确 SQL 口径  
  2. 未消耗金额：仅 `F_RemainingRightsAmount` 还是按医美品项明细剩余  
  3. 开单落月用 `kdrq` 还是 `yjsj`（建议与天王日报大项目部一致）  
  4. 活动秒杀是否单独字段或标签  
  
  定稿后同步更新 `项目文档相关/docs/数据库说明.md`（若新增配置表）。