feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

docs/miniprogram-dev/api-audit/board-finance.md

@@ -0,0 +1,352 @@
+# board-finance 页面数据来源排查
+
+> 排查日期：2026-03-18
+> 页面路径：pages/board-finance/board-finance
+> 排查人：Kiro AI
+> 状态：**全量内联 Mock，零 API 对接**
+
+## 概览
+
+| 分类 | 数量 | 说明 |
+|------|------|------|
+| Mock 数据（内联） | **120+ 个字段** | 全部财务指标写死在 `data` 对象中，无外部 mock 函数调用 |
+| 硬编码数据 | **19 个字段/配置** | 筛选选项、目录导航、指标解释、板块描述等 |
+| 已对接 API | **0 个接口** | 页面无任何 `request()` / `wx.request` 调用 |
+| 前端计算/派生 | **8 个字段** | UI 状态、滚动位置、配色等 |
+| 路由参数 | **0 个** | `onLoad` 未读取 `options` |
+| WXML 硬编码文案 | **3 处** | AI 洞察文案、平台服务费说明 |
+
+---
+
+## 一、Mock 数据（内联在 data 对象中）
+
+> 本页面 **不引用** `utils/mock-data.ts`（该文件虽定义了 `BoardFinanceData` 接口，但页面未 import）。
+> 所有 mock 数据直接写死在 `Page({ data: { ... } })` 中，文件头注释标注 `TODO: 联调时替换 mock 数据为真实 API 调用`。
+
+### 1.1 经营一览 `overview`
+
+| 字段 | 类型 | 当前 Mock 值 | 联调替换 API | 备注 |
+|------|------|-------------|-------------|------|
+| `overview.occurrence` | string | `¥823,456` | 财务看板-经营一览 | 发生额/正价 |
+| `overview.occurrenceCompare` | string | `12.5%` | 同上（环比） | |
+| `overview.discount` | string | `-¥113,336` | 同上 | 总优惠 |
+| `overview.discountCompare` | string | `3.2%` | 同上（环比） | |
+| `overview.discountRate` | string | `13.8%` | 同上 | 优惠占比 |
+| `overview.discountRateCompare` | string | `1.5%` | 同上（环比） | |
+| `overview.confirmedRevenue` | string | `¥710,120` | 同上 | 成交/确认收入 |
+| `overview.confirmedCompare` | string | `8.7%` | 同上（环比） | |
+| `overview.cashIn` | string | `¥698,500` | 同上 | 实收/现金流入 |
+| `overview.cashInCompare` | string | `5.3%` | 同上（环比） | |
+| `overview.cashOut` | string | `¥472,300` | 同上 | 现金支出 |
+| `overview.cashOutCompare` | string | `2.1%` | 同上（环比） | |
+| `overview.cashBalance` | string | `¥226,200` | 同上 | 现金结余 |
+| `overview.cashBalanceCompare` | string | `15.2%` | 同上（环比） | |
+| `overview.balanceRate` | string | `32.4%` | 同上 | 结余率 |
+| `overview.balanceRateCompare` | string | `3.8%` | 同上（环比） | |
+
+
+### 1.2 预收资产 `recharge`
+
+| 字段 | 类型 | 当前 Mock 值 | 联调替换 API | 备注 |
+|------|------|-------------|-------------|------|
+| `recharge.actualIncome` | string | `¥352,800` | 财务看板-预收资产 | 储值卡充值实收 |
+| `recharge.actualCompare` | string | `18.5%` | 同上（环比） | |
+| `recharge.firstCharge` | string | `¥188,500` | 同上 | 首充 |
+| `recharge.firstChargeCompare` | string | `12.3%` | 同上（环比） | |
+| `recharge.renewCharge` | string | `¥164,300` | 同上 | 续费 |
+| `recharge.renewChargeCompare` | string | `8.7%` | 同上（环比） | |
+| `recharge.consumed` | string | `¥238,200` | 同上 | 消耗 |
+| `recharge.consumedCompare` | string | `5.2%` | 同上（环比） | |
+| `recharge.cardBalance` | string | `¥642,600` | 同上 | 储值卡总余额 |
+| `recharge.cardBalanceCompare` | string | `11.4%` | 同上（环比） | |
+| `recharge.allCardBalance` | string | `¥586,500` | 同上 | 全类别会员卡余额合计 |
+| `recharge.allCardBalanceCompare` | string | `6.2%` | 同上（环比） | |
+
+#### 赠送卡明细 `recharge.giftRows`（3 行 × 7 字段 = 21 个值）
+
+| 行 | label | total | wine | table | coupon | 各字段均含 Compare |
+|----|-------|-------|------|-------|--------|-------------------|
+| 0 | 新增 | ¥108,600 | ¥43,200 | ¥54,100 | ¥11,300 | 9.8%/11.2%/8.5%/6.3% |
+| 1 | 消费 | ¥75,800 | ¥32,100 | ¥32,800 | ¥10,900 | 7.2%/8.1%/6.5%/5.8% |
+| 2 | 余额 | ¥243,900 | ¥118,500 | ¥109,200 | ¥16,200 | 4.5%/5.2%/3.8%/2.5% |
+
+> 联调 API：财务看板-预收资产-赠送卡统计
+
+### 1.3 应计收入确认 `revenue`
+
+#### 收入结构 `revenue.structureRows`（9 行 × 5~6 字段）
+
+| id | name | desc | amount | discount | booked | bookedCompare | isSub |
+|----|------|------|--------|----------|--------|---------------|-------|
+| `table` | 开台与包厢 | - | ¥358,600 | -¥45,200 | ¥313,400 | 9.2% | false |
+| `area-a` | A区 | - | ¥118,200 | -¥11,600 | ¥106,600 | 12.1% | true |
+| `area-b` | B区 | - | ¥95,800 | -¥11,200 | ¥84,600 | 8.5% | true |
+| `area-c` | C区 | - | ¥72,600 | -¥11,100 | ¥61,500 | 6.3% | true |
+| `team` | 团建区 | - | ¥48,200 | -¥6,800 | ¥41,400 | 5.8% | true |
+| `mahjong` | 麻将区 | - | ¥23,800 | -¥4,500 | ¥19,300 | -2.1% | true |
+| `coach-basic` | 助教 | 基础课 | ¥232,500 | - | ¥232,500 | 15.3% | false |
+| `coach-incentive` | 助教 | 激励课 | ¥112,800 | - | ¥112,800 | 8.2% | false |
+| `food` | 食品酒水 | - | ¥119,556 | -¥68,136 | ¥51,420 | 6.5% | false |
+
+> 联调 API：财务看板-应计收入-收入结构
+
+#### 项目正价 `revenue.priceItems`（4 项）
+
+| name | value | compare |
+|------|-------|---------|
+| 开台消费 | ¥358,600 | 9.2% |
+| 酒水商品 | ¥186,420 | 18.5% |
+| 包厢费用 | ¥165,636 | 12.1% |
+| 助教服务 | ¥112,800 | 15.3% |
+
+#### 发生额合计
+
+| 字段 | 值 |
+|------|-----|
+| `revenue.totalOccurrence` | ¥823,456 |
+| `revenue.totalOccurrenceCompare` | 12.5% |
+
+#### 优惠扣减 `revenue.discountItems`（4 项）
+
+| name | desc | value | compare |
+|------|------|-------|---------|
+| 团购优惠 | - | -¥56,200 | 5.2% |
+| 手动调整 + 大客户优惠 | - | -¥34,800 | 3.1% |
+| 赠送卡抵扣 | 台桌卡+酒水卡+抵用券 | -¥22,336 | 8.6% |
+| 其他优惠 | 免单+抹零 | -¥0 | （空） |
+
+#### 成交收入合计
+
+| 字段 | 值 |
+|------|-----|
+| `revenue.confirmedTotal` | ¥710,120 |
+| `revenue.confirmedTotalCompare` | 8.7% |
+
+#### 收款渠道 `revenue.channelItems`（3 项）
+
+| name | desc | value | compare |
+|------|------|-------|---------|
+| 储值卡结算冲销 | - | ¥238,200 | 11.2% |
+| 现金/线上支付 | - | ¥345,800 | 7.8% |
+| 团购核销确认收入 | 团购成交价 | ¥126,120 | 5.3% |
+
+> 联调 API：财务看板-应计收入-损益链
+
+### 1.4 现金流入 `cashflow`
+
+#### 消费收入 `cashflow.consumeItems`（3 项）
+
+| name | desc | value | compare | isDown |
+|------|------|-------|---------|--------|
+| 纸币现金 | 柜台现金收款 | ¥85,600 | 12.3% | true |
+| 线上收款 | 微信/支付宝/刷卡 已扣除平台服务费 | ¥260,200 | 8.5% | false |
+| 团购平台 | 美团/抖音回款 已扣除平台服务费 | ¥126,120 | 15.2% | false |
+
+#### 充值收入 `cashflow.rechargeItems`（1 项）
+
+| name | desc | value | compare |
+|------|------|-------|---------|
+| 会员充值到账 | 首充/续费实收 | ¥352,800 | 18.5% |
+
+#### 合计
+
+| 字段 | 值 |
+|------|-----|
+| `cashflow.total` | ¥824,720 |
+| `cashflow.totalCompare` | 10.2% |
+
+> 联调 API：财务看板-现金流入
+
+### 1.5 现金流出 `expense`
+
+#### 进货与运营 `expense.operationItems`（3 项）
+
+| name | value | compare | isDown |
+|------|-------|---------|--------|
+| 食品饮料 | ¥108,200 | 4.5% | false |
+| 耗材 | ¥21,850 | 2.1% | true |
+| 报销 | ¥10,920 | 6.8% | false |
+
+#### 固定支出 `expense.fixedItems`（4 项）
+
+| name | value | compare | isFlat |
+|------|-------|---------|--------|
+| 房租 | ¥125,000 | 持平 | true |
+| 水电 | ¥24,200 | 3.2% | false |
+| 物业 | ¥11,500 | 持平 | true |
+| 人员工资 | ¥112,000 | 持平 | true |
+
+#### 助教薪资 `expense.coachItems`（4 项）
+
+| name | value | compare | isDown |
+|------|-------|---------|--------|
+| 基础课分成 | ¥116,250 | 8.2% | false |
+| 激励课分成 | ¥23,840 | 5.6% | false |
+| 充值提成 | ¥12,640 | 12.3% | false |
+| 额外奖金 | ¥11,500 | 3.1% | true |
+
+#### 平台服务费 `expense.platformItems`（3 项）
+
+| name | value | compare |
+|------|-------|---------|
+| 汇来米 | ¥10,680 | 1.5% |
+| 美团 | ¥11,240 | 2.8% |
+| 抖音 | ¥10,580 | 3.5% |
+
+#### 合计
+
+| 字段 | 值 |
+|------|-----|
+| `expense.total` | ¥600,400 |
+| `expense.totalCompare` | 2.1% |
+
+> 联调 API：财务看板-现金流出
+
+### 1.6 助教分析 `coachAnalysis`
+
+#### 基础课 `coachAnalysis.basic`
+
+| 字段 | 值 | 环比 |
+|------|-----|------|
+| totalPay | ¥232,500 | 15.3% |
+| totalShare | ¥116,250 | 15.3% |
+| avgHourly | ¥25/h | 4.2% |
+
+明细行（4 行 × 7 字段）：
+
+| level | pay | payCompare | share | shareCompare | hourly | hourlyCompare | 特殊标记 |
+|-------|-----|------------|-------|--------------|--------|---------------|----------|
+| 初级 | ¥68,600 | 12.5% | ¥34,300 | 12.5% | ¥20/h | 持平 | hourlyFlat |
+| 中级 | ¥82,400 | 18.2% | ¥41,200 | 18.2% | ¥25/h | 8.7% | |
+| 高级 | ¥57,800 | 14.6% | ¥28,900 | 14.6% | ¥30/h | 持平 | hourlyFlat |
+| 星级 | ¥23,700 | 3.2% ↓ | ¥11,850 | 3.2% ↓ | ¥35/h | 持平 | payDown, shareDown, hourlyFlat |
+
+#### 激励课 `coachAnalysis.incentive`
+
+| 字段 | 值 | 环比 |
+|------|-----|------|
+| totalPay | ¥112,800 | 8.2% |
+| totalShare | ¥33,840 | 8.2% |
+| avgHourly | ¥15/h | 2.1% |
+
+明细行（4 行 × 7 字段）：
+
+| level | pay | payCompare | share | shareCompare | hourly | hourlyCompare | 特殊标记 |
+|-------|-----|------------|-------|--------------|--------|---------------|----------|
+| 初级 | ¥32,400 | 6.8% | ¥9,720 | 6.8% | ¥12/h | 持平 | hourlyFlat |
+| 中级 | ¥38,600 | 10.5% | ¥11,580 | 10.5% | ¥15/h | 5.2% | |
+| 高级 | ¥28,200 | 7.3% | ¥8,460 | 7.3% | ¥18/h | 持平 | hourlyFlat |
+| 星级 | ¥13,600 | 2.1% ↓ | ¥4,080 | 2.1% ↓ | ¥22/h | 持平 | payDown, shareDown, hourlyFlat |
+
+> 联调 API：财务看板-助教分析
+
+---
+
+## 二、硬编码数据
+
+| 字段 | 当前值 | 应改为 | 风险 | 所在位置 |
+|------|--------|--------|------|----------|
+| `timeOptions` | 8 个固定选项（本月/上月/本周/上周/前3月/本季/上季/近6月） | 前端常量或后端配置 | **低** | data.timeOptions |
+| `areaOptions` | 7 个固定选项（全部/大厅/A区/B区/C区/麻将房/团建房） | **API 获取门店区域列表** | **高** | data.areaOptions |
+| `tocItems` | 6 个目录项（emoji + title + sectionId） | 前端常量（合理） | **低** | data.tocItems |
+| `tipContents` | 13 个指标解释（title + content） | 前端常量或后端配置 | **低** | 模块级常量 |
+| `_sectionDescs` | 6 条板块描述文案 | 前端常量（合理） | **低** | 实例属性 |
+| `selectedTime` | `'month'` | 默认值合理，但需与 API 参数对齐 | **中** | data.selectedTime |
+| `selectedTimeText` | `'本月'` | 同上 | **低** | data.selectedTimeText |
+| `selectedArea` | `'all'` | 默认值合理 | **低** | data.selectedArea |
+| `selectedAreaText` | `'全部区域'` | 同上 | **低** | data.selectedAreaText |
+| `compareEnabled` | `false` | 默认值合理 | **低** | data.compareEnabled |
+| `pageState` | `'normal'` | 联调后应初始为 `'loading'` | **高** | data.pageState |
+| Tab 导航 `data-tab` | `finance/customer/coach` 三个固定值 | 前端常量（合理） | **低** | WXML |
+| 导航路径 | `/pages/board-customer/board-customer` 等 | 前端常量（合理） | **低** | onTabChange |
+| `onPullDownRefresh` | `setTimeout 500ms` 后停止 | 联调后应触发数据刷新 | **高** | onPullDownRefresh |
+| AI 洞察文案 | 3 行硬编码文案（优惠率Top/差异最大/建议关注） | **API 返回或 AI 生成** | **高** | WXML 内联 |
+| 平台服务费说明 | "服务费在流水流入时，平台已经扣除。不产生支出流水。" | 前端常量（合理） | **低** | WXML 内联 |
+| 板块头描述文案 | 各板块 desc（如"快速了解收入与现金流的整体健康度"） | 前端常量（合理） | **低** | WXML 内联 |
+| `filter-dropdown label` | `"本月"` / `"全部区域"` | 应绑定 `selectedTimeText` / `selectedAreaText` | **中** | WXML 属性 |
+| 激励课表格 | WXML 中只渲染了合计行，缺少明细行 `wx:for` | 需补齐明细行渲染 | **中** | WXML 板块6 |
+
+---
+
+## 三、已对接 API
+
+**无。** 页面当前零 API 调用。
+
+唯一的 `import` 是 `getRandomAiColor`（纯前端工具函数，与数据无关）。
+
+文件头注释明确标注：
+```
+// TODO: 联调时替换 mock 数据为真实 API 调用
+```
+
+`onShow` 中也有注释：
+```
+// TODO: 联调时在此刷新看板数据
+```
+
+---
+
+## 四、前端计算/派生数据
+
+| 字段 | 计算逻辑 | 说明 |
+|------|----------|------|
+| `aiColorClass` | `getRandomAiColor().className` | onLoad 时随机选取 AI 配色 |
+| `stickyHeaderVisible` | 滚动方向 + scrollTop 阈值判断 | 下滑 >80px 显示，上滑隐藏 |
+| `stickyHeaderEmoji` / `Title` / `Desc` | 从 `tocItems[currentIdx]` + `_sectionDescs[idx]` 映射 | 吸顶头内容 |
+| `currentSectionIndex` | 滚动位置与 `_sectionTops` 数组比较 | 当前所在板块索引 |
+| `_sectionTops` | `wx.createSelectorQuery` 获取各 section 的 top | 缓存的 DOM 位置 |
+| `selectedTimeText` | 从 `timeOptions` 中按 `value` 查找 `text` | 筛选文案 |
+| `selectedAreaText` | 从 `areaOptions` 中按 `value` 查找 `text` | 筛选文案 |
+| `tocVisible` / `tipVisible` | 用户交互切换 | UI 状态 |
+
+---
+
+## 五、路由参数
+
+**无。** `onLoad()` 未读取 `options` 参数。
+
+---
+
+## 六、WXML 硬编码文案（业务数据）
+
+| 位置 | 内容 | 类型 | 处理建议 |
+|------|------|------|----------|
+| AI 洞察区域 第1行 | `优惠率Top：团购(5.2%) / 大客户(3.1%) / 赠送卡(2.5%)` | **业务数据** | 应从 API 获取 |
+| AI 洞察区域 第2行 | `差异最大：酒水(+18%) / 台桌(-5%) / 包厢(+12%)` | **业务数据** | 应从 API 获取 |
+| AI 洞察区域 第3行 | `建议关注：充值高但消耗低，会员活跃度需提升` | **业务数据** | 应从 API/AI 生成 |
+| 平台服务费说明 | `服务费在流水流入时，平台已经扣除。不产生支出流水。` | UI 说明文案 | 可保留为前端常量 |
+
+---
+
+## 七、联调 TODO
+
+### 高优先级（P0 — 阻塞联调）
+
+- [ ] **设计并对接财务看板主 API**：一次请求返回全部板块数据（overview / recharge / revenue / cashflow / expense / coachAnalysis），或按板块拆分为 6 个接口
+- [ ] **替换 `data` 中全部内联 mock**：将 120+ 个字段从 API 响应填充
+- [ ] **`pageState` 初始值改为 `'loading'`**：onLoad/onShow 发起请求，成功→`'normal'`，失败→`'error'`，空数据→`'empty'`
+- [ ] **`onPullDownRefresh` 对接数据刷新**：替换当前的 `setTimeout 500ms` 空操作
+- [ ] **`areaOptions` 从 API 获取**：当前硬编码的区域列表（大厅/A区/B区/C区/麻将房/团建房）应从门店配置接口动态获取
+
+### 中优先级（P1 — 影响数据准确性）
+
+- [ ] **AI 洞察文案从 API 获取**：当前 WXML 中 3 行硬编码的洞察文案应由后端计算或 AI 生成
+- [ ] **`filter-dropdown` 的 `label` 属性绑定动态值**：当前硬编码 `"本月"` / `"全部区域"`，应改为 `"{{selectedTimeText}}"` / `"{{selectedAreaText}}"`
+- [ ] **激励课明细行补齐**：WXML 板块6 激励课部分只渲染了合计行，缺少 `wx:for="{{coachAnalysis.incentive.rows}}"` 的明细行循环
+- [ ] **时间/区域筛选参数传递给 API**：`onTimeChange` / `onAreaChange` 变更后需重新请求数据
+- [ ] **环比开关联动 API**：`toggleCompare` 切换后，若环比数据需要额外请求，需对接
+
+### 低优先级（P2 — 优化项）
+
+- [ ] **`tipContents` 指标解释考虑后端配置化**：当前 13 条解释硬编码在前端，如需动态更新可改为接口
+- [ ] **`timeOptions` 考虑后端配置化**：如需支持自定义时间范围
+- [ ] **加载态优化**：当前使用 toast 浮层，可考虑骨架屏
+- [ ] **错误态重试**：`onRetry` 当前只是重置 `pageState`，需对接真实重新请求
+
+### 数据口径注意事项（参考 DWD-DOC 标杆文档）
+
+- [ ] **助教费用拆分**：API 返回的助教数据需区分 `assistant_pd_money`（陪打/基础课）和 `assistant_cx_money`（超休/激励课），禁止使用笼统的 `service_fee`
+- [ ] **储值卡字段命名**：API 应使用 `balance_pay`（总额）、`recharge_card_pay`（现金充值卡）、`gift_card_pay`（赠送卡），与 DWS 层一致
+- [ ] **支付渠道恒等式**：`balance_amount = recharge_card_amount + gift_card_amount`，前端展示需校验
+- [ ] **折扣互斥**：`discount_manual`（大客户优惠）与 `discount_other` 互斥，两者之和 = `adjust_amount`
+- [ ] **consume_money 禁止直接用于计算**：前端展示的发生额应使用 `items_sum` 口径