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

docs/h5_ui/interactions/apply.md

@@ -0,0 +1,60 @@
+# 页面名：apply（账号申请页）
+
+> PRD 参考：`apps/miniprogram/doc/prd.md` 第七节 7.2；P3 认证系统
+> 已实现：是（`apps/miniprogram/miniprogram/pages/apply/`）
+
+## 页面说明
+新用户提交入驻申请。顶部整合欢迎信息与审核流程步骤条，下方为结构化表单。
+
+## 页面结构
+1. 顶部蓝色卡片：欢迎语 + 四步审核流程（提交申请 → 等待审核 → 审核通过 → 开始使用）
+2. 表单区域：5 个独立文本输入字段
+3. 底部固定提交按钮
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 必填 | 说明 |
+|--------|------|--------|------|------|
+| siteId | string | "" | 是 | 球房ID |
+| role | string | "" | 是 | 申请身份（如：助教、店长等） |
+| phone | string | "" | 是 | 手机号 |
+| staffNo | string | "" | 否 | 编号（选填） |
+| nickname | string | "" | 是 | 昵称 |
+| loading | boolean | false | — | 提交请求中 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 填写表单字段 | 无 | 更新对应状态变量；清除该字段错误状态 | 字段值更新 |
+| 点击"提交申请" | 表单校验通过 | POST /api/xcx-auth/apply | loading=true |
+| 点击"提交申请" | 表单校验失败 | 必填空字段高亮红框 + 下方红色提示文字，滚动到第一个错误字段 | 错误态 |
+| 提交成功 | API 返回 | 跳转 reviewing 页面 | redirectTo reviewing |
+| 提交失败 | API 报错 | Toast 提示错误信息 | loading=false |
+
+## 表单校验规则
+| 字段 | 规则 | 错误提示 |
+|------|------|----------|
+| siteId | 必填 | 请输入球房ID |
+| role | 必填 | 请输入申请身份 |
+| phone | 必填 | 请输入手机号 |
+| staffNo | 选填，无校验 | — |
+| nickname | 必填 | 请输入昵称 |
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 默认态 | 空表单，提交按钮可用 | 初始 |
+| 校验错误态 | 必填空字段红色边框 + 下方红色提示文字 | 校验失败 |
+| 加载中 | 提交按钮 loading | loading=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `/api/xcx-auth/apply` | POST | 提交入驻申请 |
+
+## 页面导航
+- 来源：login（status=new）
+- 去向：reviewing（提交成功）
+
+## 全局组件
+- 无底部 TabBar
+- 无 AI 悬浮按钮

docs/h5_ui/interactions/board-coach.md

@@ -0,0 +1,104 @@
+# 页面名：board-coach（助教看板）
+
+> PRD 参考：P8 `docs/prd/specs/P8-miniapp-fe-boards.md`；`apps/miniprogram/doc/prd.md` 第九节 9.3
+> 已实现：否
+
+## 页面说明
+按排序×技能×时间三重筛选查看助教排名列表。不同排序维度下卡片结构和突出数据不同。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| selectedSort | string | "定档业绩最高" | 排序筛选 |
+| selectedSkill | string | "不限" | 技能筛选 |
+| selectedTime | string | "本月" | 时间筛选 |
+| sortDropdownVisible | boolean | false | 排序筛选下拉展开 |
+| skillDropdownVisible | boolean | false | 技能筛选下拉展开 |
+| timeDropdownVisible | boolean | false | 时间筛选下拉展开 |
+| coaches | array | [] | 助教列表 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/board/coaches | loading→false |
+| 点击排序筛选 | 无 | 展开排序下拉，关闭其他 | sortDropdownVisible=true |
+| 选择排序 | 下拉展开 | 切换对应 dim-container 显隐，重新请求数据 | selectedSort 更新 |
+| 点击技能筛选 | 无 | 展开技能下拉，关闭其他 | skillDropdownVisible=true |
+| 选择技能 | 下拉展开 | 重新请求数据 | selectedSkill 更新 |
+| 点击时间筛选 | 无 | 展开时间下拉，关闭其他 | timeDropdownVisible=true |
+| 选择时间 | 下拉展开 | 重新请求数据 | selectedTime 更新 |
+| 点击助教卡片 | 无 | navigateTo coach-detail | — |
+| 切换看板 Tab | 顶部 Tab 栏 | navigateTo board-finance / board-customer | — |
+| 滚动页面 | 持续 | 下滑隐藏筛选栏，上滑显示 | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 筛选器选项（忠于原型 HTML）
+
+### 排序筛选（6 个）
+1. 定档业绩最高
+2. 定档业绩最低
+3. 工资最高
+4. 工资最低
+5. 客源储值最高
+6. 任务完成最多
+
+### 技能筛选
+不限 / 🎱 / 斯 / 🀄 / 🎤
+
+### 时间筛选
+本月 / 本季度 / 上月 / 前3个月（不含本月）/ 上季度 / 最近6个月（不含本月，不支持客源储值最高）
+
+## 排序切换 → 卡片结构映射（忠于原型 HTML）
+
+切换排序时，通过 `selectSort(value)` 函数切换对应的 `dim-container` 显隐。每种排序的卡片右侧突出数据不同：
+
+| 排序 | container id | 卡片右侧突出数据 |
+|------|-------------|-----------------|
+| 定档业绩最高/最低 | `dim-perf` | 定档 Xh + 折前 Xh + 距升档 Xh（或 ✅ 已达标） |
+| 工资最高/最低 | `dim-salary` | 预估标签 + ¥金额（大字）+ 定档/折前 |
+| 客源储值最高 | `dim-sv` | 储值 ¥金额（大字）+ 客户 X人 + 消耗 ¥X |
+
+> 高客源储值定义（PRD 补充）：RS > 2 的客户的会员卡储值合计（RS = 关系强度指数，> 2 表示有一定服务关系的客户）
+| 任务完成最多 | `dim-task` | 召回 X（蓝色大字）+ 回访 X |
+
+### 所有卡片共有元素
+- 助教头像圆形 + 姓名
+- 等级标签（星级/高级/中级/初级）— 不同等级不同颜色
+- 技能标签（🎱/斯/🀄/🎤）
+- 底部 TOP3 客户 emoji 列表
+
+## 等级标签颜色
+| 等级 | 颜色 |
+|------|------|
+| 星级 | 金色/amber |
+| 高级 | 蓝色/primary |
+| 中级 | 绿色/success |
+| 初级 | 灰色/gray |
+
+## 筛选栏滚动行为
+- 下滑时筛选栏隐藏，上滑时重新显示
+- 由 `initFilterBarScrollBehavior()` 实现
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 助教列表 | 有数据 |
+| 空数据态 | "暂无数据" | coaches 为空 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/board/coaches` | GET | 助教看板（排序×技能×时间三重筛选） |
+
+## 页面导航
+- 来源：board-finance / board-customer（看板 Tab 切换）
+- 去向：coach-detail / chat
+
+## 全局组件
+- 底部 TabBar（看板 active）
+- AI 悬浮按钮（右下角）
+- 看板顶部 Tab 栏（财务 / 客户 / 助教 active）

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 / 助教）

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 定位

docs/h5_ui/interactions/chat-history.md

@@ -0,0 +1,47 @@
+# 页面名：chat-history（对话历史）
+
+> PRD 参考：P9 `docs/prd/specs/P9-miniapp-fe-details.md`；`apps/miniprogram/doc/prd.md` 第十节
+> 已实现：否
+
+## 页面说明
+展示历史 AI 对话记录列表，按时间倒序排列。点击可进入继续对话。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| conversations | array | [] | 历史对话列表 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/chat/conversations | loading→false |
+| 点击对话记录 | 无 | navigateTo chat（带 sessionId，继续对话） | — |
+| 点击返回 | 顶部导航栏 | navigateBack | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 列表展示
+- 按时间倒序排列
+- 每条记录：对话标题/摘要 + 最后消息时间 + 消息数量
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 对话列表 | 有数据 |
+| 空数据态 | "暂无数据" | conversations 为空 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/chat/conversations` | GET | 对话历史列表 |
+
+## 页面导航
+- 来源：my-profile（点击"助手对话记录"）
+- 去向：chat（点击对话记录，继续对话）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "对话记录"）
+- AI 悬浮按钮

docs/h5_ui/interactions/chat.md

@@ -0,0 +1,81 @@
+# 页面名：chat（AI 对话）
+
+> PRD 参考：P9 `docs/prd/specs/P9-miniapp-fe-details.md`；`apps/miniprogram/doc/prd.md` 第十节
+> 已实现：否
+
+## 页面说明
+与 AI 助手进行对话。支持文本输入和语音输入，AI 回复流式展示（SSE）。从其他页面进入时携带上下文引用。
+
+> 原型 HTML 为纯静态展示（对话内容硬编码），仅有顶部返回 `history.back()` 一个交互事件。以下交互逻辑基于 PRD 设计。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| messages | array | [] | 对话消息列表 |
+| inputText | string | "" | 输入框内容 |
+| isRecording | boolean | false | 录音状态 |
+| referenceContent | object | null | 引用内容（来源页面 title + 基本信息） |
+| sessionId | string | "" | 会话 ID |
+| isStreaming | boolean | false | AI 正在流式回复 |
+| loading | boolean | false | 加载历史消息中 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载（新对话） | 从其他页面进入 | 创建新会话，第一条消息为页面上下文 | sessionId 设置 |
+| 页面加载（继续对话） | 从 chat-history 进入 | 加载历史消息 | messages 填充 |
+| 输入文本 + 点击发送 | inputText 非空 | POST /api/chat/conversations/:id/messages（SSE） | isStreaming=true |
+| 按住说话 | 无 | 开始录音 | isRecording=true |
+| 松开说话 | isRecording=true | 语音转文字 → 填充输入框 | isRecording=false |
+| AI 回复完成 | SSE 流结束 | 消息列表更新 | isStreaming=false |
+| 上拉加载 | 有更早记录 | 加载更早消息 | loading=true→false |
+| 距最后消息 >1 小时 | 时间判断 | 显示"新对话主题"和"继续对话"按钮 | — |
+| 点击"新对话主题" | 提示条显示 | 创建新会话 | sessionId 更新 |
+| 点击"继续对话" | 提示条显示 | 在当前会话继续 | — |
+| 点击返回 | 顶部导航栏 | navigateBack / history.back() | — |
+
+## 消息展示规则
+- IM 风格：左侧 AI 气泡，右侧用户气泡
+- AI 回复支持流式展示（逐字输出）
+- 引用内容：灰底卡片，含来源类型、标题、摘要
+- 发送后自动滚动到底部
+
+## AI 对话来源展示规则（PRD 补充）
+从不同入口进入 chat 页面时，引用卡片的来源 title 定义：
+| 入口页面 | 来源 title | 携带上下文 |
+|----------|-----------|-----------|
+| task-list 长按菜单"问问AI助手" | 任务：{客户昵称} | 任务类型 + 客户基本信息 |
+| task-detail "问问助手" | 任务详情：{客户昵称} | 任务详情 + 客户信息 + AI 分析 |
+| customer-detail "问问助手" | 客户：{客户昵称} | 客户信息 + 消费记录 + 指数 |
+| AI 悬浮按钮（任意页面） | 当前页面名称 | 当前页面上下文 |
+| chat-history 继续对话 | 历史对话 | 历史消息 |
+
+## 会话管理规则（PRD 补充）
+- 距最后一条消息超过 1 小时：页面顶部显示提示条，含两个按钮：
+  - 「新对话主题」→ 创建新 sessionId，清空消息区
+  - 「继续对话」→ 保持当前 sessionId，在原会话追加
+- 每个会话有独立 sessionId，用于后端关联上下文
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 空对话 | 引用卡片 + 空消息区 | 新对话，未发送 |
+| 对话中 | 消息列表 + 输入区 | 有消息 |
+| AI 回复中 | 最后一条消息逐字输出 | isStreaming=true |
+| 录音中 | 输入区显示录音动画 | isRecording=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `POST /api/chat/conversations` | POST | 创建对话 |
+| `POST /api/chat/conversations/:id/messages` | POST | 发送消息（SSE 流式返回） |
+| `GET /api/chat/conversations/:id/messages` | GET | 对话消息列表 |
+
+## 页面导航
+- 来源：任意业务页面（AI 悬浮按钮 / "问问助手"按钮）/ chat-history
+- 去向：无（末端页面）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "智能助手"）
+- 无底部 TabBar
+- 无 AI 悬浮按钮（本页即为 AI 对话）

docs/h5_ui/interactions/coach-detail.md

@@ -0,0 +1,100 @@
+# 页面名：coach-detail（助教详情）
+
+> PRD 参考：P9 `docs/prd/specs/P9-miniapp-fe-details.md`
+> 已实现：否
+
+## 页面说明
+展示助教完整信息：绩效概览、收入明细（本月/上月 Tab）、任务执行（展开/收起）、客户关系 TOP5、近期服务明细、更多信息。支持备注弹窗。
+
+## Banner 主题
+`banner-bg theme-coral texture-aurora`（珊瑚粉主题 + 极光丝带纹理）
+
+> ⚠️ Banner 背景使用 CSS 渐变+SVG 纹理，小程序实现时建议导出为图片资源 `/assets/images/banner-coral.png`
+
+## 页面区域结构（忠于原型 HTML）
+1. Banner（助教信息：花名/等级/技能标签/工龄/客户数）
+   - 工龄计算（PRD 补充）：入职时间到当前日期的年数（精确到 0.1 年）
+2. 绩效概览（`st blue`）— 4宫格：本月定档业绩/本月工资预估/客源储值余额/本月任务完成 + 绩效档位进度条
+3. 收入明细（`st green`）— Tab 切换：本月预估 / 上月
+4. 任务执行（`st orange`）— 任务列表 + 展开/收起
+5. 客户关系 TOP5（`st pink`）— 近60天
+6. 近期服务明细（`st purple`）
+7. 更多信息（`st teal`）— 入职日期 + 历史月份表格
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| coachInfo | object | null | 助教信息（花名、级别、技能、工龄、客户数） |
+| incomeTab | string | "this" | 收入明细当前 Tab（this=本月/last=上月） |
+| tasksExpanded | boolean | false | 任务列表展开状态 |
+| noteModalVisible | boolean | false | 备注弹窗显示状态 |
+| noteText | string | "" | 备注输入内容 |
+| notesPopupVisible | boolean | false | 备注列表弹窗显示状态 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/coaches/:id（含全部区域数据） | loading→false |
+| 切换收入明细 Tab | 点击"本月"/"上月" | 切换对应内容显隐 | incomeTab 更新 |
+| 点击"展开全部 ↓" | tasksExpanded=false | 显示隐藏的任务列表（含已放弃任务） | tasksExpanded=true |
+| 点击"收起 ↑" | tasksExpanded=true | 隐藏多余任务 | tasksExpanded=false |
+| 点击"备注"按钮 | 无 | 打开备注弹窗 | noteModalVisible=true |
+| 备注弹窗-提交 | noteText 非空 | POST /api/xcx/notes | Toast "备注已保存"，弹窗关闭 |
+| 点击客户卡片 | 客户关系 TOP5 区域 | navigateTo customer-detail | — |
+| 点击客户卡片的备注图标 | 无 | 弹出该客户的备注列表弹窗（阻止冒泡，不触发卡片跳转） | notesPopupVisible=true |
+| 点击返回 | 顶部导航栏 | navigateBack / history.back() | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 收入明细 Tab
+- 本月（`id="incomeTab_this"`）：含「预估」标签，active 状态
+- 上月（`id="incomeTab_last"`）
+- 明细项：基础课时费、激励课时费、充值提成、酒水提成、合计
+- 由 `switchIncomeTab(tab)` 控制切换
+
+## 任务执行区域
+- 默认显示前 6 项任务
+- 隐藏区域 `id="hiddenTasks"`：更多任务 + 已放弃任务
+- 已放弃任务样式：opacity 0.55 + 删除线 + 放弃原因文字
+- 展开/收起按钮 `id="toggleTasksBtn"`：文字在「展开全部 ↓」/「收起 ↑」间切换
+- 由 `toggleAllTasks()` 控制
+
+## 客户关系 TOP5
+- 标题右侧标注「近60天」
+- 5 个客户卡片，每个含：
+  - 头像圆形 + 姓名 + 关系 emoji（❤️/💛）+ 关系分数（彩色）
+  - 服务次数 / 储值 / 消费
+- 前 2 名有渐变背景（pink/amber），后 3 名灰色背景
+
+## 备注弹窗
+- 底部弹出式弹窗
+- 包含：多行文本输入 + 提交按钮
+- 空值校验：内容为空时 Toast 提示
+- 由 `showNoteModal()` / `hideNoteModal()` / `saveNote()` 控制
+
+## 备注列表弹窗
+- 点击客户卡片的备注图标触发
+- 动态渲染该客户的备注列表
+- 由 `showNotesPopup(name, notes)` / `hideNotesPopup()` 控制
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 完整助教详情 | 有数据 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/coaches/:id` | GET | 助教详情（含绩效、收入、任务、客户关系） |
+| `POST /api/xcx/notes` | POST | 创建备注 |
+
+## 页面导航
+- 来源：board-coach（点击助教卡片）
+- 去向：task-detail*（点击客户卡片）/ chat（通过悬浮按钮）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "助教详情"）
+- AI 悬浮按钮

docs/h5_ui/interactions/customer-detail.md

@@ -0,0 +1,71 @@
+# 页面名：customer-detail（客户详情）
+
+> PRD 参考：P9 `docs/prd/specs/P9-miniapp-fe-details.md`
+> 已实现：否
+
+## 页面说明
+展示客户全信息、消费记录（三种样式）、指数总览、备注、AI 维客线索、AI 客户分析。纯静态展示页（原型中无复杂交互函数）。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| customerInfo | object | null | 客户信息（昵称、手机、会员卡等级、余额、注册日期） |
+| indexes | object | null | 指数总览（WBI/NCI/SPI + 爱心 icon） |
+| consumptionRecords | array | [] | 消费记录列表 |
+| consumptionPage | number | 1 | 消费记录当前页 |
+| hasMoreRecords | boolean | true | 是否还有更多消费记录 |
+| retentionClues | array | [] | AI 维客线索（应用 8） |
+| customerAnalysis | object | null | AI 客户分析（应用 7） |
+| notes | array | [] | 备注列表 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+| loadingMore | boolean | false | 加载更多消费记录中 |
+
+## 用户操作 → 响应（忠于原型 HTML）
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | 请求客户详情+指数+消费记录+AI 数据 | loading→false |
+| 滚动到底部 | hasMoreRecords=true | GET 消费记录下一页（每次 10 条） | loadingMore=true→false |
+| 点击"问问助手" | 底部按钮 | navigateTo chat（`window.location.href='chat.html'`） | — |
+| 点击返回 | 顶部导航栏 | navigateBack（`history.back()`） | — |
+
+> 原型 HTML 中仅有两个内联事件：顶部返回 `history.back()` 和底部"问问助手" `window.location.href='chat.html'`，无其他动态交互函数。
+
+## 消费记录三种样式
+1. 台桌结账：下沉到 `dwd_table_fee_log`，每条台费详情，关联总金额汇总
+2. 商城订单：助教列表（花名+级别+课程类型+服务时长+定档绩效）、支付金额、食品酒水总金额
+3. 充值：充值金额、支付方式
+
+## 消费记录展示规则
+- 默认 10 条，拉到底懒加载（每次 10 条）
+- 金额为 0 的项不展示
+- 有团购/折扣时展示正价+实付
+- 总金额仅在消费条目 >1 时出现
+
+## AI 区域展示
+- 维客线索（应用 8）：Emoji 二级标签，提供者逗号分隔（By:系统/By:备注）
+- 客户分析（应用 7，`cache_type=app7_customer_analysis`）：运营策略数组 + 总结
+  - 触发时机（PRD 补充）：客户结账单出现后自动生成
+  - 应用 3 与应用 7 共用同一 cache_type，应用 3 为简版摘要，应用 7 为完整分析
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 完整客户详情 | 有数据 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/customers/:id` | GET | 客户详情 |
+| `GET /api/customers/:id/consumption-records` | GET | 消费记录（分页，懒加载） |
+| `GET /api/customers/:id/indexes` | GET | 客户指数总览 |
+
+## 页面导航
+- 来源：board-customer（点击客户卡片）/ task-detail / performance
+- 去向：chat（问问助手）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "客户详情"）
+- AI 悬浮按钮

docs/h5_ui/interactions/customer-service-records.md

@@ -0,0 +1,54 @@
+# 页面名：customer-service-records（客户服务记录）
+
+> PRD 参考：P9 `docs/prd/specs/P9-miniapp-fe-details.md`
+> 已实现：否
+
+## 页面说明
+展示某客户的服务记录列表，支持月份前后切换。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| records | array | [] | 服务记录列表 |
+| currentMonth | number | 当前月 | 当前显示月份 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/customers/:id/service-records | loading→false |
+| 点击"←"（上月） | currentMonth > 最小月 | 切换到上一月，更新月份标签 | currentMonth-- |
+| 点击"→"（下月） | currentMonth < 最大月 | 切换到下一月，更新月份标签 | currentMonth++ |
+| 点击返回 | 顶部导航栏 | navigateBack | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 月份切换器（忠于原型 HTML）
+- 样式：← 2026年X月 →
+- 到达边界时对应箭头按钮变灰禁用（opacity 0.3）
+- 由 `customer-service-records.js` 的 `switchMonth(direction)` 控制
+
+## 记录展示
+- 每条记录：服务时间 + 持续时长
+- 按时间倒序排列
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 服务记录列表 | 有数据 |
+| 空数据态 | "暂无数据" | records 为空 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/customers/:id/service-records` | GET | 客户服务记录（支持月份参数） |
+
+## 页面导航
+- 来源：customer-detail / task-detail
+- 去向：无（末端页面）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "服务记录"）
+- AI 悬浮按钮

docs/h5_ui/interactions/login.md

@@ -0,0 +1,52 @@
+# 页面名：login（登录页）
+
+> PRD 参考：`apps/miniprogram/doc/prd.md` 第七节 7.1；P3 认证系统
+> 已实现：是（`apps/miniprogram/miniprogram/pages/login/`）
+
+## 页面说明
+微信授权登录入口页。用户需勾选协议后才能点击登录按钮。登录后根据用户状态跳转到不同页面。
+
+## 视觉元素（忠于原型 HTML）
+- 顶部 Logo：台球图标 SVG（需转为图片资源 `/assets/icons/logo-billiard.svg`）
+- 应用名称文字
+- 微信登录按钮：渐变背景，含微信图标 SVG
+- 底部协议勾选区域：勾选框 + 协议链接文字
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| agreed | boolean | false | 协议勾选状态 |
+| loading | boolean | false | 登录请求中 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 点击协议勾选框 | 无 | 切换 agreed | agreed=!agreed |
+| 点击"使用微信登录" | agreed=true | 调用 wx.login() 获取 code → POST /api/xcx-auth/login | loading=true |
+| 点击"使用微信登录" | agreed=false | 无响应（按钮禁用态） | 不变 |
+| 登录成功（status=new） | API 返回 | 跳转 apply 页面 | redirectTo apply |
+| 登录成功（status=pending） | API 返回 | 跳转 reviewing 页面 | redirectTo reviewing |
+| 登录成功（status=approved） | API 返回 | 跳转默认首页（task-list 或 board-finance） | switchTab |
+| 登录成功（status=rejected） | API 返回 | 跳转 no-permission 页面 | redirectTo no-permission |
+| 登录成功（status=disabled） | API 返回 | 跳转 no-permission 页面 | redirectTo no-permission |
+| 登录失败 | API 报错 | Toast 提示错误信息 | loading=false |
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 默认态 | 按钮灰色禁用，协议未勾选 | agreed=false |
+| 可登录态 | 按钮蓝色渐变+阴影，协议已勾选 | agreed=true |
+| 加载中 | 按钮显示 loading 动画 | loading=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `/api/xcx-auth/login` | POST | 微信登录（code → JWT + user_status） |
+
+## 页面导航
+- 来源：小程序启动 / 退出账号后 / reviewing/no-permission 点击"更换登录账号"
+- 去向：apply / reviewing / no-permission / task-list / board-finance
+
+## 全局组件
+- 无底部 TabBar
+- 无 AI 悬浮按钮

docs/h5_ui/interactions/my-profile.md

@@ -0,0 +1,48 @@
+# 页面名：my-profile（我的首页）
+
+> PRD 参考：`apps/miniprogram/doc/prd.md` 第十一节
+> 已实现：否
+
+## 页面说明
+用户个人中心菜单页（Tab 3）。展示用户信息和功能入口列表。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| userInfo | object | null | 用户信息（用户名、身份、门店） |
+| logoutConfirmVisible | boolean | false | 退出账号确认弹窗 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | 读取缓存用户信息 | — |
+| 点击"备注记录" | 无 | navigateTo notes | — |
+| 点击"助手对话记录" | 无 | navigateTo chat-history | — |
+| 点击"退出账号" | 无 | 显示确认弹窗 | logoutConfirmVisible=true |
+| 确认退出 | 弹窗确认 | 清除登录态 + redirectTo login | — |
+| 取消退出 | 弹窗取消 | 关闭弹窗 | logoutConfirmVisible=false |
+
+## 菜单列表
+| 菜单项 | 图标 | 跳转目标 |
+|--------|------|----------|
+| 备注记录 | `<t-icon name="edit-1" />` | notes |
+| 助手对话记录 | `<t-icon name="chat" />` | chat-history |
+| 退出账号 | `<t-icon name="poweroff" />` | 确认弹窗 → login |
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 默认态 | 用户信息 + 菜单列表 | 始终 |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/xcx-auth/status` | GET | 获取用户信息（可从缓存读取） |
+
+## 页面导航
+- 来源：TabBar 切换
+- 去向：notes / chat-history / login（退出）
+
+## 全局组件
+- 底部 TabBar（我的 active）— 由 `bottom-nav.js` 自动注入
+- AI 悬浮按钮

docs/h5_ui/interactions/no-permission.md

@@ -0,0 +1,44 @@
+# 页面名：no-permission（无权限页）
+
+> PRD 参考：`apps/miniprogram/doc/prd.md` 第七节 7.4
+> 已实现：是（`apps/miniprogram/miniprogram/pages/no-permission/`）
+
+## 页面说明
+纯展示页，告知用户申请被拒或账号无权限。包含可能原因列表和联系管理员信息。底部可切换登录账号。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| （无） | — | — | 纯展示页，无交互状态 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 点击"更换登录账号" | 底部按钮 | 清除登录态 → redirectTo login | — |
+
+## 视觉元素（忠于原型 HTML）
+- 主图标：rose→red 渐变圆角方块内，白色描边的禁止符号 SVG（圆形 + 对角线）
+  - ⚠️ 此 SVG 较复杂，小程序实现时建议转为图片资源 `/assets/images/icon-no-permission.png`
+- 标题：「无访问权限」
+- 副标题：「很抱歉，您的访问申请未通过审核，或当前账号无访问权限」
+- 原因卡片：
+  - 标题「可能的原因」（Material 风格 info 图标）
+  - 列表项：申请信息不完整或不符合要求 / 非本店授权员工账号 / 账号权限已被管理员收回
+- 联系管理员：问号圆圈图标 + 「如有疑问，请联系管理员重新申请」
+- 底部按钮：登出箭头图标 + 「更换登录账号」
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 默认态 | 完整无权限展示（图标+原因+联系提示+底部按钮） | 始终 |
+
+## 后端 API 依赖
+无（纯展示页）
+
+## 页面导航
+- 来源：login（status=rejected / disabled）
+- 去向：login（点击"更换登录账号"）/ 用户再次打开小程序时重新判断状态
+
+## 全局组件
+- 无底部 TabBar
+- 无 AI 悬浮按钮

docs/h5_ui/interactions/notes.md

@@ -0,0 +1,56 @@
+# 页面名：notes（备注记录）
+
+> PRD 参考：P6 `docs/prd/specs/P6-miniapp-fe-tasks.md`；`apps/miniprogram/doc/prd.md` 第十一节
+> 已实现：否
+
+## 页面说明
+展示用户所有备注记录，支持按 Tab 切换「客户备注」和「助教备注」两个分类。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| activeTab | string | "customer" | 当前 Tab（customer/coach） |
+| customerNotes | array | [] | 客户备注列表 |
+| coachNotes | array | [] | 助教备注列表 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/xcx/notes | loading→false |
+| 点击"客户备注" Tab | activeTab≠customer | 切换显示客户备注列表，隐藏助教备注 | activeTab=customer |
+| 点击"助教备注" Tab | activeTab≠coach | 切换显示助教备注列表，隐藏客户备注 | activeTab=coach |
+| 点击返回 | 顶部导航栏 | navigateBack | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## Tab 切换（忠于原型 HTML）
+- 两个 Tab：客户备注（`id="tabCustomer"`）/ 助教备注（`id="tabCoach"`）
+- 切换时互斥显隐对应列表容器（`id="customerNotes"` / `id="coachNotes"`）
+- 由 `notes.js` 的 `switchTab(tab)` 控制
+
+## 列表展示规则
+- 按时间倒序（由近到远）平铺
+- 每条记录：备注全文 + 关联对象（客户/助教）+ 创建时间
+- 不进入详情页，本页即为详情展示
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 备注列表 | 有数据 |
+| 空数据态 | "暂无数据" | 当前 Tab 列表为空 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/xcx/notes` | GET | 获取备注列表（含客户和助教两类） |
+
+## 页面导航
+- 来源：my-profile（点击"备注记录"）
+- 去向：无（末端页面）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "备注记录"）
+- AI 悬浮按钮

docs/h5_ui/interactions/performance-records.md

@@ -0,0 +1,64 @@
+# 页面名：performance-records（业绩明细 / 服务记录）
+
+> PRD 参考：P7 `docs/prd/specs/P7-miniapp-fe-performance.md`
+> 已实现：否
+
+## 页面说明
+展示按月份切换的服务记录明细列表。顶部有统计概览（总记录/总时长/收入），下方按日期分组展示服务记录。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| records | array | [] | 服务记录列表 |
+| currentMonth | number | 当前月 | 当前显示月份 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/performance/records | loading→false |
+| 点击"←"（上月） | currentMonth > 最小月 | 切换到上一月，更新月份标签，重新请求数据 | currentMonth-- |
+| 点击"→"（下月） | currentMonth < 最大月 | 切换到下一月，更新月份标签，重新请求数据 | currentMonth++ |
+| 点击返回 | 顶部导航栏 | navigateBack / history.back() | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 月份切换器（忠于原型 HTML）
+- 样式：← 2026年X月 →
+- 到达边界时对应箭头按钮变灰禁用（opacity 0.3）
+- 由 `customer-service-records.js` 的 `switchMonth(direction)` 控制
+
+## 统计概览
+- 总记录数 / 总时长 / 收入合计
+- 当月数据标记"预估"
+
+## 记录展示规则
+- 按日期分组，每组显示日期标题
+- 每条记录：服务时间、课程类型、台桌/房间、会员昵称、开始/结束时间、业绩分钟
+- 有定档折算惩罚时展示：「120分钟（定档折算30分钟）」格式
+- 营业日以 08:00 为分割点
+
+## 记录点击交互
+- 原型 HTML 中记录条目无 onclick 跳转
+- 产品意图：点击记录可跳转对应任务详情页（需后续确认是否实现）
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 统计概览 + 明细列表 | 有数据 |
+| 空数据态 | "暂无数据" | records 为空 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/performance/records` | GET | 业绩明细（支持月份参数） |
+
+## 页面导航
+- 来源：performance（点击"查看全部"）
+- 去向：无（末端页面，原型中无跳转）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "服务记录"）
+- AI 悬浮按钮

docs/h5_ui/interactions/performance.md

@@ -0,0 +1,88 @@
+# 页面名：performance（我的业绩）
+
+> PRD 参考：P7 `docs/prd/specs/P7-miniapp-fe-performance.md`
+> 已实现：否
+
+## 页面说明
+展示助教业绩全貌：收入档位、本月/上月业绩明细（含服务记录）、新客和常客列表。多个区域支持展开/收起和"查看全部"跳转。
+
+## Banner 主题
+`banner-bg theme-blue texture-aurora`（蓝色主题）
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| performanceSummary | object | null | 业绩汇总（收入、档位、工资预估） |
+| thisMonthRecordsExpanded | boolean | false | 本月服务记录展开状态 |
+| lastMonthRecordsExpanded | boolean | false | 上月服务记录展开状态 |
+| newCustomerExpanded | boolean | false | 新客列表展开状态 |
+| regularCustomerExpanded | boolean | false | 常客列表展开状态 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 页面区域结构（忠于原型 HTML）
+1. Banner（个人信息：花名/身份/门店 + 核心数据：本月预计收入 + 上月收入）
+2. 收入情况（`bg-primary` 圆点）— 当前档位 + 下一阶段目标 + 升级提示（「距下一阶段需完成 X 小时，到达即得 Y 元」）
+   - 跳档激励计算公式（PRD 补充）：YYY = max(跳档线差值最小值, 实际差值)
+   - 各档差值：Tier0→1: 1200元 / Tier1→2: 750元 / Tier2→3: 540元 / Tier3→4: 420元
+3. 本月业绩 预估（`bg-success` 圆点）— 基础课时费/激励课时费/充值激励/TOP3销冠奖/合计 + 我的服务记录明细
+4. 上月收入（`bg-warning` 圆点）— 同结构 + 我的服务记录明细
+5. 我的新客（`bg-cyan-500` 圆点）— 按时间顺序
+6. 我的常客（`bg-pink-500` 圆点）— 近2月贡献TOP20
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | 请求业绩汇总+服务记录+新客+常客 | loading→false |
+| 点击"展开更多"（本月服务记录） | thisMonthRecordsExpanded=false | 显示隐藏的更多记录条目，按钮文字变「收起」 | thisMonthRecordsExpanded=true |
+| 点击"收起"（本月服务记录） | thisMonthRecordsExpanded=true | 隐藏多余记录条目，按钮文字变「展开更多」 | thisMonthRecordsExpanded=false |
+| 点击"展开更多"（上月服务记录） | lastMonthRecordsExpanded=false | 同上 | lastMonthRecordsExpanded=true |
+| 点击"收起"（上月服务记录） | lastMonthRecordsExpanded=true | 同上 | lastMonthRecordsExpanded=false |
+| 点击"查看全部"（本月） | 服务记录区域 | navigateTo performance-records（本月口径） | — |
+| 点击"查看全部"（上月） | 服务记录区域 | navigateTo performance-records（上月口径） | — |
+| 点击"查看更多 ↓"（新客列表） | newCustomerExpanded=false | 展开完整新客列表 | newCustomerExpanded=true |
+| 点击"收起 ↑"（新客列表） | newCustomerExpanded=true | 收起新客列表 | newCustomerExpanded=false |
+| 点击"查看更多 ↓"（常客列表） | regularCustomerExpanded=false | 展开完整常客列表 | regularCustomerExpanded=true |
+| 点击"收起 ↑"（常客列表） | regularCustomerExpanded=true | 收起常客列表 | regularCustomerExpanded=false |
+| 点击新客/常客卡片 | 无 | navigateTo task-detail（按该客户当前任务类型跳转对应详情页） | — |
+| 点击返回 | 顶部导航栏 | navigateBack / history.back() | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 服务记录展示
+- 按天归总，每天显示服务次数和总时长
+- 默认显示前几条，其余折叠
+- 展开/收起按钮：`id="thisMonthRecordsToggle"` / `id="lastMonthRecordsToggle"`
+- "查看全部"链接跳转 `performance-records.html`
+
+## 新客/常客展示
+- 我的新客：该助教首次服务 + 2 月内 + 服务次数 ≤2，按最后服务时间排列
+- 我的常客：近2月贡献TOP20，按服务次数降序，展示次数、小时数、工资合计
+- 两个列表均支持展开/收起（`toggleNewCustomer()` / `toggleRegularCustomer()`）
+
+## 业绩数据说明
+- 营业日以 08:00 为分割点（"本月"= 当月1日 08:00 ~ 次月1日 08:00）
+- 当月数据标记"预估"
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 完整业绩展示 | 有数据 |
+| 空数据态 | 各区域"暂无数据" | 对应列表为空 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/performance/summary` | GET | 当月绩效汇总 |
+| `GET /api/performance/service-records` | GET | 服务记录明细（分页） |
+| `GET /api/performance/my-new-customers` | GET | 我的新客列表 |
+| `GET /api/performance/my-regulars` | GET | 我的常客列表 |
+
+## 页面导航
+- 来源：task-list（点击 Banner 业绩区域）
+- 去向：performance-records（查看全部）/ task-detail*（点击新客/常客卡片）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "我的业绩"）
+- AI 悬浮按钮

docs/h5_ui/interactions/reviewing.md

@@ -0,0 +1,44 @@
+# 页面名：reviewing（审核中页）
+
+> PRD 参考：`apps/miniprogram/doc/prd.md` 第七节 7.3
+> 已实现：是（`apps/miniprogram/miniprogram/pages/reviewing/`）
+
+## 页面说明
+纯展示页，告知用户申请正在审核中。包含审核进度展示和联系管理员提示。底部可切换登录账号。
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| （无） | — | — | 纯展示页，无交互状态 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 点击"更换登录账号" | 底部按钮 | 清除登录态 → redirectTo login | — |
+
+## 视觉元素（忠于原型 HTML）
+- 主图标：amber→orange 渐变圆角方块内，白色描边的圆形时钟 SVG（圆形表盘 + 时针分针折线），带上下浮动动画
+  - ⚠️ 此 SVG 较复杂，小程序实现时建议转为图片资源 `/assets/images/icon-reviewing.png`
+- 标题：「申请审核中」
+- 副标题：「您的访问申请已提交成功，正在等待管理员审核，请耐心等待」
+- 审核进度卡片：
+  - 标题「审核进度」+ 副文字「通常需要 1-3 个工作日」
+  - 三步进度条：已提交（绿色对勾圆圈）→ 审核中（高亮）→ 通过（灰色）
+- 联系提示：聊天气泡图标 + 「如有疑问，请联系管理员」
+- 底部按钮：登出箭头图标 + 「更换登录账号」
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 默认态 | 完整审核中展示（图标+进度+联系提示+底部按钮） | 始终 |
+
+## 后端 API 依赖
+无（纯展示页）
+
+## 页面导航
+- 来源：login（status=pending）/ apply（提交成功）
+- 去向：login（点击"更换登录账号"）/ 用户再次打开小程序时重新判断状态
+
+## 全局组件
+- 无底部 TabBar
+- 无 AI 悬浮按钮

docs/h5_ui/interactions/task-detail-callback.md

@@ -0,0 +1,26 @@
+# 页面名：task-detail-callback（任务详情 - 客户回访）
+
+> 本页为 task-detail 系列的变体页面，完整交互说明见 `task-detail.md`。
+> 此文件仅记录与 task-detail.html 的差异。
+
+## 与 task-detail.html 的差异
+
+| 差异点 | task-detail（高优先召回） | task-detail-callback（客户回访） |
+|--------|--------------------------|----------------------------------|
+| Banner 主题 | `theme-red` 红色 | `theme-teal` 青绿色 |
+| 区域顺序 | ①与我的关系 → ②任务建议 → ③维客线索 → ④备注 → ⑤近期服务记录 | ①维客线索 → ②与我的关系（含近期服务记录）→ ③任务建议 → ④备注 |
+| 话术样式 | 气泡样式（`.speech-bubble`，带复制按钮） | 竖线样式（`border-l-2`，左侧竖线+左内边距） |
+| 任务建议标题 | 💡 建议执行 | 📞 常规回访要点 |
+| 底部按钮颜色 | `from-primary to-blue-500` | `from-teal-500 to-cyan-500` |
+| 导航栏"放弃"按钮 | 有 | 无 |
+| 近期服务记录 | 独立区域（第5区域） | 嵌入"与我的关系"卡片内（`.svc-section-bg`） |
+| ratingExpanded 初始值 | false（需点击"展开评价"） | true（默认展开） |
+
+## 实现建议
+在小程序中，task-detail 系列不需要 4 个独立页面。可以在同一页面通过路由参数 `taskType` 控制：
+- Banner 主题色
+- 区域排列顺序
+- 话术样式（气泡 vs 竖线）
+- 任务建议标题文案
+- 是否显示"放弃"按钮
+- ratingExpanded 初始值

docs/h5_ui/interactions/task-detail-priority.md

@@ -0,0 +1,17 @@
+# 页面名：task-detail-priority（任务详情 - 优先召回）
+
+> 本页为 task-detail 系列的变体页面，完整交互说明见 `task-detail.md`。
+> 此文件仅记录与 task-detail.html（高优先召回）的差异。
+
+## 与 task-detail.html 的差异
+
+| 差异点 | task-detail（高优先召回） | task-detail-priority（优先召回） |
+|--------|--------------------------|----------------------------------|
+| Banner 主题 | `theme-red` 红色 | `theme-orange` 橙色 |
+| 任务类型标签 | 高优先召回 | 优先召回 |
+| 标签颜色 | 红色系 | 橙色系 |
+
+其余结构（区域顺序、话术样式、底部操作栏、放弃按钮等）与 task-detail.html 完全一致。
+
+## 实现建议
+在小程序中，task-detail 系列不需要 4 个独立页面。可以在同一页面通过路由参数 `taskType` 控制 Banner 主题色和标签样式。

docs/h5_ui/interactions/task-detail-relationship.md

@@ -0,0 +1,26 @@
+# 页面名：task-detail-relationship（任务详情 - 关系构建）
+
+> 本页为 task-detail 系列的变体页面，完整交互说明见 `task-detail.md`。
+> 此文件仅记录与 task-detail.html（高优先召回）的差异。
+
+## 与 task-detail.html 的差异
+
+| 差异点 | task-detail（高优先召回） | task-detail-relationship（关系构建） |
+|--------|--------------------------|--------------------------------------|
+| Banner 主题 | `theme-red` 红色 | `theme-pink` 粉色 |
+| 区域顺序 | ①与我的关系 → ②任务建议 → ③维客线索 → ④备注 → ⑤近期服务记录 | ①维客线索 → ②与我的关系（含近期服务记录）→ ③任务建议 → ④备注 |
+| 话术样式 | 气泡样式（`.speech-bubble`，带复制按钮） | 竖线样式（`border-l-2`，左侧竖线+左内边距） |
+| 任务建议标题 | 💡 建议执行 | 💝 关系构建重点 |
+| 任务建议背景 | 蓝色系 | `from-pink-50 to-rose-50` |
+| 底部按钮颜色 | `from-primary to-blue-500` | `from-pink-500 to-rose-500` |
+| 导航栏"放弃"按钮 | 有 | 无 |
+| 近期服务记录 | 独立区域（第5区域） | 嵌入"与我的关系"卡片内 |
+| 备注区域 | 有已有备注展示 | 可能为空状态（提示「快点击下方备注按钮，添加客人备注！」） |
+
+## 实现建议
+在小程序中，task-detail 系列不需要 4 个独立页面。可以在同一页面通过路由参数 `taskType` 控制：
+- Banner 主题色
+- 区域排列顺序
+- 话术样式（气泡 vs 竖线）
+- 任务建议标题和背景色
+- 是否显示"放弃"按钮

docs/h5_ui/interactions/task-detail.md

@@ -0,0 +1,148 @@
+# 页面名：task-detail 系列（任务详情）
+
+> PRD 参考：P6 `docs/prd/specs/P6-miniapp-fe-tasks.md`；`apps/miniprogram/doc/prd.md` 第八节 8.2
+> 已实现：否
+
+## 页面说明
+展示客户详细信息、消费习惯、AI 分析（关系分析+任务建议+话术参考+备注评分）、维客线索、备注入口。底部固定操作栏。
+
+task-detail 系列共 4 个页面，卡片内容相同（以 task-detail.html 为准），差异仅在：头部 Banner 主题/配色、区域排列顺序、话术样式、部分文案。
+
+## Banner 主题映射表
+| 页面 | Banner class | 主题色 | 任务类型 |
+|------|-------------|--------|----------|
+| task-detail.html | `banner-bg theme-red texture-aurora` | 红色 | 高优先召回 |
+| task-detail-priority.html | （同 task-detail，橙色变体） | 橙色 | 优先召回 |
+| task-detail-relationship.html | `banner-bg theme-pink texture-aurora` | 粉色 | 关系构建 |
+| task-detail-callback.html | `banner-bg theme-teal texture-aurora` | 青绿色 | 客户回访 |
+
+> ⚠️ Banner 背景使用 CSS 渐变+SVG 纹理（`banner.css` 中的 `texture-aurora`），内含复杂的 SVG 丝带效果。小程序实现时建议将各主题 Banner 背景导出为图片资源，统一放 `/assets/images/banner-{theme}.png`。
+
+## 页面区域顺序差异
+| 区域 | task-detail（高优先/优先） | task-detail-relationship（关系构建） | task-detail-callback（客户回访） |
+|------|--------------------------|--------------------------------------|----------------------------------|
+| 1 | 与我的关系 | 维客线索 | 维客线索 |
+| 2 | 任务建议 | 与我的关系（含近期服务记录） | 与我的关系（含近期服务记录） |
+| 3 | 维客线索 | 任务建议 | 任务建议 |
+| 4 | 我给TA的备注 | 我给TA的备注 | 我给TA的备注 |
+| 5 | 近期服务记录 | （嵌入区域2） | （嵌入区域2） |
+
+## 话术样式差异
+| 页面 | 话术样式 | 说明 |
+|------|----------|------|
+| task-detail（高优先/优先） | 气泡样式 `.speech-bubble` | 浅蓝背景+边框+圆角+右下角尖角，每条带「复制」按钮 |
+| task-detail-relationship | 竖线样式 `border-l-2` | 左侧 2px 竖线 + 左内边距 |
+| task-detail-callback | 竖线样式 `border-l-2` | 同上 |
+
+## 任务建议标题差异
+| 页面 | 标题 | 背景色 |
+|------|------|--------|
+| task-detail | 💡 建议执行 | 蓝色系 |
+| task-detail-relationship | 💝 关系构建重点 | pink→rose |
+| task-detail-callback | 📞 常规回访要点 | teal→cyan |
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| taskDetail | object | null | 任务详情数据 |
+| customerInfo | object | null | 客户基本信息 |
+| serviceRecords | array | [] | 近期服务记录 |
+| aiAnalysis | object | null | AI 分析（应用 4：关系分析+任务建议+一句话总结） |
+| retentionClues | array | [] | 维客线索（应用 8 整合线索+人工） |
+| customerAnalysis | object | null | 客户分析（应用 7：运营策略+总结） |
+| talkingPoints | object | null | 话术参考（应用 5 缓存） |
+| noteScore | number | null | 备注分析评分（应用 6：1-10 分） |
+| noteModalVisible | boolean | false | 备注弹窗显示状态 |
+| noteText | string | "" | 备注输入内容 |
+| noteRating | object | {serviceWill: 0, returnChance: 0} | 星星评分（再次服务意愿+再来店可能性，各 1-5 星） |
+| ratingExpanded | boolean | false | 评分区域是否展开（回访任务默认 true） |
+| abandonModalVisible | boolean | false | 放弃客户弹窗显示状态（仅高优先/优先召回有） |
+| abandonReason | string | "" | 放弃原因 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/xcx/tasks/{id} | loading→false |
+| 点击"问问助手" | 底部操作栏 | navigateTo chat（带任务+客户上下文引用） | — |
+| 点击"备注" | 底部操作栏 | 打开备注弹窗 | noteModalVisible=true |
+| 点击"展开评价" | noteModalVisible=true, ratingExpanded=false | 展开星星评分区域，隐藏展开按钮 | ratingExpanded=true |
+| 拖动/点击星星 | 评分区域展开 | 更新对应评分值（支持触摸拖动+鼠标拖动+点击） | noteRating 更新 |
+| 备注弹窗-提交 | noteText 非空 | POST /api/xcx/notes（含评分） | Toast "备注已保存"，弹窗关闭 |
+| 点击"复制"（话术气泡） | 气泡样式页面 | 复制话术文本到剪贴板，按钮变"已复制" | — |
+| 点击"放弃" | 顶部导航栏右侧（仅高优先/优先） | 打开放弃确认弹窗 | abandonModalVisible=true |
+| 放弃弹窗-确认 | abandonReason 非空 | POST /api/xcx/tasks/{id}/abandon | Toast "已放弃该客户的维护" |
+| 点击返回 | 顶部导航栏 | navigateBack / history.back() | — |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## "与我的关系"区域
+- 标题带 section-title pink 样式
+- AI 机器人图标（可爱机器人 SVG：圆角矩形身体+天线+紫蓝色大眼睛+微笑+粉色腮红+小耳朵）
+  - 此图标可视为心形 ICON 的扩展，小程序中用 `/assets/icons/icon-ai-relationship.svg`
+- 关系等级色系：💖 非常好(>8.5 粉色渐变) / 🧡 良好(>7) / 💛 一般(>5) / 💙 待发展(<5 蓝色渐变)
+- 备注评分：星级展示（score ÷ 2 = 星数，支持半星，由 `ai-icons.js` 渲染）
+
+## AI 应用编号映射（PRD 补充）
+| 应用编号 | 功能 | cache_type | 展示位置 |
+|----------|------|------------|----------|
+| 应用 4 | 关系分析 + 任务建议 + 一句话总结（summary） | `app4_analysis` | 与我的关系 / 任务建议 / 卡片底部 AI 文字 |
+| 应用 5 | 话术参考（5 条话术） | — | 话术区域 |
+| 应用 6 | 备注评分（1-10 分，6 分为标准分） | `app6_note_analysis` | 备注弹窗提交后 |
+| 应用 7 | 客户分析（运营策略 + 总结） | `app7_customer_analysis` | 客户分析区域 |
+| 应用 8 | 维客线索整合（`member_retention_clue` 表） | — | 维客线索区域 |
+
+## AI 区域展示规则
+- 维客线索（应用 8）：Emoji 作为二级标签，提供者逗号分隔展示
+  - source=ai_consumption → "By:系统"
+  - source=ai_note → "By:备注"
+- 客户分析（应用 7）：运营策略数组 + 总结文本
+- 关系分析+任务建议+一句话总结（应用 4）
+- 话术参考（应用 5）：5 条话术，气泡/竖线样式展示
+- 备注评分（应用 6）：1-10 分，6 分为标准分
+
+## 备注弹窗规则
+- 底部弹出式弹窗（`.modal-overlay` + `.modal-card`）
+- 包含：多行文本输入 + 星星评分（再次服务意愿 + 再来店可能性）
+- 回访任务（task-detail-callback）：评分区域默认展开
+- 其他任务类型：评分区域默认隐藏，通过"展开评价"按钮手动打开
+- 星星打分交互：支持点击、触摸拖动、鼠标拖动（由 `task-detail-notes.js` 实现）
+
+### 备注评分与回访完成判定（PRD 补充）
+- 提交备注后，后端调用应用 6 进行评分（1-10 分，6 分为标准分）
+- 评分细则：综合备注文本质量、服务意愿星级、再来店可能性星级
+- 回访任务完成条件：备注评分 ≥ 5 → 任务标记完成；< 5 → 不算完成
+- 只计第一个备注的评分（后续备注不影响完成判定）
+- 回访任务有效期 2 天：超过 2 天未完成则标签跳变（回到任务列表重新分配）
+
+## 放弃客户弹窗（仅高优先/优先召回）
+- 遮罩层 + 居中弹窗
+- 包含：多行文本输入（放弃原因）+ 提交按钮（红色 `.danger`）
+- 空值校验：原因为空时显示错误提示
+- 关系构建和客户回访页面无"放弃"按钮
+
+## 底部操作栏
+- 「问问助手」按钮：渐变背景（颜色随主题变化），聊天气泡图标
+- 「备注」按钮：灰色背景，编辑笔图标
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 完整详情展示 | 有数据 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/xcx/tasks/{id}` | GET | 获取任务详情（含客户信息+AI 分析） |
+| `POST /api/xcx/notes` | POST | 创建备注（含评分，触发回访完成判定） |
+| `POST /api/xcx/tasks/{id}/abandon` | POST | 放弃任务（仅高优先/优先） |
+
+## 页面导航
+- 来源：task-list（点击任务卡片，按 task-type 跳转对应页面）
+- 去向：chat（问问助手）
+
+## 全局组件
+- 自定义顶部导航栏（返回按钮 + "任务详情"，高优先/优先召回右侧有"放弃"按钮）
+- AI 悬浮按钮

docs/h5_ui/interactions/task-list.md

@@ -0,0 +1,134 @@
+# 页面名：task-list（任务列表 + 业绩概览）
+
+> PRD 参考：P6 `docs/prd/specs/P6-miniapp-fe-tasks.md`；`apps/miniprogram/doc/prd.md` 第八节 8.1
+> 已实现：否
+
+## 页面说明
+小程序默认首页（Tab 1）。顶部 Banner 展示用户信息和业绩概览，下方为按优先级分组排序的任务列表。支持长按弹出操作菜单（置顶/放弃/问AI/备注）。
+
+## Banner 主题
+`banner-bg theme-blue texture-aurora`（蓝色主题 + 极光丝带纹理）
+
+## 状态变量
+| 变量名 | 类型 | 初始值 | 说明 |
+|--------|------|--------|------|
+| tasks | array | [] | 任务列表（按优先级分组） |
+| userInfo | object | null | 用户信息（花名、身份、门店） |
+| performanceData | object | null | 业绩概览（当月业绩、档位、工资预估、跳档激励） |
+| contextMenuVisible | boolean | false | 长按菜单显示状态 |
+| contextMenuPosition | object | {x,y} | 菜单弹出坐标 |
+| contextMenuTarget | element | null | 长按的目标卡片 |
+| remarkModalVisible | boolean | false | 备注/放弃弹窗显示状态 |
+| loading | boolean | true | 数据加载中 |
+| error | boolean | false | 加载失败 |
+
+## 用户操作 → 响应
+| 操作 | 触发条件 | 响应行为 | 目标状态 |
+|------|----------|----------|----------|
+| 页面加载 | 进入页面 | GET /api/xcx/tasks + 业绩数据 | loading→false |
+| 点击 Banner 业绩区域 | 无 | navigateTo performance 页面 | — |
+| 点击任务卡片 | 无 | 根据 task-type 跳转对应详情页（见跳转映射表） | — |
+| 长按任务卡片（500ms） | 触摸/鼠标按住 | 在按压坐标处弹出黑底浮层+白色菜单 | contextMenuVisible=true |
+| 菜单-「📌 置顶任务」 | 菜单显示 | POST /api/xcx/tasks/{id}/pin | 列表刷新，菜单关闭 |
+| 菜单-「❌ 放弃任务」 | 菜单显示 | 打开备注/放弃弹窗 | remarkModalVisible=true |
+| 菜单-「🤖 问问AI助手」 | 菜单显示 | navigateTo chat（带任务上下文引用） | 菜单关闭 |
+| 菜单-「📝 备注」 | 菜单显示 | 打开备注弹窗 | remarkModalVisible=true |
+| 弹窗-提交 | 文本非空 | POST 对应接口 | Toast 提示，弹窗关闭 |
+| 点击遮罩层 | contextMenuVisible=true | 关闭菜单 | contextMenuVisible=false |
+| 下拉刷新 | 无 | 重新请求任务列表 | loading=true |
+| 点击"重试" | error=true | 重新请求数据 | loading=true |
+
+## 任务卡片跳转映射
+| data-task-type | 跳转目标 |
+|----------------|----------|
+| high-priority | task-detail.html（高优先召回） |
+| priority | task-detail-priority.html（优先召回） |
+| relationship | task-detail-relationship.html（关系构建） |
+| callback | task-detail-callback.html（客户回访） |
+
+## 任务优先级定义（PRD 补充）
+| 优先级 | 类型 | 触发条件 | 标签颜色 |
+|--------|------|----------|----------|
+| P0 高优先召回 | high-priority | WBI + NCI > 7 | 红色 |
+| P0 优先召回 | priority | WBI + NCI > 5 | 橙色 |
+| P1 客户回访 | callback | 已完成召回但未备注（或备注评分 < 5） | 蓝色 |
+| P2 关系构建 | relationship | RS < 6 | 粉色 |
+
+> 列表内按优先级分组 → 组内按指数分数降序排列
+
+## 任务完成条件（PRD 补充）
+| 任务类型 | 完成条件 | 说明 |
+|----------|----------|------|
+| 召回（P0） | 客户出现新的服务订单 | 系统自动判定 |
+| 回访（P1） | 备注评分 ≥ 5（应用 6 评分） | 评分 < 5 不算完成；只计第一个备注；2 天有效期 |
+| 关系构建（P2） | RS 指数提升至 ≥ 6 | 系统自动判定 |
+
+## 任务卡片结构（忠于原型 HTML）
+- 外层 `.task-card`：左侧 4px 彩色边框（颜色随任务类型变化）
+- 置顶卡片额外 `.pinned` class（微亮边框阴影）
+- 内部结构：
+  - 第一行：任务类型标签（渐变背景圆角矩形）+ 客户昵称 + 关系 emoji + 备注指示器（📝，有备注时显示）
+  - 第二行：「最近到店：X天前 · 余额：XXX」
+  - 第三行：AI 机器人小图标 + AI 一句话智能建议文字（来源：AI 应用 4 的 `summary` 字段，`cache_type=app4_analysis`）
+  - 右侧：向右箭头 chevron
+
+## 列表分区结构
+1. 📌 置顶区域（amber 背景标签）：用户手动置顶的任务
+2. 一般任务区域（灰色背景标签）：按优先级分组 → 组内按分数降序
+3. ❌ 已放弃区域（灰色背景标签）：
+   - 卡片 `.abandoned`：opacity 0.55，左边框变灰，标签背景变灰，客户名变灰
+   - 无右侧箭头
+   - 显示放弃原因文字
+
+## 长按菜单样式
+- 遮罩层 `.context-overlay`（半透明黑色）
+- 白色菜单 `.context-menu`：min-width 192px，圆角 14px，阴影
+- 4 个菜单项，项间 1px 分隔线：
+  - 📌 置顶任务（已置顶时显示「取消置顶」）
+  - ❌ 放弃任务
+  - 🤖 问问AI助手
+  - 📝 备注
+
+## 业绩 Banner 展示
+- 用户花名 + 身份
+- 当月业绩进度条
+- 预计收入（标记"预估"）
+- 跳档激励：「到达 XXX 即得 YYY」
+  - YYY = max(跳档线差值最小值, 实际差值)
+  - 各档差值：Tier0→1: 1200元 / Tier1→2: 750元 / Tier2→3: 540元 / Tier3→4: 420元
+
+## 跟/弃 icon 规则（PRD 补充）
+- 跟：助教主动跟进中（绿色标记）
+- 弃：助教已放弃该客户（灰色标记）
+- 无标记：未分配助教或无跟进状态
+
+## 爱心 icon 规则
+💖(>8.5) / 🧡(>7) / 💛(>5) / 💙(<5)
+
+## 喜好标签
+🎱(中式) / 斯(斯诺克) / 🀅(麻将) / 🎤(团建)
+
+## 页面状态枚举
+| 状态名 | 视觉表现 | 触发条件 |
+|--------|----------|----------|
+| 加载中 | 区域文案"加载中..." | loading=true |
+| 正常态 | 任务列表 + 业绩 Banner | 有数据 |
+| 空数据态 | "暂无任务" | tasks 为空 |
+| 错误态 | "加载失败，请点击重试" + 重试按钮 | error=true |
+
+## 后端 API 依赖
+| API | 方法 | 说明 |
+|-----|------|------|
+| `GET /api/xcx/tasks` | GET | 获取任务列表 |
+| `POST /api/xcx/tasks/{id}/pin` | POST | 置顶/取消置顶 |
+| `POST /api/xcx/tasks/{id}/abandon` | POST | 放弃任务 |
+| `POST /api/xcx/notes` | POST | 创建备注 |
+| `GET /api/performance/summary` | GET | 业绩概览 |
+
+## 页面导航
+- 来源：login（approved）/ TabBar 切换
+- 去向：task-detail* / performance / chat
+
+## 全局组件
+- 底部 TabBar（任务 active）— 由 `bottom-nav.js` 自动注入
+- AI 悬浮按钮（右下角，渐变动画背景，可爱机器人 SVG 图标，点击 → chat）