Neo-ZQYY/docs/prd/后端接口需求说明_数据需求PRD.md

页面数据需求说明文档（推测版 / 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

{
  "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

[
  { "code": "high_priority", "name": "高优先召回" },
  { "code": "priority", "name": "优先召回" },
  { "code": "relationship", "name": "关系构建" },
  { "code": "callback", "name": "客户回访" }
]

任务状态 TaskStatus

[
  { "code": "pending", "name": "待处理" },
  { "code": "completed", "name": "已完成" },
  { "code": "abandoned", "name": "已放弃" },
  { "code": "pinned", "name": "置顶" }
]

备注对象类型 NoteEntityType

[
  { "code": "customer", "name": "客户" },
  { "code": "coach", "name": "助教" },
  { "code": "task", "name": "任务" }
]

会员等级 MemberLevel

[
  { "code": "vip", "name": "VIP" },
  { "code": "gold", "name": "黄金会员" },
  { "code": "normal", "name": "普通会员" }
]

---

4. 页面级数据需求

4.1 登录页 login

页面用途

• 微信登录入口
• 用户协议勾选
• 登录后跳转默认首页

后端需求

接口 A：登录态获取 / 登录

{
  "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：提交访问申请

请求

{
  "siteId": "site_001",
  "applyRole": "coach",
  "phone": "13800000000",
  "staffNo": "A102",
  "nickname": "小燕"
}

响应

{
  "code": 0,
  "data": {
    "applicationId": "app_001",
    "status": "reviewing"
  }
}

页面模板可写死

• 提交流程 1~4 步说明
• 填写提示文案

风险提示

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

---

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

后端需求

接口 C：当前账号权限状态查询

{
  "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：获取用户设置

{
  "code": 0,
  "data": {
    "defaultHome": "task"
  }
}

接口 D2：保存用户设置

请求

{
  "defaultHome": "board"
}

响应

{
  "code": 0,
  "data": true
}

前端模板可维护

• “任务 / 看板”的展示文案

---

4.5 我的 my-profile

后端需求

接口 E：我的信息

{
  "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：任务列表页聚合数据

{
  "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：置顶 / 取消置顶任务

{
  "taskId": "t_001",
  "isPinned": true
}

接口 H2：放弃任务

{
  "taskId": "t_001",
  "reason": "客户已转会至其他球房"
}

接口 H3：新增任务备注

{
  "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：任务详情

{
  "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：新增 / 更新备注

{
  "taskId": "t_001",
  "content": "客户上次说月底来店。",
  "ratings": {
    "intention": 4,
    "relation": 5,
    "service": 4
  }
}

接口 J2：删除备注

{
  "noteId": "n_001"
}

放弃任务接口

可复用 H2

AI 话术复制

前端行为，不需要接口。

---

4.8 客户详情 customer-detail

页面可见数据

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

接口 K：客户详情

{
  "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：客户服务记录

{
  "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：助教详情

{
  "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：备注列表

{
  "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：会话列表

{
  "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：会话详情 / 消息流

{
  "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：发送消息

{
  "sessionId": "cs_001",
  "content": "输入消息..."
}

模板可维护

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

---

4.13 业绩详情 performance

原型可见

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

接口 P：业绩详情

{
  "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：业绩明细列表

{
  "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：财务看板聚合查询

请求

{
  "timeRange": "current_month",
  "areaCode": "all",
  "compareEnabled": true
}

响应

{
  "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：客户看板榜单

请求

{
  "dimension": "recall_priority",
  "projectCode": "all",
  "timeRange": "last_60_days",
  "pageNo": 1,
  "pageSize": 100
}

响应

{
  "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：助教看板榜单

请求

{
  "sortBy": "perf_high",
  "skillCode": "all",
  "timeRange": "current_month",
  "pageNo": 1,
  "pageSize": 100
}

响应

{
  "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

{
  "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 建议目录

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. 助教看板