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

docs/h5_ui/interactions/board-customer.md

@@ -0,0 +1,90 @@
+# 页面名：board-customer（客户看板）
+
+> PRD 参考：P8 `docs/prd/specs/P8-miniapp-fe-boards.md`；`apps/miniprogram/doc/prd.md` 第九节 9.2
+> 已实现：否
+
+## 页面说明
+按 8 个维度查看前 100 名客户。支持维度切换和项目筛选，不同维度下卡片结构和展示内容不同。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| selectedType | string | "最应召回" | 维度/类型筛选（8 个维度） |
+| selectedProject | string | "全部" | 项目筛选 |
+| customers | array | [] | 客户列表（前 100 名） |
+| typeDropdownVisible | boolean | false | 维度筛选下拉展开 |
+| projectDropdownVisible | boolean | false | 项目筛选下拉展开 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/board/customers | loading→false |
+| 点击维度筛选 | 无 | 展开维度下拉，关闭其他 | typeDropdownVisible=true |
+| 选择维度 | 下拉展开 | 切换对应 dim-container 显隐，重新请求数据 | selectedType 更新 |
+| 点击项目筛选 | 无 | 展开项目下拉，关闭其他 | projectDropdownVisible=true |
+| 选择项目 | 下拉展开 | 重新请求数据 | selectedProject 更新 |
+| 点击客户卡片 | 无 | navigateTo customer-detail | — |
+| 切换看板 Tab | 顶部 Tab 栏 | navigateTo board-finance / board-coach | — |
+| 滚动页面 | 持续 | 下滑隐藏筛选栏，上滑显示 | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 筛选器选项（忠于原型 HTML）
+
+### 维度/类型筛选（8 个）
+1. 最应召回 — WBI（加权流失指数），综合到店间隔、消费频率、余额等
+2. 最大消费潜力 — 综合权重（频率×客单×余额×活跃度）
+3. 最高余额
+4. 最近充值
+5. 最近到店
+6. 最高消费 近60天
+7. 最频繁 近60天
+8. 最专一 近60天 — 亲密度最大值（该客户对某助教的服务集中度）
+
+### 项目筛选
+全部 / 中🎱 / 斯诺克 / 麻将 / 团建
+
+## 维度切换 → 卡片结构映射（忠于原型 HTML）
+
+切换维度时，通过 `selectType(value)` 函数切换对应的 `dim-container` 显隐。每个维度的卡片结构不同：
+
+| 维度 | container id | 卡片特有内容 |
+|------|-------------|-------------|
+| 最应召回 | `dim-recall` | 理想天数 / 已过天数 / 超期天数（红色标签）+ 30天到店次数 / 余额 / 召回指数 |
+| 最大消费潜力 | `dim-potential` | 频率标签（高频/中频）+ 客单标签 + 余额标签 + 4列网格：30天消费/月均到店/余额/次均消费 |
+| 最高余额 | `dim-balance` | 最近到店/理想天数 + 3列网格：余额（大字橙色）/月均消耗/可用月数 |
+| 最近充值 | `dim-recharge` | 最近到店/理想天数 + 4列网格：最后充值/充值金额/60天充值次数/当前余额 |
+| 最近到店 | `dim-recent` | 到店天数 + 到店频率 + 余额 |
+| 最高消费 近60天 | `dim-spend60` | 高消费标签 + 3列网格：60天消费/次均消费/到店次数 |
+| 最频繁 近60天 | `dim-freq60` | 频率标签 + 到店次数/消费金额/次均消费 |
+| 最专一 近60天 | `dim-loyal` | 专一度指标 + 服务助教分布 |
+
+### 所有卡片共有元素
+- 客户昵称 + 爱心 emoji（💖/🧡/💛/💙）+ 喜好标签（🎱/斯/🀅/🎤）
+- 底部助教行：助教名 + 关系 emoji + 跟/弃 badge
+- 助教标记样式：有助教跟进时显示助教名+关系状态
+
+## 筛选栏滚动行为
+- 下滑时筛选栏隐藏，上滑时重新显示
+- 由 `initFilterBarScrollBehavior()` 实现
+
+## 助教身份隐式过滤（PRD 补充）
+- 助教角色登录时，后台默认只显示该助教 14 天内服务过的客户
+- 店长角色无此限制，可查看全部客户
+
+## 页面状态枚举
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/board/customers` | GET | 客户看板（维度+项目筛选） |
+
+## 页面导航
+- 来源：board-finance / board-coach（看板 Tab 切换）
+- 去向：customer-detail / chat
+
+## 全局组件
+- 底部 TabBar（看板 active）
+- AI 悬浮按钮（右下角）
+- 看板顶部 Tab 栏（财务 / 客户 active / 助教）