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
4.8 KiB
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.mdDWD 规则 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 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
- 在文档顶部加一段"术语对照"小节:
本文涉及的金额术语 (
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(可选)
- 在 § 金额字段段落加一句:
客单价分子 (
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 拍板执行,建议:
- 先写 BD 手册主源(15 分钟)
- 再加三处链接(各 5 分钟)
- 总工作量 < 1 小时
- 全部归到 Wave 5(部署 / 文档收尾)统一执行,不阻塞 Wave 1-4
等 Neo 拍板"主 + 副"或"三处都写完整",再决定具体动手时机。