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)