微信小程序页面迁移校验之前 P5任务处理之前

docs/h5_ui/interactions/board-finance.md

@@ -0,0 +1,115 @@
+# 页面名：board-finance（财务看板）
+
+> PRD 参考：P8 `docs/prd/specs/P8-miniapp-fe-boards.md`；`apps/miniprogram/doc/prd.md` 第九节 9.1
+> 已实现：否
+
+## 页面说明
+看板 Tab 的默认页面。展示多维度交叉筛选的财务数据，含环比开关、目录导航、吸顶板块头、指标解释弹窗。顶部有时间和区域两组筛选器。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| selectedTime | string | "本月" | 时间筛选 |
+| selectedArea | string | "全部区域" | 区域筛选 |
+| compareEnabled | boolean | false | 环比对比开关 |
+| timeDropdownVisible | boolean | false | 时间筛选下拉展开 |
+| areaDropdownVisible | boolean | false | 区域筛选下拉展开 |
+| tocVisible | boolean | false | 目录导航面板展开 |
+| tipVisible | boolean | false | 指标解释弹窗显示 |
+| tipType | string | "" | 当前显示的指标解释类型 |
+| currentSection | number | 0 | 当前可视板块索引（用于吸顶和目录高亮） |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/board/finance | loading→false |
+| 点击时间筛选 | 无 | 展开时间下拉面板，关闭其他面板 | timeDropdownVisible=true |
+| 选择时间选项 | 下拉展开 | 重新请求数据，关闭下拉 | selectedTime 更新 |
+| 点击区域筛选 | 无 | 展开区域下拉面板，关闭其他面板 | areaDropdownVisible=true |
+| 选择区域选项 | 下拉展开 | 重新请求数据，关闭下拉 | selectedArea 更新 |
+| 切换环比开关 | 无 | 切换所有 `[data-compare]` 元素显隐 | compareEnabled=!compareEnabled |
+| 点击目录按钮 | 无 | 展开/关闭目录导航面板 | tocVisible=!tocVisible |
+| 点击目录项 | tocVisible=true | 滚动到对应板块，关闭目录 | currentSection 更新 |
+| 点击指标"?"图标 | 无 | 底部弹出指标解释弹窗+遮罩 | tipVisible=true |
+| 点击遮罩/关闭 | tipVisible=true | 关闭指标解释弹窗 | tipVisible=false |
+| 滚动页面 | 持续 | 检测当前可视板块 → 更新吸顶头+目录高亮；下滑隐藏筛选栏，上滑显示 | currentSection 更新 |
+| 切换看板 Tab | 顶部 Tab 栏 | navigateTo board-customer / board-coach | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 筛选器选项（忠于原型 HTML）
+
+### 时间筛选
+本月 / 上月 / 本周 / 上周 / 前3个月 不含本月 / 本季度 / 上季度 / 最近6个月不含本月
+
+### 区域筛选
+全部区域 / 大厅（含 A区/B区/C区）/ 麻将房 / 团建房
+
+### 筛选联动规则
+- 选择非"全部区域"时，预收资产板块隐藏
+- 营业日以 08:00 为分割点
+
+## 环比开关
+- 滑块开关样式：44×24px，默认灰色 `#dcdcdc`，激活后蓝色 `#0052d9`
+- 控制所有 `[data-compare]` 元素的显隐
+- 环比数据：上升绿色↑、下降红色↓
+
+## 目录导航（6 个板块）
+| 序号 | 图标 | 板块名 | section id |
+|------|------|--------|------------|
+| 1 | 📈 | 经营一览 | section-overview |
+| 2 | 💳 | 预收资产 | section-recharge |
+| 3 | 💰 | 【记账】应计收入确认 | section-revenue |
+| 4 | 🧾 | 【现金流水】流入 | section-cashflow |
+| 5 | 📤 | 【现金流水】流出 | section-expense |
+| 6 | 🎱 | 助教分析 | section-coach |
+
+## 吸顶板块头
+- 滚动时检测当前可视板块，在顶部显示对应板块标题
+- 由 `updateStickyHeader()` + `getCurrentSection()` + `initSectionScrollBehavior()` 实现
+
+## 筛选栏滚动行为
+- 下滑时筛选栏隐藏（向上收起）
+- 上滑时筛选栏重新显示
+- 由 `initFilterBarScrollBehavior()` 实现
+
+## 指标解释弹窗
+- 底部弹出式弹窗 + 半透明遮罩
+- 点击指标旁的"?"图标触发
+- 展示对应指标的计算口径和说明
+
+## 数据板块
+1. 经营一览（副标题：快速了解收入与现金流的整体健康度）
+2. 预收资产（仅"全部区域"时显示）
+3. 【记账】应计收入确认
+4. 【现金流水】流入
+5. 【现金流水】流出
+6. 助教分析
+
+## AI 智能洞察（PRD 补充）
+- 来源：AI 应用 2，`cache_type=app2_finance`
+- 数据格式：JSON 数组，每条含洞察标题+内容
+- 缓存策略：Redis / 内存缓存，key = `site_id` + 筛选条件（时间+区域），ETL 更新后失效，约 1 小时刷新
+- 展示位置：经营一览板块底部或独立洞察卡片区域
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 完整财务数据 + 环比 | 有数据 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/board/finance` | GET | 财务看板数据（交叉筛选） |
+
+## 页面导航
+- 来源：TabBar 切换 / login（approved，首页设置为看板）
+- 去向：board-customer / board-coach / chat
+
+## 全局组件
+- 底部 TabBar（看板 active）
+- AI 悬浮按钮
+- 看板顶部 Tab 栏（财务 active / 客户 / 助教）— sticky 定位