# 页面数据需求说明文档（推测版 / Mock 阶段）

版本：v1.0  
适用范围：球房运营助手原型页面的前后端数据契约设计  
说明：本文件基于现有 H5 原型代码推断，用于 **Mock / 接口设计前置**。不是最终后端接口定义，但足够支撑前端页面开发与后续接口对齐。

---

## 1. 文档目标

本文件用于回答三个问题：

1. **哪些内容应该由后端返回？**
2. **哪些内容应该写在前端模板/枚举中？**
3. **页面要稳定开发，需要哪些接口与字段？**

本阶段使用 Mock 数据代替真实接口，因此要求：
- 字段结构先稳定；
- 列表、详情、筛选、统计、弹窗提交等数据模型先统一；
- 前端派生字段与后端源字段边界清晰。

---

## 2. 总体判断原则

## 2.1 必须由后端返回的数据

以下内容不能写死在模板中：

1. 用户身份、门店、权限、审核状态
2. 任务列表、任务详情、任务状态、备注、放弃原因
3. 客户详情、服务记录、消费记录、余额、到店时间
4. 助教详情、绩效、工资、客户数、服务记录
5. 看板统计、榜单排序、筛选结果、时间范围数据
6. AI 洞察文案、AI 话术建议、对话记录
7. 月份切换、对比数据、趋势值
8. 业务枚举背后的值（类型 code、状态 code、标签 code）
9. 数值格式化前的原始值（金额、小时、次数、时间戳）

## 2.2 可以由前端模板维护的数据

以下内容可以先前端写死，后续再看是否由平台统一下发：

1. 页面固定标题
2. 静态说明文案
3. 空状态文案
4. 权限页/审核页的帮助说明
5. 通用按钮文案（取消、确认、保存）
6. 前端 UI 状态：
   - 弹窗是否打开
   - 当前激活 tab
   - 当前筛选器是否展开
   - Toast 是否显示
7. 某些纯展示枚举的样式映射：
   - 任务类型颜色
   - 标签颜色
   - 徽章图标
   - 看板 section 图标

## 2.3 建议“后端返回 code，前端做样式映射”的数据

例如：
- `taskType = high_priority | priority | relationship | callback`
- `memberLevel = vip | gold | normal`
- `gender = male | female | unknown`
- `noteType = customer | coach`
- `status = pending | approved | rejected | abandoned | completed`

原因：
- 后端可控业务语义
- 前端可控视觉样式
- 文案和颜色不会耦死在接口层

---

## 3. 全局数据模型

## 3.1 当前登录用户 `CurrentUser`

```json
{
  "userId": "u_1001",
  "name": "小燕",
  "nickname": "小燕",
  "avatarUrl": "https://...",
  "roleCode": "coach",
  "roleName": "助教",
  "siteId": "site_001",
  "siteName": "广州朗朗桌球",
  "defaultHome": "task",
  "permissionStatus": "approved"
}
```

### 字段说明

| 字段 | 类型 | 来源 | 说明 |
|---|---|---|---|
| `userId` | string | 后端 | 用户唯一 ID |
| `name` | string | 后端 | 昵称/展示名 |
| `avatarUrl` | string | 后端 | 头像 |
| `roleCode` | string | 后端 | `coach / manager / admin ...` |
| `roleName` | string | 后端或前端映射 | 展示身份 |
| `siteId` | string | 后端 | 球房 ID |
| `siteName` | string | 后端 | 球房名称 |
| `defaultHome` | string | 后端 | 默认首页 |
| `permissionStatus` | string | 后端 | 权限状态 |

---

## 3.2 通用枚举建议

### 任务类型 `TaskType`
```json
[
  { "code": "high_priority", "name": "高优先召回" },
  { "code": "priority", "name": "优先召回" },
  { "code": "relationship", "name": "关系构建" },
  { "code": "callback", "name": "客户回访" }
]
```

### 任务状态 `TaskStatus`
```json
[
  { "code": "pending", "name": "待处理" },
  { "code": "completed", "name": "已完成" },
  { "code": "abandoned", "name": "已放弃" },
  { "code": "pinned", "name": "置顶" }
]
```

### 备注对象类型 `NoteEntityType`
```json
[
  { "code": "customer", "name": "客户" },
  { "code": "coach", "name": "助教" },
  { "code": "task", "name": "任务" }
]
```

### 会员等级 `MemberLevel`
```json
[
  { "code": "vip", "name": "VIP" },
  { "code": "gold", "name": "黄金会员" },
  { "code": "normal", "name": "普通会员" }
]
```

---

## 4. 页面级数据需求

## 4.1 登录页 `login`

### 页面用途
- 微信登录入口
- 用户协议勾选
- 登录后跳转默认首页

### 后端需求
#### 接口 A：登录态获取 / 登录
```json
{
  "code": 0,
  "data": {
    "token": "xxx",
    "user": {
      "userId": "u_1001",
      "name": "小燕",
      "roleCode": "coach",
      "roleName": "助教",
      "siteId": "site_001",
      "siteName": "广州朗朗桌球",
      "permissionStatus": "approved",
      "defaultHome": "task"
    }
  }
}
```

### 页面模板可写死
- Logo / slogan
- “任务管理 / 数据看板 / 智能助手”卖点文案
- 用户协议、隐私政策入口文案

### 提交动作
- 微信登录
- 勾选协议状态仅前端控制

---

## 4.2 申请页 `apply`

### 原型可见字段
- 球房 ID
- 申请身份
- 手机号
- 编号（选填）
- 昵称

### 后端需求
#### 接口 B：提交访问申请
**请求**
```json
{
  "siteId": "site_001",
  "applyRole": "coach",
  "phone": "13800000000",
  "staffNo": "A102",
  "nickname": "小燕"
}
```

**响应**
```json
{
  "code": 0,
  "data": {
    "applicationId": "app_001",
    "status": "reviewing"
  }
}
```

### 页面模板可写死
- 提交流程 1~4 步说明
- 填写提示文案

### 风险提示
- `applyRole` 不要传中文文案，传 code
- 手机号、球房 ID、员工编号的格式校验规则建议后端也做

---

## 4.3 审核中 / 无权限页 `reviewing` / `no-permission`

### 后端需求
#### 接口 C：当前账号权限状态查询
```json
{
  "code": 0,
  "data": {
    "permissionStatus": "reviewing",
    "siteId": "site_001",
    "siteName": "广州朗朗桌球",
    "adminName": "厉超",
    "adminContact": "138****0000",
    "reason": null
  }
}
```

#### `permissionStatus` 建议取值
- `reviewing`
- `approved`
- `rejected`
- `revoked`

### 页面模板可写死
- 说明文案
- 联系管理员的固定描述结构

### 页面中真正来自后端的
- 管理员姓名/联系方式
- 驳回或收回原因
- 当前状态

---

## 4.4 首页设置 `home-settings`

### 需求
- 获取默认首页设置
- 修改默认首页设置

#### 接口 D1：获取用户设置
```json
{
  "code": 0,
  "data": {
    "defaultHome": "task"
  }
}
```

#### 接口 D2：保存用户设置
**请求**
```json
{
  "defaultHome": "board"
}
```

**响应**
```json
{
  "code": 0,
  "data": true
}
```

### 前端模板可维护
- “任务 / 看板”的展示文案

---

## 4.5 我的 `my-profile`

### 后端需求
#### 接口 E：我的信息
```json
{
  "code": 0,
  "data": {
    "userId": "u_1001",
    "name": "小燕",
    "roleCode": "coach",
    "roleName": "助教",
    "siteName": "广州朗朗桌球",
    "avatarUrl": "https://..."
  }
}
```

### 页面按钮跳转
- 备注记录
- 助手对话记录
- 退出账号

#### 接口 F：退出登录
前端即可清空 token；后端如需审计，可补一个退出埋点接口。

---

## 4.6 任务列表 `task-list`

这是最关键页面之一。

### 页面结构拆分

#### 1）顶部个人与站点信息
- 当前用户昵称
- 角色
- 门店名
- 头像

#### 2）业绩进度卡
- 距离 100h 仅剩多少小时
- 档位进度条
- 基础课 / 激励课 / 全部小时数
- 达成奖励
- 月预计收入及同比/环比变化

#### 3）任务区
- 今日客户维护总数
- 置顶任务列表
- 其他任务列表
- 已放弃任务列表

#### 4）长按上下文菜单
- 置顶
- 放弃
- AI
- 备注

### 后端数据需求

#### 接口 G：任务列表页聚合数据

```json
{
  "code": 0,
  "data": {
    "userSummary": {
      "userId": "u_1001",
      "name": "小燕",
      "roleCode": "coach",
      "roleName": "助教",
      "avatarUrl": "https://...",
      "siteName": "广州朗朗桌球"
    },
    "performanceSummary": {
      "targetHour": 100,
      "remainHour": 12.5,
      "currentTierIndex": 1,
      "tierBounds": [0, 100, 130, 160, 190, 220],
      "baseHour": 77.5,
      "incentiveHour": 12.0,
      "totalHour": 87.5,
      "rewardAmount": 800,
      "forecastIncome": 6206,
      "incomeCompareValue": -368,
      "incomeCompareLabel": "比1月同期"
    },
    "taskSections": {
      "pinnedCount": 2,
      "normalCount": 3,
      "abandonedCount": 2
    },
    "tasks": [
      {
        "taskId": "t_001",
        "taskType": "high_priority",
        "taskTypeName": "高优先召回",
        "status": "pending",
        "isPinned": true,
        "customerId": "c_001",
        "customerName": "王先生",
        "genderEmoji": "💖",
        "hasNote": true,
        "lastVisitDays": 15,
        "balanceLevel": "very_high",
        "balanceLevelName": "非常多",
        "descLine1": "最近到店：15天前 · 余额：非常多",
        "descLine2": "偏好晚间时段，可推荐夜场套餐",
        "aiHint": "偏好晚间时段，可推荐夜场套餐",
        "abandonReason": null,
        "priorityScore": 98
      }
    ]
  }
}
```

### 字段归因说明

#### 必须后端返回
- 任务列表本身
- 任务类型
- 置顶状态
- 放弃状态
- 客户姓名
- 最近到店天数
- 余额等级
- AI 提示
- 是否有备注
- 业绩进度统计
- 预计收入与比较值

#### 前端可派生
- 任务卡左侧颜色
- 任务类型 badge 样式
- `💖 💙 💛 🧡` 这类关系/情绪小符号（如果不是业务字段，可由前端映射）
- “已放弃”分组标题样式
- 进度条视觉分段

### 交互写接口需求
#### 接口 H1：置顶 / 取消置顶任务
```json
{
  "taskId": "t_001",
  "isPinned": true
}
```

#### 接口 H2：放弃任务
```json
{
  "taskId": "t_001",
  "reason": "客户已转会至其他球房"
}
```

#### 接口 H3：新增任务备注
```json
{
  "taskId": "t_001",
  "content": "客户本周不方便，建议下周三回访"
}
```

---

## 4.7 任务详情（四个页面共性）

页面：
- `task-detail`
- `task-detail-priority`
- `task-detail-callback`
- `task-detail-relationship`

### 共性信息块

1. 客户头部信息
   - 姓名
   - 手机
   - 会员等级
   - 任务类型
   - 维客线索 / AI 洞察

2. 客户基础信息 / 消费习惯 / 服务关系
3. AI 建议话术
4. 备注区
5. 放弃客户弹窗（主版）
6. 星级评分（备注弹窗内）

### 后端建议：统一一个详情接口，通过 taskType 决定展示差异

#### 接口 I：任务详情
```json
{
  "code": 0,
  "data": {
    "taskId": "t_001",
    "taskType": "high_priority",
    "taskTypeName": "高优先召回",
    "status": "pending",
    "customer": {
      "customerId": "c_001",
      "name": "王先生",
      "avatarText": "王",
      "phoneMasked": "138****5678",
      "memberLevel": "gold",
      "memberLevelName": "黄金会员",
      "registerDays": 730,
      "tags": ["VIP会员", "高价值"]
    },
    "relationship": {
      "score": 0.85,
      "label": "非常好",
      "summary": "最近3个月每周均有1-2次课程互动，客户反馈良好。"
    },
    "balance": {
      "amount": 8600,
      "level": "very_high",
      "levelName": "非常多"
    },
    "visit": {
      "lastVisitAt": "2026-02-25T20:00:00+08:00",
      "lastVisitDays": 12,
      "idealIntervalDays": 7
    },
    "insights": [
      {
        "section": "客户基础",
        "source": "system",
        "icon": "👤",
        "title": "普通会员 · 注册10个月 · 近期活跃度下降"
      },
      {
        "section": "消费习惯",
        "source": "system",
        "icon": "🌙",
        "title": "偏好夜场 20:00-22:00"
      }
    ],
    "aiSuggestions": [
      {
        "suggestionId": "s_001",
        "content": "最近是否工作较忙？周末夜场新上了双人套餐，给您预留时段。"
      }
    ],
    "latestNote": {
      "noteId": "n_001",
      "content": "客户上次说月底来店。",
      "createdAt": "2026-02-26T18:00:00+08:00",
      "ratings": {
        "intention": 4,
        "relation": 5,
        "service": 4
      }
    }
  }
}
```

### 备注相关接口

#### 接口 J1：新增 / 更新备注
```json
{
  "taskId": "t_001",
  "content": "客户上次说月底来店。",
  "ratings": {
    "intention": 4,
    "relation": 5,
    "service": 4
  }
}
```

#### 接口 J2：删除备注
```json
{
  "noteId": "n_001"
}
```

### 放弃任务接口
可复用 `H2`

### AI 话术复制
前端行为，不需要接口。

---

## 4.8 客户详情 `customer-detail`

### 页面可见数据
- 姓名、手机号、会员编号
- 储值余额
- 60天消费
- 理想到店间隔
- 距今到店天数
- AI 智能洞察
- 客户标签
- 可能还有最近服务、消费偏好等

#### 接口 K：客户详情
```json
{
  "code": 0,
  "data": {
    "customerId": "c_001",
    "name": "王先生",
    "avatarText": "王",
    "phoneMasked": "138****5678",
    "memberNo": "VIP20231215",
    "memberLevel": "vip",
    "memberLevelName": "VIP",
    "balanceAmount": 8600,
    "consume60dAmount": 2800,
    "idealVisitIntervalDays": 7,
    "daysSinceLastVisit": 12,
    "relationshipScore": 0.85,
    "insightSummary": "高价值 VIP 客户，月均到店 4 次，夜场偏好明显。",
    "tags": ["高价值", "VIP", "夜场偏好"],
    "stats": {
      "visitCount30d": 4,
      "visitCount60d": 8,
      "avgTicket30d": 350
    }
  }
}
```

---

## 4.9 客户服务记录 `customer-service-records`

### 原型可见
- 客户头部摘要
- 累计服务次数
- 关系指数
- 按月份切换
- 本月服务次数
- 服务时长
- 按时间列出服务记录

#### 接口 L：客户服务记录
```json
{
  "code": 0,
  "data": {
    "customer": {
      "customerId": "c_001",
      "name": "王先生",
      "phoneMasked": "139****5678"
    },
    "summary": {
      "totalServiceCount": 28,
      "relationshipScore": 0.85
    },
    "month": "2026-02",
    "monthSummary": {
      "serviceCount": 6,
      "serviceDurationHour": 11.5,
      "relationshipScore": 0.85
    },
    "records": [
      {
        "recordId": "sr_001",
        "startAt": "2026-02-07T20:00:00+08:00",
        "endAt": "2026-02-07T22:30:00+08:00",
        "durationHour": 2.5,
        "tableNo": "A1",
        "coachName": "小燕",
        "projectName": "中八陪练",
        "remark": null
      }
    ],
    "monthOptions": ["2026-01", "2026-02"]
  }
}
```

### 前端模板可维护
- 月份切换按钮样式
- 列表分组表现

---

## 4.10 助教详情 `coach-detail`

### 原型可见
- 姓名、星级、擅长项目
- 工龄、客户数
- 本月定档业绩
- 折算前
- 本月工资预估
- 客源储值余额
- 收入明细切换（本月 / 上月）
- 备注弹窗
- 任务展开收起

#### 接口 M：助教详情
```json
{
  "code": 0,
  "data": {
    "coach": {
      "coachId": "coach_001",
      "name": "小燕",
      "avatarText": "小",
      "level": "star",
      "levelName": "星级",
      "skills": ["中八", "斯诺克"],
      "workingYears": 3,
      "customerCount": 68
    },
    "summary": {
      "currentMonthPerfHour": 87.5,
      "rawPerfHour": 89.0,
      "forecastSalary": 6950,
      "customerBalanceAmount": 86200
    },
    "incomeTabs": {
      "thisMonth": {
        "totalAmount": 6206,
        "items": [
          { "label": "基础课收入", "amount": 4200 },
          { "label": "激励课收入", "amount": 1200 }
        ]
      },
      "lastMonth": {
        "totalAmount": 16880,
        "items": []
      }
    },
    "tasks": [
      {
        "taskId": "t_001",
        "taskType": "high_priority",
        "customerName": "王先生",
        "status": "pending"
      }
    ],
    "latestNotes": [
      {
        "noteId": "n_001",
        "content": "本月表现优秀。",
        "createdAt": "2026-02-27T12:00:00+08:00"
      }
    ]
  }
}
```

### 备注接口
可复用通用备注接口，只是实体类型变为 `coach`。

---

## 4.11 备注页 `notes`

### 原型可见
- 客户备注
- 助教备注
- 按时间倒序

#### 接口 N：备注列表
```json
{
  "code": 0,
  "data": {
    "tabs": [
      {
        "type": "customer",
        "count": 12,
        "notes": [
          {
            "noteId": "n_001",
            "entityType": "customer",
            "entityId": "c_001",
            "entityName": "王先生",
            "content": "客户今天表示下周有朋友生日聚会...",
            "createdAt": "2026-02-27T15:30:00+08:00"
          }
        ]
      },
      {
        "type": "coach",
        "count": 8,
        "notes": []
      }
    ]
  }
}
```

### 页面模板可维护
- Tab 标题文案
- 备注卡片样式
- 标签颜色映射

---

## 4.12 助手对话 `chat` 与对话记录 `chat-history`

### 需要区分两层数据

#### A. 对话会话列表
#### B. 某个会话中的消息流

### 接口 O1：会话列表
```json
{
  "code": 0,
  "data": {
    "sessions": [
      {
        "sessionId": "cs_001",
        "title": "如何提升王先生的到店频率？",
        "updatedAt": "2026-03-01T10:20:00+08:00",
        "messageCount": 8,
        "sourceType": "task",
        "sourceId": "t_001",
        "sourceSummary": "任务 - 高优先召回"
      }
    ]
  }
}
```

### 接口 O2：会话详情 / 消息流
```json
{
  "code": 0,
  "data": {
    "session": {
      "sessionId": "cs_001",
      "title": "如何提升王先生的到店频率？",
      "sourceType": "task",
      "sourceId": "t_001",
      "quoteCard": {
        "title": "任务 - 高优先召回",
        "summary": "王先生 · 最近到店15天前 · VIP客户"
      }
    },
    "messages": [
      {
        "messageId": "m_001",
        "role": "user",
        "content": "如何提升这位客户的到店频率？",
        "createdAt": "2026-03-01T10:20:00+08:00"
      },
      {
        "messageId": "m_002",
        "role": "assistant",
        "content": "根据王先生的消费数据分析，我有以下建议...",
        "createdAt": "2026-03-01T10:20:03+08:00",
        "actions": [
          { "type": "copy", "label": "复制" }
        ]
      }
    ]
  }
}
```

### 接口 O3：发送消息
```json
{
  "sessionId": "cs_001",
  "content": "输入消息..."
}
```

### 模板可维护
- 聊天气泡左右布局
- 用户/助手样式映射
- 输入栏样式
- 语音按钮是否展示（如无真实语音能力，可先前端占位）

---

## 4.13 业绩详情 `performance`

### 原型可见
- 本月预计收入
- 上月收入
- 当前档位
- 基础课到手时薪
- 激励课到手时薪
- 下一阶段
- 可能还包括新客户/老客户分段明细、本月/上月记录展开

#### 接口 P：业绩详情
```json
{
  "code": 0,
  "data": {
    "coach": {
      "coachId": "coach_001",
      "name": "小燕",
      "roleName": "助教",
      "siteName": "广州朗朗桌球"
    },
    "incomeSummary": {
      "forecastIncome": 6206,
      "lastMonthIncome": 16880
    },
    "tier": {
      "currentLevelLabel": "当前档位",
      "baseHourRate": 80,
      "incentiveHourRate": 95,
      "nextLevelLabel": "下一阶段",
      "nextBaseHourRate": 90,
      "nextThresholdHour": 100,
      "currentHour": 87.5
    },
    "sections": {
      "newCustomer": {
        "summary": {},
        "items": []
      },
      "regularCustomer": {
        "summary": {},
        "items": []
      },
      "thisMonthRecords": {
        "items": []
      },
      "lastMonthRecords": {
        "items": []
      }
    }
  }
}
```

---

## 4.14 业绩明细 `performance-records`

### 原型可见
- 月份
- 总记录笔数
- 总业绩时长
- 折算前
- 预估收入
- 每笔记录：客户、时间、时长、预估收入

#### 接口 Q：业绩明细列表
```json
{
  "code": 0,
  "data": {
    "coach": {
      "coachId": "coach_001",
      "name": "小燕",
      "levelName": "星级",
      "siteName": "球会名称店"
    },
    "month": "2026-02",
    "summary": {
      "recordCount": 32,
      "perfHour": 59.0,
      "rawHour": 60.5,
      "forecastIncome": 4720
    },
    "records": [
      {
        "recordId": "pr_001",
        "date": "2026-02-07",
        "customerName": "王先生",
        "timeRange": "20:00-22:30",
        "durationHour": 2.5,
        "forecastIncome": 210,
        "projectName": "中八陪练",
        "isEstimated": true
      }
    ],
    "monthOptions": ["2026-01", "2026-02"]
  }
}
```

---

## 4.15 财务看板 `board-finance`

这是最复杂的数据页之一。

### 原型可见
- 一级 tab：财务 / 客户 / 助教
- 二级筛选：时间、区域、是否环比
- 多个 section：
  - 经营一览
  - 预收资产
  - 收入
  - 其他财务块
- section 导航
- 粘性头部
- 比较值
- 提示弹窗

### 后端建议

#### 接口 R：财务看板聚合查询
**请求**
```json
{
  "timeRange": "current_month",
  "areaCode": "all",
  "compareEnabled": true
}
```

**响应**
```json
{
  "code": 0,
  "data": {
    "filters": {
      "timeRange": "current_month",
      "areaCode": "all",
      "compareEnabled": true
    },
    "overview": {
      "revenueAmount": 128000,
      "revenueCompare": 0.12,
      "customerCount": 860,
      "customerCompare": 0.05,
      "visitCount": 1260,
      "visitCompare": -0.03
    },
    "prepaidAssets": {
      "balanceAmount": 560000,
      "newRechargeAmount": 88000,
      "consumeAmount": 42000,
      "refundAmount": 3200
    },
    "incomeSections": [
      {
        "sectionId": "overview",
        "sectionTitle": "经营一览",
        "sectionDesc": "本月核心经营指标",
        "sectionEmoji": "📈",
        "cards": [
          {
            "metricCode": "revenue",
            "metricName": "营业收入",
            "value": 128000,
            "unit": "元",
            "compareValue": 0.12
          }
        ]
      }
    ],
    "availableTimeRanges": [
      { "code": "current_month", "name": "本月" },
      { "code": "last_month", "name": "上月" },
      { "code": "current_week", "name": "本周" }
    ],
    "availableAreas": [
      { "code": "all", "name": "全部区域" },
      { "code": "hall", "name": "大厅" },
      { "code": "a_zone", "name": "A区" }
    ]
  }
}
```

### 说明
- **所有统计卡和 section 数据必须后端返回。**
- 前端不应计算环比、同比，只负责展示。
- 提示弹窗内容如果是规则说明，可前端枚举；如果是后台运营配置，可后端返回。

---

## 4.16 客户看板 `board-customer`

### 原型可见
- 排序/维度筛选
- 项目筛选
- 时间筛选
- 客户 TOP100
- 多个维度榜单：最应召回、最大消费潜力、最高余额、最近充值、最近到店等

#### 接口 S：客户看板榜单
**请求**
```json
{
  "dimension": "recall_priority",
  "projectCode": "all",
  "timeRange": "last_60_days",
  "pageNo": 1,
  "pageSize": 100
}
```

**响应**
```json
{
  "code": 0,
  "data": {
    "dimension": "recall_priority",
    "projectCode": "all",
    "timeRange": "last_60_days",
    "total": 100,
    "list": [
      {
        "customerId": "c_001",
        "name": "王先生",
        "memberLevel": "vip",
        "balanceAmount": 8600,
        "consumePotentialScore": 95,
        "lastVisitDays": 15,
        "recentRechargeAt": "2026-02-20T12:00:00+08:00",
        "projectPreference": "中八",
        "exclusiveScore60d": 0.82,
        "frequentScore60d": 0.91,
        "mainTags": ["夜场偏好", "高价值"]
      }
    ]
  }
}
```

### 前端模板可维护
- 榜单卡片样式
- 维度图标与说明
- 维度值的视觉突出方式

---

## 4.17 助教看板 `board-coach`

### 原型可见
- 排序维度
- 擅长项目
- 时间范围
- 助教榜单
- 每个榜单卡片显示：
  - 姓名
  - 星级
  - 擅长项目
  - 定档 / 折前
  - 代表客户
  - 距升档小时数

#### 接口 T：助教看板榜单
**请求**
```json
{
  "sortBy": "perf_high",
  "skillCode": "all",
  "timeRange": "current_month",
  "pageNo": 1,
  "pageSize": 100
}
```

**响应**
```json
{
  "code": 0,
  "data": {
    "sortBy": "perf_high",
    "skillCode": "all",
    "timeRange": "current_month",
    "list": [
      {
        "coachId": "coach_001",
        "name": "小燕",
        "level": "star",
        "skills": ["中八", "斯诺克"],
        "perfHour": 86.2,
        "rawHour": 92.0,
        "representCustomers": ["王先生", "李女士", "赵总"],
        "upgradeRemainHour": 13.8,
        "salaryAmount": 6950,
        "customerBalanceAmount": 86200,
        "finishedTaskCount": 21
      }
    ]
  }
}
```

---

## 5. 通用备注 / 操作类接口

## 5.1 备注对象模型 `Note`

```json
{
  "noteId": "n_001",
  "entityType": "task",
  "entityId": "t_001",
  "entityName": "王先生",
  "content": "客户月底来店。",
  "ratings": {
    "intention": 4,
    "relation": 5,
    "service": 4
  },
  "createdBy": {
    "userId": "u_1001",
    "name": "小燕"
  },
  "createdAt": "2026-02-27T18:30:00+08:00",
  "updatedAt": "2026-02-27T18:30:00+08:00"
}
```

## 5.2 通用操作建议
- 置顶任务
- 放弃任务
- 新增备注
- 删除备注
- 修改默认首页
- 发送 AI 消息

都建议走单独写接口，而不是塞进一个大而全的“页面保存接口”。

---

## 6. 页面里哪些值建议写死，哪些不能写死

## 6.1 可以写死
- 页面标题
- 固定空状态文案
- AI 图标视觉资源
- badge 颜色映射
- section emoji
- “查看详情 / 取消 / 保存备注 / 复制”这类通用文案

## 6.2 不能写死
- 用户姓名、头像、身份、门店
- 客户姓名、手机号、余额、最近到店
- 助教绩效、工资、客户数
- 任务类型、任务状态、放弃原因
- 看板所有统计值、趋势值、榜单排序结果
- AI 话术正文
- 会话记录
- 备注正文
- 月份可选范围
- 管理员信息
- 权限状态

---

## 7. Mock 数据组织建议

## 7.1 建议目录

```text
mock/
  auth/
    login.json
    permission-status.json
  user/
    profile.json
    settings.json
  task/
    list.json
    detail-high-priority.json
    detail-priority.json
    detail-callback.json
    detail-relationship.json
  customer/
    detail.json
    service-records-2026-02.json
  coach/
    detail.json
    performance.json
    performance-records-2026-02.json
  note/
    list.json
  chat/
    sessions.json
    session-detail.json
  board/
    finance-current-month.json
    customer-recall-priority.json
    coach-perf-high.json
```

## 7.2 Mock 规则
- 所有金额统一返回 number，不带 `¥`
- 所有比率统一返回 number，不带 `%`
- 所有时间统一返回 ISO 8601 字符串
- 所有状态统一返回 code，不直接返回样式
- 所有列表都返回 `total/pageNo/pageSize/list`
- 所有详情都返回固定对象结构，不随页面版本频繁变化

---

## 8. 最终接口分组建议

## 8.1 认证与权限
- `POST /auth/login`
- `GET /auth/permission-status`
- `POST /auth/apply`
- `POST /auth/logout`

## 8.2 用户与设置
- `GET /user/profile`
- `GET /user/settings`
- `POST /user/settings/default-home`

## 8.3 任务
- `GET /task/list`
- `GET /task/detail`
- `POST /task/pin`
- `POST /task/abandon`
- `POST /task/note`
- `DELETE /task/note`

## 8.4 客户
- `GET /customer/detail`
- `GET /customer/service-records`

## 8.5 助教与业绩
- `GET /coach/detail`
- `GET /coach/performance`
- `GET /coach/performance-records`

## 8.6 备注
- `GET /note/list`

## 8.7 AI 会话
- `GET /chat/sessions`
- `GET /chat/session-detail`
- `POST /chat/send`

## 8.8 看板
- `GET /board/finance`
- `GET /board/customer-ranking`
- `GET /board/coach-ranking`

---

## 9. 结论

1. **原型中的绝大多数业务内容都应视为后端数据，不应写死到模板。**
2. **真正适合写死的是页面外壳、样式映射、空态文案和按钮文案。**
3. **对前端最重要的不是接口数量少，而是字段结构稳定。**
4. **建议尽早统一 code/enum 体系，否则后续页面会出现同义字段多版本并存。**
5. **Mock 阶段就应按真实接口结构组织 JSON，避免后续全量返工。**

---

## 10. 建议优先落地的接口顺序

### P0
1. 登录 / 权限状态
2. 当前用户信息
3. 任务列表
4. 任务详情
5. 备注新增/删除
6. 放弃任务
7. AI 会话列表 / 会话详情 / 发消息

### P1
1. 客户详情
2. 助教详情
3. 业绩详情
4. 业绩明细
5. 服务记录

### P2
1. 财务看板
2. 客户看板
3. 助教看板