# P8：小程序前端 — 看板模块 — miniapp-fe-boards

> 优先级：P8（依赖 P2 + P3 + P5-A）
> 预估工作量：大

---

## 需求（Requirements）

### 用户故事

1. 作为管理者，我在财务看板能看到多维度交叉筛选的财务数据、环比、AI 洞察。
2. 作为管理者，我在客户看板能按 8 个维度排序查看前 100 名客户。
3. 作为管理者，我在助教看板能按业绩/工资/客源储值/任务完成等维度排序查看助教。
4. 作为系统，看板数据需要缓存层以提升查询性能。

### 验收标准

- AC1：财务看板支持 2 组筛选交叉（区域 × 时间），选择非"全部区域"时预收资产板块消失
- AC2：财务看板环比数据正确计算
- AC3：财务看板 AI 洞察从缓存读取（应用 2 每日更新，JSON 格式：序号+标题+正文数组）
- AC4：客户看板 8 个维度筛选正确（最应召回/最大消费潜力/最高余额/最近充值/最高消费60天/最频繁60天/最近到店/最专一）
- AC5：客户看板"最专一"维度下类型筛选锁定为"不限"
- AC6：助教看板维度×项目×日期三重筛选交叉正确
- AC7：看板数据有缓存层，非每次实时查询 FDW

---

## 页面清单

### board-finance（财务看板）

- 筛选器：区域筛选 + 时间筛选（本月/上月/本周/上周/前3月/本季/上季/近6月；营业日以 08:00 为分割点，如"本月"= 当月1日 08:00 ~ 次月1日 08:00）
- 数据板块：收入结构、预收资产（条件隐藏）、支出汇总、平台结算
- 环比展示
- AI 智能洞察（应用 2 缓存结果，JSON 结构化输出：数组，每条含序号+标题+正文详情；UI 布局参考 `docs/h5_ui/` 财务看板 AI 智能洞察）
- "问问助手"入口 → chat.html

### board-customer（客户看板）

- 维度筛选（8 个维度，默认"最应召回"）
- 类型筛选（全部/🎱 中式/追分/斯诺克/🀄 麻将/棋牌/🎤 团建/K歌 + 台费包厢流水过滤）
- 筛选互斥规则："最专一"锁定类型为"不限"
- 客户列表（前 100 名）
- 每个客户卡片：昵称、爱心 icon、喜好标签、关键指标值
- 右下角 AI 按钮 → chat.html

### board-coach（助教看板）

- 维度筛选：定档业绩最高/最低、工资最高/最低、高客源储值额最高、任务完成最多
- 项目筛选：全部/🎱 中式/追分/斯诺克/🀄 麻将/棋牌/🎤 团建/K歌
- 日期维度筛选：本月/上月/本周/上周/前3月/本季/上季/近6月（营业日以 08:00 为分割点，如"本月"= 当月1日 08:00 ~ 次月1日 08:00）
- 助教列表
- 右下角 AI 按钮 → chat.html

---

## 后端 API 需求

| API | 说明 | 缓存 |
|-----|------|------|
| `GET /api/board/finance` | 财务看板数据（交叉筛选） | 是 |
| `GET /api/board/finance/ai-insight` | 财务 AI 洞察 | 是（应用2缓存） |
| `GET /api/board/customers` | 客户看板（维度+类型筛选） | 是 |
| `GET /api/board/coaches` | 助教看板（维度×项目×日期） | 是 |

### 财务看板数据字段映射（已校准，数据源：DWD-DOC 03-财务全景）

收入结构（settle_type=1，台桌结账）：

| 收入来源 | DWS 字段 | 占比 | 说明 |
|----------|----------|-----:|------|
| 台费 | `table_charge_money` | 56.6% | 按秒计时，台区单价固定 |
| 助教陪打 | `assistant_pd_money` | 30.6% | 按秒计时，单价按等级 |
| 商品 | `goods_money` | 10.1% | 酒水食品 |
| 助教超休 | `assistant_cx_money` | 0.9% | 按课时，190 元/课时 |
| 灯控电费 | `electricity_money` | 0% | 门店未启用，全为 0 |

> ⚠️ 消费金额口径：使用 `items_sum`（= tc + goods + pd + cx + electricity），不得使用 `consume_money`（三种历史口径混合）。

充值收入（settle_type=5）：从 `dws_finance_recharge_summary` 读取，充值退款（settle_type=7）需扣除。

支付渠道分布（settle_type=1）：
- 纯团购券 60.6%、纯线上支付 14.0%、纯储值卡 10.6%、线上+团购券 9.7%

### 客户看板金额口径说明

- "最高消费60天"：基于 `dws_member_consumption_summary` 中的消费汇总字段，底层应基于 `items_sum` 聚合
- "最高余额"：基于 `dws_member_consumption_summary` 中的余额字段（= 储值卡余额，独立于消费金额）
- "最近充值"：基于 `dwd_recharge_order`（settle_type=5）

### 缓存策略

- 看板数据缓存层：Redis 或内存缓存
- 缓存粒度：`site_id` + 筛选条件组合
- 缓存过期：ETL 数据更新后失效（约 1 小时）
- AI 洞察缓存：从 `biz.ai_cache` 读取（应用 2 每日更新，`cache_type = app2_finance`，`result_json` 为 JSON 数组：序号+标题+正文详情）

---

## 小程序前端开发强制规范

> 以下规范适用于本 SPEC 中所有小程序页面实现，具有强制约束力。

1. **原型图是唯一视觉真相**：`docs/h5_ui/pages/*.html` 中的结构、层次、元素、配色、间距、交互行为是小程序页面实现的唯一参考标准。任何偏离原型图的实现都需要明确的产品确认。
2. **WXML ≠ HTML**：严禁在小程序中使用 HTML 标签（div/span/p/a/img 等），必须使用小程序原生标签（view/text/image/navigator 等）。
3. **WXSS ≠ CSS**：使用 rpx 单位、仅支持有限选择器、无 DOM/BOM API、样式隔离机制不同。Tailwind CSS 类名必须手动转换为 WXSS。
4. **TDesign 优先**：凡 TDesign 组件库能覆盖的 UI 元素，必须使用 TDesign 组件；自定义实现仅限 TDesign 无法覆盖的场景。
5. **Power 文档优先**：实现前必须加载 `wechat-miniprogram` Power 的相关 steering 文件（`view-layer.md`、`tdesign.md`、`builtin-components.md`），确保语法和组件用法正确。
6. **项目踩坑指南必读**：实现前必须阅读 `docs/prd/MIGRATION-PLAYBOOK.md` 第六章，该文档是基于本项目实际转换经验的避坑手册，涵盖 WXML/WXSS 差异、事件系统、TDesign 用法、rpx 换算规则及新页面开发 Checklist。

---

## 任务清单

- [ ] T1：实现看板缓存层（Redis/内存，按 site_id + 筛选条件）
- [ ] T2：实现财务看板 API（交叉筛选 + 环比 + 预收资产条件隐藏）
- [ ] T3：实现客户看板 API（8 维度排序 + 类型筛选 + 互斥规则）
- [ ] T4：实现助教看板 API（维度×项目×日期三重筛选）
- [ ] T5：实现 board-finance 小程序页面
- [ ] T6：实现 board-customer 小程序页面
- [ ] T7：实现 board-coach 小程序页面
- [ ] T8：实现通用筛选器组件（时间/维度/项目）