Neo-ZQYY/.kiro/specs/rns1-infra-contract-rewrite/requirements.md

需求文档 — RNS1.0：基础设施与契约重写

简介

RNS1.0 是 NS1 小程序后端 API 补全项目的第一个子 spec，负责建立全局基础设施（响应包装、camelCase 转换）、修正路由路径、适配前端解包逻辑、完全重写 API 契约响应定义、以及修复前端跨页面参数传递问题。本 spec 阻塞所有后续子 spec（RNS1.1-1.4），必须最先完成。

来源文档

• docs/prd/Neo_Specs/RNS1-split-plan.md — 拆分计划主文档
• docs/prd/Neo_Specs/NS1-xcx-backend-api.md — NS1 原始 spec（含八½前置审查决策 R1-R8）
• docs/prd/Neo_Specs/storyboard-walkthrough-assistant-view.md — 助教视角走查报告（51 Gap）
• docs/prd/Neo_Specs/miniprogram-storyboard-walkthrough-gaps.md — 管理层视角走查报告（31 Gap）

术语表

• Response_Wrapper：全局响应包装中间件，将 FastAPI 路由返回值统一封装为 { code: 0, data: ... } 格式
• Exception_Handler：全局异常处理器，将 HTTPException 和未捕获异常统一封装为 { code: <status_code>, message: <detail> } 格式
• CamelCase_Converter：Pydantic schema 的 alias_generator=to_camel 配置，使 JSON 响应字段名从 snake_case 转为 camelCase
• API_Contract：docs/miniprogram-dev/API-contract.md，定义前后端接口的请求/响应格式基准文档
• Frontend_Unpacker：前端 services/api.ts 中 request() 工具函数的 .data 解包逻辑，从全局包装中提取业务数据
• Backend：FastAPI 后端应用，位于 apps/backend/
• Miniprogram：微信小程序前端应用，位于 apps/miniprogram/
• FDW：PostgreSQL Foreign Data Wrapper，用于从业务库 zqyy_app 访问 ETL 库 etl_feiqiu 的数据
• DateGroup：按日期分组的数据结构，包含日期标签、当日汇总、记录列表
• DWD-DOC：docs/reports/DWD-DOC/ 标杆文档，金额口径和字段语义的权威参考
• items_sum：DWD-DOC 强制使用的消费金额口径，= table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money
• 环比：月环比，当期值与上一个相同时间周期的对比百分比

需求

需求 1：全局响应包装中间件（T0-1）

用户故事： 作为后端开发者，我希望所有 API 响应自动包装为统一格式，以便前端可以用一致的方式解析成功和错误响应。

验收标准

1. THE Response_Wrapper SHALL 将所有成功响应（HTTP 2xx）封装为 { "code": 0, "data": <原始响应体> } 格式
2. THE Exception_Handler SHALL 将 HTTPException 封装为 { "code": <HTTP状态码>, "message": <错误详情> } 格式
3. THE Exception_Handler SHALL 将未捕获的服务端异常封装为 { "code": 500, "message": "Internal Server Error" } 格式，同时将完整异常堆栈写入服务端日志
4. WHEN 已有接口（Auth、Tasks、Notes、AI Chat 共 16 个端点）返回响应时，THE Response_Wrapper SHALL 对这些接口同样生效，保持向后兼容
5. WHEN 响应内容类型为 text/event-stream（SSE 流式端点）时，THE Response_Wrapper SHALL 跳过包装，直接透传原始响应
6. WHEN 响应内容类型为非 JSON 格式（如文件下载）时，THE Response_Wrapper SHALL 跳过包装，直接透传原始响应

需求 2：Pydantic Schema 统一 camelCase 输出（T0-2）

用户故事： 作为前端开发者，我希望后端 API 响应的 JSON 字段名统一为 camelCase 格式，以便前端无需手动转换 snake_case 字段。

验收标准

1. THE CamelCase_Converter SHALL 为所有 Pydantic 响应 schema 配置 alias_generator=to_camel 和 populate_by_name=True
2. WHEN Backend 返回 JSON 响应时，THE CamelCase_Converter SHALL 将所有字段名从 snake_case 转换为 camelCase（例如 user_id → userId，store_name → storeName）
3. THE CamelCase_Converter SHALL 同时应用于所有现有 schema（Auth、Tasks、Notes、AI Chat 模块）和所有新增 schema
4. WHEN Backend 接收请求体时，THE CamelCase_Converter SHALL 同时接受 camelCase 和 snake_case 格式的字段名（通过 populate_by_name=True 实现）

需求 3：后端路由路径修正（T0-3）

用户故事： 作为前端开发者，我希望后端任务恢复端点的路径与 API 契约和前端调用一致，以便联调时不会因路径不匹配而失败。

验收标准

1. THE Backend SHALL 将 POST /api/xcx/tasks/{taskId}/cancel-abandon 端点的路径修改为 POST /api/xcx/tasks/{taskId}/restore
2. WHEN 前端调用 POST /api/xcx/tasks/{taskId}/restore 时，THE Backend SHALL 执行与原 /cancel-abandon 端点相同的业务逻辑（将任务状态从 abandoned 恢复为 pending）
3. THE Backend SHALL 移除原 /cancel-abandon 路径，不保留旧路径的兼容映射

需求 4：前端请求工具函数适配全局包装（T0-4）

用户故事： 作为前端开发者，我希望 request() 工具函数自动从全局包装中提取业务数据，以便各页面调用 API 后无需手动解包。

验收标准

1. THE Frontend_Unpacker SHALL 在 services/api.ts 的 request() 函数中，对成功响应自动提取 .data 字段并返回给调用方
2. WHEN 响应的 code 字段不为 0 时，THE Frontend_Unpacker SHALL 抛出包含 code 和 message 的错误对象，供调用方的 catch 块处理
3. WHEN 响应不包含 code 字段（非标准格式，如 SSE 流式响应）时，THE Frontend_Unpacker SHALL 直接返回原始响应体，不做解包处理
4. THE Frontend_Unpacker SHALL 确保所有现有 API 调用（Auth、Tasks、Notes、AI Chat）在解包后行为不变

需求 5：API 契约完全重写（T0-5）

用户故事： 作为前后端开发者，我希望 API 契约文档准确反映前端实际需要的响应结构，以便后续子 spec（RNS1.1-1.4）的后端实现有明确的、与前端一致的接口定义作为基准。

5.1 BOARD-3 财务看板契约重写

验收标准

1. THE API_Contract SHALL 将 BOARD-3 响应从扁平 metrics 数组重写为 6 个独立板块的嵌套结构：overview（经营一览）、recharge（预收资产）、revenue（应计收入确认）、cashflow（现金流入）、expense（现金流出）、coachAnalysis（助教分析）
2. THE API_Contract SHALL 为 overview 板块定义 8 个指标字段（occurrence/discount/discountRate/confirmedRevenue/cashIn/cashOut/cashBalance/balanceRate），每个指标附带对应的环比字段（xxxCompare: string）和方向标记（isDown: boolean、isFlat: boolean）
3. THE API_Contract SHALL 为 recharge 板块定义储值卡 5 个指标（actualIncome/firstCharge/renewCharge/consumed/cardBalance）及各自环比字段，以及赠送卡 3×4 矩阵（行：新增/消费/余额，列：合计/酒水卡/台费卡/抵用券），每个单元格含值和环比字段，以及全类别会员卡余额合计（allCardBalance）及环比
4. THE API_Contract SHALL 为 revenue 板块定义收入结构表（structureRows：9 行含子行标记 isSub，每行含 name/desc/amount/discount/booked/bookedCompare）、正价明细（priceItems：4 项）、优惠明细（discountItems：4 项）、渠道明细（channelItems：3 项），以及确认收入合计及环比
5. THE API_Contract SHALL 为 cashflow 板块定义消费收款（consumeItems：3 项）、充值收款（rechargeItems：1 项）、合计及环比，每项含 name/desc/value/compare/isDown
6. THE API_Contract SHALL 为 expense 板块定义 4 个子分组：经营支出（operationItems：3 项）、固定支出（fixedItems：4 项）、助教分成（coachItems：4 项）、平台服务费（platformItems：3 项），以及合计及环比
7. THE API_Contract SHALL 为 coachAnalysis 板块定义基础课（basic）和激励课（incentive）两个子表，每个子表含汇总行（totalPay/totalShare/avgHourly 及各自环比）和按等级分行的数组（rows：初级/中级/高级/星级，每行含 level/pay/payCompare/share/shareCompare/hourly/hourlyCompare 及 payDown/shareDown/hourlyFlat 布尔标记）
8. THE API_Contract SHALL 为 BOARD-3 定义请求参数：time（8 种时间范围枚举：month/lastMonth/week/lastWeek/quarter3/quarter/lastQuarter/half6）、area（7 种区域枚举：all/hall/hallA/hallB/hallC/mahjong/teamBuilding）、compare（0/1，控制是否返回环比数据）
9. WHEN area 不为 all 时，THE API_Contract SHALL 标注 recharge（预收资产）板块不返回数据（储值卡数据不按区域拆分）
10. THE API_Contract SHALL 标注所有金额字段使用 items_sum 口径（DWD-DOC 强制规则 1），助教费用使用 assistant_pd_money + assistant_cx_money 拆分（DWD-DOC 强制规则 2）

5.2 BOARD-1 助教看板契约重写

验收标准

1. THE API_Contract SHALL 将 BOARD-1 响应从 10 个通用字段扩展为包含基础字段和 4 维度专属字段的结构
2. THE API_Contract SHALL 为每个助教 item 定义基础字段：id/name/initial/avatarGradient/level/skills/topCustomers，其中 skills 类型为 Array<{ text: string, cls: string }>（含 emoji 和样式类），topCustomers 类型为 string[]（含 P6 AC3 四级 emoji 前缀，如 '💖 王先生'/'🧡 李女士'/'💛 张先生'/'💙 赵女士'）
3. THE API_Contract SHALL 为 perf 维度定义专属字段：perfHours（当期定档工时）、perfHoursBefore（上期定档工时，可选）、perfGap（距升档差距描述，可选）、perfReached（是否已达标）
4. THE API_Contract SHALL 为 salary 维度定义专属字段：salary（工资总额）、salaryPerfHours（定档工时）、salaryPerfBefore（上期定档工时，可选）
5. THE API_Contract SHALL 为 sv 维度定义专属字段：svAmount（客源储值总额）、svCustomerCount（储值客户数）、svConsume（储值消耗额）
6. THE API_Contract SHALL 为 task 维度定义专属字段：taskRecall（召回任务完成数）、taskCallback（回访任务完成数）
7. THE API_Contract SHALL 为 BOARD-1 定义请求参数：sort（6 种排序枚举：perf_desc/perf_asc/salary_desc/salary_asc/sv_desc/task_desc）、skill（5 种技能枚举：all/chinese/snooker/mahjong/karaoke）、time（6 种时间范围枚举：month/quarter/last_month/last_3m/last_quarter/last_6m）
8. THE API_Contract SHALL 标注交叉约束：time=last_6m 与 sort=sv_desc 不兼容，后端收到此组合时返回 HTTP 400

5.3 BOARD-2 客户看板契约重写

验收标准

1. THE API_Contract SHALL 将 BOARD-2 响应从 8 个通用字段扩展为包含基础字段和 8 维度专属字段的结构
2. THE API_Contract SHALL 为每个客户 item 定义基础字段：id/name/initial/avatarCls/assistants，其中 assistants 类型为 Array<{ name: string, cls: string, heartScore: number, badge?: string, badgeCls?: string }>，heartScore 范围 0-10，前端通过 heart-icon 组件按 P6 AC3 四级映射渲染（💖>8.5 / 🧡>7 / 💛>5 / 💙≤5）
3. THE API_Contract SHALL 为 recall（最应召回）维度定义专属字段：idealDays/elapsedDays/overdueDays/visits30d/balance/recallIndex
4. THE API_Contract SHALL 为 potential（最大消费潜力）维度定义专属字段：potentialTags（Array<{ text: string, theme: string }>）/spend30d/avgVisits/avgSpend
5. THE API_Contract SHALL 为 balance（最高余额）维度定义专属字段：balance/lastVisit/monthlyConsume/availableMonths
6. THE API_Contract SHALL 为 recharge（最近充值）维度定义专属字段：lastRecharge/rechargeAmount/recharges60d/currentBalance
7. THE API_Contract SHALL 为 recent（最近到店）维度定义专属字段：daysAgo/visitFreq/idealDays/visits30d/avgSpend
8. THE API_Contract SHALL 为 spend60（最高消费近60天）维度定义专属字段：spend60d/visits60d/highSpendTag/avgSpend
9. THE API_Contract SHALL 为 freq60（最频繁近60天）维度定义专属字段：visits60d/avgInterval/weeklyVisits（Array<{ val: number, pct: number }>，8 周柱状图数据）/spend60d
10. THE API_Contract SHALL 为 loyal（最专一近60天）维度定义专属字段：intimacy/topCoachName/topCoachHeart/topCoachScore/coachName/coachRatio/coachDetails（Array<{ name, cls, heartScore, badge?, avgDuration, serviceCount, coachSpend, relationIdx }>）
11. THE API_Contract SHALL 为 BOARD-2 定义请求参数：dimension（8 种维度枚举）、project（5 种项目枚举：all/chinese/snooker/mahjong/karaoke）、page（页码，默认 1）、pageSize（每页条数，默认 20）

5.4 CUST-1 客户详情契约重写

验收标准

1. THE API_Contract SHALL 为 CUST-1 响应补充客户 Banner 字段：balance（余额）、consumption60d（近60天消费）、idealInterval（理想到店间隔）、daysSinceVisit（距上次到店天数）
2. THE API_Contract SHALL 为 CUST-1 响应补充 aiInsight 模块：summary（AI 分析摘要，string）和 strategies（策略建议列表，Array<{ color: string, text: string }>），数据来源标注为 biz.ai_cache（cache_type=app4_analysis）
3. THE API_Contract SHALL 为 CUST-1 响应补充 coachTasks 模块（关联助教任务列表）：每个助教含 name/level/levelColor/taskType/taskColor/bgClass/status/lastService/metrics（Array<{ label, value, color? }>，含近60天次数/总时长/次均时长）
4. THE API_Contract SHALL 为 CUST-1 响应补充 favoriteCoaches 模块（最亲密助教）：每位助教含 emoji/name/relationIndex/indexColor/bgClass/stats（Array<{ label, value, color? }>，含基础课时/激励课时/上课次数/充值金额）
5. THE API_Contract SHALL 将 CUST-1 消费记录从扁平结构重写为嵌套结构：每条记录含 id/type（table/shop/recharge 枚举）/date/tableName/startTime/endTime/duration/tableFee/tableOrigPrice/coaches（Array<{ name, level, levelColor, courseType, hours, perfHours?, fee }>）/foodAmount/foodOrigPrice/totalAmount/totalOrigPrice/payMethod/rechargeAmount
6. THE API_Contract SHALL 为 CUST-1 响应补充 notes 模块（备注列表）：每条备注含 id/tagLabel/createdAt/content
7. THE API_Contract SHALL 标注会员信息获取规则：通过 member_id JOIN dim_member 获取手机号和昵称（DWD-DOC 强制规则 DQ-6），禁止直接使用 settlement_head.member_phone

5.5 COACH-1 助教详情契约重写

验收标准

1. THE API_Contract SHALL 为 COACH-1 响应补充基本信息字段：workYears（工龄）、customerCount（客户数）、hireDate（入职日期）
2. THE API_Contract SHALL 为 COACH-1 响应补充 performance 模块（6 个绩效指标）：monthlyHours/monthlySalary/customerBalance/tasksCompleted/perfCurrent/perfTarget
3. THE API_Contract SHALL 为 COACH-1 响应补充 income 模块（收入明细）：thisMonth 和 lastMonth 各含 4 项收入分类（基础课时费/激励课时费/充值提成/酒水提成），每项含 label/amount/color
4. THE API_Contract SHALL 为 COACH-1 响应补充 tierNodes 字段（档位节点数组，如 [0, 100, 130, 160, 190, 220]），供前端绩效进度条组件使用
5. THE API_Contract SHALL 为 COACH-1 响应补充 historyMonths 模块（历史月份统计，最近 5+ 个月）：每月含 month（标签）/estimated（是否预估）/customers/hours/salary/callbackDone/recallDone
6. THE API_Contract SHALL 扩展 COACH-1 的 topCustomers 字段结构，从 5 个字段扩展为 10 个字段：补充 initial/avatarGradient/heartEmoji（P6 AC3 四级映射：💖/🧡/💛/💙）/relationScore（关系指数，0-10）/scoreColor/balance
7. THE API_Contract SHALL 为 COACH-1 响应补充近期服务明细中的 perfHours（折算工时）和 customerId 字段
8. THE API_Contract SHALL 为 COACH-1 的任务分组（visibleTasks/hiddenTasks/abandonedTasks）补充字段：TaskItem 补充 noteCount/pinned/notes（Array<{ pinned?, text, date }>），AbandonedTask 补充 reason
9. THE API_Contract SHALL 为 COACH-1 响应补充 notes 模块（备注列表）：每条备注含 id/content/timestamp/aiScore（AI 应用 6 评分，1-10，展示用）/customerName/tagLabel/createdAt

5.6 PERF-1 绩效概览契约重写

验收标准

1. THE API_Contract SHALL 将 PERF-1 的 thisMonthRecords 从扁平数组重写为按日期分组的 DateGroup 结构：每组含 date（日期标签）/totalHours（当日总工时）/totalIncome（当日总收入）/records（记录列表），每条记录含 customerName/timeRange/hours/courseType/courseTypeClass/location/income
2. THE API_Contract SHALL 为 PERF-1 响应补充收入档位数据：currentTier（当前档，含 basicRate/incentiveRate）、nextTier（下一档，含 basicRate/incentiveRate）、upgradeHoursNeeded（距升档所需工时）、upgradeBonus（升档奖金）
3. THE API_Contract SHALL 为 PERF-1 响应补充 lastMonthIncome（上月收入）字段
4. THE API_Contract SHALL 为 PERF-1 的 incomeItems 每项补充 desc 字段（费率×工时的拆分描述，如 "80元/h × 75h"）
5. THE API_Contract SHALL 为 PERF-1 的 newCustomers 补充 lastService（最后服务日期）和 count（服务次数）字段；为 regularCustomers 补充 hours（总工时）和 income（总收入）字段

5.7 TASK-1 绩效概览字段契约重写

验收标准

1. THE API_Contract SHALL 将 TASK-1 响应中的 performance 从 4 个字段（totalHours/totalIncome/totalCustomers/monthLabel）扩展为 15+ 个字段，补充：tierNodes（档位节点数组）/basicHours（基础课时）/bonusHours（激励课时）/currentTier（当前档位索引）/nextTierHours（下一档位工时阈值）/tierCompleted（是否已达标）/bonusMoney（升档奖金）/incomeTrend（收入趋势，如 "↓368"）/incomeTrendDir（up/down）/prevMonth（上月标签）
2. THE API_Contract SHALL 为 TASK-1 的任务 item 补充可选扩展字段：lastVisitDays（距上次到店天数）、balance（客户余额）、aiSuggestion（AI 建议摘要）

5.8 CHAT-1/2 对话模块契约重写

验收标准

1. THE API_Contract SHALL 统一 CHAT-2 消息的时间字段名为 createdAt（替代前端使用的 timestamp 和契约定义的 created_at，遵循 camelCase 规范）
2. THE API_Contract SHALL 为 CHAT-1 历史列表的每条记录补充 title（对话标题）字段
3. THE API_Contract SHALL 为 CHAT-2 消息补充 referenceCard 可选字段：含 type（customer/record 枚举）/title/summary/data（Record<string, string> 键值对）
4. THE API_Contract SHALL 补充 SSE 流式端点定义：POST /api/xcx/chat/stream，请求体含 chatId/content，响应为 text/event-stream
5. THE API_Contract SHALL 标注 CHAT 消息查询端点支持 customerId 查询参数：后端根据 customerId 自动查找或创建对话，返回对应的 chatId 和消息列表

需求 6：前端跨页面参数修复（T0-6）

用户故事： 作为助教或管理层用户，我希望在小程序中从一个页面跳转到另一个页面时，目标页面能正确加载对应的数据，而不会因为参数传递错误导致页面空白或加载错误数据。

6.1 task-detail 页面跳转修复

验收标准

1. WHEN 用户从 task-detail 页面点击"问问助手"跳转到 chat 页面时，THE Miniprogram SHALL 传递 customerId={detail.customerId} 参数（而非当前错误传递的 detail.id 即 taskId）
2. WHEN 用户从 task-detail 页面点击"查看全部服务记录"跳转到 customer-service-records 页面时，THE Miniprogram SHALL 传递 customerId={detail.customerId} 参数（而非当前错误传递的 detail.id 即 taskId）
3. IF TASK-2 响应中不包含 customerId 字段，THEN THE Miniprogram SHALL 无法完成上述跳转修复，因此本需求依赖 API 契约中 TASK-2 响应包含 customerId 字段的定义

6.2 customer-detail 页面跳转修复

验收标准

1. WHEN 用户从 customer-detail 页面点击"查看服务记录"跳转到 customer-service-records 页面时，THE Miniprogram SHALL 传递 customerId={detail.id} 参数（当前未传任何参数）
2. WHEN 用户从 customer-detail 页面点击"问问助手"跳转到 chat 页面时，THE Miniprogram SHALL 传递 customerId={detail.id} 参数（当前未传任何参数）
3. THE Miniprogram SHALL 修复 customer-detail 页面的 loadDetail() 函数，从 onLoad(options) 的 options.id 获取客户 ID，替代当前通过 __route__ 解析的错误方式

6.3 coach-detail 页面跳转修复

验收标准

1. WHEN 用户从 coach-detail 页面点击任务项跳转到 customer-detail 页面时，THE Miniprogram SHALL 传递 id={customerId} 参数（而非当前错误传递的 name={customerName}），此修复依赖 COACH-1 响应中 TaskItem 包含 customerId 字段

6.4 performance 页面跳转修复

验收标准

1. WHEN 用户从 performance 页面点击客户卡片或服务记录跳转到 task-detail 页面时，THE Miniprogram SHALL 传递 id={taskId} 参数（而非当前错误传递的 customerName={name}），此修复依赖 PERF-1 响应中记录包含 taskId 字段

6.5 chat 页面多入口参数路由

验收标准

1. WHEN chat 页面从 task-detail 或 customer-detail 跳转进入（携带 customerId 参数）时，THE Miniprogram SHALL 使用 customerId 查询参数调用 CHAT 消息端点，由后端自动查找或创建对话
2. WHEN chat 页面从 chat-history 跳转进入（携带 historyId 参数）时，THE Miniprogram SHALL 使用 historyId 作为 chatId 直接加载历史消息
3. WHEN chat 页面从 coach-detail 跳转进入（携带 coachId 参数）时，THE Miniprogram SHALL 使用 coachId 作为上下文参数传递给 CHAT 端点

6.6 globalData.authUser 字段扩展

验收标准

1. THE Miniprogram SHALL 在登录成功后（/api/xcx/me 响应）将 role、storeName、coachLevel、avatar 字段存入 globalData.authUser，供 task-list Banner、performance Banner、performance-records Banner 等多个页面使用
2. WHEN globalData.authUser 已包含上述字段时，THE Miniprogram SHALL 不再需要各页面单独请求 /me 接口获取这些信息

需求 7：契约文档一致性与完整性

用户故事： 作为后续子 spec（RNS1.1-1.4）的开发者，我希望重写后的 API 契约文档内部一致、无歧义，以便直接作为后端实现的唯一基准。

验收标准

1. THE API_Contract SHALL 确保所有接口的响应字段名统一使用 camelCase 格式（与需求 2 的 CamelCase_Converter 输出一致）
2. THE API_Contract SHALL 确保所有涉及金额的字段标注使用 items_sum 口径，禁止使用 consume_money（DWD-DOC 强制规则 1）
3. THE API_Contract SHALL 确保所有涉及助教费用的字段标注使用 assistant_pd_money（陪打）+ assistant_cx_money（超休）拆分，禁止使用 service_fee（DWD-DOC 强制规则 2）
4. THE API_Contract SHALL 确保所有涉及会员信息的字段标注通过 member_id JOIN dim_member 获取，禁止直接使用 member_phone/member_name（DWD-DOC 强制规则 DQ-6/DQ-7）
5. THE API_Contract SHALL 为每个接口标注数据源（FDW 表名或业务表名），供后续子 spec 实现时参考
6. THE API_Contract SHALL 确保重写后的 8 个接口响应定义（BOARD-1/2/3、CUST-1、COACH-1、PERF-1、TASK-1 performance、CHAT-1/2）与前端内联 mock 数据结构完全对齐，无字段遗漏或类型不匹配