Neo
509cf43284
建立项目级标杆文档 docs/_overview/ 作为产品全景索引, 解决"PRD 零碎、文档膨胀、跨子系统调研无入口"的问题。 主要内容: - 00-index 总索引 + 维护协议 + 与 CLAUDE.md 关系 - 01-product-overview 产品全景脑图(6 角色 / 6 子系统 / 数据流 / 7 业务概念 / 8+1 AI 矩阵 / 22 术语) - 02a-miniprogram-page-matrix 小程序 21 页业务指纹 - 02b-adminweb-page-matrix admin-web 19 路由业务指纹 - 03-test-spec 测试规范 (L1-L5 分层 + 走查模板 + 75-95 case 估算) - 04-doc-conflicts 39 条冲突索引(P0×8 / P1×13 / P2×13 + 5 子项) - 04a/b/c-conflicts-*-detail 业务故事卡(7 字段:关联/逻辑/影响/选项/判定) - 05-orphan-pages-cleanup admin-web 6 孤儿页面处置(1 归档 + 4 保留) - WAVES-MASTER-PLAN.md 全 Wave 主计划(0-5,共 22-32 工作日) - WAVE-1-KICKOFF.md Wave 1 实施 kickoff - GLOBAL-DECISION-DASHBOARD.md 全局决策仪表板 反馈调研产物: - 04a-feedback/ P0 两轮反馈(8+8 项决策 + D-1/2/3 + F-1/2 子代理产出) - 04b-feedback/ P1 两轮反馈(13+1+5 项 + E-1/2/3/4 + G-1/2 子代理产出) - 04c-feedback/ P2 反馈(13 项 + 5 子项 + H-1/2/3 子代理产出) - NEO-DECISIONS-LOG 累积决策记录 关键追加发现 8 处 D Bug(原蓝本 0): - P0-3 看板沙箱接入(Wave 1 W1-T1) - P0-5 致命 1 (4 处 fdw_etl 残留, 已修 commit17f045a) - P0-5 致命 2 (JWT aud 缺失, 已修 commit17f045a) - P0-6 clearAllTasks 守卫 (Wave 3) - P0-8 DBViewer 黑名单漏 (已修 commit17f045a) - P1-3 task-detail 跳转传 task_id 而非 customer_id - P2-7 board-finance 隐式 null - 2 个独立 Bug (page_context.created_at + ClueCategory 字典) 参考: docs/_overview/00-index.md
91 lines
4.8 KiB
Markdown
91 lines
4.8 KiB
Markdown
# 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 拍板"主 + 副"或"三处都写完整",再决定具体动手时机。
|