From 87a5e3b08e2941b3d398b30a2025cc7813370c65 Mon Sep 17 00:00:00 2001 From: Neo Date: Tue, 5 May 2026 18:43:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(audit):=20F1-5b=20MP-1=20=E5=82=A8?= =?UTF-8?q?=E5=80=BC=E5=8D=A1=E5=85=85=E5=80=BC=E5=AD=97=E6=AE=B5=E8=AF=AD?= =?UTF-8?q?=E4=B9=89=E5=A4=8D=E6=A0=B8=20(false=20alarm)=20(W1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 走查发现 board-finance "储值卡充值实收" 66000 vs ETL 直查 ~132000 2 倍差异,怀疑前后端字段错位。 复核结论:链路完全正确,无代码改动。 - 小程序 board-finance.ts L409 'recharge.actualIncome' ← 后端 actual_income - 后端 fdw_queries:2825 SELECT SUM(recharge_cash) AS actual_income - 用的是 recharge_cash(现金口径),非 recharge_total(全口径=cash+gift) DB 直查 site=2790685415443269 / 2026-04 月度: - recharge_cash = 66998 - recharge_gift = 66998 - recharge_total = 133996(= cash + gift,刚好 2 倍) 走查时 132000 = recharge_total(全口径),66000 = recharge_cash (现金实收),两者本就不同语义。recharge_cash 是"实收"应有的现金 口径(赠送非真实现金流入,业务上不算"实收"),后端字段使用正确。 端到端验证(weixin-devtools-mcp + DB): - sandbox=4-20: 小程序 actualIncome=66000(SQL stat_date<=4-20) - 与 DB 全月 SUM(recharge_cash) 66998 差额 998 = 4-21 之后被 sandbox 业务日上界裁剪(F1-5b T1/A1 收益,跨任务交叉验证) 留给 Wave B 的改进建议(非本次任务范围): - 小程序 helpKey 'rechargeActual' 文案补充"现金口径(不含赠送)" - DWS 视图列注释明确 cash/gift/total 三字段语义 审计: - docs/audit/changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md Co-Authored-By: Claude Opus 4.7 (1M context) --- ..._f1_5b_mp1_recharge_field_clarification.md | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/audit/changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md diff --git a/docs/audit/changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md b/docs/audit/changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md new file mode 100644 index 0000000..8e088d0 --- /dev/null +++ b/docs/audit/changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md @@ -0,0 +1,93 @@ +# 2026-05-05 · F1-5b MP-1 board-finance 储值充值字段复核(false alarm) + +> Wave 1 / F1-5b Wave A 第 6 项任务(详见 `docs/_overview/wave1-findings/F1-5b-tasks.md` §4.2) +> +> 工作量评估 M / 2-3h(实际 ~ 30min,纯复核,**无代码改动**)。 + +## 背景 + +Wave 1 走查发现小程序 board-finance(财务总览)"储值卡充值实收"卡片金额 = 66000,而某次 ETL 直查得到 ≈ 132000,怀疑前后端某处把 `recharge_cash` 写成了 `recharge_total`(差刚好 2 倍)。 + +## 复核流程 + +### Step 1 调研(Explore agent) + +链路分析: +- 小程序 `board-finance.wxml` 第 355 行"储值卡充值实收" → `recharge.actualIncome` +- `board-finance.ts` 第 409 行 `'recharge.actualIncome': rc.actualIncome ?? 0` +- 后端 `xcx_board.py` GET `/api/xcx/board/finance` → `FinanceRechargeResponse.actual_income` +- 后端 `board_service._build_recharge` → `fdw_queries.get_finance_recharge` +- SQL `apps/backend/app/services/fdw_queries.py:2825` `SELECT SUM(recharge_cash) AS actual_income FROM app.v_dws_finance_recharge_summary` + +字段使用的是 `recharge_cash`(现金口径),非 `recharge_total`(cash + gift 全口径)。 + +### Step 2 DB 直查复核 + +site=2790685415443269 / 2026-04 月度聚合: + +| 字段 | 值 | 语义 | +|------|---|------| +| `SUM(recharge_cash)` | **66998** | 现金口径(不含赠送) | +| `SUM(recharge_gift)` | **66998** | 赠送口径 | +| `SUM(recharge_total)` | **133996** | 全口径 = cash + gift | + +`recharge_total = recharge_cash + recharge_gift` 完全成立(差额 0.00)。 + +### Step 3 端到端验证 + +切 sandbox=2026-04-20,小程序 board-finance 实际显示: + +```json +{ + "recharge.actualIncome": 66000, // SUM(recharge_cash) where stat_date <= 04-20 + "recharge.firstCharge": 3000, + "recharge.renewCharge": 63000, + "recharge.consumed": 76154.84, + "recharge.cardBalance": 90143.26, + "recharge.allCardBalance": 103055.69 +} +``` + +差额 66998 - 66000 = 998 = 4-21 之后(被 sandbox 业务日上界裁剪)的 `recharge_cash` 累计。证明: +- 后端 SQL 字段用 `SUM(recharge_cash)`,正确 +- sandbox 上界裁剪生效(F1-5b T1/A1 收益) +- 前端 `actualIncome` 字段映射正确 + +## 结论 + +**字段链路完全正确,无需改代码**。 + +走查时的 2 倍差异 = "现金口径 vs 全口径" 的语义对比,而非 bug。具体数字对应关系: + +| 走查数字 | 实际口径 | 后端字段 | +|---------|---------|---------| +| 66000 | 现金充值实收 | `recharge_cash` | +| ~132000 | 现金 + 赠送(全口径) | `recharge_total` | + +`recharge_cash` 是"储值卡充值实收"应有的语义(赠送非真实现金流入,业务上不算"实收")。 + +## 留给 Wave B 的改进建议(非本任务范围) + +为避免后续走查再次混淆"实收 vs 全口径",可考虑: + +1. **小程序 helpKey 文案补充**:`board-finance.ts` 中 `onHelpTap` 的 `rechargeActual` 文案明确写"现金口径(不含赠送)" +2. **DWS 视图列注释**:在 `db/etl_feiqiu/schemas/dws.sql` 的 `dws_finance_recharge_summary` 字段注释中补 `recharge_cash`/`recharge_gift`/`recharge_total` 的明确语义 +3. **走查文档登记**:在 `docs/_overview/wave1-findings/` 字段对照表中加一条"现金 vs 全口径" + +以上仅为后续可选改进,与本任务无关,不在本审计范围内。 + +## 影响范围 + +无代码变更,无任何端影响。 + +## 测试 + +无新增测试。复核脚本(`_DEL/walkthrough_f1_5b/step_mp1_db_probe.py`)证明字段使用正确。 + +## 风险与回滚 + +无改动,无回滚需求。 + +## Co-Authored-By + +Claude Opus 4.7 (1M context)