root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3d2e5f816556c17b008946e7c7b7d18283c1098c
Neo-ZQYY/.kiro/specs/rns1-infra-contract-rewrite/requirements.md

240 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 需求文档 — 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 数据结构完全对齐，无字段遗漏或类型不匹配
Reference in New Issue View Git Blame Copy Permalink