Neo-ZQYY/docs/prd/specs/P15-miniapp-real-api-switch.md

P15 — 小程序前后端联调：Mock → 真实 API 切换

创建时间：2026-03-22 状态：草案 优先级：P0（dev-trace-log 的前置依赖） 关联 Spec：dev-trace-log（调试工具链）

---

一、背景

小程序前端已完成 H5 → 原生迁移（h5-miniprogram-migration spec）和格式统一（P13 spec）， 26 个后端接口已全部实现（API 契约文档确认）。但当前 services/api.ts 所有函数返回空 Mock 数据， request 导入已注释，前端与后端之间没有真实的 HTTP 通信。

本 PRD 覆盖"前后端联调"中 dev-trace-log 未涵盖的部分：将小程序从 Mock 数据切换到真实后端接口。

二、目标用户与场景

• 用户：开发者（前后端联调阶段）
• 场景：小程序连接本地 FastAPI 后端（localhost），验证登录、审核、任务、AI 模块的完整数据流

三、切换范围

3.1 本期切换（P0）

模块	涉及页面	涉及接口
认证	login、apply、reviewing、no-permission	AUTH-1~5（login、dev-login、me、refresh、apply）
任务	task-list、task-detail（4 变体）	TASK-1~4（列表、详情、操作、绩效概览）
审核	reviewing、apply	AUTH-3（me，状态判断）、AUTH-5（apply）
AI	chat、chat-history	CHAT-1~3（对话列表、发送消息/SSE、历史记录）

3.2 本期不做

模块	页面	原因
看板	board-finance、board-customer、board-coach	用户明确排除
助教	coach-detail	非优先联调模块
客户	customer-detail、customer-service-records	非优先联调模块
备注	notes	非优先联调模块
绩效	performance、performance-records	非优先联调模块
个人	my-profile	非优先联调模块

四、需求清单

REQ-1：API 环境配置

描述：创建统一的 API 配置模块，支持开发/测试/生产环境切换。

验收标准：

• 创建 apps/miniprogram/miniprogram/config/api.ts
• 定义 API_BASE_URL 常量，开发环境指向 http://localhost:8000
• 支持通过构建变量或条件编译切换环境
• utils/request.ts 从配置模块读取 base URL，禁止硬编码

REQ-2：恢复真实 API 调用

描述：将 services/api.ts 从 Mock 数据恢复为真实 HTTP 请求。

验收标准：

• 取消 request 导入的注释
• 移除 delay() 辅助函数
• 移除所有空 Mock 数据返回
• P0 模块（认证、任务、审核、AI）的 service 函数改为调用 request() 发起真实 HTTP 请求
• 非 P0 模块暂时保留 Mock（添加 // TODO: P15 后续批次切换 注释）

REQ-3：请求层统一封装

描述：确保 utils/request.ts 提供完整的请求封装能力。

验收标准：

• 自动附加 Authorization: Bearer <token> 请求头（从 Storage 读取）
• 统一解析响应格式 { code: 0, data: ... } / { code: number, message: string }
• code ≠ 0 时抛出业务错误（含 code 和 message）
• 网络异常（超时、断连）抛出网络错误（区分于业务错误）
• Token 过期（401）自动尝试 refresh，refresh 失败跳转登录页
• 请求超时设置（默认 30s，AI 接口 120s）

REQ-4：错误处理与用户反馈

描述：切换到真实接口后，网络错误、超时、空数据等场景需要有明确的用户反馈。

验收标准：

• 网络错误：显示"网络连接失败，请检查网络后重试"+ 重试按钮
• 请求超时：显示"请求超时，请稍后重试"+ 重试按钮
• 业务错误（code ≠ 0）：显示后端返回的 message
• 鉴权失败（401/403）：跳转登录页或显示无权限页
• 空数据：显示对应的空态页面（已有四态框架，确保正确触发）
• 所有错误场景记录到 console（开发环境），便于调试
• 页面级 pageState 四态（loading/empty/error/normal）在真实 API 场景下正确流转

REQ-5：数据格式适配验证

描述：验证前端数据结构与后端接口返回的数据结构一致，不一致处做适配。

验收标准：

• 后端响应统一 camelCase（ResponseWrapperMiddleware 已处理）
• 前端类型定义（services/api.ts 中的 interface）与后端实际返回字段一一对应
• 分页格式对齐：{ items: T[], total, page, pageSize }
• 金额字段：number 类型，保留 2 位小数，前端通过 formatMoney() 展示
• 时间字段：ISO 8601 字符串，前端通过 formatDateShort() / formatDateFull() 展示
• 不一致处在 service 层做适配转换，不在页面层处理

REQ-6：SSE 流式对接（AI 模块）

描述：AI 对话模块的 SSE 流式响应需要特殊处理，不能用普通 HTTP 请求。

验收标准：

• services/api.ts 中 chat 相关函数使用 SSE 方式调用后端
• 支持流式接收 token 并实时渲染到对话界面
• SSE 连接异常时显示错误提示并允许重试
• SSE 超时处理（AI 响应可能较慢，超时阈值 120s）
• 流式过程中显示"正在思考..."loading 态

REQ-7：登录流程对接

描述：小程序登录流程从 Mock 切换到真实微信登录 → 后端换 Token 流程。

验收标准：

• 开发环境使用 POST /api/xcx/dev-login（openid 模拟登录）
• 登录成功后将 access_token 和 refresh_token 存入 Storage
• app.ts 中 checkAuthStatus() 调用真实 GET /api/xcx/me 判断用户状态
• 根据用户 status（new/pending/approved/rejected/disabled）正确路由到对应页面
• Token 过期自动 refresh，refresh 失败清除 Storage 并跳转登录页

五、数据流

小程序页面
  ↓ 调用 service 函数
services/api.ts
  ↓ 调用 request()
utils/request.ts
  ↓ wx.request() + Authorization header
  ↓ 响应解析 + 错误处理
FastAPI 后端 (localhost:8000)
  ↓ ResponseWrapperMiddleware (camelCase)
  ↓ { code: 0, data: ... }
返回页面 → 更新 data → 渲染

六、依赖与约束

依赖项	状态	说明
后端 26 个接口	✅ 已实现	API 契约文档确认
API 契约文档	✅ 已就绪	docs/miniprogram-dev/API-contract.md
前端类型定义	✅ 已定义	services/api.ts 中的 interface
四态框架	✅ 已实现	loading/empty/error/normal
格式化工具函数	✅ 已实现	P13 spec 已完成
request.ts 封装	⚠️ 需验证	文件存在但当前未使用
dev-trace-log	🔜 并行开发	联调时提供调试可视化

七、验收标准（整体）

1. 登录流程：dev-login → 获取 token → 自动路由到正确页面
2. 任务列表：真实数据加载、分页、筛选正常工作
3. 任务详情：4 种变体页面正确渲染真实数据
4. AI 对话：SSE 流式响应实时渲染，错误时有提示
5. 错误场景：断网、超时、401、403、空数据均有正确的用户反馈
6. 非 P0 模块：保持 Mock 不受影响

八、风险

风险	影响	缓解措施
后端接口返回格式与前端类型不一致	页面渲染异常	REQ-5 要求逐字段验证
微信开发者工具不支持 localhost	无法联调	使用 dev-login 绕过微信登录；配置开发者工具"不校验合法域名"
SSE 在小程序中的兼容性	AI 模块无法工作	需验证 wx.request 的 enableChunked 或使用 requestTask
Token 过期处理不完善	用户体验中断	REQ-3 要求自动 refresh

九、与 dev-trace-log 的关系

本 PRD 是 dev-trace-log 的前置依赖：

• 没有真实 API 调用 → trace 系统无数据可采集
• 建议并行推进：先完成 REQ-13（基础设施），再逐模块切换（REQ-7 → REQ-2 → REQ-46）
• 切换过程中使用 dev-trace-log 的 span 链路验证每个接口的完整处理流程