213 lines
11 KiB
Markdown
213 lines
11 KiB
Markdown
# performance 页面数据来源排查
|
||
|
||
> 排查日期：2026-03-18
|
||
> 页面路径：pages/performance/performance
|
||
|
||
## 概览
|
||
|
||
| 分类 | 数量 | 说明 |
|
||
|------|------|------|
|
||
| A. Mock 数据（页面内联） | 4 组 | incomeItems / thisMonthRecords / newCustomers / regularCustomers，全部在 `loadData()` 的 `setTimeout` 中硬构造 |
|
||
| B. 硬编码数据 | 11 个字段 | Banner 个人信息、收入档位、月度合计等，写死在 `data` 初始值中 |
|
||
| C. 已对接 API | 0 | 页面无任何 `wx.request` 调用，无 API 对接 |
|
||
| D. 前端计算/派生数据 | 3 个 | 展开/收起状态、AI 配色、pageState |
|
||
| E. 路由参数 | 0 | `onLoad()` 未读取任何路由参数 |
|
||
| F. WXML 硬编码文案 | 28+ 处 | 标题、标签、提示文字等 |
|
||
|
||
---
|
||
|
||
## 一、Mock 数据（页面内联 mock，`loadData()` 内 setTimeout 构造）
|
||
|
||
> 页面未 import `utils/mock-data.ts`，所有 mock 数据均为 `loadData()` 方法内局部变量。
|
||
|
||
| # | 字段/变量 | 类型 | 位置 | 说明 |
|
||
|---|-----------|------|------|------|
|
||
| A1 | `incomeItems` | `IncomeItem[]` | `loadData()` 局部变量 | 4 条业绩明细：基础课 / 激励课 / 充值激励 / TOP3 销冠奖，icon + label + desc + value 全部硬写 |
|
||
| A2 | `thisMonthRecords` | `DateGroup[]` | `loadData()` 局部变量 | 4 个日期组、共 7 条服务记录，含客户名 / 头像 / 时间 / 课时 / 课程类型 / 台位 / 收入 |
|
||
| A3 | `newCustomers` | `Array<{...}>` | `loadData()` 局部变量 | 8 条新客数据：姓名 / 头像 / 最近服务日期 / 服务次数 |
|
||
| A4 | `regularCustomers` | `Array<{...}>` | `loadData()` 局部变量 | 8 条常客数据：姓名 / 头像 / 累计课时 / 累计收入 / 服务次数 |
|
||
| A5 | `gradients` | `string[]` | `loadData()` 局部变量 | 头像配色数组 `['blue','pink','teal',...]`，用于给 mock 数据分配 avatarColor |
|
||
|
||
### Mock 数据内部字段明细
|
||
|
||
**incomeItems 每条字段：**
|
||
| 字段 | 示例值 | 联调时对应 API 字段（待定） |
|
||
|------|--------|---------------------------|
|
||
| `icon` | `'🎱'` | — |
|
||
| `label` | `'基础课'` | 收入类型名称 |
|
||
| `desc` | `'80元/h × 75h'` | 单价 × 课时的计算描述 |
|
||
| `value` | `'¥6,000'` | 该类型收入金额 |
|
||
|
||
**thisMonthRecords → DateGroup 字段：**
|
||
| 字段 | 示例值 | 联调时对应 API 字段（待定） |
|
||
|------|--------|---------------------------|
|
||
| `date` | `'2月7日'` | 服务日期 |
|
||
| `totalHours` | `'4.0h'` | 当日总课时 |
|
||
| `totalIncome` | `'¥350'` | 当日总收入 |
|
||
|
||
**thisMonthRecords → ServiceRecord 字段：**
|
||
| 字段 | 示例值 | 联调时对应 API 字段（待定） |
|
||
|------|--------|---------------------------|
|
||
| `customerName` | `'王先生'` | 客户姓名 |
|
||
| `avatarChar` | `'王'` | 姓氏首字（前端可派生） |
|
||
| `avatarColor` | `'blue'` | 头像配色（前端可派生） |
|
||
| `timeRange` | `'20:00-22:00'` | 服务时间段 |
|
||
| `hours` | `'2.0h'` | 服务时长 |
|
||
| `courseType` | `'基础课'` | 课程类型 |
|
||
| `courseTypeClass` | `'tag-basic'` | CSS 类名（前端派生） |
|
||
| `location` | `'3号台'` | 台位/包厢 |
|
||
| `income` | `'¥160'` | 该次服务预估收入 |
|
||
|
||
**newCustomers 每条字段：**
|
||
| 字段 | 示例值 | 联调时对应 API 字段（待定） |
|
||
|------|--------|---------------------------|
|
||
| `name` | `'王先生'` | 客户姓名 |
|
||
| `avatarChar` | `'王'` | 姓氏首字（前端可派生） |
|
||
| `avatarColor` | `'blue'` | 头像配色（前端可派生） |
|
||
| `lastService` | `'2月7日'` | 最近服务日期 |
|
||
| `count` | `2` | 服务次数 |
|
||
|
||
**regularCustomers 每条字段：**
|
||
| 字段 | 示例值 | 联调时对应 API 字段（待定） |
|
||
|------|--------|---------------------------|
|
||
| `name` | `'张先生'` | 客户姓名 |
|
||
| `avatarChar` | `'张'` | 姓氏首字（前端可派生） |
|
||
| `avatarColor` | `'teal'` | 头像配色（前端可派生） |
|
||
| `hours` | `12` | 累计课时（number） |
|
||
| `income` | `'¥960'` | 累计收入 |
|
||
| `count` | `6` | 服务次数 |
|
||
|
||
---
|
||
|
||
## 二、硬编码数据（`Page.data` 初始值）
|
||
|
||
| # | 字段 | 硬编码值 | 说明 |
|
||
|---|------|----------|------|
|
||
| B1 | `coachName` | `'小燕'` | 助教姓名，应从登录态/API 获取 |
|
||
| B2 | `coachRole` | `'助教'` | 角色标签，应从用户信息获取 |
|
||
| B3 | `storeName` | `'广州朗朗桌球'` | 门店名称，应从用户绑定门店获取 |
|
||
| B4 | `monthlyIncome` | `'¥6,206'` | 本月预计收入，应从 API 获取 |
|
||
| B5 | `lastMonthIncome` | `'¥16,880'` | 上月收入，应从 API 获取 |
|
||
| B6 | `currentTier.basicRate` | `80` | 当前档位基础课单价（元/h） |
|
||
| B7 | `currentTier.incentiveRate` | `95` | 当前档位激励课单价（元/h） |
|
||
| B8 | `nextTier.basicRate` | `90` | 下一档位基础课单价（元/h） |
|
||
| B9 | `nextTier.incentiveRate` | `114` | 下一档位激励课单价（元/h） |
|
||
| B10 | `upgradeHoursNeeded` | `15` | 距下一阶段所需课时 |
|
||
| B11 | `upgradeBonus` | `800` | 到达下一阶段奖金（元） |
|
||
| B12 | `monthlyTotal` | `'¥6,950.5'` | 本月合计预估收入 |
|
||
| B13 | `visibleRecordGroups` | `2` | 默认显示前 N 条日期组（UI 配置，可保留硬编码） |
|
||
|
||
---
|
||
|
||
## 三、已对接 API
|
||
|
||
**无。** 页面中不存在任何 `wx.request`、API 服务调用、或从 `getApp()` 获取全局数据的逻辑。
|
||
|
||
`loadData()` 使用 `setTimeout(500ms)` 模拟异步加载，内部全部为内联 mock 数据。
|
||
|
||
文件头部注释明确标注：`// TODO: 联调时替换为真实 API 调用`
|
||
|
||
---
|
||
|
||
## 四、前端计算/派生数据
|
||
|
||
| # | 字段 | 来源 | 说明 |
|
||
|---|------|------|------|
|
||
| D1 | `pageState` | 前端状态机 | `'loading' → 'normal' / 'error' / 'empty'`，由 `loadData()` 控制 |
|
||
| D2 | `aiColor` | `initPageAiColor('performance')` | 从 `utils/ai-color-manager.ts` 获取，固定返回 `'blue'` |
|
||
| D3 | `thisMonthRecordsExpanded` | 前端 toggle | 服务记录展开/收起状态，默认 `false` |
|
||
| D4 | `newCustomerExpanded` | 前端 toggle | 新客列表展开/收起状态，默认 `false` |
|
||
| D5 | `regularCustomerExpanded` | 前端 toggle | 常客列表展开/收起状态，默认 `false` |
|
||
|
||
---
|
||
|
||
## 五、路由参数
|
||
|
||
**无。** `onLoad()` 未接收任何路由参数（`options` 未使用）。
|
||
|
||
页面作为业绩总览入口，当前设计不依赖路由传参。联调后可能需要接收 `coachId` / `month` 等参数。
|
||
|
||
---
|
||
|
||
## 六、WXML 硬编码文案
|
||
|
||
| # | 文案内容 | 位置 | 说明 |
|
||
|---|----------|------|------|
|
||
| F1 | `加载中...` | 加载态 toast | 可保留 |
|
||
| F2 | `暂无业绩数据` | 空数据态 | 可保留 |
|
||
| F3 | `加载失败，请点击重试` | 错误态 | 可保留 |
|
||
| F4 | `重试` | 错误态按钮 | 可保留 |
|
||
| F5 | `本月预计收入` | Banner 收入卡片标签 | 可保留 |
|
||
| F6 | `上月收入` | Banner 收入卡片标签 | 可保留 |
|
||
| F7 | `收入情况` | section 标题 | 可保留 |
|
||
| F8 | `当前档位`（×2） | 档位卡片 badge + label | 可保留 |
|
||
| F9 | `元/h`（×4） | 费率单位 | 可保留 |
|
||
| F10 | `基础课到手`（×2） | 费率描述 | 可保留 |
|
||
| F11 | `激励课到手`（×2） | 费率描述 | 可保留 |
|
||
| F12 | `下一阶段`（×2） | 档位卡片 badge + label | 可保留 |
|
||
| F13 | `距离下一阶段` | 升级提示标签 | 可保留 |
|
||
| F14 | `需完成 ... 小时` | 升级提示（含动态插值） | 可保留 |
|
||
| F15 | `到达即得` | 升级奖金标签 | 可保留 |
|
||
| F16 | `元`（奖金后缀） | 升级奖金值 | 可保留 |
|
||
| F17 | `本月业绩 预估` | section 标题 | 可保留 |
|
||
| F18 | `本月合计 预估` | 合计行标签 | 可保留 |
|
||
| F19 | `📋 我的服务记录明细` | 服务记录 header | 可保留 |
|
||
| F20 | `展开更多` / `收起` | 服务记录 toggle | 可保留 |
|
||
| F21 | `查看全部` | 跳转业绩记录按钮 | 可保留 |
|
||
| F22 | `我的预估收入` | 服务记录行内文案 | 可保留 |
|
||
| F23 | `我的新客` | section 标题 | 可保留 |
|
||
| F24 | `最近服务:` | 新客详情前缀 | 可保留 |
|
||
| F25 | `次` | 新客服务次数后缀 | 可保留 |
|
||
| F26 | `查看更多 ↓` / `收起 ↑` | 新客/常客 toggle | 可保留 |
|
||
| F27 | `我的常客` | section 标题 | 可保留 |
|
||
| F28 | `📊` / `🎯` / `⏱️` | 档位/升级提示 emoji | 可保留 |
|
||
| F29 | `业绩详情` | `performance.json` → `navigationBarTitleText` | 可保留 |
|
||
|
||
---
|
||
|
||
## 七、联调 TODO
|
||
|
||
### 7.1 需要对接的 API（按优先级排序）
|
||
|
||
| 优先级 | API 用途 | 涉及字段 | 备注 |
|
||
|--------|----------|----------|------|
|
||
| P0 | 助教个人信息 | B1 `coachName`, B2 `coachRole`, B3 `storeName` | 可从登录态/全局 store 获取 |
|
||
| P0 | 本月/上月收入概览 | B4 `monthlyIncome`, B5 `lastMonthIncome` | Banner 核心数据 |
|
||
| P0 | 收入档位信息 | B6-B9 `currentTier.*`, `nextTier.*`, B10 `upgradeHoursNeeded`, B11 `upgradeBonus` | 档位规则可能来自配置表 |
|
||
| P0 | 本月业绩明细 | A1 `incomeItems`, B12 `monthlyTotal` | 基础课/激励课/充值激励/奖金 |
|
||
| P1 | 服务记录列表（按日期分组） | A2 `thisMonthRecords` | 需支持分页或按月查询 |
|
||
| P1 | 新客列表 | A3 `newCustomers` | 本月新服务的客户 |
|
||
| P1 | 常客列表 | A4 `regularCustomers` | 累计服务数据 |
|
||
|
||
### 7.2 联调时需要处理的事项
|
||
|
||
- [ ] 移除 `loadData()` 中的 `setTimeout` 模拟延迟
|
||
- [ ] 移除所有内联 mock 数据（incomeItems / thisMonthRecords / newCustomers / regularCustomers）
|
||
- [ ] 替换 Banner 区域硬编码字段（coachName / coachRole / storeName / monthlyIncome / lastMonthIncome）
|
||
- [ ] 替换收入档位硬编码（currentTier / nextTier / upgradeHoursNeeded / upgradeBonus / monthlyTotal）
|
||
- [ ] 添加 `wx.request` 或封装的 API 调用
|
||
- [ ] 处理 API 错误 → 设置 `pageState: 'error'`
|
||
- [ ] 处理空数据 → 设置 `pageState: 'empty'`
|
||
- [ ] `avatarChar` / `avatarColor` / `courseTypeClass` 等前端派生字段需确认是后端返回还是前端计算
|
||
- [ ] `onLoad()` 可能需要接收路由参数（如 `coachId`、`month`）
|
||
- [ ] 金额格式化（`¥` 前缀、千分位）确认由后端返回还是前端处理
|
||
- [ ] 服务记录的 `taskId` 字段当前 mock 中未提供，但 `onRecordTap` 已预留读取逻辑
|
||
|
||
### 7.3 页面引用的外部依赖
|
||
|
||
| 依赖 | 类型 | 来源 | 数据影响 |
|
||
|------|------|------|----------|
|
||
| `ai-color-manager.ts` | 工具函数 | `utils/` | 仅提供 AI 图标配色，无业务数据 |
|
||
| `ai-float-button` | 自定义组件 | `components/` | AI 悬浮按钮，无业务数据 |
|
||
| `dev-fab` | 自定义组件 | `components/` | 开发调试按钮，无业务数据 |
|
||
| `metric-card` | 自定义组件 | `components/` | 已注册但 WXML 中未使用 |
|
||
| `t-icon` / `t-loading` | TDesign 组件 | `tdesign-miniprogram` | UI 组件，无业务数据 |
|
||
| `mock-data.ts` | Mock 数据文件 | `utils/` | **未被本页面引用**（页面使用内联 mock） |
|
||
|
||
### 7.4 注意事项
|
||
|
||
1. 页面文件头部已有 `// TODO: 联调时替换为真实 API 调用` 注释
|
||
2. `loadData()` 内部也有 `// TODO: 替换为真实 API` 注释
|
||
3. `performance.json` 中注册了 `metric-card` 组件但 WXML 中未使用，联调时可清理或启用
|
||
4. 金额字段涉及助教收入计算，联调时需参考 DWD-DOC 标杆文档中的助教费用拆分规则（`assistant_pd_money` 陪打 / `assistant_cx_money` 超休）
|