# 品项名称改造方案（按 ID 关联显示）

## 1. 背景与目标

当前系统已运行较长时间，品项名称在多个业务环节被“快照存储”（例如开单/耗卡/退卡/业绩明细），导致“主档改名后历史数据是否跟随变化”成为核心问题。

本方案目标：
- 以 `品项ID` 作为唯一业务事实源；
- 查询/统计场景可按 `ID -> 当前主档名称` 展示最新名称；
- 保留历史快照名称用于审计与追溯；
- 在不破坏生产数据稳定性的前提下，分阶段完成改造。

## 2. 关键结论

- **同意“按 ID 关联即可”**，但必须区分“展示口径”和“审计口径”。
- 不建议直接全量回写历史快照名称（风险高、不可逆、对账成本大）。
- 推荐“双字段口径”：
  - `itemNameSnapshot`：历史快照名（业务发生当时）
  - `itemNameCurrent`：按 ID 关联主档实时名（当前名称）

## 3. 现状梳理（影响面）

### 3.1 主档与产品主数据
- `lq_xmzl.xmmc`（项目资料）
- `lq_product.F_ProductName`（库存产品）

### 3.2 历史快照字段（重点）
以下表存在名称快照字段，主档改名后不会自动联动：
- `lq_kd_pxmx.pxmc`（开单明细）
- `lq_xh_pxmx.pxmc`（耗卡明细）
- `lq_hytk_mx.pxmc`（退卡明细）
- `lq_yyjl_px.F_Pxmc`（预约明细）
- `lq_kd_jksyj.F_ItemName`、`lq_kd_kjbsyj.F_ItemName`
- `lq_xh_jksyj.F_ItemName`、`lq_xh_kjbsyj.F_ItemName`
- `lq_hytk_jksyj.F_ItemName`、`lq_hytk_kjbsyj.F_ItemName`
- `lq_kd_deductinfo.F_ItemName`
- `lq_yjmxb.xmmc`

### 3.3 后端服务与接口（高频）
- 项目资料：`LqXmzlService`
- 开单：`LqKdKdjlbService`
- 耗卡：`LqXhHyhkService`
- 退卡：`LqHytkHytkService`
- 统计/报表：`LqStatisticsService`、`LqReportService`
- 库存使用：`LqInventoryUsageService`

### 3.4 前端三端
- 管理后台：`antis-ncc-admin`
- 门店 PC：`store-pc`
- 手机端：`绿纤uni-app`

存在大量 `xmmc / itemName / pxmc / productName` 展示与搜索逻辑，需要统一口径。

## 4. 改造原则

1. **业务判断永远用 ID / 分类编码，不用名称字符串判断。**
2. **保存时保留快照**（兼容历史与审计）。
3. **查询时可选“当前名称”展示**（用户视角一致）。
4. **导出口径可配置**：审计导出用快照；运营报表可用当前名。
5. **渐进式发布**：先“加字段不替换”，再页面逐步切换。

## 5. 目标数据模型（接口返回层）

对涉及品项的列表/明细 DTO 增加统一字段（命名可按现有风格微调）：
- `itemId`（已有则复用）
- `itemNameSnapshot`（来自明细表快照字段）
- `itemNameCurrent`（通过 itemId 关联 `lq_xmzl` 或 `lq_product` 得到）
- `itemNameDisplay`（后端统一赋值：优先 current，兜底 snapshot）

说明：
- 不强制修改现有数据库表结构；
- 以“查询拼装”实现，优先低风险落地。

## 6. 分阶段实施计划

### Phase 0：基线与开关（1-2 天）
- 建“名称显示口径”开关（建议放系统配置）：
  - `snapshot`：显示历史快照
  - `current`：显示当前主档名（默认）
  - `both`：显示“当前名（历史名）”
- 梳理核心接口清单并建立回归用例。

交付物：
- 口径开关配置
- 接口改造白名单
- 回归清单 v1

### Phase 1：后端查询层改造（3-5 天）
- 先改高频接口：开单、耗卡、退卡、统计看板、库存使用。
- 统一在服务层拼装 `itemNameCurrent` 与 `itemNameDisplay`。
- 导出接口补“显示口径”参数（默认 current，审计类可切 snapshot）。

交付物：
- 后端接口新增字段并兼容老字段
- 导出口径参数
- 核心接口测试通过

### Phase 2：前端三端展示切换（3-5 天）
- 三端页面统一显示 `itemNameDisplay`；
- 搜索支持“名称（当前名/快照名）+ ID”混合查询；
- 关键页面加 tooltip（显示历史名，便于核对）。

交付物：
- admin/store-pc/uni-app 主流程页面切换完成
- 页面回归通过

### Phase 3：统计与导出全覆盖（2-4 天）
- 统计报表全部统一名称口径；
- 导出模板区分“运营版（当前名）/审计版（快照名）”。

交付物：
- 报表与导出口径一致性验收
- 业务方签字确认

### Phase 4：可选增强（后续）
- 增加“品项名称变更日志表”（记录旧名、新名、操作人、时间）。
- 提供“历史名称映射查询”能力，辅助追溯。

## 7. 兼容与风险控制

### 7.1 兼容策略
- 老字段不删：`xmmc/pxmc/F_ItemName` 继续保留。
- 新字段增量返回，不破坏现有前端。
- 分批切页面，先灰度后全量。

### 7.2 主要风险
- 同名不同 ID 的品项被误归并。
- 历史单据显示变化引发财务误解。
- 导出模板与页面口径不一致。
- 局部代码仍用“品项名称字符串”做业务判断，改名后会误判。
- 聚合 SQL 同时按 `itemId + itemName` 分组，改名前后可能被拆成两行。
- 查询参数仍按名称模糊匹配时，用户可能误以为“数据丢失”。

### 7.3 防控措施
- 所有聚合统计以 `itemId` 为主键分组。
- 报表标题显式标注“按当前名称展示/按历史快照展示”。
- 发布前做“同一时间区间、新旧口径对比报表”。
- 对“名称参与业务判断”的代码做专项整改清单并逐条回归（见第 11 节）。
- 所有搜索接口支持“名称 + ID 双通道”检索，避免仅靠名称检索导致漏数。

## 8. 验收标准（必须通过）

1. 主档改名后，开单/耗卡/退卡新数据立即显示新名称。
2. 历史数据在“当前口径”下可显示新名称，在“审计口径”下可显示旧名称。
3. 所有统计页与导出页口径一致，不出现同 ID 双名称拆分。
4. 不出现任何基于名称字符串的业务判断回归问题。
5. 全流程回归通过：开单、耗卡（医美 T 区/科美）、退卡、薪资、分摊、看板、导出。

## 9. 建议上线顺序

1. 后端接口先增量返回新字段（不切前端）。
2. 管理后台先切换并灰度给运营。
3. 门店 PC 与手机端随后切换。
4. 最后切导出默认口径，并保留审计口径开关。

## 10. 需要产品/业务确认的决策项

上线前请明确以下口径：
- 默认展示口径：`current` 还是 `both`？
- 财务导出默认用快照名还是当前名？
- 历史页面是否允许看到“当前名（历史名）”双显？
- 是否需要落地“名称变更日志”审计功能？

## 11. 本轮复盘补充的遗漏点（必须纳入改造）

### 11.1 逻辑层仍存在“按名称判断”的代码（高风险）

已发现典型位置（示例）：
- `LqXhHyhkService.AppointmentConsume` 中存在 `string.Equals(a.Pxmc, item.pxmc)` 等按名称比对逻辑。
- 这类逻辑在品项改名后会直接出现“同一品项无法匹配/重复匹配”问题。

要求：
- 统一改为 `itemId` 比对（如 `Px` / `F_ItemId`）。
- 名称仅用于提示文案，不作为判定条件。

### 11.2 聚合/统计存在“ID + 名称”双字段分组（高风险）

已发现示例：
- `LqReportService` 中 `GROUP BY xhpx.px, xhpx.pxmc`、`GROUP BY kdpx.px, kdpx.pxmc`
- `LqPackageInfoService` 中 `GroupBy(new { ItemId = px.Px, ItemName = px.Pxmc })`

风险：
- 改名前后同一 `itemId` 可能因为 `itemName` 不同而被拆分成多行统计结果。

要求：
- 聚合一律按 `itemId` 分组；
- 名称由关联主档或聚合后再映射，避免分组维度携带名称。

### 11.3 搜索条件目前大量按名称模糊查询（中风险）

现状：
- 多个接口 `WhereIF(input.ItemName, ... Contains(Pxmc))`；
- 用户只记得新名称时，若页面仍走快照字段搜索，会查不到部分历史数据。

要求：
- 查询参数升级为：`itemKeyword`（名称或编码），并支持 `itemId` 精确查询；
- 在口径切换为 current 时，搜索需兼容快照名与当前名。

### 11.4 导出与接口说明文档口径同步（中风险）

现状：
- 导出列大量使用“品项名称”单字段；
- 接口文档/前端说明仍默认“品项名称唯一”。

要求：
- 导出增加“名称口径”标识或参数；
- 文档示例同步为 `itemNameSnapshot/itemNameCurrent/itemNameDisplay`。

### 11.5 数据前置校验（已核验）

本次查库结果（开发库）：
- 核心明细表 `itemId` 缺失量为 0（开单/耗卡/退卡/预约/业绩表均可按 ID 关联）。
- 说明：以 ID 关联改造具备可落地数据基础，无需先做大规模补数。

## 12. 增补后的实施清单（执行版）

在原 Phase 计划基础上，新增强制任务：

1. **专项任务 A：名称判定逻辑清零**
   - 扫描并替换所有 `pxmc/xmmc/itemName` 参与判定、去重、匹配的代码。
   - 验收标准：业务判定逻辑中不再出现名称等值比较。

2. **专项任务 B：聚合 SQL 维度整改**
   - 所有 `GROUP BY` 涉及品项维度时，只允许 `itemId` 作为主分组键。
   - 验收标准：同一 `itemId` 不会因改名前后名称变化而拆分。

3. **专项任务 C：查询参数升级**
   - 列表接口统一支持 `itemId` 精确过滤；
   - 名称搜索支持“当前名+快照名”兼容检索。

4. **专项任务 D：文档与导出口径统一**
   - 对外接口文档、前端调用说明、导出模板说明全部补充口径说明。

---

该方案遵循“ID 作为业务主键、名称作为展示属性”的原则，可在不改历史数据的前提下实现平滑升级，并保留审计可追溯能力。