1381 lines
28 KiB
Markdown
1381 lines
28 KiB
Markdown
# 页面数据需求说明文档（推测版 / 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. 助教看板
|