收口文档评审冲突并补齐 Sprint 执行计划

统一性能、token、配额与成本口径,补齐短信登录等缺口任务,并回写脚手架实测暴露的思考模式与峰谷计价约束。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
xsl
2026-08-14 09:40:50 +08:00
co-authored by Cursor
parent e31755e343
commit f4075f6827
13 changed files with 1200 additions and 290 deletions
+49 -25
View File
@@ -1,6 +1,6 @@
# 「美搭」需求规格说明
> 版本:v1.0 | 更新日期:2026-08-13 | 状态:待评审
> 版本:**v1.2** | 更新日期:2026-08-13 | 状态:待评审
>
> **本文的定位**:把散落在五份需求文档中的需求统一编号、统一优先级、统一验收标准,成为开发任务拆解与测试用例编写的唯一索引。
>
@@ -76,15 +76,17 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-ACC-01 | 华为账号登录(UnionID/OpenID) | P0 | V1 | 登录成功率 ≥ 99%;首次登录自动创建用户;UnionID 与内部 user_id 映射唯一 | TD-15 |
| FR-ACC-02 | 游客模式:未登录可体验非付费功能 | P0 | V1 | 游客可完成拍照与初级报告体验流程中被允许的部分;关键动作前引导登录 | — |
| FR-ACC-02 | 游客模式:未登录可体验核心功能 | P0 | V1 | **游客配额(唯一事实源:产品方案 §3.2 配额表游客行)**:换装 1 次、发型 1 次、初级报告 1 次、对话 3 轮,全部为**设备维度终身额度**(非每日);用尽后引导登录而非静默失败;额度用尽提示不出现价格字样 | FR-BILL-06、FR-BILL-07 |
| FR-ACC-03 | 游客数据迁移:登录后合并游客期间产生的数据 | P0 | V1 | 合并后游客期的报告、收藏、记忆归属新账号;重复合并幂等;多设备场景以先登录设备为准并提示 | FR-ACC-02 |
| FR-ACC-04 | 手机号验证码登录 | P0 | V1 | 作为华为账号登录之外的兜底通道;验证码 5 分钟有效、单号限频;与华为账号可互相绑定 | TD-15 |
| FR-ACC-04 | 手机号验证码登录 | P0 | V1 | 作为华为账号登录之外的**唯一独立兜底通道**(一键登录已推 V2)。验证码 6 位数字、5 分钟有效、一次性使用、**校验失败 5 次即作废**;与华为账号可互相绑定;两条通道**不得互相依赖**(华为侧异常时手机号仍可登录,反之亦然) | TD-15、**TD-32**、FR-ACC-14 |
| **FR-ACC-14** | **短信通道防刷**(新增,原 `NFR-SEC-05` 未覆盖短信场景) | **P0** | **V1** | 单号码 60s 内 1 条 / 1h ≤ 5 条 / 24h ≤ 10 条;单 IP 24h ≤ 20 条、单设备 ≤ 10 条;触发阈值后强制人机校验;号码在日志与后台一律掩码;**日发送量突增告警生效**。验收需有脚本化刷量测试证明拦截有效 | **TD-32**、NFR-SEC-03/05 |
| FR-ACC-13 | 华为账号一键登录获取手机号 | P1 | **V2** | 需企业开发者资质 + `quickLoginMobilePhone` scope。V1 不做(`TD-29`),仅为体验优化非能力缺口 | TD-15、TD-29 |
| FR-ACC-05 | 会话管理:access/refresh 双令牌,可撤销 | P0 | V1 | 登出后旧令牌立即失效;refresh 令牌服务端可单条撤销 | — |
| FR-ACC-06 | 个人资料维护(昵称、头像、性别、年龄段) | P0 | V1 | 修改即时生效;头像走私有桶签名访问 | — |
| FR-ACC-07 | 用户中心:报告入口、我的记忆、我的收藏、**剩余额度**、设置 | P0 | V1 | 各入口可达且状态正确(无报告时显示引导);额度展示为「今日剩余 N 次」,**不出现价格与购买入口** | FR-BILL-07 |
| FR-ACC-08 | 授权同意记录:协议、隐私政策、人脸单独同意 | P0 | V1 | 人脸授权为**独立单独同意**页,非混入总协议;同意记录含版本号与时间,可查询 | CR-01 |
| FR-ACC-09 | 账号注销:数据删除 | P0 | V1 | 提交后 7 日内彻底删除个人数据;期间可撤销;删除完成有记录可审计 | CR-03 |
| **FR-ACC-15** | **清空我的照片**(新增,不注销账号) | **P0** | **V1** | 用户可一键删除全部已上传照片与派生结果图,**保留账号与诊断结论**;删除后 COS 对象与数据库引用同步清除,签名 URL 立即失效;操作有二次确认与结果回执,并写审计日志。⚠️ 涉及人脸相关数据删除,须纳入合规检查清单(`CR-02`) | CR-02、CR-03 |
| FR-ACC-10 | 个人信息导出 | P1 | V2 | 用户可申请导出自身数据,机器可读格式 | CR-03 |
| FR-ACC-11 | 未成年人保护:年龄判定与功能限制 | P0 | V1 | 识别为未成年时禁用外观评价类内容并提供监护提示(V1 无付费功能,故无付费限制项) | CR-04 |
| FR-ACC-12 | 多形象档案(帮家人诊断) | P2 | V2+ | 数据模型 V1 预留 `profile_id`,不实现 UI | — |
@@ -96,7 +98,7 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| FR-MEM-01 | 分层记忆模型 L0~L2 落地(身份/画像/显式偏好) | P0 | V1 | 三层均可写入、可查询、可注入;数据结构含置信度与来源 | — |
| FR-MEM-02 | 报告结论自动写入 L1 画像记忆 | P0 | V1 | 报告完成后 L1 记忆同步生成,置信度继承诊断置信度 | FR-RPT-06 |
| FR-MEM-03 | 显式偏好抽取与写入 L2 | P0 | V1 | 用户明确表达偏好(「我不穿裙子」)后写入成功率 ≥ 90%,并给用户回执确认 | FR-AGT-08 |
| FR-MEM-04 | 记忆注入 Agent 上下文 | P0 | V1 | 注入 token ≤ 500;有画像用户的回答需体现画像(人工抽检 ≥ 80% 体现) | FR-AGT-03 |
| FR-MEM-04 | 记忆注入 Agent 上下文 | P0 | V1 | **注入 token ≤ 1400**(V1 实际 ≤ 1200,L3 不启用;分项预算见架构 §7.2 为唯一事实源。原「≤ 500」系误写);有画像用户的回答需体现画像(人工抽检 ≥ 80% 体现);**硬禁忌在任何裁剪策略下都不得被丢弃** | FR-AGT-03、架构 §7.2 |
| FR-MEM-05 | 「我的记忆」页面:可见、可编辑、可删除 | P0 | V1 | 用户可看到每条记忆的内容、来源、时间;删除后不再注入;编辑后优先级最高 | CR-02 |
| FR-MEM-06 | 置信度与衰减机制 | P1 | V1 | 定时任务按规则降低未强化记忆的置信度;低于阈值不再注入 | — |
| FR-MEM-07 | 冲突消解:显式 > 报告 > 隐式,新 > 旧 | P0 | V1 | 同 key 冲突时按规则裁决并写变更事件;用户编辑不被自动覆盖 | FR-MEM-05 |
@@ -128,14 +130,16 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| FR-RPT-16 | 全面报告付费触发点 | P1 | V2 | 触发点不影响免费体验完整性;无诱导性欺骗文案 | — |
| FR-RPT-17 | 报告 PDF 导出 | P2 | V2 | 含 AI 标识元数据 | — |
| ~~FR-RPT-18~~ | ~~五行/命理模块~~ | — | **不做** | **已决定 V1 与 V2 均不纳入**(`TD-31`)。诊断维度由 34 项减为 32 项;编号不再复用 | — |
| **FR-RPT-19** | **报告结论的认同/修正入口**(新增) | **P0** | **V1** | 每个可修正维度旁提供「不准?修正一下」入口;用户修正后置信度置 1.0 且标记 `user_confirmed`,并即时反映到 L1 记忆;**认同与修正行为全量埋点**。⚠️ **这是 §3.1「结论认同率 > 70%、修正率 < 15%」两项核心质量指标的唯一数据来源,缺它则该指标无法计算** | FR-MEM-05、FR-SYS-06 |
| **FR-RPT-20** | **全面报告预约留资**(新增) | **P0** | **V1** | 初级报告结果页底部展示预览卡片(模糊目录 + 内容清单,**不含价格**);点击留资并埋点;记录预约数/预约率/停留时长/目录章节点击分布。⚠️ **这是 V1 唯一的商业化验证数据来源(预约率 ≥ 8% 为 V2 立项门槛)**,缺它则 V1 上线后无法回答"要不要做付费报告" | FR-BILL-07、FR-SYS-06 |
### 2.4 AGT 穿搭 Agent
| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-AGT-01 | 文字对话与流式输出 | P0 | V1 | 首字 p95 < 2s;整轮 p95 < 8s;断线可恢复 | — |
| FR-AGT-02 | 意图识别(场景咨询/单品搭配/风格建议/越界) | P0 | V1 | 主要意图识别准确率 ≥ 85%;越界意图(医疗、身材贬损、他人评价)正确拒答 | — |
| FR-AGT-03 | 画像注入 + token 预算控制 | P0 | V1 | 输入 token ≤ 3700;预算超限时按优先级裁剪而非报错 | FR-MEM-04 |
| FR-AGT-01 | 文字对话与流式输出 | P0 | V1 | 首字 p95 < 2s(`NFR-PERF-02`);整轮 p95 < 15s(`NFR-PERF-02b`);断线可恢复 | NFR-PERF-02 |
| FR-AGT-02 | 意图识别(场景咨询/单品搭配/风格建议/越界) | P0 | V1 | **验证门槛 ≥ 85%,上线门槛 ≥ 90%**(两档口径见美学报告 §9.4);越界意图(医疗、身材贬损、他人评价)正确拒答 | — |
| FR-AGT-03 | 画像注入 + token 预算控制 | P0 | V1 | **输入 token ≤ 4200**(V1 实际 ≤ 4000;分项预算见架构 §7.2 为唯一事实源。原 3700 因漏算会话近轮原文而偏低);预算超限时按既定优先级裁剪而非报错;硬禁忌永不裁剪 | FR-MEM-04、架构 §7.2 |
| FR-AGT-04 | 知识库混合检索 | P0 | V1 | 检索 p95 < 200ms;黄金集 Top-5 命中率 ≥ 80% | FR-KB-06 |
| FR-AGT-05 | 生成后校验(禁忌违反 = 0、色值在板内) | P0 | V1 | 黄金集 100 例违反数 = 0 | FR-KB-05 |
| FR-AGT-06 | 搭配方案结构化输出(卡片) | P0 | V1 | 输出可解析为结构化单品组合,字段完整 | — |
@@ -200,16 +204,18 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| FR-TASK-01 | 统一任务提交与状态查询 | P0 | V1 | 所有长耗时任务(报告/换装/发型)统一入口;状态机完整 | — |
| FR-TASK-02 | 进度与预估时间 | P0 | V1 | 阶段文案 + 排队位次 + 预估剩余时间(基于历史 p50) | — |
| FR-TASK-03 | 任务列表页(进行中/已完成/失败) | P0 | V1 | 失败项有原因与重试入口 | — |
| FR-TASK-04 | 完成推送通知 | P0 | V1 | 推送到达率 ≥ 90%;文案不含敏感结论 | TD-17 |
| FR-TASK-05 | 幂等与重试 | P0 | V1 | 相同幂等键不重复扣点、不重复出图;可重试错误自动重试并有上限 | — |
| FR-TASK-06 | 任务取消 | P1 | V1 | 排队中可取消并退点;执行中标记取消,不再返回结果 | — |
| FR-TASK-04 | 完成推送通知 | P0 | V1 | **推送到达率 ≥ 90%,分母为「已授权通知的用户」**(`TD-17` 指出鸿蒙通知授权默认关闭,用全体用户作分母则该指标永远不可能达标,且会掩盖真实的推送链路问题);未授权用户由**应用内任务中心轮询兜底**,不计入本指标;文案不含敏感结论 | TD-17 |
| FR-TASK-05 | 幂等与重试 | P0 | V1 | 相同幂等键**不重复扣减配额**、不重复出图;可重试错误自动重试并有上限 | — |
| FR-TASK-06 | 任务取消 | P1 | V1 | 排队中可取消并**退还配额**;执行中标记取消,不再返回结果 | — |
| FR-TASK-07 | 死信与告警 | P0 | V1 | 连续失败进死信队列并告警,不静默丢弃 | — |
### 2.9 BILL 配额与计量
> ⚠️ **V1 不收费**(`TD-28`)。本模块在 V1 的职责是「**配额限制 + 计量**」,不含任何支付、订单、购买能力。
>
> **架构约束(不可妥协)**:V1 的配额账本与 V2 的点数账本**必须是同一张表** —— V1 只使用 `system_grant`(系统发放)与 `consume`(消耗)两种流水类型,V2 增加 `purchase`(购买)与 `gift`(赠送)。这样 V2 上支付时不需要数据迁移,也不需要重写扣减逻辑。
> **架构约束(不可妥协)**:V1 的配额账本与 V2 的点数账本**必须是同一张表** —— V1 使用 `system_grant`(系统发放)、`consume`(消耗)、**`refund`(退还)三种**流水类型,V2 增加 `purchase`(购买)与 `gift`(赠送)。这样 V2 上支付时不需要数据迁移,也不需要重写扣减逻辑。
>
> ⚠️ `refund` **不可省略**:它是预扣三段式(`FR-BILL-05`)的必需类型,也是熔断降级时退还额度(`NFR-COST-02`)的唯一途径。原文写「两种」属漏写,已更正。
| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
@@ -221,6 +227,7 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| FR-BILL-06 | 服务端硬校验与防绕过 | P0 | V1 | 额度校验在服务端,客户端提示仅为体验;伪造请求无法超额;设备/账号/IP 三重限流 | NFR-SEC-04 |
| FR-BILL-07 | 额度耗尽文案约束 | P0 | V1 | **提示中不出现任何价格、购买、会员、升级字样**;只提供「等待恢复」与「做任务换额度」两条路径 | — |
| FR-BILL-08 | 成本归因记录 | P0 | V1 | 每次 AI 调用落 `ob_ai_call`,可按功能/模型/用户聚合;**这是 V2 定价的唯一数据来源,不可裁剪** | NFR-COST-01 |
| **FR-BILL-12** | **会员页静态展示 + 「上线提醒我」留资**(新增) | **P0** | **V1** | 展示 V2 规划权益的静态对比表,**不含任何价格与购买按钮**;「上线提醒我」点击即留资并埋点;记录曝光数与留资率。⚠️ 这是**订阅意愿**的唯一验证数据来源(与 `FR-RPT-20` 验证的**单次付费意愿**是两件事,都需要) | FR-BILL-07、FR-SYS-06 |
| ~~FR-BILL-09~~ | ~~华为 IAP 商品购买~~ | P1 | **V2** | 服务端收据校验;`purchase_token` 唯一防重复发货;掉单可补发 | TD-16 |
| ~~FR-BILL-10~~ | ~~会员等级与权益~~ | P1 | **V2** | 权益判定集中在 billing 域,其他模块只查询 | — |
| ~~FR-BILL-11~~ | ~~订单与退款对账~~ | P1 | **V2** | 日对账报表;异常订单告警 | — |
@@ -288,22 +295,37 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
### 4.1 性能(NFR-PERF)
| 编号 | 指标 | 目标 |
| --- | --- | --- |
| NFR-PERF-01 | 普通 API p95 | < 300ms |
| NFR-PERF-02 | Agent 首字 p95 / 整轮 p95 | < 2s / < 8s |
| NFR-PERF-03 | 初级报告 p50 / p95 | < 45s / < 90s |
| NFR-PERF-04 | 全面报告 p95 | < 180s |
| NFR-PERF-05 | 换装出图 p95(不含排队) | < 40s |
| NFR-PERF-06 | 知识检索 p95 | < 200ms |
| NFR-PERF-07 | 长图渲染 p95 | < 8s |
| NFR-PERF-08 | 客户端首屏 | < 1.5s |
> 🔒 **本节是性能指标的唯一定义位置**。产品方案 §8.3.1、美学报告 §10.2、穿搭 Agent §7.1/§8.3、技术架构 §12.1 **一律引用本表编号,不得复述数值**。此前五处文档给出过四套互相矛盾的数值,已在本轮收口。
| 编号 | 指标 | 目标 | 说明 |
| --- | --- | --- | --- |
| NFR-PERF-01 | 普通 API p95 | < 300ms | 不含 AI 调用的读写接口 |
| NFR-PERF-02 | Agent **首字** p95 | **< 2s** | **这是 UX 上唯一关键的延迟指标**(输出为流式) |
| NFR-PERF-02b | Agent 整轮完成 p95 | < 15s | 按输出约 800 token、生成速率 60~100 tok/s 推算;原定 8s 不可达,已修正 |
| NFR-PERF-03 | 初级报告 p50 / p95 | < 45s / **< 90s** | 视觉分析 + LLM + 渲染串行;原产品方案的 60s 过紧,以本表为准 |
| NFR-PERF-04 | 全面报告 p95 | < 180s | **V2 指标**,需在 V2 立项时按实测重新基线 |
| NFR-PERF-05 | 换装出图 p95(不含排队) | **见下方两段式** | 不可用单一数值表达 |
| NFR-PERF-06 | 知识检索 p95 | < 200ms | 硬过滤 < 50ms |
| NFR-PERF-07 | 长图渲染 p95 | < 8s | Playwright 服务端渲染 |
| NFR-PERF-08 | 客户端首屏 | < 1.5s | — |
#### 4.1.1 换装/发型的性能必须用「现状基线 → 目标值」两段式表达
这是此前冲突最严重的一处(`FR-TRY-01` 写 p95 < 40s,产品方案写前端超时 ≥ 320s)。两个数字分别是**目标**与**现状**,但没有任何文档写明这层关系,导致 `FR-TRY-01` 按现有接口实测必然不达标。
| 阶段 | 换装 p95 | 发型 p95 | 来源 |
| --- | --- | --- | --- |
| **现状基线** | 待 `T-P0-13` 实测填入(前端超时按 ≥ 320s 设置,说明现状可能接近该量级) | 待 `T-P0-14` 实测填入 | 现有服务实测 |
| **V1 上线门槛** | ≤ 现状基线,且**不得劣化** | 同 | 不以性能优化为 V1 前置条件 |
| **优化目标** | < 40s | < 60s | 改造后(`TD-00`),排期不绑定 V1 |
**纪律**:`FR-TRY-01` 的验收标准改为「不劣于现状基线」,40s 作为优化目标单独跟踪。**在 `T-P0-13/14` 完成实测前,任何文档不得引用 40s 作为验收线。**
### 4.2 可靠性(NFR-REL)
| 编号 | 指标 | 目标 |
| --- | --- | --- |
| NFR-REL-01 | 月度可用性 | ≥ 99.5% |
| NFR-REL-01 | 月度可用性 | **≥ 99.5%**(约 3.6h/月停机预算)。产品方案原写 > 99.9% **已废弃** —— V1 是单可用区 Docker Compose 部署(架构 §14.1),无跨区冗余、无自动故障转移,承诺 99.9%(43min/月)在架构上不可兑现。99.9% 需等 V2 迁 TKE 多可用区后再谈 |
| NFR-REL-02 | 任务最终成功率(含重试) | ≥ 95% |
| NFR-REL-03 | 数据零丢失 | 已提交任务不因重启丢失 |
| NFR-REL-04 | RPO / RTO | RPO ≤ 5min,RTO ≤ 1h(需演练验证) |
@@ -312,8 +334,9 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| 编号 | 要求 |
| --- | --- |
| NFR-COST-01 | 所有付费调用 100% 可归因到功能与用户 |
| NFR-COST-02 | 场景级日预算 + 日成本预警生效 |
| NFR-COST-01 | 所有付费调用 100% 可归因到功能与用户(落 `ob_ai_call`,不允许"先上线后补埋点") |
| NFR-COST-02 | **全局日成本熔断生效(自动降级,非仅告警)**:日累计成本达 60/80/90/100% 阈值时按既定顺序降级;在途任务放行;被熔断拒绝的请求必须退还配额(不得扣减);运营后台可查看状态并手动解除。验收:压测注入成本后四档降级均可复现,且配额账本无净扣减。详见架构 §13.3 |
| NFR-COST-02b | 场景级日预算:单功能超预算自动切轻量模型或暂停,并告警 |
| NFR-COST-03 | LLM 缓存命中率可观测,固定前缀设计到位 |
| NFR-COST-04 | GPU 实例按需启停,空闲不计费 |
@@ -325,7 +348,7 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| NFR-SEC-02 | 结果图私有桶 + 短期签名 URL + 防盗链 |
| NFR-SEC-03 | 日志脱敏(手机号、UnionID、诊断结论、图片地址) |
| NFR-SEC-04 | Prompt 注入防护:用户内容不得影响系统指令与工具决策 |
| NFR-SEC-05 | 防刷:设备指纹 + 频控 + 异常注册风控 |
| NFR-SEC-05 | 防刷:设备指纹 + 频控 + 异常注册风控 + **短信轰炸防护**(`FR-ACC-14`,短信是被刷时的直接现金损失,且没有配额兜底) |
### 4.5 可维护性(NFR-MAINT)
@@ -423,5 +446,6 @@ CR-<序号> 合规需求(Compliance Requirement,不可裁剪)
| 日期 | 版本 | 变更 |
| --- | --- | --- |
| 2026-08-13 | v1.2 | **文档一致性评审修订**。**§4.1 升为性能指标唯一事实源**,并修正三处不可达/不可兑现的目标:Agent 整轮 8s→**15s**(按 800 输出 token 与生成速率推算,8s 不可达)、可用性 99.9%→**99.5%**(V1 单可用区无冗余)、换装改「现状基线 → 目标值」**两段式**(40s 是改造目标、320s 是现状,此前混为一谈导致 `FR-TRY-01` 必然不达标)。`NFR-COST-02` 由「日成本预警」**升级为「全局日成本熔断(自动降级)」** —— 原设计只有告警,而按人头发配额封不住总成本。`FR-MEM-04` 注入预算 500→**1400**、`FR-AGT-03` 总输入 3700→**4200**(原值漏算会话近轮原文)。`FR-AGT-02` 准确率拆验证/上线两档。配额流水由「两种」更正为**三种**(`refund` 不可省略)。**新增 5 条需求**:`FR-ACC-14` 短信防刷、`FR-ACC-15` 清空照片、`FR-RPT-19` 结论认同/修正入口、`FR-RPT-20` 全面报告预约留资、`FR-BILL-12` 会员页留资 —— 后三条此前"有指标但无数据来源"。`FR-ACC-02` 补入游客配额引用;`FR-TASK-04` 明确到达率分母为已授权用户 |
| 2026-08-13 | v1.1 | 按业务决策收口调整需求范围。**§2.9 BILL 由「权益与计费」改为「配额与计量」**:移除 V1 全部支付能力,新增 `FR-BILL-06`(服务端硬校验防绕过)与 `FR-BILL-07`(额度耗尽文案不得出现价格字样);IAP/会员/对账顺延至 `FR-BILL-09`~`11` 并推至 V2。`FR-ACC-04` 改为手机号验证码登录(P0),一键登录移为 `FR-ACC-13`(V2)。`FR-RPT-18` 五行模块标记为永久不做。§5.2 新增「全部支付能力」「广告变现」两项 V1 不做。**§5.3 前置阻塞项状态更新**:备案已完成、企业资质依赖已解除,新的关键路径为全职顾问到岗与素材自采产能 |
| 2026-08-13 | v1.0 | 首次建立统一需求编号体系,收拢五份需求文档 |