# 医美驾驶舱接口清单

> **编制说明**：对标 `科技部驾驶舱接口清单.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`（若新增配置表）。