feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

docs/miniprogram-dev/API-requirement.md

@@ -0,0 +1,65 @@
+# 小程序前端 → 后端接口需求记录
+
+> 记录小程序前端在硬编码审计中发现的、需要后端配合的接口需求。
+> 创建时间：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 项时间范围）、维度选项等硬编码在前端
+- 决定：这些筛选选项全平台共用，暂保持前端硬编码
+- 后续：如果需要动态调整，再改为后端配置接口
+- 状态：🔒 暂不处理