814 lines
47 KiB
Markdown
814 lines
47 KiB
Markdown
# 小程序管理层视角 Storyboard 走查报告 — API 需求 Gap 分析
|
||
|
||
> 走查日期：2026-03-18
|
||
> 走查角色：管理层/店长
|
||
> 走查路线：3 个看板 → 助教详情 → 客户详情 → 服务记录
|
||
> 对比基准：前端内联 mock 数据 vs API 契约 (`API-contract.md`) vs 八¾节 (`NS1-xcx-backend-api.md`)
|
||
|
||
---
|
||
|
||
## 场景 1：助教看板 → 助教详情 → 客户详情
|
||
|
||
### 1.1 board-coach（`pages/board-coach/board-coach.ts`）
|
||
|
||
#### API 调用
|
||
- `fetchBoardCoaches({ skill, sort, time })` → `CoachItem[]`
|
||
- 页面 `onLoad()` → `loadData()` → `fetchBoardCoaches()`
|
||
- 下拉刷新 `onPullDownRefresh()` → `loadData()`
|
||
- ⚠️ 筛选变更（`onSortChange`/`onSkillChange`/`onTimeChange`）仅更新 data 状态，**不调用 `loadData()`**（八¾节 F1 已记录）
|
||
|
||
#### 前端期望字段（从内联 MOCK_COACHES 的 CoachItem 接口提取，共 18 个字段）
|
||
|
||
| 字段 | 类型 | 说明 | 数据源 |
|
||
|------|------|------|--------|
|
||
| `id` | string | 助教 ID | dim_assistant |
|
||
| `name` | string | 助教姓名 | dim_assistant |
|
||
| `initial` | string | 姓名首字（头像占位） | 前端可计算 |
|
||
| `avatarGradient` | string | 头像渐变色 (blue/green/pink/amber/violet/cyan) | 前端可计算或后端分配 |
|
||
| `level` | string | 等级 key: star/senior/middle/junior | dim_assistant |
|
||
| `levelClass` | string | 等级样式类 | 前端可映射（LEVEL_CLASS 常量） |
|
||
| `skills` | `Array<{text: string, cls: string}>` | 技能列表含 emoji 和样式类 | cfg 表 |
|
||
| `topCustomers` | `string[]` | Top 客户列表含 emoji 前缀（如 `'💖 王先生'`） | dws_member_assistant_relation_index |
|
||
| `perfHours` | number | 当期定档工时 | dws_assistant_salary_calc |
|
||
| `perfHoursBefore` | number? | 上期定档工时（可选） | dws_assistant_salary_calc (上期) |
|
||
| `perfGap` | string? | 距升档差距描述（如 `"距升档 13.8h"`，已达标时不返回） | 后端计算 |
|
||
| `perfReached` | boolean | 是否已达标 | 后端计算 |
|
||
| `salary` | number | 工资总额(元) | dws_assistant_salary_calc |
|
||
| `salaryPerfHours` | number | 定档工时 | 同 perfHours |
|
||
| `salaryPerfBefore` | number? | 上期定档工时 | 同 perfHoursBefore |
|
||
| `svAmount` | number | 客源储值总额(元) | dws_member_consumption_summary |
|
||
| `svCustomerCount` | number | 储值客户数 | dws_member_consumption_summary |
|
||
| `svConsume` | number | 储值消耗额(元) | dws_member_consumption_summary |
|
||
| `taskRecall` | number | 召回任务完成数 | biz.coach_tasks |
|
||
| `taskCallback` | number | 回访任务完成数 | biz.coach_tasks |
|
||
|
||
#### 筛选参数映射
|
||
|
||
| 筛选项 | 前端参数 | 后端参数 | 查询影响 |
|
||
|--------|---------|---------|---------|
|
||
| 排序维度 | `sort`: perf_desc/perf_asc/salary_desc/salary_asc/sv_desc/task_desc | `sort` | 决定排序字段和方向 + 卡片模板(dimType) |
|
||
| 技能筛选 | `skill`: all/chinese/snooker/mahjong/karaoke | `skill` | WHERE 过滤助教技能类型 |
|
||
| 时间范围 | `time`: month/quarter/last_month/last_3m/last_quarter/last_6m | `time` | 决定统计日期区间 |
|
||
|
||
交叉约束：`time=last_6m` + `sort=sv_desc` 不兼容（TIME_OPTIONS 注释标注）
|
||
|
||
#### 页面跳转
|
||
- 点击助教卡片 `onCoachTap` → `/pages/coach-detail/coach-detail?id={coachId}`
|
||
- Tab 切换 → `board-finance`（switchTab）/ `board-customer`（navigateTo）
|
||
|
||
#### API 契约 vs Mock 数据 vs 八¾节 差异
|
||
|
||
| 差异项 | API 契约 (BOARD-1) | 前端 Mock (CoachItem) | 八¾节 (B1) | 严重度 |
|
||
|--------|--------------------|-----------------------|------------|--------|
|
||
| 字段结构 | 扁平简单：`id, name, avatar, level, level_class, skills(string[]), total_hours, total_income, customer_count, satisfaction` | 丰富结构：4 维度 20 个字段，skills 为对象数组，含 topCustomers | 与 Mock 一致，详细列出 4 维度字段 | 🔴 高 |
|
||
| `initial` 字段 | ❌ 无 | ✅ 有 | ✅ 有 | 🟠 中 |
|
||
| `avatarGradient` 字段 | ❌ 无（仅 `avatar` URL） | ✅ 有 | ✅ 有 | 🟠 中 |
|
||
| `skills` 类型 | `string[]` | `Array<{text, cls}>` | `Array<{text, cls}>` | 🔴 高 |
|
||
| `topCustomers` 字段 | ❌ 无 | ✅ 有 | ✅ 有 | 🔴 高 |
|
||
| 4 维度专属字段 | ❌ 全部缺失（仅 total_hours/total_income/customer_count/satisfaction） | ✅ 完整（perf/salary/sv/task 各 2-4 个字段） | ✅ 完整 | 🔴 高 |
|
||
| `sort` 参数格式 | `sort=field:direction` | `sort=perf_desc` 等枚举 | `sort=perf_desc` 等枚举 | 🟠 中 |
|
||
| 分页 | 无分页定义 | 无分页（全量返回） | 无分页 | 🟡 低 |
|
||
|
||
#### spec 未记录的 Gap
|
||
1. 🔴 API 契约 BOARD-1 响应字段与前端实际需求严重不匹配 — 契约仅定义 10 个通用字段，前端需要 20 个含 4 维度专属字段
|
||
2. 🔴 `skills` 类型不一致 — 契约为 `string[]`，前端需要 `Array<{text, cls}>`（含 emoji 和样式类）
|
||
3. 🔴 `topCustomers` 字段契约完全缺失 — 前端每个助教卡片展示 Top 3 客户
|
||
4. 🟠 `sort` 参数格式不一致 — 契约用 `field:direction`，前端用枚举值 `perf_desc`
|
||
5. 🟠 `initial`/`avatarGradient` 字段契约缺失 — 前端用于头像渲染，需确认由前端计算还是后端返回
|
||
|
||
---
|
||
|
||
### 1.2 coach-detail（`pages/coach-detail/coach-detail.ts`）
|
||
|
||
#### API 调用
|
||
- `fetchCoachDetail(coachId)` → `CoachCard | null`（api.ts 返回类型过于简单）
|
||
- 页面 `onLoad({ id })` → `loadData(id)` → `fetchCoachDetail(id)`
|
||
- 实际使用内联 mock 数据组装 CoachDetail 对象
|
||
|
||
#### 前端期望字段（从 mockCoachDetail + 各 mock 数组提取）
|
||
|
||
**CoachDetail 基础信息：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | string | 助教 ID |
|
||
| `name` | string | 助教姓名 |
|
||
| `avatar` | string | 头像 URL |
|
||
| `level` | string | 等级（中文：星级/高级/中级/初级） |
|
||
| `skills` | string[] | 技能列表 |
|
||
| `workYears` | number | 工龄 |
|
||
| `customerCount` | number | 客户数 |
|
||
| `hireDate` | string | 入职日期 |
|
||
|
||
**performance 绩效指标：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `performance.monthlyHours` | number | 本月定档业绩工时 |
|
||
| `performance.monthlySalary` | number | 本月工资（预估） |
|
||
| `performance.customerBalance` | number | 客源储值余额 |
|
||
| `performance.tasksCompleted` | number | 本月任务完成数 |
|
||
| `performance.perfCurrent` | number | 当前绩效值 |
|
||
| `performance.perfTarget` | number | 目标绩效值 |
|
||
|
||
**income 收入明细（本月/上月 Tab 切换）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `income.thisMonth` | `IncomeItem[]` | 本月收入明细（基础课时费/激励课时费/充值提成/酒水提成） |
|
||
| `income.lastMonth` | `IncomeItem[]` | 上月收入明细 |
|
||
| IncomeItem: `label` | string | 收入项名称 |
|
||
| IncomeItem: `amount` | string | 金额（格式化，如 `"¥3,500"`） |
|
||
| IncomeItem: `color` | string | 颜色标识 |
|
||
|
||
**任务执行区域（管理层视角核心）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `visibleTasks` | `TaskItem[]` | 可见任务（active 状态） |
|
||
| `hiddenTasks` | `TaskItem[]` | 隐藏任务（inactive 状态，被顶替但未过期） |
|
||
| `abandonedTasks` | `AbandonedTask[]` | 已放弃任务 |
|
||
| TaskItem: `typeLabel` | string | 任务类型标签（高优先召回/优先召回/关系构建/客户回访） |
|
||
| TaskItem: `typeClass` | string | 样式类（high-priority/priority/relationship/callback） |
|
||
| TaskItem: `customerName` | string | 客户姓名 |
|
||
| TaskItem: `noteCount` | number | 备注数量 |
|
||
| TaskItem: `pinned` | boolean | 是否置顶 |
|
||
| TaskItem: `notes` | `Array<{pinned?, text, date}>` | 备注列表（可选） |
|
||
| AbandonedTask: `customerName` | string | 客户姓名 |
|
||
| AbandonedTask: `reason` | string | 放弃原因 |
|
||
|
||
**客户关系 TOP20（管理层关注指标）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| TopCustomer: `id` | string | 客户 ID |
|
||
| TopCustomer: `name` | string | 客户姓名 |
|
||
| TopCustomer: `initial` | string | 姓名首字 |
|
||
| TopCustomer: `avatarGradient` | string | 头像渐变色 |
|
||
| TopCustomer: `heartEmoji` | string | 爱心 emoji（❤️/💛/🤍） |
|
||
| TopCustomer: `score` | string | 关系指数 |
|
||
| TopCustomer: `scoreColor` | string | 分数颜色（success/warning/gray） |
|
||
| TopCustomer: `serviceCount` | number | 服务次数 |
|
||
| TopCustomer: `balance` | string | 余额（格式化） |
|
||
| TopCustomer: `consume` | string | 消费额（格式化） |
|
||
|
||
**近期服务明细：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| ServiceRecord: `customerId` | string? | 客户 ID |
|
||
| ServiceRecord: `customerName` | string | 客户姓名 |
|
||
| ServiceRecord: `initial` | string | 姓名首字 |
|
||
| ServiceRecord: `avatarGradient` | string | 头像渐变色 |
|
||
| ServiceRecord: `type` | string | 课程类型（基础课/激励课） |
|
||
| ServiceRecord: `typeClass` | string | 样式类（basic/incentive） |
|
||
| ServiceRecord: `table` | string | 台桌号 |
|
||
| ServiceRecord: `duration` | string | 时长（格式化） |
|
||
| ServiceRecord: `income` | string | 收入（格式化） |
|
||
| ServiceRecord: `date` | string | 日期时间 |
|
||
| ServiceRecord: `perfHours` | string? | 定档工时（可选） |
|
||
|
||
**历史月份统计（管理层评估助教表现）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| HistoryMonth: `month` | string | 月份标签（本月/上月/4月...） |
|
||
| HistoryMonth: `estimated` | boolean | 是否预估 |
|
||
| HistoryMonth: `customers` | string | 客户数（格式化，如 `"22人"`） |
|
||
| HistoryMonth: `hours` | string | 工时（格式化，如 `"87.5h"`） |
|
||
| HistoryMonth: `salary` | string | 工资（格式化） |
|
||
| HistoryMonth: `callbackDone` | number | 回访完成数 |
|
||
| HistoryMonth: `recallDone` | number | 召回完成数 |
|
||
|
||
**备注列表：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| NoteItem: `id` | string | 备注 ID |
|
||
| NoteItem: `content` | string | 备注内容 |
|
||
| NoteItem: `timestamp` | string | 时间戳 |
|
||
| NoteItem: `score` | number | 评分 |
|
||
| NoteItem: `customerName` | string | 关联客户/管理员名 |
|
||
| NoteItem: `tagLabel` | string | 标签 |
|
||
| NoteItem: `createdAt` | string | 创建时间（格式化） |
|
||
|
||
**绩效进度条数据（前端需要后端提供）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `tierNodes` | number[] | 档位节点数组（如 `[0, 100, 130, 160, 190, 220]`） |
|
||
| `maxHours` | number | 最大工时（进度条满值） |
|
||
|
||
#### 筛选参数映射
|
||
- 无筛选项，单次加载全部数据
|
||
- 收入明细有本月/上月 Tab 切换（纯前端切换，数据一次性返回）
|
||
|
||
#### 页面跳转
|
||
- 点击任务项 `onTaskItemTap` → `/pages/customer-detail/customer-detail?name={customerName}`（⚠️ 用 name 而非 id）
|
||
- 点击客户卡片 `onCustomerTap` → `/pages/customer-detail/customer-detail?id={customerId}`
|
||
- 点击服务记录 `onSvcCardTap` → `/pages/customer-detail/customer-detail?id={customerId}`
|
||
- 查看更多服务记录 `onViewMoreRecords` → `/pages/performance-records/performance-records?coachId={coachId}`
|
||
- 问问助手 `onStartChat` → `/pages/chat/chat?coachId={coachId}`
|
||
|
||
#### API 契约 vs Mock 数据 vs 八¾节 差异
|
||
|
||
| 差异项 | API 契约 (COACH-1) | 前端 Mock | 八¾节 | 严重度 |
|
||
|--------|--------------------|-----------|----|--------|
|
||
| 返回类型 | api.ts 返回 `CoachCard`（仅 id/name/avatar/level/keyMetrics） | 实际需要 CoachDetail（含 performance/income/tasks/topCustomers/serviceRecords/historyMonths/notes） | 仅提到基本信息+任务分组+Top客户+服务记录 | 🔴 高 |
|
||
| `income` 本月/上月明细 | ❌ 无 | ✅ 有（4 项收入分类 × 2 月） | ❌ 无 | 🔴 高 |
|
||
| `topCustomers` TOP20 | 契约仅 `top_customers: Array<{id, name, avatar, total_spend, visit_count}>` | Mock 含 20 条，每条含 heartEmoji/score/scoreColor/serviceCount/balance/consume | ❌ 未详细定义字段 | 🔴 高 |
|
||
| `historyMonths` 历史月份 | ❌ 完全缺失 | ✅ 有（5 个月，含 estimated/customers/hours/salary/callbackDone/recallDone） | ❌ 完全缺失 | 🔴 高 |
|
||
| `tierNodes` 档位节点 | ❌ 缺失 | ✅ 有（进度条组件需要） | ❌ 缺失 | 🟠 中 |
|
||
| 任务分组 | `visible_tasks`/`hidden_tasks`/`abandoned_tasks` | 同，但 TaskItem 结构含 notes 子数组 | ✅ 已确认 active/inactive/abandoned 映射 | 🟡 低 |
|
||
| 备注列表 | ❌ 未在 COACH-1 定义 | ✅ 有（含 score 字段） | ❌ 未提及 | 🟠 中 |
|
||
|
||
#### spec 未记录的 Gap
|
||
1. 🔴 COACH-1 响应缺少 `income` 收入明细（本月/上月 4 项分类）— 管理层评估助教收入结构的核心数据
|
||
2. 🔴 COACH-1 响应缺少 `historyMonths` 历史月份统计 — 管理层评估助教长期表现趋势
|
||
3. 🔴 `topCustomers` 字段结构不完整 — 契约仅 5 个字段，前端需要 10 个字段（含 heartEmoji/scoreColor/balance/consume）
|
||
4. 🟠 COACH-1 响应缺少 `tierNodes`/`maxHours` — 绩效进度条组件需要档位节点数据
|
||
5. 🟠 COACH-1 响应缺少备注列表 — 管理层需要查看助教相关备注
|
||
6. 🟠 `onTaskItemTap` 用 `name` 而非 `id` 跳转客户详情 — 前端 Bug，name 不唯一
|
||
7. 🟡 api.ts 中 `fetchCoachDetail` 返回类型为 `CoachCard`（mock-data.ts 中的简单类型），与实际需要的 CoachDetail 不匹配
|
||
|
||
---
|
||
|
||
## 场景 2：客户看板 → 客户详情 → 客户服务记录
|
||
|
||
### 2.1 board-customer（`pages/board-customer/board-customer.ts`）
|
||
|
||
#### API 调用
|
||
- `fetchBoardCustomers({ dimension, project })` → `CustomerItem[]`
|
||
- 页面 `onLoad()` → `loadData()` → `fetchBoardCustomers()`
|
||
- 下拉刷新 `onPullDownRefresh()` → `loadData()`
|
||
- ⚠️ 筛选变更（`onDimensionChange`/`onProjectChange`）仅更新 data 状态，**不调用 `loadData()`**（八¾节 F2 已记录）
|
||
- ⚠️ 缺少分页参数 `page`/`pageSize`（八¾节 F3 已记录）
|
||
|
||
#### 前端期望字段（从内联 MOCK_CUSTOMERS 的 CustomerItem 接口提取）
|
||
|
||
**所有维度共享基础字段（每个 item 都返回）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | string | 客户 member_id |
|
||
| `name` | string | 客户姓名 |
|
||
| `initial` | string | 姓名首字 |
|
||
| `avatarCls` | string | 头像样式类（avatar--amber/pink/blue 等） |
|
||
| `assistants` | `AssistantInfo[]` | 关联助教列表 |
|
||
|
||
**AssistantInfo 结构：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | string | 助教姓名 |
|
||
| `cls` | string | 样式类（assistant--assignee/abandoned/normal） |
|
||
| `heartScore` | number | 爱心分 0-10 |
|
||
| `badge` | string? | 标记（跟/弃） |
|
||
| `badgeCls` | string? | 标记样式类 |
|
||
|
||
**8 维度专属字段（按 dimension 参数返回对应字段）：**
|
||
|
||
| 维度 | 专属字段 | 类型 | 说明 |
|
||
|------|---------|------|------|
|
||
| recall | `idealDays` | number | 理想到店间隔(天) |
|
||
| | `elapsedDays` | number | 已过天数 |
|
||
| | `overdueDays` | number | 超期天数 |
|
||
| | `visits30d` | number | 近30天到店次数 |
|
||
| | `balance` | string | 余额（格式化） |
|
||
| | `recallIndex` | string | 召回指数 |
|
||
| potential | `potentialTags` | `Array<{text, theme}>` | 潜力标签 |
|
||
| | `spend30d` | string | 近30天消费 |
|
||
| | `avgVisits` | string | 月均到店 |
|
||
| | `avgSpend` | string | 次均消费 |
|
||
| balance | `balance` | string | 当前余额 |
|
||
| | `lastVisit` | string | 最近到店 |
|
||
| | `monthlyConsume` | string | 月均消耗 |
|
||
| | `availableMonths` | string | 可用月数 |
|
||
| recharge | `lastRecharge` | string | 最后充值日期 |
|
||
| | `rechargeAmount` | string | 充值金额 |
|
||
| | `recharges60d` | string | 近60天充值次数 |
|
||
| | `currentBalance` | string | 当前余额 |
|
||
| recent | `daysAgo` | number | 距今天数 |
|
||
| | `visitFreq` | string | 到店频率 |
|
||
| | `idealDays` | number | 理想间隔 |
|
||
| | `visits30d` | number | 近30天到店 |
|
||
| | `avgSpend` | string | 次均消费 |
|
||
| spend60 | `spend60d` | string | 近60天消费总额 |
|
||
| | `visits60d` | string | 近60天到店次数 |
|
||
| | `highSpendTag` | boolean | 是否高消费标签 |
|
||
| | `avgSpend` | string | 次均消费 |
|
||
| freq60 | `visits60d` | string | 近60天到店次数 |
|
||
| | `avgInterval` | string | 平均到店间隔 |
|
||
| | `weeklyVisits` | `Array<{val, pct}>` | 8周到店柱状图 |
|
||
| | `spend60d` | string | 近60天消费 |
|
||
| loyal | `intimacy` | string | 亲密度指数 |
|
||
| | `topCoachName` | string | 最亲密助教姓名 |
|
||
| | `topCoachHeart` | number | 最亲密助教爱心分 |
|
||
| | `topCoachScore` | string | 最亲密助教关系指数 |
|
||
| | `coachName` | string | 主助教姓名 |
|
||
| | `coachRatio` | string | 主助教占比 |
|
||
| | `coachDetails` | `Array<{name, cls, heartScore, badge?, avgDuration, serviceCount, coachSpend, relationIdx}>` | 助教服务明细表 |
|
||
|
||
#### 筛选参数映射
|
||
|
||
| 筛选项 | 前端参数 | 后端参数 | 查询影响 |
|
||
|--------|---------|---------|---------|
|
||
| 维度切换 | `dimension`: recall/potential/balance/recharge/recent/spend60/freq60/loyal | `dimension` | 决定查询的 FDW 表和排序字段 |
|
||
| 项目筛选 | `project`: all/chinese/snooker/mahjong/karaoke | `project` | WHERE 过滤客户偏好项目 |
|
||
|
||
无交叉约束，8×5=40 种有效组合。
|
||
|
||
#### 页面跳转
|
||
- 点击客户卡片 `onCustomerTap` → `/pages/customer-detail/customer-detail?id={customerId}`
|
||
- Tab 切换 → `board-finance`（switchTab）/ `board-coach`（navigateTo）
|
||
|
||
#### API 契约 vs Mock 数据 vs 八¾节 差异
|
||
|
||
| 差异项 | API 契约 (BOARD-2) | 前端 Mock (CustomerItem) | 八¾节 (B2) | 严重度 |
|
||
|--------|--------------------|-----------------------|------------|--------|
|
||
| 字段结构 | 扁平简单：`id, name, avatar, tags(string[]), total_spend, visit_count, last_visit, relation_index` | 丰富结构：8 维度 40+ 专属字段 + assistants 对象数组 | 与 Mock 一致 | 🔴 高 |
|
||
| `assistants` 字段 | ❌ 无 | ✅ 有（含 name/cls/heartScore/badge/badgeCls） | ✅ 有 | 🔴 高 |
|
||
| `avatarCls` 字段 | ❌ 无（仅 `avatar` URL） | ✅ 有 | ✅ 有 | 🟠 中 |
|
||
| `initial` 字段 | ❌ 无 | ✅ 有 | ✅ 有 | 🟠 中 |
|
||
| 8 维度专属字段 | ❌ 全部缺失 | ✅ 完整 | ✅ 完整 | 🔴 高 |
|
||
| `weeklyVisits` 柱状图 | ❌ 无 | ✅ 有（freq60 维度，8 周数据） | ✅ 有 | 🔴 高 |
|
||
| `coachDetails` 明细表 | ❌ 无 | ✅ 有（loyal 维度，助教服务明细） | ✅ 有 | 🔴 高 |
|
||
| `potentialTags` 标签 | ❌ 无 | ✅ 有（potential 维度，含 text+theme） | ✅ 有 | 🟠 中 |
|
||
| 分页 | ✅ 有（page/pageSize） | ❌ 无（全量返回 3 条 mock） | ✅ 已确认 20 条懒加载 | 🟡 低 |
|
||
|
||
#### spec 未记录的 Gap
|
||
1. 🔴 API 契约 BOARD-2 响应字段与前端实际需求严重不匹配 — 契约仅 8 个通用字段，前端需要 40+ 维度专属字段
|
||
2. 🔴 `assistants` 关联助教列表契约完全缺失 — 每个客户卡片展示关联助教及其爱心分/跟弃状态
|
||
3. 🔴 `weeklyVisits` 8 周柱状图数据契约缺失 — freq60 维度的核心可视化数据
|
||
4. 🔴 `coachDetails` 助教服务明细表契约缺失 — loyal 维度展示每个助教的详细服务数据
|
||
5. 🟠 `potentialTags` 标签结构契约缺失 — potential 维度展示客户潜力标签
|
||
|
||
---
|
||
|
||
### 2.2 customer-detail（`pages/customer-detail/customer-detail.ts`）
|
||
|
||
#### API 调用
|
||
- `fetchCustomerDetail(customerId)` → `MockCustomerDetail | null`
|
||
- 页面 `onLoad()` → `loadDetail()` → `fetchCustomerDetail(id)`
|
||
- ⚠️ `loadDetail()` 中 id 获取方式有 Bug：`(this as any).__route__?.split('?')[1]` 无法正确解析 query 参数
|
||
|
||
#### 前端期望字段（从内联 data 提取，管理层视角）
|
||
|
||
**客户基础信息：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `detail.id` | string | 客户 ID |
|
||
| `detail.name` | string | 客户姓名 |
|
||
| `detail.avatarChar` | string | 头像字符 |
|
||
| `detail.phone` | string | 完整手机号（前端控制脱敏显示） |
|
||
| `detail.balance` | string | 余额（格式化） |
|
||
| `detail.consumption60d` | string | 近60天消费（格式化） |
|
||
| `detail.idealInterval` | string | 理想到店间隔 |
|
||
| `detail.daysSinceVisit` | string | 距上次到店天数 |
|
||
|
||
**AI 洞察（管理层视角特有）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `aiInsight.summary` | string | AI 分析摘要 |
|
||
| `aiInsight.strategies` | `Array<{color, text}>` | 策略建议列表 |
|
||
|
||
**维客线索（clues）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `clues[].category` | string | 线索大类（含换行符格式化） |
|
||
| `clues[].categoryColor` | string | 分类颜色 |
|
||
| `clues[].text` | string | 线索文本（含 emoji） |
|
||
| `clues[].source` | string | 来源（系统/助教名） |
|
||
| `clues[].detail` | string? | 详情（可选，展开显示） |
|
||
|
||
**关联助教 coachTasks（管理层关注多助教对同一客户的服务）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `coachTasks[].name` | string | 助教姓名 |
|
||
| `coachTasks[].level` | string | 等级 |
|
||
| `coachTasks[].levelColor` | string | 等级颜色 |
|
||
| `coachTasks[].taskType` | string | 任务类型标签 |
|
||
| `coachTasks[].taskColor` | string | 任务颜色 |
|
||
| `coachTasks[].bgClass` | string | 背景样式类 |
|
||
| `coachTasks[].status` | string | 状态（normal/pinned/abandoned） |
|
||
| `coachTasks[].lastService` | string | 最后服务时间 |
|
||
| `coachTasks[].metrics` | `Array<{label, value, color?}>` | 指标列表（近60天次数/总时长/次均时长） |
|
||
|
||
**喜好助教 favoriteCoaches：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `favoriteCoaches[].emoji` | string | 爱心 emoji |
|
||
| `favoriteCoaches[].name` | string | 助教姓名 |
|
||
| `favoriteCoaches[].relationIndex` | string | 关系指数 |
|
||
| `favoriteCoaches[].indexColor` | string | 指数颜色 |
|
||
| `favoriteCoaches[].bgClass` | string | 背景样式类 |
|
||
| `favoriteCoaches[].stats` | `Array<{label, value, color?}>` | 统计（基础/激励/上课/充值） |
|
||
|
||
**消费记录 consumptionRecords（3 种类型，管理层关注消费结构）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `ConsumptionRecord.id` | string | 记录 ID |
|
||
| `ConsumptionRecord.type` | `"table" \| "shop" \| "recharge"` | 消费类型 |
|
||
| `ConsumptionRecord.date` | string | 日期 |
|
||
| `ConsumptionRecord.tableName` | string? | 台桌名（table 类型） |
|
||
| `ConsumptionRecord.startTime` | string? | 开始时间 |
|
||
| `ConsumptionRecord.endTime` | string? | 结束时间 |
|
||
| `ConsumptionRecord.duration` | string? | 时长 |
|
||
| `ConsumptionRecord.tableFee` | number? | 台费（优惠后） |
|
||
| `ConsumptionRecord.tableOrigPrice` | number? | 台费原价 |
|
||
| `ConsumptionRecord.coaches` | `Array<{name, level, levelColor, courseType, hours, perfHours?, fee}>` | 助教服务明细 |
|
||
| `ConsumptionRecord.foodAmount` | number? | 食品酒水金额（优惠后） |
|
||
| `ConsumptionRecord.foodOrigPrice` | number? | 食品酒水原价 |
|
||
| `ConsumptionRecord.totalAmount` | number? | 总金额 |
|
||
| `ConsumptionRecord.totalOrigPrice` | number? | 总原价 |
|
||
| `ConsumptionRecord.payMethod` | string? | 支付方式 |
|
||
| `ConsumptionRecord.rechargeAmount` | number? | 充值金额（recharge 类型） |
|
||
|
||
**备注列表：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `sortedNotes[].id` | string | 备注 ID |
|
||
| `sortedNotes[].tagLabel` | string | 标签（管理员/助教名） |
|
||
| `sortedNotes[].createdAt` | string | 创建时间 |
|
||
| `sortedNotes[].content` | string | 备注内容 |
|
||
|
||
#### 页面跳转
|
||
- 查看服务记录 `onViewServiceRecords` → `/pages/customer-service-records/customer-service-records`（⚠️ 未传 customerId 参数！）
|
||
- 问问助手 `onStartChat` → `/pages/chat/chat`（⚠️ 未传 customerId 参数！）
|
||
|
||
#### API 契约 vs Mock 数据 差异
|
||
|
||
| 差异项 | API 契约 (CUST-1) | 前端 Mock | 严重度 |
|
||
|--------|--------------------|-----------| --------|
|
||
| `aiInsight` AI 洞察 | ❌ 完全缺失 | ✅ 有（summary + strategies） | 🔴 高 |
|
||
| `coachTasks` 关联助教任务 | ❌ 完全缺失 | ✅ 有（4 个助教，含 metrics） | 🔴 高 |
|
||
| `favoriteCoaches` 喜好助教 | ❌ 完全缺失 | ✅ 有（含 stats 统计） | 🔴 高 |
|
||
| `clues` 维客线索 | 契约有 `retention_clues` 但结构不同 | 前端用 category/categoryColor/text/source/detail | 🟠 中 |
|
||
| `consumptionRecords` 结构 | 契约为扁平 `{id, date, type, type_class, amount, table, duration}` | 前端为嵌套结构（含 coaches 子数组、tableFee/foodAmount 分项） | 🔴 高 |
|
||
| `balance`/`consumption60d`/`idealInterval`/`daysSinceVisit` | ❌ 缺失 | ✅ 有 | 🟠 中 |
|
||
| `avatarChar` | ❌ 无（仅 avatar URL） | ✅ 有 | 🟡 低 |
|
||
| 备注列表 | ❌ 未在 CUST-1 定义 | ✅ 有 | 🟠 中 |
|
||
|
||
#### spec 未记录的 Gap
|
||
1. 🔴 CUST-1 缺少 `aiInsight` AI 洞察 — 管理层查看客户时的核心决策辅助信息（来源：biz.ai_cache app4_analysis）
|
||
2. 🔴 CUST-1 缺少 `coachTasks` 关联助教任务区域 — 管理层关注多助教对同一客户的服务情况
|
||
3. 🔴 CUST-1 缺少 `favoriteCoaches` 喜好助教 — 展示客户与各助教的关系指数和服务统计
|
||
4. 🔴 CUST-1 消费记录结构严重不匹配 — 契约为扁平结构，前端需要嵌套结构（含助教明细、台费/食品分项、原价/优惠后价格）
|
||
5. 🟠 `onViewServiceRecords` 跳转未传 `customerId` — 前端 Bug
|
||
6. 🟠 `onStartChat` 跳转未传 `customerId` — 前端 Bug
|
||
7. 🟠 `loadDetail()` 中 id 解析方式有 Bug — 应从 `onLoad(options)` 的 options 中获取
|
||
|
||
---
|
||
|
||
### 2.3 customer-service-records（`pages/customer-service-records/customer-service-records.ts`）
|
||
|
||
#### API 调用
|
||
- `fetchCustomerRecords({ customerId })` → `{ records, hasMore }`
|
||
- 页面 `onLoad({ customerId, id })` → `loadData(id)` → `fetchCustomerRecords({ customerId: id })`
|
||
- ⚠️ 首次加载拉取全部记录，月份切换仅本地过滤（八¾节 F10/L4 已记录）
|
||
|
||
#### 前端期望字段
|
||
|
||
**页面头部信息：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `customerName` | string | 客户姓名 |
|
||
| `customerPhone` | string | 脱敏手机号 |
|
||
| `customerPhoneFull` | string | 完整手机号 |
|
||
| `totalServiceCount` | number | 累计服务次数 |
|
||
| `relationIndex` | string | 关系指数 |
|
||
|
||
**ServiceRecord 结构（转换后）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `table` | string | 台桌号 |
|
||
| `type` | string | 课程类型标签 |
|
||
| `typeClass` | `'basic' \| 'vip' \| 'tip' \| 'recharge'` | 样式类 |
|
||
| `recordType` | `'course' \| 'recharge'` | 记录类型 |
|
||
| `duration` | number | 折算后小时数 |
|
||
| `durationRaw` | number | 折算前小时数 |
|
||
| `income` | number | 到手金额 |
|
||
| `isEstimate` | boolean | 是否预估 |
|
||
| `drinks` | string | 饮品描述 |
|
||
| `date` | string | 显示日期+时间段 |
|
||
|
||
#### 筛选参数映射
|
||
|
||
| 筛选项 | 前端参数 | 后端参数 | 查询影响 |
|
||
|--------|---------|---------|---------|
|
||
| 月份切换 | `currentYear`/`currentMonth` | `year`/`month` | 按月筛选记录（当前为本地过滤） |
|
||
| 客户 ID | `customerId` | `customerId` | WHERE 过滤 |
|
||
|
||
#### 页面跳转
|
||
- 无跳转（详情页，仅返回上一页）
|
||
|
||
#### API 契约 vs Mock 数据 差异
|
||
|
||
| 差异项 | API 契约 (CUST-2) | 前端 Mock | 严重度 |
|
||
|--------|--------------------|-----------| --------|
|
||
| 源数据结构 | 契约返回 ServiceRecord 格式 | Mock 使用 ConsumptionRecord（来自 mock-data.ts），前端转换为 ServiceRecord | 🟠 中 |
|
||
| `customerPhone`/`customerPhoneFull` | 契约有 `customer_phone` | Mock 硬编码 | 🟡 低 |
|
||
| `tables` 台桌列表 | 契约有 `tables: Array<{id, name}>` | Mock 无（前端模拟台号） | 🟡 低 |
|
||
| `relationIndex` | 契约有 `relation_index` | Mock 硬编码 `"0.85"` | 🟡 低 |
|
||
| 月度统计 | ❌ 契约无 | ✅ 前端本地计算 `monthCount`/`monthHours`/`monthRelation` | 🟠 中 |
|
||
|
||
#### spec 未记录的 Gap
|
||
1. 🟠 CUST-2 响应缺少月度统计汇总 — 前端需要 `monthCount`/`monthHours`，当前本地计算，联调后应由后端返回
|
||
2. 🟠 首次加载全量 vs 按月分页 — 当前设计一次拉全部记录本地过滤，数据量大时需改为按月请求
|
||
|
||
---
|
||
|
||
## 场景 3：财务看板（最复杂）
|
||
|
||
### 3.1 board-finance（`pages/board-finance/board-finance.ts`）
|
||
|
||
#### API 调用
|
||
- `fetchBoardFinance()` → `BoardFinanceData`（⚠️ 当前签名仅 `{ date?: string }`，缺少 time/area/compare 参数）
|
||
- 页面 `onLoad()` → `fetchBoardFinance()` → 设置 `pageState: 'normal'`
|
||
- ⚠️ 筛选变更（`onTimeChange`/`onAreaChange`/`toggleCompare`）仅更新 data 状态，**不调用 API**（八¾节 F4/F5 已记录）
|
||
- ⚠️ 所有 6 个板块数据完全内联在 `data` 中，`fetchBoardFinance` 返回的 `_data` 未使用
|
||
|
||
#### 前端期望字段（从内联 data 提取，6 个板块完整结构）
|
||
|
||
**板块 1：经营一览 (overview) — 8 个指标 + 8 个环比值**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `overview.occurrence` | string | 发生额/正价（格式化，如 `"¥823,456"`） |
|
||
| `overview.occurrenceCompare` | string | 环比百分比（如 `"12.5%"`） |
|
||
| `overview.discount` | string | 总优惠（负值，如 `"-¥113,336"`） |
|
||
| `overview.discountCompare` | string | 环比 |
|
||
| `overview.discountRate` | string | 优惠率（如 `"13.8%"`） |
|
||
| `overview.discountRateCompare` | string | 环比 |
|
||
| `overview.confirmedRevenue` | string | 成交/确认收入 |
|
||
| `overview.confirmedCompare` | string | 环比 |
|
||
| `overview.cashIn` | string | 实收/现金流入 |
|
||
| `overview.cashInCompare` | string | 环比 |
|
||
| `overview.cashOut` | string | 现金支出 |
|
||
| `overview.cashOutCompare` | string | 环比 |
|
||
| `overview.cashBalance` | string | 现金结余 |
|
||
| `overview.cashBalanceCompare` | string | 环比 |
|
||
| `overview.balanceRate` | string | 结余率 |
|
||
| `overview.balanceRateCompare` | string | 环比 |
|
||
|
||
**板块 2：预收资产 (recharge) — 储值卡 + 赠送卡矩阵**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `recharge.actualIncome` | string | 储值卡充值实收 |
|
||
| `recharge.actualCompare` | string | 环比 |
|
||
| `recharge.firstCharge` | string | 首充 |
|
||
| `recharge.firstChargeCompare` | string | 环比 |
|
||
| `recharge.renewCharge` | string | 续费 |
|
||
| `recharge.renewChargeCompare` | string | 环比 |
|
||
| `recharge.consumed` | string | 消耗 |
|
||
| `recharge.consumedCompare` | string | 环比 |
|
||
| `recharge.cardBalance` | string | 储值卡总余额 |
|
||
| `recharge.cardBalanceCompare` | string | 环比 |
|
||
| `recharge.giftRows` | `Array<{label, total, totalCompare, wine, wineCompare, table, tableCompare, coupon, couponCompare}>` | 赠送卡矩阵（3行：新增/消费/余额 × 4列：合计/酒水卡/台费卡/抵用券） |
|
||
| `recharge.allCardBalance` | string | 全类别会员卡余额合计 |
|
||
| `recharge.allCardBalanceCompare` | string | 环比 |
|
||
|
||
赠送卡矩阵结构（3×4 = 12 个数据单元 + 12 个环比值 = 24 个字段）：
|
||
- 行：新增 / 消费 / 余额
|
||
- 列：合计(total) / 酒水卡(wine) / 台费卡(table) / 抵用券(coupon)
|
||
|
||
**板块 3：应计收入确认 (revenue) — 4 个子表**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `revenue.structureRows` | `Array<{id, name, desc?, amount, discount, booked, bookedCompare, isSub?}>` | 收入结构表（9行，含子行标记） |
|
||
| `revenue.priceItems` | `Array<{name, value, compare}>` | 正价明细（4项） |
|
||
| `revenue.totalOccurrence` | string | 正价合计 |
|
||
| `revenue.totalOccurrenceCompare` | string | 环比 |
|
||
| `revenue.discountItems` | `Array<{name, desc?, value, compare}>` | 优惠明细（4项） |
|
||
| `revenue.confirmedTotal` | string | 确认收入合计 |
|
||
| `revenue.confirmedTotalCompare` | string | 环比 |
|
||
| `revenue.channelItems` | `Array<{name, desc?, value, compare}>` | 渠道明细（3项） |
|
||
|
||
收入结构表行结构：
|
||
- 开台与包厢（含 A区/B区/C区/团建区/麻将区 5 个子行）
|
||
- 助教基础课
|
||
- 助教激励课
|
||
- 食品酒水
|
||
|
||
**板块 4：现金流入 (cashflow)**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `cashflow.consumeItems` | `Array<{name, desc, value, compare, isDown}>` | 消费收款（3项：纸币现金/线上收款/团购平台） |
|
||
| `cashflow.rechargeItems` | `Array<{name, desc, value, compare}>` | 充值收款（1项：会员充值到账） |
|
||
| `cashflow.total` | string | 现金流入合计 |
|
||
| `cashflow.totalCompare` | string | 环比 |
|
||
|
||
**板块 5：现金流出 (expense) — 4 个子分组**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `expense.operationItems` | `Array<{name, value, compare, isDown}>` | 经营支出（3项：食品饮料/耗材/报销） |
|
||
| `expense.fixedItems` | `Array<{name, value, compare, isFlat}>` | 固定支出（4项：房租/水电/物业/人员工资） |
|
||
| `expense.coachItems` | `Array<{name, value, compare, isDown}>` | 助教分成（4项：基础课/激励课/充值提成/额外奖金） |
|
||
| `expense.platformItems` | `Array<{name, value, compare}>` | 平台服务费（3项：汇来米/美团/抖音） |
|
||
| `expense.total` | string | 现金流出合计 |
|
||
| `expense.totalCompare` | string | 环比 |
|
||
|
||
**板块 6：助教分析 (coachAnalysis) — 基础课 + 激励课两个子表**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `coachAnalysis.basic.totalPay` | string | 基础课总收入 |
|
||
| `coachAnalysis.basic.totalPayCompare` | string | 环比 |
|
||
| `coachAnalysis.basic.totalShare` | string | 基础课总分成 |
|
||
| `coachAnalysis.basic.totalShareCompare` | string | 环比 |
|
||
| `coachAnalysis.basic.avgHourly` | string | 平均时薪 |
|
||
| `coachAnalysis.basic.avgHourlyCompare` | string | 环比 |
|
||
| `coachAnalysis.basic.rows` | `Array<{level, pay, payCompare, share, shareCompare, hourly, hourlyCompare, hourlyFlat?, payDown?, shareDown?}>` | 按等级分行（初级/中级/高级/星级） |
|
||
| `coachAnalysis.incentive.*` | 同 basic | 激励课（结构完全相同） |
|
||
|
||
每行字段：
|
||
- `level`: string — 等级名
|
||
- `pay`: string — 收入
|
||
- `payCompare`: string — 收入环比
|
||
- `payDown`: boolean? — 收入是否下降
|
||
- `share`: string — 分成
|
||
- `shareCompare`: string — 分成环比
|
||
- `shareDown`: boolean? — 分成是否下降
|
||
- `hourly`: string — 时薪
|
||
- `hourlyCompare`: string — 时薪环比
|
||
- `hourlyFlat`: boolean? — 时薪是否持平
|
||
|
||
#### 筛选参数映射
|
||
|
||
| 筛选项 | 前端参数 | 后端参数 | 查询影响 |
|
||
|--------|---------|---------|---------|
|
||
| 时间范围 | `selectedTime`: month/lastMonth/week/lastWeek/quarter3/quarter/lastQuarter/half6 | `time` | 决定统计日期区间 |
|
||
| 区域筛选 | `selectedArea`: all/hall/hallA/hallB/hallC/mahjong/teamBuilding | `area` | WHERE 过滤区域；area≠all 时预收资产板块隐藏 |
|
||
| 环比开关 | `compareEnabled`: true/false | `compare`: 0/1 | 控制是否返回环比数据 |
|
||
|
||
时间范围→日期区间映射（后端需实现）：
|
||
- `month` → 当月1日 ~ 当月末日
|
||
- `lastMonth` → 上月1日 ~ 上月末日
|
||
- `week` → 本周一 ~ 本周日
|
||
- `lastWeek` → 上周一 ~ 上周日
|
||
- `quarter3` → 前3个月（不含本月）
|
||
- `quarter` → 本季度第1天 ~ 本季度末日
|
||
- `lastQuarter` → 上季度
|
||
- `half6` → 最近6个月（不含本月）
|
||
|
||
#### 目录导航 (sectionNav)
|
||
- 6 个板块：经营一览/预收资产/应计收入确认/现金流入/现金流出/助教分析
|
||
- 每个板块有 emoji + 标题 + sectionId
|
||
- 吸顶头显示当前板块 emoji + 标题 + 描述
|
||
- 板块描述（`_sectionDescs`）：6 段固定文案
|
||
|
||
#### 帮助图标 (helpTip)
|
||
- 7 个指标解释：occurrence/discount/confirmed/cashIn/cashOut/balance/rechargeActual/firstCharge/renewCharge/consume/cardBalance/allCardBalance
|
||
- 每个含 `title` + `content`（多行文本）
|
||
|
||
#### API 契约 vs Mock 数据 vs 八¾节 差异
|
||
|
||
| 差异项 | API 契约 (BOARD-3) | 前端 Mock (内联 data) | 八¾节 (B3) | 严重度 |
|
||
|--------|--------------------|-----------------------|------------|--------|
|
||
| 响应结构 | 扁平 `metrics: Array<{key, label, value, unit, trend, compareValue, sub_items}>` | 6 个板块独立对象，深度嵌套结构 | 仅定义了参数，未定义完整响应结构 | 🔴 高 |
|
||
| 板块数量 | 未区分板块（单一 metrics 数组） | 6 个独立板块（overview/recharge/revenue/cashflow/expense/coachAnalysis） | 提到 6 个板块但未定义结构 | 🔴 高 |
|
||
| 环比数据格式 | `trend: 'up'\|'down'\|'flat'` + `compareValue?: string` | 每个值旁有独立的 `xxxCompare` 字段（百分比字符串） + `isDown`/`isFlat` 布尔标记 | 已确认需补充 `compareValue` 字段 | 🔴 高 |
|
||
| 赠送卡矩阵 | ❌ 完全缺失 | ✅ 3×4 矩阵（24 个字段） | ❌ 未详细定义 | 🔴 高 |
|
||
| 收入结构表 | ❌ 缺失 | ✅ 9 行含子行标记 | ❌ 未详细定义 | 🔴 高 |
|
||
| 助教分析子表 | ❌ 缺失 | ✅ 基础课+激励课各 4 行（按等级） | ❌ 未详细定义 | 🔴 高 |
|
||
| 现金流出 4 子分组 | ❌ 缺失 | ✅ 经营支出/固定支出/助教分成/平台服务费 | ❌ 未详细定义 | 🔴 高 |
|
||
| `time`/`area`/`compare` 参数 | 八¾节末尾补充了参数定义 | 前端未传参（Bug） | ✅ 已定义 | 🟠 中（八¾节已补充） |
|
||
| `isDown`/`isFlat` 标记 | ❌ 无 | ✅ 有（控制箭头颜色方向） | ❌ 无 | 🟠 中 |
|
||
| 帮助图标内容 | ❌ 完全缺失 | ✅ 12 个指标解释 | ❌ 未提及 | 🟡 低 |
|
||
|
||
#### spec 未记录的 Gap
|
||
1. 🔴 BOARD-3 响应结构与前端实际需求完全不匹配 — 契约为扁平 metrics 数组，前端需要 6 个独立板块的深度嵌套结构
|
||
2. 🔴 赠送卡矩阵（3×4=12 单元 + 12 环比）完全未定义 — 预收资产板块的核心数据
|
||
3. 🔴 收入结构表（9 行含子行层级）完全未定义 — 应计收入确认板块的核心数据
|
||
4. 🔴 助教分析子表（基础课+激励课各 4 行按等级）完全未定义
|
||
5. 🔴 现金流出 4 个子分组（经营/固定/助教分成/平台服务费）完全未定义
|
||
6. 🔴 环比数据格式不匹配 — 契约仅 `trend` + `compareValue`，前端需要每个值旁独立的 `xxxCompare` 字段 + `isDown`/`isFlat` 布尔标记
|
||
7. 🟠 `isDown`/`isFlat` 布尔标记未定义 — 前端用于控制环比箭头方向和颜色
|
||
8. 🟡 帮助图标内容（12 个指标解释文案）未定义 — 可硬编码在前端，但后端可提供配置化
|
||
|
||
---
|
||
|
||
## 场景 4：跨页面数据关联
|
||
|
||
### 4.1 board-coach → coach-detail → customer-detail → customer-service-records
|
||
|
||
**参数传递链：**
|
||
1. `board-coach` 点击助教卡片 → `coach-detail?id={coachId}`
|
||
2. `coach-detail` 点击客户卡片 → `customer-detail?id={customerId}`
|
||
3. `coach-detail` 点击任务项 → `customer-detail?name={customerName}`（⚠️ 用 name 而非 id）
|
||
4. `customer-detail` 查看服务记录 → `customer-service-records`（⚠️ 未传 customerId）
|
||
5. `coach-detail` 查看更多服务记录 → `performance-records?coachId={coachId}`
|
||
6. `coach-detail` 问问助手 → `chat?coachId={coachId}`
|
||
|
||
**跨页面 Gap：**
|
||
- 🔴 步骤 3 用 `name` 跳转，name 不唯一，应改为 `id`
|
||
- 🔴 步骤 4 未传 `customerId`，`customer-service-records` 无法知道查哪个客户
|
||
- 🟠 `customer-detail` 的 `onStartChat` 未传 `customerId`，chat 页面无法关联客户上下文
|
||
|
||
### 4.2 board-customer → customer-detail → chat
|
||
|
||
**参数传递链：**
|
||
1. `board-customer` 点击客户卡片 → `customer-detail?id={customerId}`
|
||
2. `customer-detail` 问问助手 → `chat`（⚠️ 未传参数）
|
||
|
||
**跨页面 Gap：**
|
||
- 🟠 `chat` 页面无法获取客户上下文（customerId/customerName）
|
||
|
||
### 4.3 board-finance → coach-detail 入口
|
||
|
||
**分析结果：**
|
||
- board-finance 的助教分析板块（coachAnalysis）展示按等级汇总的数据，**无跳转到 coach-detail 的入口**
|
||
- 这是合理的设计 — 财务看板关注的是汇总数据而非个体
|
||
|
||
---
|
||
|
||
## 汇总 Gap 清单（按严重度排序）
|
||
|
||
### 🔴 高严重度（阻塞联调，必须在后端开发前解决）
|
||
|
||
| # | 类别 | Gap 描述 | 涉及接口 | 涉及页面 |
|
||
|---|------|---------|---------|---------|
|
||
| G1 | 契约缺陷 | **BOARD-3 响应结构与前端完全不匹配** — 契约为扁平 metrics 数组，前端需要 6 个独立板块的深度嵌套结构（overview/recharge/revenue/cashflow/expense/coachAnalysis），含 200+ 个字段 | BOARD-3 | board-finance |
|
||
| G2 | 契约缺陷 | **BOARD-1 响应字段严重不足** — 契约仅 10 个通用字段，前端需要 20 个含 4 维度专属字段（perf/salary/sv/task），且 skills 类型不匹配（string[] vs Array<{text,cls}>） | BOARD-1 | board-coach |
|
||
| G3 | 契约缺陷 | **BOARD-2 响应字段严重不足** — 契约仅 8 个通用字段，前端需要 40+ 维度专属字段（8 个维度各有独立字段集），且缺少 assistants 关联助教列表 | BOARD-2 | board-customer |
|
||
| G4 | 契约缺陷 | **COACH-1 响应缺少多个核心区域** — 缺少 income 收入明细（本月/上月）、historyMonths 历史月份统计、tierNodes 档位节点、备注列表；topCustomers 字段结构不完整（契约 5 字段 vs 前端 10 字段） | COACH-1 | coach-detail |
|
||
| G5 | 契约缺陷 | **CUST-1 响应缺少管理层核心数据** — 缺少 aiInsight AI 洞察、coachTasks 关联助教任务、favoriteCoaches 喜好助教；消费记录结构严重不匹配（契约扁平 vs 前端嵌套含助教明细） | CUST-1 | customer-detail |
|
||
| G6 | 契约缺陷 | **BOARD-3 赠送卡矩阵完全未定义** — 预收资产板块的 3×4 矩阵（新增/消费/余额 × 合计/酒水卡/台费卡/抵用券）= 24 个数据字段 + 24 个环比字段 | BOARD-3 | board-finance |
|
||
| G7 | 契约缺陷 | **BOARD-3 收入结构表完全未定义** — 9 行含子行层级（开台与包厢含 5 个区域子行 + 助教基础课 + 助教激励课 + 食品酒水），每行含 amount/discount/booked/bookedCompare | BOARD-3 | board-finance |
|
||
| G8 | 契约缺陷 | **BOARD-3 助教分析子表完全未定义** — 基础课+激励课各含汇总行 + 4 个等级行（初级/中级/高级/星级），每行含 pay/share/hourly 及各自环比 | BOARD-3 | board-finance |
|
||
| G9 | 契约缺陷 | **BOARD-3 现金流出 4 子分组完全未定义** — 经营支出(3项)/固定支出(4项)/助教分成(4项)/平台服务费(3项) | BOARD-3 | board-finance |
|
||
| G10 | 契约缺陷 | **环比数据格式不匹配** — 契约仅 `trend` + `compareValue`，前端需要每个值旁独立的 `xxxCompare` 百分比字段 + `isDown`/`isFlat` 布尔标记 | BOARD-3 | board-finance |
|
||
| G11 | 前端 Bug | **customer-detail 跳转 customer-service-records 未传 customerId** — 服务记录页无法知道查哪个客户 | CUST-2 | customer-detail → customer-service-records |
|
||
| G12 | 前端 Bug | **coach-detail 任务项跳转用 name 而非 id** — `onTaskItemTap` 传 `name={customerName}`，name 不唯一 | — | coach-detail → customer-detail |
|
||
| G13 | 类型不匹配 | **api.ts 中 fetchCoachDetail 返回类型为 CoachCard** — 实际需要完整的 CoachDetail（含 performance/income/tasks/topCustomers/serviceRecords/historyMonths/notes），类型定义严重不足 | COACH-1 | coach-detail |
|
||
| G14 | 类型不匹配 | **mock-data.ts 中的类型与页面内联 mock 完全脱节** — BoardFinanceData 仅含 4 个 metrics，实际页面需要 6 个板块 200+ 字段；CustomerCard/CoachCard 过于简单 | 全部看板 | 全部看板页 |
|
||
|
||
### 🟠 中严重度（影响功能完整性，联调前需解决）
|
||
|
||
| # | 类别 | Gap 描述 | 涉及接口 | 涉及页面 |
|
||
|---|------|---------|---------|---------|
|
||
| G15 | 契约缺陷 | **BOARD-1 sort 参数格式不一致** — 契约用 `field:direction`，前端用枚举值 `perf_desc` | BOARD-1 | board-coach |
|
||
| G16 | 契约缺陷 | **BOARD-1/2 缺少 initial/avatarGradient/avatarCls 字段** — 前端用于头像渲染，需确认由前端计算还是后端返回 | BOARD-1/2 | board-coach/board-customer |
|
||
| G17 | 契约缺陷 | **CUST-1 缺少 balance/consumption60d/idealInterval/daysSinceVisit** — 客户详情页头部展示的核心指标 | CUST-1 | customer-detail |
|
||
| G18 | 契约缺陷 | **CUST-1 维客线索结构不匹配** — 契约用 tag/tag_color/emoji/text/source/desc，前端用 category/categoryColor/text/source/detail | CUST-1 | customer-detail |
|
||
| G19 | 契约缺陷 | **CUST-1 缺少备注列表** — 客户详情页展示关联备注 | CUST-1 | customer-detail |
|
||
| G20 | 契约缺陷 | **COACH-1 缺少备注列表** — 助教详情页展示关联备注 | COACH-1 | coach-detail |
|
||
| G21 | 契约缺陷 | **CUST-2 缺少月度统计汇总** — 前端需要 monthCount/monthHours，当前本地计算 | CUST-2 | customer-service-records |
|
||
| G22 | 契约缺陷 | **BOARD-3 isDown/isFlat 布尔标记未定义** — 前端用于控制环比箭头方向和颜色 | BOARD-3 | board-finance |
|
||
| G23 | 前端 Bug | **customer-detail 的 onStartChat 未传 customerId** — chat 页面无法关联客户上下文 | CHAT | customer-detail → chat |
|
||
| G24 | 前端 Bug | **customer-detail 的 loadDetail() 中 id 解析方式有 Bug** — 应从 onLoad(options) 获取，而非 `__route__` 解析 | CUST-1 | customer-detail |
|
||
| G25 | 设计缺陷 | **BOARD-2 potentialTags 标签结构契约缺失** — potential 维度展示客户潜力标签（含 text+theme） | BOARD-2 | board-customer |
|
||
| G26 | 设计缺陷 | **COACH-1 tierNodes/maxHours 缺失** — 绩效进度条组件需要档位节点数据，当前硬编码 `[0, 100, 130, 160, 190, 220]` | COACH-1 | coach-detail |
|
||
|
||
### 🟡 低严重度（不阻塞联调，可后续优化）
|
||
|
||
| # | 类别 | Gap 描述 | 涉及接口 | 涉及页面 |
|
||
|---|------|---------|---------|---------|
|
||
| G27 | 设计决策 | **BOARD-1 无分页定义** — 当前全量返回，助教数量少（<50）可接受 | BOARD-1 | board-coach |
|
||
| G28 | 设计决策 | **BOARD-3 帮助图标内容未定义** — 12 个指标解释文案，可硬编码在前端 | BOARD-3 | board-finance |
|
||
| G29 | 设计决策 | **customer-service-records 首次加载全量 vs 按月分页** — 数据量小时可接受，量大时需改为按月请求 | CUST-2 | customer-service-records |
|
||
| G30 | 类型不匹配 | **mock-data.ts ConsumptionRecord 结构过于简单** — 仅 6 个字段，customer-detail 内联 mock 有 16 个字段（含嵌套 coaches 数组） | CUST-1 | customer-detail |
|
||
| G31 | 契约缺陷 | **CUST-2 tables 台桌列表** — 契约定义了但前端未使用（前端模拟台号） | CUST-2 | customer-service-records |
|
||
|
||
---
|
||
|
||
## 行动建议
|
||
|
||
### 优先级 1：更新 API 契约（阻塞后端开发）
|
||
|
||
以下接口的契约需要**完全重写**，以匹配前端实际需求：
|
||
|
||
1. **BOARD-3 财务看板** — 从扁平 metrics 改为 6 板块嵌套结构，补充赠送卡矩阵、收入结构表、助教分析子表、现金流出子分组的完整字段定义
|
||
2. **BOARD-1 助教看板** — 从 10 个通用字段扩展为 20 个含 4 维度专属字段，修正 skills 类型，补充 topCustomers
|
||
3. **BOARD-2 客户看板** — 从 8 个通用字段扩展为 40+ 维度专属字段，补充 assistants/weeklyVisits/coachDetails/potentialTags
|
||
4. **COACH-1 助教详情** — 补充 income/historyMonths/tierNodes/备注列表，扩展 topCustomers 字段
|
||
5. **CUST-1 客户详情** — 补充 aiInsight/coachTasks/favoriteCoaches/备注列表，重写消费记录为嵌套结构
|
||
|
||
### 优先级 2：修复前端 Bug（联调前必须完成）
|
||
|
||
1. G11: customer-detail → customer-service-records 传 customerId
|
||
2. G12: coach-detail onTaskItemTap 改用 id 而非 name
|
||
3. G23: customer-detail → chat 传 customerId
|
||
4. G24: customer-detail loadDetail() 修复 id 解析
|
||
5. F1-F6: 看板筛选变更触发重新请求（八¾节已记录）
|
||
|
||
### 优先级 3：统一 mock-data.ts 类型定义
|
||
|
||
当前 `mock-data.ts` 中的类型（BoardFinanceData/CustomerCard/CoachCard/CustomerDetail）与页面内联 mock 数据严重脱节。建议：
|
||
- 将页面内联的完整接口定义（CoachItem/CustomerItem/CoachDetail 等）提取到 `mock-data.ts` 或独立的 `types.ts`
|
||
- 更新 `api.ts` 中各函数的返回类型
|
||
- 确保类型定义与更新后的 API 契约一致
|