# P0-2 confirmed_income vs items_sum 反馈处理

> 日期:2026-05-04 / 触发:Neo 在 04a-conflicts 反馈
> Neo 原话:"我理解这个问题是一个说明性的问题,我认为在涉及的前后端及数据库文档都应该留痕进行解释说明,也就是 ABC 选项都要做,我的理解对么?你的建议是什么?"

## 一、Neo 的理解校核

**结论:Neo 的理解大致正确,但建议做"主权威 + 副链接"而非"三处都写完整说明",避免维护负担。**

理由:

- 这个问题的本质**不是逻辑冲突**,是**口径术语未沉淀到唯一权威源**
- 如果三处都写完整定义(ETL CLAUDE.md / DWS 权威规范 / 看板优化 PRD),后续任何字段调整需要同步改 3 处,极易漂移,反而制造新冲突
- 文档维护的工程经验:**单一权威源(SSOT) + 链接指向**,比"多处冗余"更易维护

## 二、推荐方案("主 + 副"而非"三处都写完整")

### 主权威源(写完整定义)

**`apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_finance_daily_summary.md`**(已存在,L148-L149 已有部分描述)

理由:
- 飞球 DWS 权威规范是金额口径的最终归属(参考 `apps/etl/connectors/feiqiu/CLAUDE.md` DWD 规则 1)
- BD 手册本身就是"DWD/DWS 字段权威清单",拓展几行术语对照表是这份文档的天然职责
- 修改频率最低,不会跟随业务迭代变动

**补充内容**:在 BD 手册 § 字段说明 上方加 § "金额口径术语对照表":
```
| 术语 | 定义 | DWD/DWS 层 | 用途 |
| --- | --- | --- | --- |
| consume_money | (历史)三种口径并存,不可直接使用 | DWS 上游 | 已废弃 |
| items_sum | 5 项费用之和:台桌费 + 商品费 + 陪打费 + 超休费 + 电费 | DWD | 替代 consume_money |
| gross_amount | 4 项之和(items_sum 减 electricity_money) | DWS | DWS 内部聚合基础 |
| confirmed_income | gross_amount - discount_total(总和减优惠) | DWS | 客单价 / 日均额 分子 |

关系:items_sum = gross_amount + electricity_money;confirmed_income = gross_amount - discount_total
```

### 副链接(只加一行指向主权威)

**位置 1:[`apps/etl/connectors/feiqiu/CLAUDE.md`](../../../apps/etl/connectors/feiqiu/CLAUDE.md) DWD 规则 1**
- 在已有的 "DWS 层及下游统一改用 `items_sum`" 后加一句:
  > 完整术语对照(items_sum / gross_amount / confirmed_income / discount_total 关系)见 `docs/database/DWS/main/BD_manual_dws_finance_daily_summary.md` § 金额口径术语对照表

**位置 2:[`docs/prd/2026-04-08__board-finance-optimization.md`](../../prd/2026-04-08__board-finance-optimization.md)**
- 在文档顶部加一段"术语对照"小节:
  > 本文涉及的金额术语 (`confirmed_income`、`items_sum`、`gross_amount`) 完整定义见 `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_finance_daily_summary.md` § 金额口径术语对照表

**位置 3:[`docs/miniprogram-dev/api-audit/board-finance.md`](../../miniprogram-dev/api-audit/board-finance.md)**(可选)
- 在 § 金额字段段落加一句:
  > 客单价分子 (`confirmed_income`) 与营收发生额 (`gross_amount + ...`) 的口径差异,见 `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_finance_daily_summary.md` § 金额口径术语对照表

## 三、Neo 理解 vs 推荐方案对比

| 维度 | Neo 原方案("ABC 都做") | 推荐方案(主 + 副) |
|---|---|---|
| 信息完整性 | 3 处都有完整说明 | 1 处完整 + 3 处链接 |
| 首次落地工作量 | 大(写 3 份完整说明) | 小(写 1 份 + 3 个一行链接) |
| 后续维护(字段调整) | 大(改 3 处,易漂移) | 小(只改主源) |
| 跨仓库读者体验 | 任一文档自给自足 | 跨链接跳转(主流文档习惯) |
| 文档膨胀风险 | 高 | 低 |

**Neo 担心的"留痕"目的(任何看到这个字段的人都能查到完整定义)** 通过链接也能达到,且风险更小。

## 四、若 Neo 仍要"三处都写完整"

如果 Neo 出于"防链接失效"或"工程审计可读性"坚持要"三处都写完整",建议加一个保护:

- 三处都用**同一个 markdown 引用块**(footnote / blockquote 模板),通过文档生成脚本(可选)从主源生成
- 在每处下方标"如有调整请优先改 BD 手册主源,本处为副本"
- 这样仍然有一个主权威源,只是物理上有 3 个副本

## 五、与 Wave 验证的关系

- Wave 4(DWS / RLS 验证)走查 `dws_finance_daily_summary` 时,会自然校验这个口径定义,可顺带核对术语对照表是否在 BD 手册中
- 不需要额外开 Wave

## 六、最终建议

**强烈推荐"主 + 副"方案**(BD 手册写完整,其他三处加链接)。

如 Neo 拍板执行,建议:
1. 先写 BD 手册主源(15 分钟)
2. 再加三处链接(各 5 分钟)
3. 总工作量 < 1 小时
4. 全部归到 Wave 5(部署 / 文档收尾)统一执行,不阻塞 Wave 1-4

---

> 等 Neo 拍板"主 + 副"或"三处都写完整",再决定具体动手时机。