# 小程序前端 → 后端接口需求记录

> 记录小程序前端在硬编码审计中发现的、需要后端配合的接口需求。
> 创建时间：2026-03-18

---

## REQ-1：技能类型配置接口

- 来源页面：`board-coach`
- 当前状态：`SKILL_OPTIONS` 硬编码 5 项（全部/中🎱/🎯斯诺克/小组课/打赏课）
- 需求：门店技能类型应可配置，需要后端提供配置接口
- 建议接口：`GET /api/xcx/config/skill-types`
- 返回格式：`{ skills: Array<{ value: string; text: string }> }`
- 优先级：P2（联调阶段处理）

---

## REQ-2：对话图标颜色固定化

- 来源页面：`chat-history`
- 当前状态：`iconGradient` 每次渲染随机分配颜色，刷新后颜色会变
- 需求：颜色应按对话 ID 哈希固定，无需后端配合
- 前端方案：已改为按 `id` 字符串哈希取模，从 6 色渐变数组中固定选取
- 状态：✅ 已完成（前端自行处理）

---

## REQ-3：开发模式 openid 上线安全

- 来源页面：`login`
- 当前状态：开发模式使用固定 `dev_test_openid`，通过 `API_BASE.startsWith("http://127.0.0.1")` 判断
- 风险：如果 `isDevMode` 判断逻辑被绕过，可能存在安全隐患
- 需求：上线前确保后端 `/api/xcx/dev-login` 接口在生产环境不可用
- 建议：后端通过环境变量控制 dev-login 路由注册，生产环境不注册该路由
- 优先级：P0（上线前必须处理）

---

## REQ-4：`authUser` 字段扩展

- 来源页面：`performance-records`、`my-profile`、`coach-detail`
- 当前状态：`globalData.authUser` 仅有 `userId`、`status`、`nickname`
- 需求：多个页面需要展示当前用户的角色、门店名、助教等级等信息
- 建议：`GET /api/xcx/me` 返回扩展字段，前端存入 `authUser`
- 新增字段：

| 字段 | 类型 | 说明 | 来源 |
|------|------|------|------|
| `role` | `string` | 用户角色（如"助教"） | 后端用户表 |
| `storeName` | `string` | 所属门店名称 | 后端门店表 |
| `coachLevel` | `string?` | 助教等级（junior/middle/senior/star） | 后端助教表（仅助教角色有） |
| `avatar` | `string?` | 用户头像 URL | 后端用户表 |

- 优先级：P1（联调阶段处理）

---

## REQ-5：筛选选项全平台共用

- 来源页面：`board-coach`、`board-customer`
- 当前状态：`SORT_OPTIONS`（6 项排序维度）、`TIME_OPTIONS`（6 项时间范围）、维度选项等硬编码在前端
- 决定：这些筛选选项全平台共用，暂保持前端硬编码
- 后续：如果需要动态调整，再改为后端配置接口
- 状态：🔒 暂不处理