546 lines
15 KiB
Markdown
546 lines
15 KiB
Markdown
# 小程序后端接口输出规范
|
||
|
||
> **文档编号**：DS-API-OUTPUT-001
|
||
> **版本**：v1.0.0
|
||
> **适用范围**：NeoZQYY 小程序所有后端接口（HTTP JSON 响应体）
|
||
> **最后更新**：2026-03-18
|
||
> **关联文档**：
|
||
> - [DISPLAY-STANDARDS.md](./design-system/DISPLAY-STANDARDS.md) — 前端展示规范第 1～6 章
|
||
> - [DISPLAY-STANDARDS-2.md](./design-system/DISPLAY-STANDARDS-2.md) — 第 7～9 章（截止日期 / 评分 / Mock）
|
||
> - [DATETIME-DISPLAY-STANDARD.md](./design-system/DATETIME-DISPLAY-STANDARD.md) — 时间展示规范
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [总体约定](#1-总体约定)
|
||
2. [响应体结构](#2-响应体结构)
|
||
3. [字段类型规范（核心规则）](#3-字段类型规范核心规则)
|
||
4. [各业务字段细则](#4-各业务字段细则)
|
||
5. [枚举值规范](#5-枚举值规范)
|
||
6. [分页规范](#6-分页规范)
|
||
7. [接口端点命名规范](#7-接口端点命名规范)
|
||
8. [各页面接口字段对照表](#8-各页面接口字段对照表)
|
||
9. [禁止事项速查](#9-禁止事项速查)
|
||
|
||
---
|
||
|
||
## 1. 总体约定
|
||
|
||
| 项目 | 规范 |
|
||
|------|------|
|
||
| 协议 | HTTPS REST JSON |
|
||
| 编码 | UTF-8 |
|
||
| Content-Type | `application/json` |
|
||
| 时区 | **后端统一输出 UTC，前端负责本地化展示** |
|
||
| 数值精度 | 金额为整数（元），课时为 0.5 步长浮点 |
|
||
| 空值 | 字段不存在时输出 `null`，**不得省略字段** |
|
||
| 布尔值 | `true` / `false`，不用 `0/1` |
|
||
| 字符串编码格式 | 纯数据，**不含展示单位**（¥、h、%、笔等） |
|
||
|
||
---
|
||
|
||
## 2. 响应体结构
|
||
|
||
### 2.1 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
### 2.2 失败响应
|
||
|
||
```json
|
||
{
|
||
"code": 40001,
|
||
"message": "参数错误：缺少 customerId",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 2.3 分页列表响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [ ... ],
|
||
"total": 32,
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"hasMore": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 字段类型规范（核心规则）
|
||
|
||
> **核心原则：后端输出原始语义数值，前端负责格式化展示。**
|
||
> 后端不拼接 `¥`、`h`、`%`、`笔` 等展示字符，也不做千分位格式化。
|
||
|
||
### 3.1 类型对照表
|
||
|
||
| 字段类型 | 后端输出类型 | 示例 | 前端处理函数 | 禁止输出 |
|
||
|----------|-------------|------|-------------|----------|
|
||
| **金额** | `number`（元，整数） | `12680` | `formatMoney()` | `"¥12,680"` `"12680.00"` |
|
||
| **课时** | `number`（小时，0.5步长） | `2.5` | `formatHours()` | `"2.5h"` `"2h30min"` |
|
||
| **计数** | `number`（整数） | `32` | `formatCount()` | `"32笔"` `"32次"` |
|
||
| **百分比** | `number`（0～100，整数或1位小数） | `85.5` | `formatPercent()` | `"85.5%"` `"0.855"` |
|
||
| **日期** | `string`（`YYYY-MM-DD`） | `"2026-03-18"` | `formatDeadline()` | `"2026/03/18"` `1742256000000` |
|
||
| **时间戳** | `string`（ISO 8601，含时区） | `"2026-03-18T08:30:00+08:00"` | `formatRelativeTime()` | Unix 毫秒整数 |
|
||
| **等级 key** | `string`（英文 key） | `"star"` | 查 `LEVEL_MAP` | `"星级"` `"gold"` |
|
||
| **状态 key** | `string`（英文 key） | `"pending"` | 查枚举映射 | `"待处理"` |
|
||
| **评分** | `number`（0～10，0.5步长） | `8.5` | `scoreToHalfStar()` | `"8.5分"` `4` (5分制) |
|
||
| **布尔** | `boolean` | `true` | 直接使用 | `1` `"true"` |
|
||
| **空值** | `null` | `null` | 展示 `--` | `""` `0`（有语义时除外） |
|
||
|
||
---
|
||
|
||
## 4. 各业务字段细则
|
||
|
||
### 4.1 金额字段
|
||
|
||
```json
|
||
// 正确
|
||
{ "balance": 2000, "income": 510, "salary": 12680 }
|
||
|
||
// 错误
|
||
{ "balance": "¥2,000", "income": "¥510", "salary": "¥12,680" }
|
||
```
|
||
|
||
- 统一以「元」为单位，**不含分**
|
||
- 负数直接输出负整数：`-368`
|
||
- 零值输出 `0`，不输出 `null`
|
||
- 前端调用 `formatMoney(value)` 展示
|
||
|
||
### 4.2 课时字段
|
||
|
||
```json
|
||
// 正确
|
||
{ "hours": 2.5, "hoursRaw": 3.0 }
|
||
|
||
// 错误
|
||
{ "hours": "2.5h", "deduct": "(折0.5h)" }
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `hours` | `number` | 折算后实际计入课时（小时） |
|
||
| `hoursRaw` | `number \| null` | 折算前原始小时数；无折算时输出 `null` |
|
||
|
||
- 前端仅在 `hoursRaw !== null && hoursRaw !== hours` 时展示折算备注
|
||
- 步长为 0.5，如 `1.0`、`1.5`、`2.0`、`2.5`
|
||
|
||
### 4.3 计数字段
|
||
|
||
```json
|
||
// 正确
|
||
{ "totalCount": 32, "serviceCount": 18 }
|
||
|
||
// 错误
|
||
{ "totalCount": "32笔", "serviceCount": "18次" }
|
||
```
|
||
|
||
- 前端调用 `formatCount(value, '笔')` 展示，单位由页面层决定
|
||
|
||
### 4.4 百分比字段
|
||
|
||
```json
|
||
// 正确（进度/完成率）
|
||
{ "filledPct": 85, "completionRate": 72.5 }
|
||
|
||
// 错误
|
||
{ "filledPct": "85%", "completionRate": 0.725 }
|
||
```
|
||
|
||
- 统一 0～100 整数或1位小数，**不用小数形式**
|
||
- 允许超过 100（如完成率 120%）
|
||
|
||
### 4.5 日期与时间
|
||
|
||
| 场景 | 格式 | 示例 |
|
||
|------|------|------|
|
||
| 纯日期（截止日、生日等） | `YYYY-MM-DD` | `"2026-03-18"` |
|
||
| 精确时间（备注时间、服务记录） | ISO 8601 含时区 | `"2026-03-18T08:30:00+08:00"` |
|
||
| 时间区间（service timeRange） | 直接拼接字符串 | `"20:00-22:00"` |
|
||
|
||
- **禁止** 输出 Unix 毫秒时间戳整数
|
||
- **禁止** 输出 `YYYY/MM/DD` 格式
|
||
- 前端截止日期调用 `formatDeadline(date)` 语义化
|
||
- 前端相对时间调用 `formatRelativeTime(iso)` 展示
|
||
|
||
### 4.6 评分字段
|
||
|
||
```json
|
||
// 正确
|
||
{ "heartScore": 8.5, "noteScore": 7.0 }
|
||
|
||
// 错误
|
||
{ "heartScore": 4, "noteScore": "7.5分" }
|
||
```
|
||
|
||
- 统一使用 **0～10 分制**，0.5 步长
|
||
- 0 表示「未评分」，前端展示 `--`
|
||
- 前端调用 `scoreToHalfStar(score)` 转换为 0～5 星展示
|
||
|
||
### 4.7 等级字段
|
||
|
||
```json
|
||
// 正确
|
||
{ "level": "star" }
|
||
|
||
// 错误
|
||
{ "level": "星级" }
|
||
```
|
||
|
||
| 后端 key | 前端展示 |
|
||
|----------|----------|
|
||
| `star` | 星级助教 |
|
||
| `senior` | 高级助教 |
|
||
| `middle` | 中级助教 |
|
||
| `junior` | 初级助教 |
|
||
|
||
### 4.8 天数字段
|
||
|
||
```json
|
||
// 正确
|
||
{ "lastVisitDays": 23, "daysAbsent": 23 }
|
||
|
||
// 错误
|
||
{ "lastVisitDays": "23天前", "daysAbsent": "23天" }
|
||
```
|
||
|
||
- 统一输出整数天数，不含「天」「天前」等汉字
|
||
- 前端拼接文案时自行添加单位
|
||
|
||
---
|
||
|
||
## 5. 枚举值规范
|
||
|
||
所有枚举字段统一使用英文下划线 key，前端维护映射表。
|
||
|
||
### 5.1 任务类型 `taskType`
|
||
|
||
| key | 展示文案 |
|
||
|-----|----------|
|
||
| `callback` | 回访 |
|
||
| `priority_recall` | 优先召回 |
|
||
| `high_priority` | 高优先召回 |
|
||
| `relationship` | 关系构建 |
|
||
|
||
### 5.2 任务状态 `status`
|
||
|
||
| key | 展示文案 |
|
||
|-----|----------|
|
||
| `pending` | 待处理 |
|
||
| `completed` | 已完成 |
|
||
| `abandoned` | 已放弃 |
|
||
|
||
### 5.3 助教等级 `level`
|
||
|
||
| key | 展示文案 |
|
||
|-----|----------|
|
||
| `star` | 星级助教 |
|
||
| `senior` | 高级助教 |
|
||
| `middle` | 中级助教 |
|
||
| `junior` | 初级助教 |
|
||
|
||
### 5.4 课程类型 `courseType`
|
||
|
||
| key | 展示文案 | 样式 key |
|
||
|-----|----------|----------|
|
||
| `basic` | 基础课 | `tag-basic` |
|
||
| `vip` | 包厢课 | `tag-vip` |
|
||
| `tip` | 打赏课 | `tag-tip` |
|
||
| `recharge` | 充值 | `tag-recharge` |
|
||
| `incentive` | 激励 | `tag-incentive` |
|
||
|
||
### 5.5 线索来源 `source`
|
||
|
||
| key | 展示文案 |
|
||
|-----|----------|
|
||
| `manual` | 助教手动录入 |
|
||
| `ai_consumption` | 系统自动（消费分析） |
|
||
| `ai_note` | 系统自动（备注分析） |
|
||
|
||
### 5.6 线索分类 `category`
|
||
|
||
| key | 展示文案 |
|
||
|-----|----------|
|
||
| `customer_basic` | 客户基础 |
|
||
| `consumption` | 消费习惯 |
|
||
| `play_pref` | 玩法偏好 |
|
||
| `promo_pref` | 促销偏好 |
|
||
| `social` | 社交偏好 |
|
||
| `feedback` | 重要反馈 |
|
||
|
||
### 5.7 截止日期语义化（前端计算，非接口字段）
|
||
|
||
后端只输出 `deadline: "YYYY-MM-DD"`，前端调用 `formatDeadline()` 计算：
|
||
|
||
| diff | 展示文案 | 样式 |
|
||
|------|----------|------|
|
||
| < 0 | `逾期 N 天` | `danger`（红） |
|
||
| = 0 | `今天到期` | `warning`（橙） |
|
||
| 1～7 | `还剩 N 天` | `normal` |
|
||
| > 7 | `MM-DD` | `muted`（灰） |
|
||
| null | `--` | `muted` |
|
||
|
||
---
|
||
|
||
## 6. 分页规范
|
||
|
||
```json
|
||
{
|
||
"list": [],
|
||
"total": 100,
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"hasMore": true
|
||
}
|
||
```
|
||
|
||
- `page` 从 1 开始计数
|
||
- `hasMore` 由后端根据 `total` 和当前 `page * pageSize` 计算
|
||
- `total` 为全量数据总条数（不是当前页条数）
|
||
|
||
---
|
||
|
||
## 7. 接口端点命名规范
|
||
|
||
```
|
||
GET /api/xcx/tasks 任务列表
|
||
GET /api/xcx/tasks/:id 任务详情
|
||
GET /api/xcx/tasks/:id/notes 任务备注列表
|
||
POST /api/xcx/tasks/:id/notes 新增备注
|
||
GET /api/xcx/tasks/:id/service-records 近期服务记录
|
||
GET /api/xcx/coaches 助教看板列表
|
||
GET /api/xcx/coaches/:id 助教详情
|
||
GET /api/xcx/performance 绩效概览
|
||
GET /api/xcx/performance/records 绩效记录列表（支持月份分页）
|
||
GET /api/xcx/retention-clues/:customerId 维客线索
|
||
```
|
||
|
||
- 资源名用复数小写连字符
|
||
- 路径参数用 `:id`，不用查询参数代替
|
||
- 月份筛选用 `?year=2026&month=2`
|
||
|
||
---
|
||
|
||
## 8. 各页面接口字段对照表
|
||
|
||
### 8.1 任务列表页 `GET /api/xcx/tasks`
|
||
|
||
```json
|
||
{
|
||
"id": "task-001",
|
||
"customerName": "王先生",
|
||
"taskType": "high_priority",
|
||
"taskTypeLabel": "高优先召回",
|
||
"deadline": "2026-03-20",
|
||
"heartScore": 8.5,
|
||
"isPinned": true,
|
||
"hasNote": true,
|
||
"status": "pending",
|
||
"lastVisitDays": 23,
|
||
"balance": 2000,
|
||
"filledPct": 85,
|
||
"aiSuggestion": "建议本周内回访，余额即将到期"
|
||
}
|
||
```
|
||
|
||
**说明：**
|
||
- `lastVisitDays`：integer，距上次到店天数，null 表示从未到店
|
||
- `balance`：integer（元），余额；null 表示无储值
|
||
- `filledPct`：integer（0～100），关系进度百分比
|
||
- `deadline`：`YYYY-MM-DD`，前端调用 `formatDeadline()` 语义化
|
||
- `aiSuggestion`：string，AI 摘要文案，后端生成，前端直接展示
|
||
|
||
### 8.2 任务详情页 `GET /api/xcx/tasks/:id`
|
||
|
||
```json
|
||
{
|
||
"id": "task-001",
|
||
"customerName": "王先生",
|
||
"taskType": "high_priority",
|
||
"taskTypeLabel": "高优先召回",
|
||
"status": "pending",
|
||
"deadline": "2026-03-20",
|
||
"heartScore": 8.5,
|
||
"phone": "138****5678",
|
||
"lastVisitDate": "2026-03-01",
|
||
"lastSpendAmount": 380,
|
||
"daysAbsent": 23,
|
||
"callbackReason": "上次体验课后未续费，需跟进意向",
|
||
"churnRisk": "high",
|
||
"spendTrend": "down",
|
||
"aiAnalysis": {
|
||
"summary": "最近 3 个月每周均有 1-2 次课程互动",
|
||
"suggestions": ["询问近期是否有空", "告知会员专属活动"]
|
||
},
|
||
"talkingPoints": ["王哥好久不见..."],
|
||
"notes": [
|
||
{
|
||
"id": "note-001",
|
||
"content": "已通过微信联系王先生...",
|
||
"tagType": "customer",
|
||
"tagLabel": "客户：王先生",
|
||
"createdAt": "2026-03-10T16:30:00+08:00",
|
||
"score": 8.5
|
||
}
|
||
],
|
||
"serviceRecords": [
|
||
{
|
||
"table": "A12号台",
|
||
"type": "基础课",
|
||
"typeClass": "basic",
|
||
"recordType": "course",
|
||
"hours": 2.5,
|
||
"hoursRaw": 3.0,
|
||
"income": 200,
|
||
"isEstimate": true,
|
||
"drinks": "百威x2 红牛x1",
|
||
"date": "2026-02-07T21:30:00+08:00"
|
||
}
|
||
],
|
||
"serviceSummary": {
|
||
"totalHours": 6.0,
|
||
"totalIncome": 510,
|
||
"avgIncome": 170
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明：**
|
||
- `phone`：后端已做脱敏处理（`138****5678`），或根据权限返回明文
|
||
- `score`：0～10 分制，0 表示未评分
|
||
- `serviceRecords.hours`、`hoursRaw`：number（小时），前端调用 `formatHours()`
|
||
- `serviceRecords.income`、`serviceSummary.*`：integer（元），前端调用 `formatMoney()`
|
||
- `isEstimate`：boolean，true 时前端展示「预估」标注
|
||
|
||
### 8.3 助教看板页 `GET /api/xcx/coaches`
|
||
|
||
```json
|
||
{
|
||
"id": "coach-001",
|
||
"name": "小燕",
|
||
"level": "star",
|
||
"storeName": "朗朗桌球",
|
||
"customerCount": 28,
|
||
"monthHours": 86.0,
|
||
"monthIncome": 18600,
|
||
"svAmount": 5000,
|
||
"filledPct": 92,
|
||
"taskCount": 6,
|
||
"urgentTaskCount": 2,
|
||
"aiSuggestion": "本月表现优秀，建议重点跟进 2 位高风险流失客户"
|
||
}
|
||
```
|
||
|
||
**说明：**
|
||
- `level`：英文 key，前端查 `LEVEL_MAP` 展示中文
|
||
- `monthHours`：number（小时），前端调用 `formatHours()`
|
||
- `monthIncome`、`svAmount`：integer（元），前端调用 `formatMoney()`
|
||
- `filledPct`：integer（0～100），前端调用 `formatPercent()` 或 `toProgressWidth()`
|
||
- `customerCount`、`taskCount`、`urgentTaskCount`：integer，前端调用 `formatCount()`
|
||
|
||
### 8.4 绩效记录页 `GET /api/xcx/performance/records`
|
||
|
||
请求参数：`?year=2026&month=2&page=1&pageSize=20`
|
||
|
||
```json
|
||
{
|
||
"summary": {
|
||
"totalCount": 32,
|
||
"totalHours": 59.0,
|
||
"totalIncome": 4720
|
||
},
|
||
"dateGroups": [
|
||
{
|
||
"date": "2026-02-07",
|
||
"totalHours": 6.0,
|
||
"totalIncome": 510,
|
||
"records": [
|
||
{
|
||
"id": "r1",
|
||
"customerName": "王先生",
|
||
"timeRange": "20:00-22:00",
|
||
"hours": 2.0,
|
||
"hoursRaw": null,
|
||
"courseType": "basic",
|
||
"location": "3号台",
|
||
"income": 160
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"hasMore": false,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
```
|
||
|
||
**说明：**
|
||
- `date`：`YYYY-MM-DD`，前端格式化为「2月7日」
|
||
- `summary.*`、`dateGroups.totalIncome`、`records.income`：integer（元）
|
||
- `summary.totalHours`、`dateGroups.totalHours`、`records.hours`：number（小时）
|
||
- `hoursRaw`：null 表示无折算，有值时前端展示折算备注
|
||
- `courseType`：英文 key（`basic`/`vip`/`tip`/`recharge`/`incentive`）
|
||
|
||
### 8.5 备注接口 `GET /api/xcx/tasks/:id/notes`
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "note-001",
|
||
"content": "已通过微信联系王先生...",
|
||
"tagType": "customer",
|
||
"tagLabel": "客户：王先生",
|
||
"createdAt": "2026-03-10T16:30:00+08:00",
|
||
"score": 8.5
|
||
}
|
||
]
|
||
```
|
||
|
||
- `tagType`：`customer` / `coach` / `system`
|
||
- `score`：0 表示未评分，0.5 步长，前端调用 `scoreToHalfStar()` 转 5 星制
|
||
- `createdAt`：ISO 8601，前端调用 `formatRelativeTime()` 展示相对时间
|
||
|
||
---
|
||
|
||
## 9. 禁止事项速查
|
||
|
||
| 禁止行为 | 正确做法 |
|
||
|----------|----------|
|
||
| 输出 `"¥12,680"` | 输出 `12680` |
|
||
| 输出 `"2.5h"` | 输出 `2.5` |
|
||
| 输出 `"32笔"` | 输出 `32` |
|
||
| 输出 `"85%"` | 输出 `85` |
|
||
| 输出 `"星级"` 作为等级 | 输出 `"star"` |
|
||
| 输出 `"待处理"` 作为状态 | 输出 `"pending"` |
|
||
| 省略值为 null 的字段 | 显式输出 `null` |
|
||
| 用 `0` 代替 `null` 表示「无」 | 用 `null`（0 保留给有意义的零值） |
|
||
| 输出 Unix 毫秒时间戳 | 输出 ISO 8601 字符串 |
|
||
| 输出 `YYYY/MM/DD` 日期格式 | 输出 `YYYY-MM-DD` |
|
||
| 后端做 `toLocaleString()` 格式化 | 后端输出原始数值，前端格式化 |
|
||
| `hoursRaw` 输出 `"(折0.5h)"` | 输出 `3.0`（原始小时数） |
|
||
|
||
---
|
||
|
||
## 关联文档
|
||
|
||
- [DISPLAY-STANDARDS.md](./design-system/DISPLAY-STANDARDS.md) — 前端格式化规范
|
||
- [DISPLAY-STANDARDS-2.md](./design-system/DISPLAY-STANDARDS-2.md) — 截止日期 / 评分 / Mock 规范
|
||
- [DATETIME-DISPLAY-STANDARD.md](./design-system/DATETIME-DISPLAY-STANDARD.md) — 时间展示规范
|
||
- `utils/money.ts` — `formatMoney` / `formatCount` / `formatPercent` / `toProgressWidth`
|
||
- `utils/time.ts` — `formatHours` / `formatDeadline` / `formatRelativeTime`
|
||
- `utils/rating.ts` — `scoreToHalfStar` / `isUnrated`
|
||
- `utils/mock-data.ts` — Mock 数据（字段结构与接口保持一致）
|