10 KiB
10 KiB
board-coach 页面数据来源排查
排查日期：2026-03-18 页面路径：pages/board-coach/board-coach 排查范围：board-coach.ts / board-coach.wxml / board-coach.wxss / board-coach.json + 引用工具函数
概览
| 分类 | 数量 | 说明 |
|---|---|---|
| A. Mock 数据 | 1 组（6 条记录，含 ~20 个字段/条） | 页面内联 MOCK_COACHES 数组，未引用 utils/mock-data.ts |
| B. 硬编码数据 | 6 组常量 + 3 个默认值 | 排序/技能/时间选项、等级/技能样式映射、默认筛选值 |
| C. 已对接 API | 0 | 全部数据来自 Mock，无任何 wx.request / service 调用 |
| D. 前端计算/派生数据 | 10 个派生字段 | loadData() 中通过 formatMoney/formatHours/formatCount 生成展示标签 |
| E. 路由参数 | 0 | onLoad() 未读取任何 query 参数 |
| F. WXML 硬编码文案 | 14 处 | Tab 标签、状态提示、维度标签等 |
一、Mock 数据
1.1 页面内联 Mock：MOCK_COACHES（board-coach.ts L82-L161）
页面顶部定义了 const MOCK_COACHES: CoachItem[]，包含 6 位助教的完整数据。loadData() 通过 setTimeout(400ms) 模拟异步加载后直接使用该数组。
未引用 utils/mock-data.ts 中的 mockCoaches（该文件有独立的 CoachCard 接口和 3 条记录，字段结构不同）。
| Mock 字段 | 类型 | 示例值 | 联调时应替换为 |
|---|---|---|---|
id |
string | 'c1' |
API 返回的助教 ID |
name |
string | '小燕' |
助教姓名 |
initial |
string | '小' |
前端根据 name 首字计算，或 API 返回头像 URL |
avatarGradient |
string | 'blue' |
API 返回头像 URL 后可移除，改用真实头像 |
level |
string | 'star' |
助教等级（API：star/senior/middle/junior） |
skills |
Array | [{text:'🎱', cls:'skill--chinese'}] |
API 返回技能列表，前端映射 cls |
topCustomers |
string[] | ['💖 王先生','💖 李女士'] |
API 返回 top 客户列表（含亲密度标记） |
perfHours |
number | 86.2 |
定档业绩课时（API 聚合） |
perfHoursBefore |
number? | 92.0 |
折前课时（API 聚合） |
perfGap |
string? | '距升档 13.8h' |
可由前端计算或 API 直接返回 |
perfReached |
boolean | false |
是否已达标（API 或前端判断） |
salary |
number | 12680 |
预估工资（API 聚合） |
salaryPerfHours |
number | 86.2 |
工资维度-定档课时 |
salaryPerfBefore |
number? | 92.0 |
工资维度-折前课时 |
svAmount |
number | 45200 |
客源储值金额（API 聚合） |
svCustomerCount |
number | 18 |
储值客户数 |
svConsume |
number | 8600 |
储值消耗金额 |
taskRecall |
number | 18 |
召回任务完成数 |
taskCallback |
number | 14 |
回访任务完成数 |
联调替换目标 API（待后端提供）：
GET /api/v1/board/coach/list
Query: sort={selectedSort}&skill={selectedSkill}&time={selectedTime}
Response: { coaches: CoachItem[] }
二、硬编码数据
2.1 筛选选项常量（board-coach.ts L14-L50）
| 常量名 | 字段数 | 风险 | 说明 |
|---|---|---|---|
SORT_OPTIONS |
6 项 | 🟡 中 | 排序维度选项，value/text 写死。若后端新增排序维度需同步修改 |
SKILL_OPTIONS |
5 项 | 🟡 中 | 技能筛选选项，含 emoji。若门店技能类型可配置则需改为 API 获取 |
TIME_OPTIONS |
6 项 | 🟢 低 | 时间范围选项，纯前端逻辑，变动概率低 |
SORT_TO_DIM |
6 项映射 | 🟢 低 | 排序值→维度类型映射，纯前端 UI 逻辑 |
2.2 样式映射常量（board-coach.ts L53-L68）
| 常量名 | 风险 | 说明 |
|---|---|---|
LEVEL_CLASS |
🟢 低 | 等级→CSS 类映射，含中英文 key 兼容。纯前端样式逻辑 |
SKILL_CLASS |
🟢 低 | 技能 emoji→CSS 类映射。纯前端样式逻辑 |
2.3 data 对象默认值（board-coach.ts L165-L180）
| 字段 | 硬编码值 | 风险 | 说明 |
|---|---|---|---|
selectedSort |
'perf_desc' |
🟢 低 | 默认排序，合理默认值 |
selectedSkill |
'all' |
🟢 低 | 默认不限技能 |
selectedTime |
'month' |
🟢 低 | 默认本月 |
dimType |
'perf' |
🟢 低 | 默认维度类型，与 selectedSort 联动 |
filterBarVisible |
true |
🟢 低 | 筛选栏初始可见 |
pageState |
'loading' |
🟢 低 | 页面初始状态 |
activeTab |
'coach' |
🟢 低 | 当前 Tab 标识 |
2.4 loadData() 中的模拟延迟（board-coach.ts L195）
setTimeout(() => { ... }, 400) // 🔴 高风险：联调时必须替换为真实 API 调用
2.5 onPullDownRefresh 中的延迟（board-coach.ts L192）
setTimeout(() => wx.stopPullDownRefresh(), 500) // 🟡 中风险：联调后应在 API 回调中停止
三、已对接 API
无。 当前页面 0 个 API 调用，全部数据来自页面内联 Mock。
页面中存在的导航跳转（非数据 API）：
wx.switchTab({ url: '/pages/board-finance/board-finance' })— Tab 切换wx.navigateTo({ url: '/pages/board-customer/board-customer' })— Tab 切换wx.navigateTo({ url: '/pages/coach-detail/coach-detail?id=' + id })— 助教详情跳转
四、前端计算/派生数据
4.1 loadData() 中的格式化派生字段（board-coach.ts L197-L208）
| 派生字段 | 源字段 | 格式化函数 | 输出示例 |
|---|---|---|---|
perfHoursLabel |
perfHours |
formatHours() |
'86.2h' |
perfHoursBeforeLabel |
perfHoursBefore |
formatHours() |
'92h' |
salaryLabel |
salary |
formatMoney() |
'¥12,680' |
salaryPerfHoursLabel |
salaryPerfHours |
formatHours() |
'86.2h' |
salaryPerfBeforeLabel |
salaryPerfBefore |
formatHours() |
'92h' |
svAmountLabel |
svAmount |
formatMoney() |
'¥45,200' |
svCustomerCountLabel |
svCustomerCount |
formatCount(n,'人') |
'18人' |
svConsumeLabel |
svConsume |
formatMoney() |
'¥8,600' |
taskRecallLabel |
taskRecall |
formatCount(n,'次') |
'18次' |
taskCallbackLabel |
taskCallback |
formatCount(n,'次') |
'14次' |
4.2 维度类型切换（board-coach.ts L218-L222）
onSortChange 根据 SORT_TO_DIM 映射计算 dimType，控制 WXML 中四种卡片模板的条件渲染。
4.3 滚动隐藏/显示筛选栏（board-coach.ts L196-L215 onPageScroll）
纯前端交互逻辑：累积滚动距离超过阈值（上滑 12px / 下滑 24px）时切换 filterBarVisible。
五、路由参数
无。 onLoad() 未接收任何 options 参数。
六、WXML 硬编码文案
| 位置 | 硬编码文案 | 风险 | 建议 |
|---|---|---|---|
| 加载态 | 加载中... |
🟢 低 | 通用文案，可保留 |
| 空状态 | 暂无助教数据 |
🟢 低 | 可保留 |
| 错误态 | 加载失败 |
🟢 低 | 可保留 |
| 重试按钮 | 点击重试 |
🟢 低 | 可保留 |
| Tab-财务 | 财务 |
🟢 低 | 固定 Tab 文案 |
| Tab-客户 | 客户 |
🟢 低 | 固定 Tab 文案 |
| Tab-助教 | 助教 |
🟢 低 | 固定 Tab 文案 |
| 定档维度标签 | 定档 / 折前 |
🟢 低 | 业务术语，可保留 |
| 工资维度标签 | 预估 |
🟢 低 | 业务术语 |
| 储值维度标签 | 储值 |
🟢 低 | 业务术语 |
| 召回维度标签 | 召回 |
🟢 低 | 业务术语 |
| 达标标记 | ✅ 已达标 |
🟢 低 | 可保留 |
| 工资底部 | 定档 / 折前 |
🟢 低 | 同上 |
| 储值底部 | 客户 / 消耗 / | 分隔符 |
🟢 低 | 业务术语 |
| 任务底部 | 回访 |
🟢 低 | 业务术语 |
| 导航栏标题 | 助教看板（board-coach.json） |
🟢 低 | 固定页面标题 |
七、引用组件清单
| 组件 | 来源 | 数据依赖 |
|---|---|---|
coach-level-tag |
自定义组件 | 接收 level 属性 |
filter-dropdown |
自定义组件 | 接收 label/options/value，触发 change 事件 |
ai-float-button |
自定义组件 | 无数据依赖 |
board-tab-bar |
自定义 Tab Bar | 接收 active="board" |
t-loading / t-empty |
TDesign 组件 | 无业务数据依赖 |
dev-fab |
开发调试组件 | wx:if="{{false}}" 已禁用 |
八、联调 TODO
🔴 P0 — 必须完成
- 替换
MOCK_COACHES为 API 调用：移除页面内联 Mock 数组，loadData()改为调用后端接口- 需后端提供：助教列表接口（含排序/技能/时间筛选参数）
- 接口需返回：四种维度的全部字段（perf/salary/sv/task）
- 错误处理：API 失败时
setData({ pageState: 'error' })
- 移除
setTimeout(400ms)模拟延迟：替换为真实异步请求 onPullDownRefresh改为 API 回调中停止：wx.stopPullDownRefresh()应在请求完成后调用
🟡 P1 — 建议完成
- 筛选联动 API：当前
onSortChange/onSkillChange/onTimeChange仅更新本地状态，未触发重新请求。联调时需在筛选变更后重新调用 API - 头像方案确认：当前使用
initial（首字）+avatarGradient（渐变色）模拟头像。确认是否改为真实头像 URL perfGap字段来源确认：当前为 Mock 字符串（如'距升档 13.8h'），确认由后端计算还是前端根据阈值计算topCustomers格式确认：当前含 emoji 亲密度标记（💖/💛），确认 API 返回格式
🟢 P2 — 可后续优化
SKILL_OPTIONS是否需要动态获取：若门店技能类型可配置，应改为 API 获取SORT_OPTIONS/TIME_OPTIONS是否需要后端控制：当前写死，若需动态调整需改为配置化- 清理
utils/mock-data.ts中的CoachCard接口：与页面内联CoachItem接口不一致，联调完成后统一或移除 levelClass字段：当前在 Mock 中预计算，联调后应由前端根据level字段通过LEVEL_CLASS映射生成