# 「美搭」需求规格说明

> 版本：**v1.2**　｜　更新日期：2026-08-13　｜　状态：待评审
>
> **本文的定位**：把散落在五份需求文档中的需求统一编号、统一优先级、统一验收标准，成为开发任务拆解与测试用例编写的唯一索引。
>
> **本文与其他文档的关系**：
> - 各模块的**设计细节与推理过程**仍在各自的需求文档中（报告分级逻辑、记忆分层模型、知识分类体系等），本文不重复。
> - 本文提供**可勾选、可验收、可指派**的需求条目。开发任务、测试用例、验收清单都引用本文编号。
> - 技术实现方式见《技术架构文档》，技术选型理由见《技术选型与调研报告》。

---

## 1. 编号与优先级规范

### 1.1 编号规则

```
FR-<模块>-<序号>    功能需求（Functional Requirement）
NFR-<类别>-<序号>   非功能需求
CR-<序号>           合规需求（Compliance Requirement，不可裁剪）
```

模块代码：

| 代码 | 模块 | 主文档 |
| --- | --- | --- |
| ACC | 账号与用户系统 | 用户系统与记忆系统-需求文档 |
| MEM | 记忆系统 | 用户系统与记忆系统-需求文档 |
| RPT | 美学报告 | 美学报告-需求文档 |
| AGT | 穿搭 Agent | 穿搭Agent-需求文档 |
| TRY | 智能试穿（换装） | 产品方案 §2.1 |
| HAIR | 发型设计 | 产品方案 §2.1 |
| KB | 美学知识库 | 美学知识库-建设方案 |
| TASK | 任务中心 | 产品方案 §2.7 |
| BILL | 权益与计费 | 产品方案 §3、§5 |
| ADM | 运营后台 | 技术选型报告 TD-25 |
| WDB | 我的衣橱 | 产品方案 §2.6 |
| SYS | 系统级/横切 | 技术架构文档 |

### 1.2 优先级定义

| 级别 | 含义 | 判定标准 |
| --- | --- | --- |
| **P0** | V1 必须有 | 缺它则核心闭环不成立，或无法合法上线 |
| **P1** | V1 期望有 / V2 必须有 | 缺它体验受损但闭环仍在 |
| **P2** | 增强 | 锦上添花，可随时后置 |

### 1.3 验收标准的书写要求

每条 P0 需求必须有**可判定**的验收标准。不合格的写法与合格的写法对比：

| ❌ 不可验收 | ✅ 可验收 |
| --- | --- |
| 报告生成速度快 | 初级报告 p95 生成耗时 < 90s，超时转后台并推送 |
| 建议要专业 | 生成结果中硬性禁忌规则违反数 = 0（黄金集 100 例全通过） |
| 记忆要准确 | 显式偏好写入后，下一轮对话注入率 100%，且用户可在「我的记忆」看到该条 |

### 1.4 完成定义（DoD）

任一需求标记为完成，必须同时满足：

1. 功能实现且通过验收标准；
2. 单元/集成测试覆盖主路径与关键异常路径；
3. 涉及生成内容的，已接入统一合规出口（`CR-05`）；
4. 涉及配额消耗的，已接入预扣-确认-退还三段式（`FR-BILL-05`），且消耗前有剩余量提示；
5. 关键埋点已上报（`FR-SYS-06`）；
6. 失败态有用户可读的错误文案与下一步指引。

---

## 2. 功能需求

### 2.1 ACC 账号与用户系统

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-ACC-01 | 华为账号登录（UnionID/OpenID） | P0 | V1 | 登录成功率 ≥ 99%；首次登录自动创建用户；UnionID 与内部 user_id 映射唯一 | TD-15 |
| 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 | 作为华为账号登录之外的**唯一独立兜底通道**（一键登录已推 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 | — |

### 2.2 MEM 记忆系统

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| 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 ≤ 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 |
| FR-MEM-08 | 隐式行为推断 + 待确认机制 | P1 | V2 | 同属性连续 3 次拒绝生成待确认候选；确认后才生效；不打断当前任务 | — |
| FR-MEM-09 | L3 事件记忆与语义召回 | P1 | V2 | 可按语义召回历史事件（「上次面试穿的那套」） | — |
| FR-MEM-10 | L4 会话滚动摘要 | P1 | V2 | 长会话摘要压缩后 token ≤ 400，关键约束不丢失 | — |
| FR-MEM-11 | L5 衣橱记忆 | P1 | V2 | 与衣橱模块联动 | FR-WDB-01 |
| FR-MEM-12 | 记忆变更审计 | P0 | V1 | 每次写入/衰减/冲突/用户编辑均留事件记录 | — |

### 2.3 RPT 美学报告

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-RPT-01 | 初级报告（免费）内容生成 | P0 | V1 | 覆盖需求文档 §2.2 全部模块；结构完整率 100%；无空模块 | — |
| FR-RPT-02 | 触发时机：首次进入核心功能前引导生成 | P0 | V1 | 未有报告的用户进入换装/Agent 时出现引导，可跳过但有降级说明 | FR-RPT-11 |
| FR-RPT-03 | 拍照/上传引导与质量校验 | P0 | V1 | 不合格照片（多人/遮挡/过暗/侧脸过大）在分析前拦截并给出具体重拍指引，拦截准确率 ≥ 85% |  — |
| FR-RPT-04 | 问卷采集（生活场景、风格倾向、禁忌） | P0 | V1 | 问卷完成率 ≥ 80%；可跳过项不阻断生成 | — |
| FR-RPT-05 | 视觉分析：体型 / 色彩季型 / 脸型 | P0 | V1 | 与人工标注一致率：体型 ≥ 80%、季型 ≥ 75%、脸型 ≥ 80%（各 30~50 样本） | TD-05、TD-06 |
| FR-RPT-06 | 结构化诊断结论（**32 维度字典**） | P0 | V1 | 每维度输出 value + confidence + evidence + rule_hits；缺失维度显式标注 | FR-KB-04、TD-31 |
| FR-RPT-07 | 报告文案生成（规则约束 + LLM 表达） | P0 | V1 | 硬禁忌违反数 = 0；结论与诊断值一致（无自相矛盾）；黄金集 30 例人工评审通过 | FR-KB-05 |
| FR-RPT-08 | 生成后校验 | P0 | V1 | 校验项：禁忌违反、色值在色板内、维度引用存在、无绝对化医疗/身材贬损表述；不通过则重试或降级模板 | — |
| FR-RPT-09 | 生成进度与等待体验 | P0 | V1 | 阶段文案随进度更新；超阈值转后台生成 + 完成推送；用户离开页面不丢任务 | FR-TASK-01 |
| FR-RPT-10 | 报告页展示与交互 | P0 | V1 | 分模块展开；术语配白话释义；低置信度维度降级表述 | — |
| FR-RPT-11 | 无照片/拒绝授权的降级路径 | P0 | V1 | 可用问卷生成简版画像，明确告知能力差异，不阻断产品使用 | — |
| FR-RPT-12 | 报告分享（长图） | P0 | V1 | 服务端渲染，跨设备一致；含 AI 生成显式标识；分享链接可失效 | TD-12、CR-05 |
| FR-RPT-13 | 重新生成 / 更新报告 | P1 | V1 | 有频控与配额（每 30 天 1 次，任务可 +1）；历史版本保留可对比 | FR-BILL-04 |
| FR-RPT-14 | 报告与其他模块联动 | P0 | V1 | 报告结论驱动 Agent 建议、换装推荐、发型推荐 | FR-MEM-02 |
| FR-RPT-15 | 全面报告内容 | P1 | V2 | 覆盖需求文档 §2.3 全部模块；付费前有清晰的内容对比说明。**V1 仅做预约留资，且预览卡片不展示任何价格**（`TD-28`） | FR-BILL-09 |
| 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（`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 | 输出可解析为结构化单品组合，字段完整 | — |
| FR-AGT-07 | 快捷问题入口 | P0 | V1 | 首屏提供场景化快捷问题，点击直达 | — |
| FR-AGT-08 | 显式偏好抽取与回执 | P0 | V1 | 抽取成功后给用户可见回执（「已记住」），可撤销 | FR-MEM-03 |
| FR-AGT-09 | 对话历史保存与会话列表 | P0 | V1 | 会话可回看；保留期符合数据保留策略 | CR-03 |
| FR-AGT-10 | 无画像用户的降级路径 | P0 | V1 | 无画像时给通用建议 + 报告引导，不空转 | FR-RPT-11 |
| FR-AGT-11 | 知识缺口埋点 | P0 | V1 | 无检索结果的 query 全量记录，可导出驱动内容生产 | FR-KB-10 |
| FR-AGT-12 | 输入输出双向内容审核 | P0 | V1 | 输入拦截、输出拦截均生效；审核不可用时 fail-close | CR-06 |
| FR-AGT-13 | 「为什么推荐」解释链 | P1 | V2 | 解释的事实部分来自知识库路径与规则 ID，非模型自由生成 | FR-KB-07 |
| FR-AGT-14 | 联动换装试穿 | P1 | V2 | 从建议卡片一键发起换装任务 | FR-TRY-01 |
| FR-AGT-15 | 联动发型设计 | P1 | V2 | 同上 | FR-HAIR-01 |
| FR-AGT-16 | 图片输入理解（穿搭评价） | P1 | V2 | 支持上传穿搭照获得点评，评价不含贬损表述 | TD-04 |
| FR-AGT-17 | 语音输入 | P1 | V2 | 端侧识别；识别失败可切文字 | TD-14 |
| FR-AGT-18 | 主动推荐（天气/日程驱动） | P2 | V3 | — | — |

### 2.5 TRY 智能试穿

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-TRY-01 | 换装任务提交与出图（三种工作流） | P0 | V1 | 任务成功率 ≥ 90%（排除输入不合格）；p95 < 40s（不含排队） | TD-00 改造 |
| FR-TRY-02 | 输入前置校验（人像质量、单品白底图规格） | P0 | V1 | 不合格输入在提交前拦截并说明原因，**不消耗配额**（拦截发生在预扣之前） | FR-KB-08 |
| FR-TRY-03 | 结果图审核与合规标识 | P0 | V1 | 100% 经审核 + 显式水印 + 隐式元数据 | CR-05、CR-06 |
| FR-TRY-04 | 排队与容量保护 | P0 | V1 | 展示排队位次与预估时间；超阈值拒绝新任务并提示 | FR-TASK-02 |
| FR-TRY-05 | 失败退还配额 | P0 | V1 | 不可重试失败立即退还；对账日报中无「扣额未出图」记录 | FR-BILL-05 |
| FR-TRY-06 | 结果收藏与管理 | P0 | V1 | 可收藏、删除；删除后存储对象同步清理 | — |
| FR-TRY-07 | 结果对比（原图/换装后） | P1 | V1 | 前后对比视图 | — |
| FR-TRY-08 | 基于画像的单品推荐入口 | P0 | V1 | 推荐单品需 `tryon_ready`，避免推荐了却试不了 | FR-KB-08 |
| FR-TRY-09 | 多单品组合试穿 | P2 | V2 | — | — |

### 2.6 HAIR 发型设计

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-HAIR-01 | 发型更换与发色调整 | P0 | V1 | 成功率 ≥ 90%；p95 < 40s | — |
| FR-HAIR-02 | 发型库适配标签打标（脸型/量感/直曲/长度/卷度/刘海/正式度） | P0 | V1 | 60 款发型 100% 完成打标并通过抽检复核 | FR-KB-03 |
| FR-HAIR-03 | 基于脸型与画像的发型推荐 | P0 | V1 | 推荐结果不含该脸型禁忌发型（规则校验通过率 100%） | FR-RPT-06 |
| FR-HAIR-04 | 结果审核与合规标识 | P0 | V1 | 同 FR-TRY-03 | CR-05 |

### 2.7 KB 美学知识库

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-KB-01 | 本体 Schema 与属性字典定稿 | P0 | V1 | 12 类实体的字段、枚举值、必填项全部明确并落库 | — |
| FR-KB-02 | 自建色板（12 季型 Lab 色值） | P0 | V1 | 每季型含主色/点缀色/禁忌色，色值可用于计算；命名自研规避商标 | TD-18 |
| FR-KB-03 | 实体内容录入（单品、发型、场合、材质等） | P0 | V1 | 达到冷启动规模目标（见知识库文档 §9）；每条含 source 与 license | — |
| FR-KB-04 | 规则库（建议/禁忌，含硬约束标记） | P0 | V1 | 覆盖体型×场合、季型×色彩、脸型×发型三大矩阵；每条含依据说明与审核人 | FR-ADM-02 |
| FR-KB-05 | 规则引擎求值与硬约束校验 | P0 | V1 | 求值 p95 < 50ms；硬约束校验可拦截违规输出 | — |
| FR-KB-06 | 混合检索链路（硬过滤+规则+向量+关键词+重排） | P0 | V1 | 黄金集 Top-5 命中率 ≥ 80%；硬过滤零漏（禁忌项不得出现在候选中） | TD-08 |
| FR-KB-07 | 图谱关系与解释路径输出 | P1 | V1 | 1~3 跳查询可返回路径，供解释链使用 | TD-09 |
| FR-KB-08 | 单品白底图流水线（抠图+规格校验+入库） | P0 | V1 | 10 件样本走通全流程；`tryon_ready` 标志准确；抠图人工质检通过率 ≥ 90% | TD-07 |
| FR-KB-09 | 内容审核与发布流程（草稿→审核→发布→归档） | P0 | V1 | 未审核内容不进入线上检索；发布可回滚 | FR-ADM-03 |
| FR-KB-10 | 知识缺口发现与优先级排序 | P0 | V1 | 缺口按命中频次排序，可导出为内容生产任务 | FR-AGT-11 |
| FR-KB-11 | 黄金测试集与回归 | P0 | V1 | ≥ 100 条测试用例；CI 中自动跑；指标退化阻断合并 | — |
| FR-KB-12 | 视觉模型辅助属性标注 | P1 | V1 | 单品属性自动预标注 + 人工复核；预标注准确率 ≥ 70%（降低人工量即达标） | TD-04 |
| FR-KB-13 | 趋势内容更新机制 | P2 | V2 | — | — |

### 2.8 TASK 任务中心

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-TASK-01 | 统一任务提交与状态查询 | P0 | V1 | 所有长耗时任务（报告/换装/发型）统一入口；状态机完整 | — |
| FR-TASK-02 | 进度与预估时间 | P0 | V1 | 阶段文案 + 排队位次 + 预估剩余时间（基于历史 p50） | — |
| FR-TASK-03 | 任务列表页（进行中/已完成/失败） | P0 | 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`（消耗）、**`refund`（退还）三种**流水类型，V2 增加 `purchase`（购买）与 `gift`（赠送）。这样 V2 上支付时不需要数据迁移，也不需要重写扣减逻辑。
>
> ⚠️ `refund` **不可省略**：它是预扣三段式（`FR-BILL-05`）的必需类型，也是熔断降级时退还额度（`NFR-COST-02`）的唯一途径。原文写「两种」属漏写，已更正。

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-BILL-01 | 配额定义与周期重置 | P0 | V1 | 按周期（日/月/终身）正确重置；跨时区按 UTC+8 统一；额度耗尽有明确提示与获取途径 | — |
| FR-BILL-02 | 配额账本与流水 | P0 | V1 | 余额可由流水完整重算校验；每日自动对账无差异；流水类型可扩展至购买/赠送而无需改表结构 | — |
| FR-BILL-03 | 任务奖励额度发放 | P0 | V1 | 签到、完善资料、反馈、邀请、分享完成即到账；**发放幂等**（同一任务同一周期不重复发放） | — |
| FR-BILL-04 | 配额消耗表（配置化） | P0 | V1 | 各功能消耗量可配置，不硬编码；改配置不需发版 | TD-28 |
| FR-BILL-05 | 预扣-确认-退还三段式 | P0 | V1 | 长耗时任务失败自动退还；**无「扣了额度但没出图」case**；退还幂等 | FR-TASK-05 |
| 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** | 日对账报表；异常订单告警 | — |

> **编号变更说明**：原 `FR-BILL-02`（点数钱包）语义改为「配额账本」；原 `FR-BILL-06`~`FR-BILL-08`（IAP / 会员 / 对账）顺延为 `FR-BILL-09`~`FR-BILL-11` 且全部推至 V2；原 `FR-BILL-09`（成本归因）改为 `FR-BILL-08`。新增 `FR-BILL-06`（服务端硬校验）与 `FR-BILL-07`（文案约束）两条 V1 需求。

### 2.10 ADM 运营后台（极简版）

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-ADM-01 | 独立登录与权限（运营/顾问/管理员） | P0 | V1 | 与用户端账号体系隔离；操作留审计日志 | — |
| FR-ADM-02 | 知识条目与规则的增删改查 | P0 | V1 | 顾问可独立完成内容维护，无需工程介入 | FR-KB-04 |
| FR-ADM-03 | 素材上传与抠图任务触发 | P0 | V1 | 批量上传、查看抠图结果、标记 `tryon_ready` | FR-KB-08 |
| FR-ADM-04 | 内容发布与回滚 | P0 | V1 | 发布后线上检索生效；可回滚到上一版本 | FR-KB-09 |
| FR-ADM-05 | 知识缺口看板 | P1 | V1 | 按频次展示缺口，支持导出 | FR-KB-10 |
| FR-ADM-06 | 用户与配额查询（客服支持） | P1 | V1 | 可按用户查任务状态与配额流水，用于客诉处理（V1 无订单概念） | — |
| FR-ADM-07 | 版本管理与效果看板 | P2 | V2 | — | — |

### 2.11 WDB 我的衣橱

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-WDB-01 | 衣物录入（拍照 + 自动属性识别） | P1 | V2 | 属性自动识别准确率 ≥ 70%，可人工修正 | TD-04 |
| FR-WDB-02 | 衣橱管理与分类 | P1 | V2 | — | — |
| FR-WDB-03 | 基于真实衣橱的搭配建议 | P1 | V2 | 建议只使用用户实际拥有的单品 | FR-MEM-11 |

### 2.12 SYS 系统级需求

| 编号 | 需求 | P | 版本 | 验收标准 | 依赖 |
| --- | --- | --- | --- | --- | --- |
| FR-SYS-01 | 统一鉴权与越权防护 | P0 | V1 | 所有资源访问校验归属；越权测试用例全通过 | — |
| FR-SYS-02 | 统一错误码与用户可读文案 | P0 | V1 | 每个错误码有 message + hint；无裸露堆栈 | — |
| FR-SYS-03 | 图片直传（预签名 URL） | P0 | V1 | 图片不经应用服务器；上传失败可重试 | — |
| FR-SYS-04 | LLM 网关（路由/降级/成本/Prompt 版本） | P0 | V1 | 主供应商故障自动切备用，切换耗时 < 3s；成本 100% 记录 | TD-04 |
| FR-SYS-05 | 三张监控看板 | P0 | V1 | 业务漏斗、AI 成本、任务健康均可用 | TD-24 |
| FR-SYS-06 | 全链路埋点 | P0 | V1 | 漏斗关键节点无缺失（上线前用测试账号走查验证） | TD-23 |
| FR-SYS-07 | 成本预警 | P0 | V1 | 日成本环比突增超阈值告警；场景级日预算生效 | NFR-COST-02 |
| FR-SYS-08 | 外部依赖降级策略 | P0 | V1 | 各依赖失效时表现符合架构文档 §2 表格；审核为 fail-close | — |
| FR-SYS-09 | 数据备份与恢复演练 | P0 | V1 | 至少完成一次真实恢复演练并记录 RTO/RPO | — |

---

## 3. 合规需求（不可裁剪）

> 这些需求不接受「先上线后补」。缺失将直接导致无法上架或面临处罚。详见《合规与安全方案》。

| 编号 | 需求 | 依据 | 验收标准 |
| --- | --- | --- | --- |
| CR-01 | 人脸信息单独同意 + 处理目的告知 | 人脸识别技术应用安全管理办法 | 独立同意页；拒绝后仍可使用降级功能；同意记录含版本与时间 |
| CR-02 | 人脸原图不持久化，仅保留派生特征 | 同上 + 最小必要原则 | 处理完成后原图删除；临时桶生命周期 ≤ 2 小时；抽查无残留 |
| CR-03 | 数据保留与删除：注销后 7 日内彻底删除 | 个人信息保护法 | 删除任务可审计；对象存储同步清理 |
| CR-04 | 未成年人保护 | 未成年人网络保护条例 | 未成年账号禁用外观评价与付费；有监护提示 |
| CR-05 | AI 生成内容双重标识（显式 + 隐式元数据） | 人工智能生成合成内容标识办法 + GB 45438-2025 | 所有生成物含可见标识；元数据含属性信息、服务提供者编码、27 位内容编号；**经 CDN/压缩/客户端保存后元数据仍存在** |
| CR-06 | 内容审核：输入与输出双向 | 生成式人工智能服务管理暂行办法 | 用户上传图、生成图、用户文本、模型输出、知识内容全覆盖；审核不可用时 fail-close |
| CR-07 | 关键词拦截库 | 备案要求 | 拦截库可维护；命中记录留存 |
| CR-08 | 大模型登记 + 算法备案 | 生成式 AI 管理暂行办法 + 算法推荐管理规定 | 取得登记号/备案号；界面显著位置公示模型名称与编号 |
| CR-09 | 隐私政策与用户协议 | 多项法规 | 明确 AI 生成、数据处理、第三方共享清单；版本化留存 |
| CR-10 | 个人信息保护影响评估（PIA） | 个人信息保护法 | 完成 PIA 报告并归档 |
| CR-11 | 日志留存 | 深度合成管理规定 | 生成记录与审核日志留存 ≥ 6 个月 |
| CR-12 | 不得提供医疗、命理等越界结论 | 广告法 + 内容合规 | 报告与对话中无诊疗承诺、无绝对化效果承诺；越界问题正确拒答 |

---

## 4. 非功能需求

### 4.1 性能（NFR-PERF）

> 🔒 **本节是性能指标的唯一定义位置**。产品方案 §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%**（约 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（需演练验证） |

### 4.3 成本（NFR-COST）

| 编号 | 要求 |
| --- | --- |
| 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 实例按需启停，空闲不计费 |

### 4.4 安全（NFR-SEC）

| 编号 | 要求 |
| --- | --- |
| NFR-SEC-01 | 敏感数据传输与存储加密；密钥不落代码 |
| NFR-SEC-02 | 结果图私有桶 + 短期签名 URL + 防盗链 |
| NFR-SEC-03 | 日志脱敏（手机号、UnionID、诊断结论、图片地址） |
| NFR-SEC-04 | Prompt 注入防护：用户内容不得影响系统指令与工具决策 |
| NFR-SEC-05 | 防刷：设备指纹 + 频控 + 异常注册风控 + **短信轰炸防护**（`FR-ACC-14`，短信是被刷时的直接现金损失，且没有配额兜底） |

### 4.5 可维护性（NFR-MAINT）

| 编号 | 要求 |
| --- | --- |
| NFR-MAINT-01 | 契约先行：接口 schema 先定义，客户端类型由 OpenAPI 生成 |
| NFR-MAINT-02 | ruff + mypy strict 进 CI，失败阻断合并 |
| NFR-MAINT-03 | 域间依赖规则由工具校验，禁止跨域直查表 |
| NFR-MAINT-04 | 黄金集回归进 CI，指标退化阻断合并 |
| NFR-MAINT-05 | 规则/色板/定价/模型路由全部配置化，不硬编码 |
| NFR-MAINT-06 | 数据库变更必须走 Alembic 且向后兼容 |

### 4.6 体验（NFR-UX）

| 编号 | 要求 |
| --- | --- |
| NFR-UX-01 | 所有长耗时操作有进度反馈与可离开能力 |
| NFR-UX-02 | 所有失败态有原因说明 + 下一步指引 |
| NFR-UX-03 | 专业术语必须配白话释义 |
| NFR-UX-04 | 外观相关表述遵循「描述而非评判」，不使用贬损性词汇 |
| NFR-UX-05 | 低置信度结论使用不确定表述，不做断言 |

---

## 5. V1 范围矩阵（一页看清）

### 5.1 V1 包含（P0 全量）

| 模块 | V1 交付内容 |
| --- | --- |
| 账号 | 华为账号授权登录 + 手机号验证码、游客与迁移、资料、同意授权、注销、未成年保护 |
| 记忆 | L0~L2 + 报告写入 + 注入 + 我的记忆页 + 冲突消解 + 审计 |
| 报告 | **初级报告完整闭环**（引导→拍照→问卷→分析→诊断→文案→校验→长图→分享） |
| Agent | 文字对话、意图识别、画像注入、混合检索、生成后校验、偏好抽取、缺口埋点 |
| 换装 | 三工作流出图、前置校验、审核标识、排队保护、失败退还配额、收藏 |
| 发型 | 发型更换与发色、60 款打标、基于脸型推荐 |
| 知识库 | 本体定稿、自建色板、冷启动内容、规则库、混合检索、白底图流水线、黄金集 |
| 任务中心 | 统一提交与状态、进度、列表、推送、幂等、死信告警 |
| 配额与计量 | 配额定义与重置、配额账本与流水、任务奖励发放、消耗表配置化、预扣三段式、服务端硬校验、**成本归因埋点**。⚠️ **不含支付、订单、购买** |
| 后台 | 极简版：知识与规则维护、素材上传、发布回滚、缺口看板 |
| 系统 | 鉴权、错误码、直传、LLM 网关、三看板、埋点、成本预警、降级、备份演练 |
| 合规 | CR-01 ~ CR-12 全部 |

### 5.2 V1 明确不做

| 内容 | 原因 | 归属 |
| --- | --- | --- |
| **全部支付能力**（IAP、会员、点数购买、订单、退款、对账） | **V1 完全不收费**，用配额限制控成本。定价需要 V1 采集的真实数据才有依据（`TD-28`） | V2 |
| 全面报告 | 需先用 V1 预约率验证意愿；**V1 预览卡片不展示价格** | V2 |
| 广告变现 | V1 不接任何广告，避免影响首发体验与评价 | V2+ |
| 华为账号一键登录 | 需企业资质 + scope；属体验优化非能力缺口（`TD-29`） | V2 |
| 我的衣橱 | 依赖属性识别与记忆 L5，工作量大 | V2 |
| 语音输入、图片输入理解 | 非核心闭环 | V2 |
| 联动试穿/联动发型（从 Agent 一键跳转） | 各自功能先独立稳定 | V2 |
| 解释链自然语言化 | 数据结构 V1 已具备，展示层后置 | V2 |
| 多形象档案 | 仅预留数据字段 | V2+ |
| **五行/命理** | **永久不做**：收益边缘但渠道审核风险全局（`TD-31`） | **不做** |
| 多端（iOS/Android） | 见 `TD-01` | V2+ |

### 5.3 V1 的前置阻塞项（不属于开发，但决定能否上线）

| 事项 | 状态 | 说明 |
| --- | --- | --- |
| 大模型登记 + 算法备案 | ✅ **已完成** | 原周期 2~4 个月的关键路径已解除。转为持续义务：编号界面公示、备案范围一致性、变更备案（`CR-08`） |
| 备案覆盖的模型清单核实 | ⏳ **唯一开放项** | 若备案未覆盖 DeepSeek + GLM 两家，双路由属超范围，需办变更或 V1 先单路由（`TD-19`） |
| ~~华为企业开发者资质~~ | ✅ 已解除依赖 | V1 不接 IAP，一键登录降级 V2（`TD-29`） |
| **全职形象顾问到岗** | 🔴 **新的关键路径** | 规则库产能直接决定 M2 排期（`TD-27`） |
| **单品素材自采产能** | 🔴 **新的关键路径** | 300 件 `tryon_ready` 需按周产能倒排；备案解除后这是最长工序（`TD-26`） |

---

## 6. 需求变更控制

| 情形 | 处理 |
| --- | --- |
| 新增 P0 需求 | 必须同时说明它挤掉哪个现有 P0，或延后哪个里程碑 |
| 合规需求（CR-xx） | 不可裁剪、不可降级，只能新增 |
| 验收标准调整 | 需在本文更新并记录原因，不允许口头放宽 |
| 优先级变更 | 在本文标注变更日期与原因 |

---

## 7. 相关文档

- [文档索引](./README.md)
- [技术架构文档](./技术架构文档.md)（§20 给出章节与本文需求的映射）
- [技术选型与调研报告](./技术选型与调研报告.md)（`TD-xx` 编号来源）
- [合规与安全方案](./合规与安全方案.md)（`CR-xx` 的义务来源与落地要求）
- [开发任务拆解](./开发任务拆解.md)（每条 P0 与 CR 需求都应能反查到至少一个任务）
- 需求原文：[美学报告](./美学报告-需求文档.md)、[穿搭 Agent](./穿搭Agent-需求文档.md)、[用户系统与记忆系统](./用户系统与记忆系统-需求文档.md)、[美学知识库](./美学知识库-建设方案.md)、[产品方案](./鸿蒙美搭-智能穿搭美学助手-产品方案.md)

---

## 变更记录

| 日期 | 版本 | 变更 |
| --- | --- | --- |
| 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 | 首次建立统一需求编号体系，收拢五份需求文档 |