From f4075f6827e969df419300281903eff1e8da281a Mon Sep 17 00:00:00 2001 From: xiangsilian Date: Fri, 14 Aug 2026 09:40:50 +0800 Subject: [PATCH] =?UTF-8?q?=E6=94=B6=E5=8F=A3=E6=96=87=E6=A1=A3=E8=AF=84?= =?UTF-8?q?=E5=AE=A1=E5=86=B2=E7=AA=81=E5=B9=B6=E8=A1=A5=E9=BD=90=20Sprint?= =?UTF-8?q?=20=E6=89=A7=E8=A1=8C=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 统一性能、token、配额与成本口径，补齐短信登录等缺口任务，并回写脚手架实测暴露的思考模式与峰谷计价约束。 Co-authored-by: Cursor --- docs/README.md | 73 ++++-- docs/Sprint执行计划.md | 234 ++++++++++++++++++ docs/合规与安全方案.md | 7 +- docs/开发任务拆解.md | 35 ++- docs/技术架构文档.md | 264 ++++++++++++++++----- docs/技术选型与调研报告.md | 68 +++++- docs/文档评审报告-2026-08-13.md | 230 ++++++++++++++++++ docs/用户系统与记忆系统-需求文档.md | 37 +-- docs/穿搭Agent-需求文档.md | 96 +++++--- docs/美学报告-需求文档.md | 64 +++-- docs/美学知识库-建设方案.md | 111 +++++---- docs/需求规格说明.md | 74 ++++-- docs/鸿蒙美搭-智能穿搭美学助手-产品方案.md | 197 ++++++++++----- 13 files changed, 1200 insertions(+), 290 deletions(-) create mode 100644 docs/Sprint执行计划.md create mode 100644 docs/文档评审报告-2026-08-13.md diff --git a/docs/README.md b/docs/README.md index a52bd0c..e8d5ded 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,10 @@ | 客户端 | 鸿蒙原生 ArkTS（V1 单端） | 可触达基数是 HarmonyOS NEXT+ 设备，非全部鸿蒙生态设备 | | 单品素材 | **全部自采实拍** | 版权干净，但**成为项目新的关键路径** | | 形象顾问 | **全职编制** | 规则库产能可控，但到岗时间决定 M2 排期 | -| 五行/命理模块 | **永久不做** | 诊断维度 34 → **32 项** | +| 五行/命理模块 | **永久不做** | 诊断维度 **32 项**（原 34 项，移除五行分布与幸运色） | +| 成本封顶 | **全局日成本熔断**（四档自动降级） | ⚠️ **配额封不住总成本** —— 总成本 = MAU × 人均，MAU 无上限 | +| 天气数据 | **V1 不接天气 API** | Agent 反问用户或按城市月份推断，**不编造温度** | +| 登录通道 | 华为账号 + **手机号验证码**（两条互不依赖） | 一键登录推 V2（需企业资质） | ### 0.2 现在最该先做的三件事 @@ -30,7 +33,7 @@ ### 0.3 待业务输入的事项 -**仅剩 1 项**：备案登记覆盖的模型清单（见上方第 1 条）。其余 20 项决策已全部收口，见产品方案 §11 与技术选型报告 §7。 +**仅剩 1 项**：备案登记覆盖的模型清单（见上方第 1 条）。其余 **24 项**决策已全部收口，见产品方案 §11.1 与技术选型报告（`TD-00`~`TD-33`）。 --- @@ -60,8 +63,10 @@ 合规与安全方案.md 第四层｜谁来做、什么时候做 -└─ 开发任务拆解 ★ ───────── WBS、依赖关系、里程碑、验收条件 - 开发任务拆解.md +├─ 开发任务拆解 ★ ───────── WBS、依赖关系、里程碑、验收条件 +│ 开发任务拆解.md +└─ Sprint 执行计划 ★ ────── 排期、轨道并行、已交付部分的验收状态 + Sprint执行计划.md ``` ★ = 本轮新增文档 @@ -80,6 +85,7 @@ | 3 | [技术选型与调研报告](./技术选型与调研报告.md) ★ | 31 项技术决策的结论、理由与切换条件 | | 3 | [合规与安全方案](./合规与安全方案.md) ★ | 人脸、AI 标识、**备案后的持续义务**、审核、数据安全 | | 4 | [开发任务拆解](./开发任务拆解.md) ★ | WBS、依赖图、六个里程碑、验收条件 | +| 4 | [Sprint 执行计划](./Sprint执行计划.md) ★ | 六个 Sprint 的排期与出口条件、四轨并行、**后端脚手架已交付部分的实测验收状态** | --- @@ -116,6 +122,8 @@ | 人脸数据怎么处理才合法 | 合规与安全方案 §2.1 | | 上线前必须做完什么 | 合规与安全方案 §5 检查清单 | | 我的任务依赖谁 | 开发任务拆解 §1 依赖图 + 各任务表的「依赖」列 | +| 现在该做哪个 Sprint、哪些已经做完了 | Sprint 执行计划 §1.1（已交付）+ §1.2（待补） | +| 后端代码在哪、怎么跑起来 | Sprint 执行计划 §1；仓库 `meida_backend` 的 `README.md` | | 报告触发时机的完整规则 | 美学报告-需求文档 §3 | | 记忆分层与冲突消解规则 | 用户系统与记忆系统-需求文档 §3 | | 知识库有哪些类目和模态 | 美学知识库-建设方案 §3、§4 | @@ -136,6 +144,29 @@ **引用纪律**：跨文档引用一律用编号，不要复制内容。同一事实只在一处定义，其他地方引用——这是这套文档能长期维护的前提。 +### 4.1 单一事实源索引（🔒 修改前必查） + +2026-08-13 的一致性评审发现，**几乎所有跨文档冲突都是"同一个数字被复制到多处"造成的**，而不是判断分歧。下表锁定每类关键数字的唯一定义位置。 + +**规则：要改这些数字，只改「唯一定义位置」那一列指向的地方；其余位置只允许写引用，不允许写数值。** + +| 事实 | 🔒 唯一定义位置 | 引用方 | +| --- | --- | --- | +| 性能指标（延迟、可用性） | 需求规格说明 **§4.1** | 产品方案 §8.3.1、美学报告 §10.2、Agent §7.1/§8.3、架构 §12.1 | +| 换装/发型耗时 | 需求规格说明 **§4.1.1**（现状基线 → 目标值两段式） | 同上。**实测前不得引用 40s 作为验收线** | +| 配额数值（含游客） | 产品方案 **§3.2** | 用户系统 §2.4.1、`FR-ACC-02`、`FR-BILL-*`、`bl_quota_rule` 初始化数据 | +| Token 预算 | 技术架构文档 **§7.2**（嵌套表，合计 4200） | `FR-MEM-04`、`FR-AGT-03`、用户系统 §3.8、Agent §3.5.2、`T-P3-17`、`T-P4-03` | +| 成本口径（三档 + 熔断阈值） | 产品方案 **§5.2.1 / §5.3.1** | 架构 §13.1、§8.2.3、`NFR-COST-*` | +| 诊断维度字典与覆盖数 | 美学报告 **§4**（32 项；初级覆盖 21） | 架构 §6.2/§6.3、`FR-RPT-06`、README §5、产品方案 §2.2.1 | +| 诊断准确率门槛 | 美学报告 **§9.4**（验证档 / 上线档两档） | `FR-RPT-05`、`FR-AGT-02`、产品方案 §8.3.3、`T-P0-10/11` | +| 知识库规模 | 美学知识库 **§9.1**（V1 硬指标 / 长期目标两列） | 产品方案 §2.5.2/§2.8、`FR-KB-*`、`T-P2-*` | +| 黄金集规模 | 美学知识库 **§7**（四个子集共 330 例） | `FR-KB-11`、`FR-AGT-05`、`FR-RPT-07`、美学报告 §9.4 | +| 人脸原图保留期 | 合规与安全方案 **§2.1.2** / `CR-02`（2 小时） | 产品方案 §7.1.4、美学报告 §9.1、架构 §7.1/§11.2、`T-P1-27` | +| 记忆枚举与置信度初值 | 用户系统 **§3.3 / §3.5** | 架构 §6.2、§8.4 | +| 配额账本四表职责 | 技术架构文档 **§7.4** 开头 | `FR-BILL-*`、`T-P1-26` | + +**流程建议**：每次大改版后专门做一次「同一数字全局搜索」（搜 `32`、`1400`、`4200`、`90s`、`300`、`99.5%`）。本轮的问题高度集中在数字上，人工通读很难发现。 + --- ## 5. 术语表 @@ -179,13 +210,14 @@ | 类别 | 状态 | | --- | --- | -| 产品需求 | 已定稿（V1 范围明确，见需求规格说明 §5） | -| 技术选型 | 已定稿（**31 项决策全部收口**，待业务输入仅剩 1 项） | +| 产品需求 | **待评审**（V1 范围已明确，见需求规格说明 §5；各需求文档页尾状态均为「待评审」，本表与之一致） | +| 技术选型 | 已定稿（**`TD-00`~`TD-33` 共 34 项决策全部收口**，待业务输入仅剩 1 项） | | 业务决策 | ✅ **已全部收口**（素材自采、顾问全职、V1 不收费、命理不做、市场数据信源） | | 备案 | ✅ **已完成**，转为持续义务 | | 技术架构 | 待技术评审 | | 合规方案 | 待法务复核 | | 任务拆解 | 待评审后进入执行 | +| **文档一致性评审** | ✅ 已完成一轮（见《文档评审报告-2026-08-13》），P0/P1/P2 全部修订完毕 | **最紧急的三件事见 §0.2**（备案完成后已重排：模型清单核实 → 顾问到岗 → 自采流水线）。 @@ -193,16 +225,25 @@ ## 8. 本轮（2026-08-13）文档更新摘要 -九份文档全部更新，核心是三件事：**备案完成**、**V1 不收费**、**市场数据换成官方信源**。 +**十份内容文档全部更新 + 新增《Sprint 执行计划》**（此前本表漏列《穿搭 Agent-需求文档》），分三批： + +**第一批 —— 业务决策落地**：备案完成、V1 不收费、市场数据换官方信源、素材自采、顾问全职、命理不做。 + +**第二批 —— 文档一致性评审修订**（见《[文档评审报告](./文档评审报告-2026-08-13.md)》）：11 项 P0 事实冲突、9 项 P1 覆盖缺口、9 项 P2 一致性问题全部修订。 + +**第三批 —— 后端脚手架落地后的回写**：`meida_backend` 仓库跑通真实纵向切片后，两项文档未覆盖的问题被实测暴露并回写为 +`T-P1-24a`（思考模式）与 `T-P1-25c`（峰谷计价）；同时新增《Sprint 执行计划》承接排期与已交付部分的验收状态。 | 文档 | 版本 | 主要变更 | | --- | :---: | --- | -| [产品方案](./鸿蒙美搭-智能穿搭美学助手-产品方案.md) | v6.0 | §5.0 新增「V1 不收费只限量」；§3 权益拆为 V1 配额与 V2 规划；§4.1 市场数据全部换官方信源并纠正鸿蒙可触达口径；§8.1.1 用户目标下调且**以季度回访率替代 DAU**；§5.3 财务预期重写；备案风险关闭 | -| [需求规格说明](./需求规格说明.md) | v1.1 | BILL 域由「权益与计费」改为「配额与计量」，V1 移除全部支付；一键登录降级 V2；五行模块标记永久不做；§5.3 前置阻塞项状态重排 | -| [技术架构文档](./技术架构文档.md) | v1.1 | billing 域降级为配额与计量，`bl_point_tx`→`bl_ledger` 且新增 `tx_type` 使 V2 免迁移；§7.4 拆为 V1 配额与 V2 支付；成本模型补 V1 上限公式；风险登记重排 | -| [技术选型与调研报告](./技术选型与调研报告.md) | v1.1 | §7 由「待业务输入」改为「决策收口」，`TD-26`~`TD-31` 六项全部给出结论与理由；`TD-19` 备案已办结 | -| [合规与安全方案](./合规与安全方案.md) | v1.1 | 新增 §2.2.0 备案后四项持续义务；公示要求升为开发任务并加三条实现要求；检查清单标记已完成项 | -| [开发任务拆解](./开发任务拆解.md) | v1.1 | **关键路径转移**：备案申报任务关闭，内容与素材生产升为最优先；`T-P0-20`/`21` 要求输出每周产能用于倒排 | -| [美学知识库-建设方案](./美学知识库-建设方案.md) | v1.2 | 新增 §4.2.1 素材自采流水线（五工序 + 拍摄规范 + 降级路径）、§5.1.1 全职顾问工作流（四项职责按投入顺序） | -| [美学报告-需求文档](./美学报告-需求文档.md) | v1.2 | 五行模块整体移除（维度 34→32）；预约卡片不得展示价格，价格敏感度改用访谈采集 | -| [用户系统与记忆系统-需求文档](./用户系统与记忆系统-需求文档.md) | v1.2 | §2.4 重构为 V1 配额表 + V2 规划；一键登录降级；主表移除 `points_balance`；强化计量要求 | +| [产品方案](./鸿蒙美搭-智能穿搭美学助手-产品方案.md) | v6.1 | §5.0「V1 不收费只限量」；§3.2 配额表补入**游客列**并成为唯一事实源；§4.1 市场数据换官方信源并纠正鸿蒙可触达口径；§8.1.1 用户目标下调且**以季度回访率替代 DAU**；**§5.2.1/§5.3.1 成本口径重写为三档并推翻「配额封顶总成本」的错误论证**；§8.3.1 性能指标改为引用 `NFR-PERF-*`；§8.3.3 准确率拆为验证/上线两档；删除全部日历周期承诺 | +| [需求规格说明](./需求规格说明.md) | v1.2 | BILL 域改为「配额与计量」，V1 移除全部支付；**§4.1 成为性能指标唯一事实源**（修正 Agent 整轮 8s→15s、可用性 99.9%→99.5%，换装改两段式）；`NFR-COST-02` 升级为**自动熔断**；新增 `FR-ACC-14` 短信防刷、`FR-ACC-15` 清空照片、`FR-RPT-19` 结论修正入口、`FR-RPT-20` 预约留资、`FR-BILL-12` 会员页留资 | +| [技术架构文档](./技术架构文档.md) | v1.3 | billing 域降级为配额与计量；**§7.4 新增四张表职责边界与 `task_bonus` 物化方案**（此前开发会卡在这里）；**§7.2 token 预算改为嵌套表并修正合计 3700→4200**；**§13 成本模型重写为三口径 + §13.3 四档熔断降级**；`pf_memory`/`id_consent` 枚举与用户系统对齐；手机号存储位置明确；`points_reserved`→`quota_reserved`；v1.3 按脚手架实现回写五处：**§16.1 补全 11 个业务域包与三层判别标准**、**`ob_ai_call` 补 4 列**（Prompt 版本/思考 token/峰谷档位）、**§9.1 澄清 `/api/v1` 为规范写法**、**§13.2 新增峰谷计价约束**、**§13.3 补关键场景豁免** | +| [技术选型与调研报告](./技术选型与调研报告.md) | v1.2 | `TD-26`~`TD-31` 六项业务决策收口；`TD-19` 备案已办结；**补 `TD-00` 定义**（此前被引用却未定义）；**新增 `TD-32` 短信通道**（此前 P0 需求无选型）、**`TD-33` 天气数据源**（V1 不接，给降级方案） | +| [合规与安全方案](./合规与安全方案.md) | v1.2 | §2.2.0 备案后四项持续义务；公示要求升为开发任务；**人脸原图保留期统一为 2 小时**（此前与产品方案的 24h 冲突） | +| [开发任务拆解](./开发任务拆解.md) | v1.3 | **关键路径转移**：内容与素材生产升为最优先；**M4 拆为 a/b 两块**消除依赖图歧义；新增 `T-P1-12b/12c` 短信、`T-P1-16b` 清空照片、`T-P1-25b` 熔断、`T-P3-21/22` 两个埋点、`T-P5-17/18/19`；v1.3 补 **`T-P1-24a` 思考模式显式配置**与 **`T-P1-25c` 峰谷计价**（均由后端实测暴露） | +| [Sprint 执行计划](./Sprint执行计划.md) | v1.0 | 新增。按依赖就绪切分六个 Sprint，标注 `meida_backend` 已交付任务的实测证据，并把「内容产能」明确为倒排上线时间的唯一依据 | +| [美学知识库-建设方案](./美学知识库-建设方案.md) | v1.2 | §4.2.1 素材自采流水线；§5.1.1 全职顾问工作流；**§9.1 成为规模唯一事实源**（V1 硬指标与长期目标分列）；**§7 黄金集拆为四个子集共 330 例**；修正脸型 8→7、局部特征 12→13 | +| [美学报告-需求文档](./美学报告-需求文档.md) | v1.2 | 五行模块移除（维度 34→32）；**§9.4 成为准确率门槛唯一事实源**（验证/上线两档）；**清除全部价格残留**（¥29.9、预计价格、点击价格档位）；**维度覆盖改为准确口径**（初级 21/32，原「40+ 项」不存在） | +| [用户系统与记忆系统-需求文档](./用户系统与记忆系统-需求文档.md) | v1.2 | §2.4 重构为 V1 配额 + V2 规划；一键登录降级；**§3.8 记忆注入分项被采纳为全局事实源**；配额数值改为引用产品方案 §3.2 | +| [穿搭 Agent-需求文档](./穿搭Agent-需求文档.md) | v1.2 | **语音输入由 P0 改为 P1/V2**（此前与 `FR-AGT-17` 冲突）；§2.1 能力表补版本与编号列；token 预算与性能指标改为引用；**天气类问题明确不得编造数值**；意图识别准确率拆两档；删除无依据的「1000+ 并发」 | diff --git a/docs/Sprint执行计划.md b/docs/Sprint执行计划.md new file mode 100644 index 0000000..9798792 --- /dev/null +++ b/docs/Sprint执行计划.md @@ -0,0 +1,234 @@ +# 「美搭」Sprint 执行计划 + +> 版本：**v1.0**　｜　创建日期：2026-08-13　｜　状态：待评审 +> +> **本文与《开发任务拆解》的分工**：WBS 回答「一共有哪些任务、谁依赖谁」，本文回答**「下一步做什么、做完怎么算过、谁在这个 Sprint 里没被阻塞」**。 +> 任务编号沿用 WBS 的 `T-P<阶段>-<序号>`，本文不新造编号，只做排期与状态标注。 +> +> **排期原则**：Sprint 按**依赖就绪**切分，不按固定天数。一个 Sprint 的出口条件全绿才开下一个； +> 但**内容生产轨（顾问 + 自采）从 Sprint 0 起持续跑**，永不等待工程轨 —— 它是关键路径。 + +**状态图例**：✅ 已完成　🟡 部分完成（括号内为剩余）　⬜ 未开始　🔴 关键路径 + +--- + +## 0. 团队轨道划分 + +4~6 人的实际约束是：**同一时间最多四条轨并行**，且算法与内容两轨的产能不能靠 AI 加速。 + +| 轨道 | 角色 | 本项目里的特点 | +| --- | --- | --- | +| **BE** 后端 | 后端 + AI 辅助 | 地基与业务逻辑，可被 AI 显著加速 | +| **FE** 端侧 | 鸿蒙 ArkTS | 受 `T-P0-17` 骨架验证结论约束，不能提前铺量 | +| **ALG** 算法 | 算法 | 体型/色彩/脸型三项验证是硬门槛，**结论不达标要换方案而不是硬做** | +| **CONT** 内容 | 全职形象顾问 + 产品 | **产能决定上线时间**，见 §6 | + +--- + +## 1. Sprint 0：地基已落地部分的验收与补齐 + +> **本 Sprint 的特殊性**：工程地基的骨架已经在 `meida_backend` 仓库落地并跑通了一条真实纵向切片 +> （取 token → 预扣配额 → 真实调用 DeepSeek → 记成本 → 提交配额）， +> 因此 Sprint 0 的重点不是「从零搭」，而是**验收既有部分 + 补齐缺口**。 + +### 1.1 已交付（`meida_backend`，实测通过） + +| 任务 | 状态 | 实测证据 | +| --- | --- | --- | +| `T-P1-01` 仓库结构与包边界 | ✅ | `apps / packages / services` 三层；**四条 import-linter 契约全绿**，`packages/domain` 禁 framework 与 IO 由机器强制 | +| `T-P1-02` CI 流水线 | ✅ | ruff + mypy(domain/llm 为 strict) + pytest + lint-imports + detect-secrets + gitleaks + **迁移 upgrade→downgrade→upgrade 往返** 六道防线 | +| `T-P1-03` 本地开发环境 | 🟡（缺 COS mock） | `make up` 起 pgvector + Redis，端口 55432/56379 避冲突；`make install` 一条命令装齐 | +| `T-P1-06` Alembic 基线 | ✅ | `0001` 建 9 张表并创建 `vector` 扩展；正反向往返实测通过 | +| `T-P1-07` 统一响应与错误码 | ✅ | `code/message/data/request_id` 信封；每个错误码有文案，且**配额文案经测试断言不含价格字样** | +| `T-P1-08` 可观测性 | 🟡（缺 CLS 与看板） | structlog JSON + request_id 贯穿；**日志脱敏有专项测试**（手机号/令牌/密钥/诊断结论）；Prometheus 指标就绪，OTel 留开关 | +| `T-P1-19` 任务中心 | 🟡（仅骨架任务） | `tk_task` + 状态机（非法跃迁有测试）+ 幂等键；`POST /tasks/ping`、`GET /tasks/{id}`、列表可用 | +| `T-P1-24` **LLM 网关** | ✅ | 场景路由、主备故障转移、熔断器、结构化输出重试、Prompt 版本、成本归因，共 28 个单测 | +| `T-P1-25` 成本归因表 | ✅ | `ob_ai_call` 每次调用（含失败）落一行；实测行：`tokens_in=240 / cached=128 / cost_cents=0.10744` | +| `T-P1-26` 配额账本 | 🟡（缺周期重置与后台） | 预扣三段式 + `bl_ledger` 幂等；实测 DeepSeek 超时时**自动退还**、成功时 `committed` | + +### 1.2 本 Sprint 待补（BE） + +| 任务 | 内容 | 验收标准 | +| --- | --- | --- | +| `T-P1-04` 🔴 | 腾讯云基础设施开通（VPC/CVM/PG/Redis/COS 四桶/CDN/CLS） | 四桶权限与生命周期策略生效；**临时桶 2 小时清理实测**（`CR-02`） | +| `T-P1-05` | 密钥改由 SSM/KMS 注入 | 镜像与代码中无任何密钥；`APP_ENV=prod` 时占位密钥直接拒绝启动（已实现，需接 SSM） | +| `T-P1-27` | 图片直传预签名 URL + 临时桶生命周期 | 图片不经应用服务器；2 小时自动清理 | +| `T-P1-11`/`12`/`13` | 用户模型、华为账号登录、双令牌会话 | UnionID 映射唯一；登出后旧令牌立即失效 | +| `T-P1-12b`/`12c` 🔴 | 短信登录 + 三重频控防刷 | **断开华为依赖后本通道仍可登录**；脚本化刷量测试证明拦截有效 | +| `T-P1-25b` | 日成本熔断补齐四档降级与后台开关 | 注入成本可复现四档；**被拒请求配额净扣减 = 0**；在途任务放行 | +| `T-P1-09`/`10` | 三张看板 + 埋点事件字典 | 能回答架构 §15 的三个问题 | + +### 1.3 本 Sprint 新增（工程实测暴露的两项，原 WBS 未覆盖） + +| 任务 | 类型 | 内容 | 为什么必须单独立项 | +| --- | --- | --- | --- | +| **`T-P1-24a`** | DEV | **思考模式按场景显式配置** | `deepseek-v4-flash` **默认开启思考模式**。实测同一个单句问答：开启 13.5s、关闭 1.8s，且思考 token 按输出价计费。漏配会同时打破 `NFR-PERF-02b`（整轮 15s）与成本模型。已实现：四个场景全部显式关闭，可按场景改配置打开，并单独记 `tokens_reasoning` | +| **`T-P1-25c`** | DEV | **峰谷单价按调用时刻计价** | DeepSeek 自 **2026-08-17 00:00** 起峰谷定价，高峰（北京时间 09:00-12:00、14:00-18:00）单价是空闲时段的 **2 倍**。报告生成多发生在白天高峰，用单一均价记账会让成本与账单差出近一倍 —— 而 `ob_ai_call` 是 V2 定价的唯一依据。已实现：两套价目表 + 按时刻选择 | + +> **`T-P1-25c` 对成本模型的直接影响**：`NFR-COST` 的预算与熔断阈值是按旧单价（输入 ¥1 / 输出 ¥2 每百万 token）推算的。 +> 8-17 之后空闲档为 ¥1.5/¥4.5、高峰档为 ¥3/¥9，**输出侧涨 2.25~4.5 倍**。 +> 上线前必须用实测 token 分布重算一次日预算，否则熔断阈值会在错误的位置触发。 + +### 1.4 出口条件 + +1. 端到端 `make smoke` 在**接入真实 COS 与短信通道后**仍全绿 +2. `make check`（lint + typecheck + imports + test + secrets）零告警 +3. 腾讯云环境清单归档，四桶生命周期实测通过 +4. 两条登录通道**互不依赖**，各自单独可用 + +--- + +## 2. Sprint 1：验证门槛闯关（ALG 主导，与 Sprint 0 并行） + +> **这个 Sprint 的产出是结论与数据，不是功能。** 结论不达标就换方案，不要带着不达标的模块往下走 —— +> 报告的可信度是产品的根，根不稳后面全是返工。 + +| 任务 | 轨道 | 验证门槛（`Phase 0` 档，非上线档） | 不达标的处置 | +| --- | --- | --- | --- | +| `T-P0-10` 🔴 | ALG | 体型测算与人工标注一致率 **≥ 80%** | 换方案（引入关键点比例法或第三方） | +| `T-P0-11` 🔴 | ALG | 色彩季型一致率 **≥ 75%** | 降级为「色彩倾向」而非「季型结论」 | +| `T-P0-12` | ALG | BiRefNet 抠图质检通过 **≥ 90%** | 调参或改用商业抠图 API | +| `T-P0-13` | BE | 换装单次 `gpu_seconds` 与成功率基线 | 数据直接填入成本模型，**并按 §1.3 的新单价重算** | +| `T-P0-14` | BE | 发型接口可用性与耗时基线 | — | +| `T-P0-16` | ALG | RTMPose ONNX CPU 单张耗时可接受 | 上 GPU 或降采样 | +| `T-P0-17` 🔴 | FE | 鸿蒙骨架打通登录/拍照/直传/轮询/展示 | **结论决定 FE 能否铺量**，不通则先解决工程链路 | +| `T-P0-18` | BE | AI 标识元数据经水印/COS/CDN/保存后仍存活 | 改用不可剥离的显式水印 | +| `T-P0-19` | BE | LLM 缓存命中率与成本降幅 | 已有初步实测：固定前缀命中 128/240 输入 token | + +**并行的合规轨（BIZ，不占用开发产能）**：`T-P0-01` 核实备案模型清单是否覆盖 DeepSeek + 智谱两家 🔴、 +`T-P0-02` 合规档案归集、`T-P0-05` 三份协议文案、`T-P0-06` PIA、`T-P0-07` 词库与制度。 + +> `T-P0-01` 之所以标红：**备案只含一家而线上跑两家，是上架核验的直接失败项。** 网关虽已实现主备路由， +> 但若备案未覆盖智谱，V1 就必须配成单路由 —— 这会改变故障转移的前提，越早知道越好。 + +**出口条件**：六项技术验证全部有明确结论（含「不达标 → 换方案」的决定）， +`T-P0-01` 有书面结论，`T-P0-17` 骨架 Demo 可运行。 + +--- + +## 3. Sprint 2：知识库可运营（M2） + +> **依赖**：Sprint 0 出口 + `T-P0-23` Schema 定稿 + 顾问到岗。 +> **本 Sprint 的成败标志不是代码，而是「顾问能不能不找工程就把内容录进去」。** + +| 任务 | 轨道 | 验收标准 | +| --- | --- | --- | +| `T-P2-01` | BE | 12 类实体可存取；`tryon_ready` 标志可用 | +| `T-P2-02` | BE | 规则求值 p95 < 50ms；**硬约束可拦截** | +| `T-P2-03` | BE | BGE-M3 向量化可重跑，模型版本可切换 | +| `T-P2-04` 🔴 | BE | 检索 p95 < 200ms；**硬过滤零漏** | +| `T-P2-05` | BE | 1~3 跳返回可解释路径 | +| `T-P2-07` | ALG | 抠图批处理 + 白底规格校验拦截不合格图 | +| `T-P2-08` | ALG | 属性预标注准确率 ≥ 70%，人工可修正 | +| `T-P2-09` 🔴 | BE | **顾问可独立完成内容维护、审核、发布与回滚，全程无工程介入** | +| `T-P2-10` | BE | 发布后检索缓存自然失效 | +| `T-P2-11` 🔴 | BE | 黄金集框架接入 CI，**指标退化即阻断合并** | +| `T-P2-06` | BE | 无结果 query 全量记录并可排序 | + +**内容轨（CONT，本 Sprint 的真实瓶颈）**：`T-P2-12` 色板、`T-P2-13` 规则库冷启动（**V1 硬指标 400 条**）、 +`T-P2-14` 实体录入、`T-P2-15` 单品 300 件 `tryon_ready`、`T-P2-16` 黄金集标注（**四个子集共 330 例**）。 + +**出口条件**：知识库达到《美学知识库-建设方案》§9.1 的 **V1 硬指标**（规则 400 / 单品 300 / 方案 100）， +黄金集四子集就位并在 CI 里生效，后台可由顾问独立操作。 + +--- + +## 4. Sprint 3：报告闭环（M3） + +> **依赖**：Sprint 1 的三项算法结论 + Sprint 2 的规则与检索。 + +| 任务 | 轨道 | 验收标准 | +| --- | --- | --- | +| `T-P3-01` | ALG | 各项返回置信度与质量标记 | +| `T-P3-02` | ALG | 图片质量门禁拦截准确率 ≥ 85%，**给出具体重拍指引**（不是「照片不合格」） | +| `T-P3-03`/`04`/`05` | ALG | 达到 Sprint 1 的验证基线 | +| `T-P3-06` 🔴 | BE | **32 维度**每维四要素（值/置信度/依据/规则命中）完整，缺失显式标注 | +| `T-P3-07` | BE | 触发与频控符合需求文档 §3；配额生效 | +| `T-P3-08` | FE | 问卷完成率 ≥ 80%，可跳过不阻断 | +| `T-P3-09` 🔴 | BE | **LLM 或渲染失败不需重新上传照片**（中间态落库 + 分步恢复） | +| `T-P3-10` | BE | 文案结论与诊断值一致，无自相矛盾 | +| `T-P3-11` 🔴 | BE | 黄金集**硬性禁忌违反数 = 0**；贬损词零通过 | +| `T-P3-12` | BE | 长图渲染 p95 < 8s，跨设备一致 | +| `T-P3-21` | BE+FE | **结论认同/修正入口** —— 「认同率 > 70%、修正率 < 15%」的唯一数据来源 | +| `T-P3-22` | BE+FE | **全面报告预约留资** —— V1 唯一的商业化验证数据来源 | + +> `T-P3-21`/`T-P3-22` 是本轮评审补的两项。**缺了它们，V1 会白跑一遍**： +> 前者缺失就无法判断报告质量指标是否达标，后者缺失就拿不到 V2 定价所需的需求信号。 + +**出口条件**：用户可完整走通初级报告并产出画像与记忆； +初级报告 P95 < 90s（`NFR-PERF-03`）；诊断准确率达到**上线质量门槛**（体型 85% / 季型 80%）。 + +--- + +## 5. Sprint 4：Agent 与换装（M4） + +> **可并行度是本 Sprint 的关键**：`M4-a` 换装/发型只依赖 Sprint 0 与素材入库，**可与 Sprint 3 并行启动**； +> `M4-b` Agent 必须等 Sprint 2 检索 + Sprint 3 画像，**是真正的关键路径**。 + +**M4-a（可提前）**：`T-P4-01`~ 换装服务纳管改造（`TD-00`）、发型打标与推荐、素材联调。 +**M4-b（关键路径）**：意图识别（验证 85% / 上线 90% 两档）、多轮上下文、画像注入、 +生成后校验、越界拒答、SSE 流式。 + +**本 Sprint 的两条硬红线**： + +1. **不得编造天气数值**（`TD-33`）。V1 不接天气 API，只能反问用户或按城市+月份推断气候区 —— + 模型幻觉出一个温度，用户第二天就会发现。 +2. **token 预算按架构 §7.2 执行**（注入 ≤ 1400，总输入 ≤ 4200）。超预算不是「效果更好」， + 是成本线性上涨且缓存命中率下降。 + +**出口条件**：报告 + Agent + 换装/发型三者可用且互相联动；Agent 整轮 P95 < 15s（`NFR-PERF-02b`）。 + +--- + +## 6. 持续轨：内容生产（贯穿全程，**关键路径**） + +> 关键路径已从「备案审批」转移到「内容产能」。这条轨的特点是 **不能靠 AI 加速，只能靠产能倒排**。 + +| 任务 | 何时启动 | 产出 | +| --- | --- | --- | +| `T-P0-20` 🔴 | **立刻，全项目最优先** | 全职顾问到岗 + 规则库产能基线（条/周） | +| `T-P0-21` 🔴 | **立刻** | 自采流水线跑通 + 首批 20 件 + 每周产能数据 | +| `T-P0-22`/`23`/`25` | 顾问到岗后 | 拍摄 SOP、本体 Schema、32 维字典与规则矩阵框架 | +| `T-P0-24` | 与 Sprint 1 并行 | 60 款发型适配标签打标 | +| `T-P0-26` | 与 Sprint 1 并行 | ≥ 15 人用户访谈（**V1 不展示价格，价格敏感度只能靠访谈采集**） | +| `T-P0-28` | 采购开始前 | 素材版权留档机制（`license=self_shot`） | + +**倒排方法**：拿到 `T-P0-20`/`T-P0-21` 的周产能后，用「V1 硬指标 ÷ 周产能」推出 M2 出口日期， +再据此反推整体上线时间。**在拿到产能数据之前，任何上线日期承诺都没有依据。** + +--- + +## 7. Sprint 5：上线就绪（M5） + +`T-P5-*` 全量执行，其中最容易被漏的四项： + +| 任务 | 为什么容易漏 | +| --- | --- | +| `T-P0-03`/`04` | 备案编号公示位必须**发布包实机验证**，且展示的模型名与网关实际路由**同源校验** | +| `T-P5-18` | CLS 日志留存 ≥ 6 个月（`CR-11`）是法定义务，原 WBS 无人认领 | +| `T-P5-19` | 熔断四档演练 —— 熔断逻辑没演练过等于没有 | +| `T-P5-17` | 会员页静态展示 + 「上线提醒我」留资，为 V2 蓄客 | + +**出口条件**：合规检查清单全绿、压测通过（容量基线见架构 §12.2）、 +监控齐备、备案编号公示实机验证通过、V1 可用性 ≥ 99.5%（`NFR-REL-01`，单可用区部署的现实取值）。 + +--- + +## 8. 风险与应对 + +| 风险 | 触发信号 | 应对 | +| --- | --- | --- | +| **内容产能不足** | 周产能低于「硬指标 ÷ 可接受周数」 | 增加拍摄棚时或外采白底图；**不要降低 `tryon_ready` 质检标准** | +| **算法门槛不达标** | `T-P0-10`/`11` 一致率低于验证门槛 | 该维度降级为「仅供参考」或不展示，**不要延期整个产品** | +| **备案未覆盖两家模型** | `T-P0-01` 结论为单家 | V1 配单路由，故障转移改为降级重试；同步办变更 | +| **成本超预算** | 日成本达预算 70% | 四档熔断自动降级；同时按 §1.3 用实测分布重算阈值 | +| **8-17 涨价冲击** | 空闲/高峰单价 2.25~4.5 倍于旧输出价 | 优先做缓存前缀纪律与输出长度约束；必要时把报告文案改到空闲时段生成 | +| **短信被刷** | 发送量突增告警 | 三重频控 + 人机校验；**短信是唯一没有配额兜底的直接现金损失** | + +--- + +**文档版本**：v1.0 +**创建日期**：2026-08-13 +**状态**：待评审 +**关联文档**：《开发任务拆解》（任务定义与依赖）、《需求规格说明》（验收指标唯一事实源）、 +《技术架构文档》（token 预算与成本模型）、《技术选型与调研报告》（`TD-00`~`TD-33`） diff --git a/docs/合规与安全方案.md b/docs/合规与安全方案.md index 000034b..d2ea2dc 100644 --- a/docs/合规与安全方案.md +++ b/docs/合规与安全方案.md @@ -1,6 +1,6 @@ # 「美搭」合规与安全方案 -> 版本：v1.0　｜　更新日期：2026-08-13　｜　状态：待法务/合规复核 +> 版本：**v1.2**　｜　更新日期：2026-08-13　｜　状态：待法务/合规复核 > > **为什么这份文档单独存在**：本产品同时踩在三条监管线上——处理**人脸信息**（敏感个人信息）、提供**生成式 AI 服务**、产出**AI 生成合成内容**。这三条线各自有独立的法定义务，把它们混在技术文档里会被当成技术细节忽略，所以单独成文。 > @@ -231,7 +231,7 @@ AI 生成内容仅供参考，不构成专业建议 | 对象 | 时机 | 工具 | 失败处理 | | --- | --- | --- | --- | | 用户上传照片 | 分析前 | 腾讯云 IMS | 拒绝并提示，不消耗点数 | -| 换装/发型结果图 | 返回前 | IMS | 拦截，任务标记失败并退点 | +| 换装/发型结果图 | 返回前 | IMS | 拦截，任务标记失败并**退还配额** | | 用户对话输入 | 送 LLM 前 | 腾讯云 TMS + 自有关键词库 | 返回安全提示，记录日志 | | LLM 输出 | 返回前 | TMS | 重新生成（最多 2 次）或返回兜底话术 | | 报告文案与长图 | 发布前 | TMS + IMS | 降级为模板文案 | @@ -302,7 +302,7 @@ AI 生成内容仅供参考，不构成专业建议 | 越权防护 | 所有资源访问校验 `user_id` 归属；越权用例进自动化测试 | | 日志 | 脱敏中间件（手机号、UnionID、图片地址、诊断结论）；审计日志独立留存 ≥ 6 个月 | | 图片访问 | 私有桶 + 短期签名 URL + CDN 防盗链 + Referer 校验 | -| 防刷 | 设备指纹、频控、异常注册识别、点数消耗 | +| 防刷 | 设备指纹、频控、异常注册识别、**配额硬限制**、**短信通道防刷**（`FR-ACC-14`） | | Prompt 注入 | 用户内容与系统指令严格分区；输出侧校验；用户内容不得触发工具调用决策 | | 漏洞管理 | 依赖漏洞扫描进 CI；密钥泄露扫描 pre-commit | | 应急 | 数据泄露应急预案 + 联系人 + 上报流程（法定 72 小时内通知义务） | @@ -424,5 +424,6 @@ AI 生成内容仅供参考，不构成专业建议 | 日期 | 版本 | 变更 | | --- | --- | --- | +| 2026-08-13 | v1.2 | **文档一致性评审修订**。**本文的「人脸原图保留期 ≤ 2 小时」被确认为全局唯一事实源** —— 产品方案 §7.1.4 与美学报告 §9.1 原写「≤ 24h 仅用于任务重试」，已按本文更正（2 小时已足够覆盖重试窗口：最长任务 320s、重试上限 3 次；24h 只是白担合规风险，保留期越长越可能被认定为"存储了人脸信息"从而触发 10 万人备案义务）。§5.3 检查清单补入 `FR-ACC-15`「清空我的照片」（涉及人脸数据删除，此前无 FR 也未纳入清单）；防刷项补入配额硬限制与短信通道防刷（`FR-ACC-14`）；措辞「退点」→「退还配额」 | | 2026-08-13 | v1.1 | **主线二状态更新为「备案已完成」**。新增 §2.2.0「备案完成后的四项持续义务」（编号公示、备案范围与实际调用一致、变更备案 30 工作日、材料维护），并标出唯一开放风险 —— 备案覆盖的模型清单是否含 DeepSeek + GLM 两家，若只含一家则双路由属超范围。§2.2.3 时间线改为已完成说明，指出关键路径已转移到素材与规则库生产。§2.2.4 公示要求从"待办材料"升为"必须落地的开发任务"，补充三条实现要求（入口硬编码、编号可下发、文案与网关路由同源）。§5.1 检查清单标记已完成项，移除华为企业开发者认证（V1 不需要）；§5.3 移除支付类合规项 | | 2026-08-13 | v1.0 | 首次输出。确立三条主线：① 人脸原图不落盘以规避 10 万人备案阈值；② 大模型登记 + 算法备案须在 Phase 0 启动（周期 2~4 个月）；③ AI 生成内容显式 + 隐式双重标识，经统一合规出口收口 | diff --git a/docs/开发任务拆解.md b/docs/开发任务拆解.md index b679366..286f949 100644 --- a/docs/开发任务拆解.md +++ b/docs/开发任务拆解.md @@ -1,6 +1,6 @@ # 「美搭」开发任务拆解（WBS） -> 版本：v1.0　｜　更新日期：2026-08-13　｜　状态：待评审 +> 版本：**v1.3**　｜　更新日期：2026-08-13　｜　状态：待评审 > > **本文的定位**：把需求与架构翻译成可指派、可验收的任务清单，并明确任务之间的依赖与关键路径。 > @@ -23,7 +23,7 @@ | **M1** | 工程地基可用 | 骨架跑通：登录 → 上传 → 提交任务 → 查状态 → 拿到带标识的产物 | 阻塞所有业务功能 | | **M2** | 知识库可运营 | 顾问能在后台独立录入规则与素材并发布，检索链路返回可解释结果 | 阻塞报告与 Agent 的质量 | | **M3** | 报告闭环打通 | 用户能完整走通初级报告并产出画像与记忆 | 阻塞 Agent 与换装的个性化 | -| **M4** | 三大功能闭环 | 报告 + Agent + 换装/发型均可用且互相联动 | — | +| **M4** | 三大功能闭环 | 报告 + Agent + 换装/发型均可用且互相联动。拆为 **M4-a 换装/发型**（可与 M3 并行）与 **M4-b Agent 对话**（须等 M2+M3） | M4-b 是 Phase 4 的关键路径 | | **M5** | 上线就绪 | 合规检查清单全绿、压测通过、监控齐备、**备案编号公示位实机验证通过** | 依赖 M0 的编号公示实现 | | **M6** | V2 能力 | 全面报告付费、IAP 接入、衣橱、多端评估 | **依赖 V1 的成本与频次数据** | @@ -48,7 +48,7 @@ M1 工程地基 │ │ │ │ │ │ │ ├──────────────┬────────────┼───┼──────┐ │ ▼ ▼ ▼ ▼ ▼ │ -M2 知识库 M3 报告闭环 M4 换装/发型 │ +M2 知识库 M3 报告闭环 M4-a 换装/发型 │ ├─ 本体与色板 ├─ 视觉分析 ├─ 换装服务改造 │ ├─ 规则引擎 ◀────┤ 诊断生成 ├─ 素材入库 ◀───┘ ├─ 混合检索 ├─ 文案生成 └─ 发型打标与推荐 @@ -57,13 +57,15 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ │ │ │ └──────────────┴──────────────┘ ▼ - M4 Agent 对话 + M4-b Agent 对话（依赖 M2 检索 + M3 画像） ▼ M5 上线就绪 ▼ M6 V2（含 IAP 与付费报告） ``` +> **M4 拆为 a/b 两块**（原图两处都标 M4，易误读为同一批工作）：`M4-a` 换装/发型只依赖 M1 与素材入库，**可与 M3 报告并行**；`M4-b` Agent 对话必须等 M2 检索与 M3 画像就绪，**是 M4 的关键路径**。两者同属 Phase 4，但可并行度完全不同。 + **关键路径已经改变（这是本轮最重要的变化）**： | | 原关键路径 | 现关键路径 | @@ -164,7 +166,10 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ | T-P1-11 | DEV | 用户数据模型与身份映射 | 表 + 迁移 | UnionID 映射唯一；预留 `profile_id` | FR-ACC-01、FR-ACC-12 | | T-P1-12 | DEV | 华为账号登录（服务端） | 接口 | 登录成功率 ≥ 99%（联调环境） | FR-ACC-01 | | T-P1-13 | DEV | 双令牌会话与撤销 | 接口 | 登出后旧令牌立即失效 | FR-ACC-05 | -| T-P1-14 | DEV | 游客模式与数据合并 | 接口 | 合并幂等；多设备场景有确定策略 | FR-ACC-02/03 | +| T-P1-12b | DEV | **短信验证码登录**（下发 + 校验 + 腾讯云 SMS 接入） | 接口 | 6 位码、5 分钟有效、一次性、失败 5 次作废；**华为侧异常时本通道仍可登录**（须有断开华为依赖的测试） | FR-ACC-04、**TD-32** | +| T-P1-12c | DEV | **短信防刷**（号码/IP/设备三重频控 + 人机校验 + 发送量告警） | 中间件 + 告警 | **脚本化刷量测试证明拦截有效**；号码在日志与后台全部掩码 | FR-ACC-14、NFR-SEC-03/05 | +| T-P1-14 | DEV | 游客模式与数据合并 | 接口 | 合并幂等；多设备场景有确定策略；**游客配额按设备维度终身计量**（非每日），用尽引导登录而非报错 | FR-ACC-02/03 | +| T-P1-16b | DEV | **清空我的照片**（保留账号） | 接口 + 页面 | COS 对象与 DB 引用同步清除；签名 URL 立即失效；二次确认 + 回执 + 审计日志 | **FR-ACC-15**、CR-02 | | T-P1-15 | DEV | 同意授权记录（含人脸单独同意） | 表 + 接口 | 记录含版本与时间，可查询 | CR-01、FR-ACC-08 | | T-P1-16 | DEV | 账号注销与数据删除任务 | 接口 + 定时任务 | 7 日内彻底删除，含 COS 对象；有执行记录 | CR-03、FR-ACC-09 | | T-P1-17 | DEV | 未成年人判定与功能限制 | 中间件 | 未成年账号禁用付费与外观评价 | CR-04、FR-ACC-11 | @@ -180,7 +185,10 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ | T-P1-22 | DEV | **统一合规出口**（审核 + 水印 + 元数据 + 内容编号登记） | 模块 | 所有产物必经；元数据全链路存活测试通过 | CR-05、CR-06 | | T-P1-23 | DEV | 内容审核接入（IMS + TMS + 关键词库） | 模块 | 六类审核对象全覆盖；fail-close 生效 | CR-06/07 | | T-P1-24 | DEV | **LLM 网关**（路由/降级/熔断/结构化输出/Prompt 版本/成本记录） | 模块 | 主备切换 < 3s；成本 100% 记录 | FR-SYS-04 | +| **T-P1-24a** | DEV | **思考模式按场景显式配置** | 场景配置 + provider 参数 | 每个场景**显式**给出 `thinking` 值，不依赖供应商默认；对话与结构化抽取场景一律关闭；单独记录 `tokens_reasoning` | `NFR-PERF-02b`、`NFR-COST-01`、TD-04 | | T-P1-25 | DEV | 成本归因表与日成本预警 | 表 + 告警 | 可按功能/模型/用户聚合；突增告警生效。**不允许后置到上线后补**（V2 定价的唯一数据来源） | FR-BILL-08、NFR-COST-01、FR-SYS-07 | +| T-P1-25b | DEV | **全局日成本熔断**（四档自动降级） | 模块 + 后台开关 | 注入成本可复现 60/80/90/100% 四档降级；**在途任务放行**；**被熔断拒绝的请求配额净扣减 = 0**；后台可查状态并手动解除 | NFR-COST-02、架构 §13.3 | +| **T-P1-25c** | DEV | **峰谷单价按调用时刻计价** | 两套价目表 + 时段判定 | 高峰（北京时间 09:00-12:00、14:00-18:00）与空闲各一套单价；成本在**调用当时**算好落库，事后不按当前价重算；跨时段有测试 | `NFR-COST-01`、TD-04 | | T-P1-26 | DEV | **配额账本**（余额、流水、预扣三段式、周期重置、规则配置化） | 模块 + 接口 | 余额可由流水重算；失败自动退还；**表结构含 `tx_type` 字段，V2 上支付无需迁移**；服务端硬校验不可绕过 | FR-BILL-01/02/04/05/06 | | T-P1-26b | DEV | 额度耗尽文案与提示 | 端侧组件 | **不出现任何价格、购买、会员、升级字样**；消耗前提示剩余量 | FR-BILL-07 | | T-P1-27 | DEV | 图片直传（预签名 URL）与临时桶生命周期 | 接口 + 桶策略 | 图片不经应用服务器；2 小时自动清理 | FR-SYS-03、CR-02 | @@ -247,12 +255,16 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ | T-P3-14 | DEV | 报告分享（长图 + 可失效链接） | 功能 | 分享图含显式标识；链接可撤回 | FR-RPT-12 | | T-P3-15 | DEV | 画像与记忆写入（L0~L2 + 冲突消解 + 审计） | 模块 | 报告完成后 L1 记忆同步生成 | FR-MEM-01/02/07/12 | | T-P3-16 | DEV | 「我的记忆」页面（可见可编辑可删除） | 页面 | 删除后不再注入；编辑优先级最高 | FR-MEM-05、CR-02 | -| T-P3-17 | DEV | 记忆快照与注入（token 预算裁剪 + 缓存） | 模块 | 注入 ≤ 500 token；记忆变更即失效缓存 | FR-MEM-04 | +| T-P3-17 | DEV | 记忆快照与注入（token 预算裁剪 + 缓存） | 模块 | **注入 ≤ 1400 token**（V1 实际 ≤ 1200）；记忆变更即失效缓存；**裁剪时硬禁忌不丢失**（须有单测） | FR-MEM-04、架构 §7.2 | | T-P3-18 | DEV | 记忆衰减定时任务 | 任务 | 未强化记忆置信度按规则下降 | FR-MEM-06 | | T-P3-19 | DEV | 无照片/拒绝授权的降级路径 | 功能 | 问卷可生成简版画像，明确告知差异 | FR-RPT-11 | | T-P3-20 | DEV | 报告引导流程（首次进入核心功能前） | 功能 | 可跳过；跳过后有降级说明 | FR-RPT-02 | +| **T-P3-21** | DEV | **报告结论认同/修正入口 + 埋点** | 功能 + 埋点 | 每个可修正维度均有入口；修正后置信度置 1.0 并即时写 L1；**认同率与修正率两项指标可从埋点直接算出** | **FR-RPT-19** | +| **T-P3-22** | DEV | **全面报告预约留资卡片 + 埋点** | 页面 + 埋点 | 卡片**不含任何价格字样**；预约率、停留时长、目录章节点击分布可查 | **FR-RPT-20** | -**M3 出口条件**：真实用户（内部 10 人）走完报告流程，人工评审报告质量：结论准确、无禁忌违反、无贬损表述、术语可理解；画像正确写入并能被 Agent 读到。 +> ⚠️ **`T-P3-21`/`T-P3-22` 不是"锦上添花"，缺了会让 V1 白跑一遍**：前者是「结论认同率 > 70%、修正率 < 15%」两项核心质量指标的唯一数据来源；后者是 V1 唯一的商业化验证数据来源（预约率 ≥ 8% 是 V2 立项门槛）。**指标没有数据来源就等于没有指标。** + +**M3 出口条件**：真实用户（内部 10 人）走完报告流程，人工评审报告质量：结论准确、无禁忌违反、无贬损表述、术语可理解；画像正确写入并能被 Agent 读到；**认同/修正埋点与预约留资埋点均可查到数据**。 --- @@ -264,7 +276,7 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ | --- | --- | --- | --- | --- | --- | | T-P4-01 | DEV | 会话与消息模型（含检索轨迹与规则命中） | 表 + 迁移 | 每条回答可复盘 | FR-AGT-09 | | T-P4-02 | DEV | 意图识别（含越界意图拒答） | 模块 | 主要意图准确率 ≥ 85%；越界正确拒答 | FR-AGT-02、CR-12 | -| T-P4-03 | DEV | 上下文组装与 token 预算控制 | 模块 | 输入 ≤ 3700 token；超限按优先级裁剪 | FR-AGT-03 | +| T-P4-03 | DEV | 上下文组装与 token 预算控制 | 模块 | **输入 ≤ 4200 token**（V1 实际 ≤ 4000）；超限按既定优先级裁剪而非报错 | FR-AGT-03、架构 §7.2 | | T-P4-04 | DEV | 流式对话接口（SSE） | 接口 | 首字 p95 < 2s | FR-AGT-01 | | T-P4-05 | DEV | 生成后校验（复用 T-P3-11） | 模块 | 黄金集违反数 = 0 | FR-AGT-05 | | T-P4-06 | DEV | 搭配方案结构化输出与卡片渲染 | 功能 | 可解析为单品组合，字段完整 | FR-AGT-06 | @@ -280,7 +292,7 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ | --- | --- | --- | --- | --- | --- | | T-P4-12 | DEV | **换装服务改造**（鉴权/异步回调/幂等/并发上报/成本埋点/COS 迁移） | 改造后服务 | 架构 §4.4 全部改造项完成 | FR-TRY-01 | | T-P4-13 | DEV | 换装任务编排（三工作流） | 模块 | 成功率 ≥ 90%（排除输入不合格） | FR-TRY-01 | -| T-P4-14 | DEV | 输入前置校验（人像质量 + 单品白底图规格） | 模块 | 不合格输入在扣点前拦截 | FR-TRY-02 | +| T-P4-14 | DEV | 输入前置校验（人像质量 + 单品白底图规格） | 模块 | 不合格输入**在预扣配额前**拦截（顺序错了会白扣用户额度） | FR-TRY-02 | | T-P4-15 | DEV | GPU 队列容量保护与排队体验 | 机制 + 页面 | 展示位次与预估；超阈值拒绝新任务 | FR-TRY-04 | | T-P4-16 | DEV | 结果审核 + 合规标识 + 存储 | 流程 | 100% 经统一合规出口 | FR-TRY-03、CR-05 | | T-P4-17 | DEV | 结果收藏与管理（含删除清理对象） | 功能 | 删除后 COS 对象同步清理 | FR-TRY-06 | @@ -314,6 +326,9 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ | T-P5-14 | BIZ | 内部测试与用户测试（种子用户） | 测试报告 | 核心链路无 P0 缺陷；报告质量人工评审通过 | — | | T-P5-15 | DEV | **配额对账任务与告警** | 定时任务 | 每日校验余额与流水一致性，不一致告警。V1 就要做，否则 V2 上支付时对账逻辑无历史数据可验证 | FR-BILL-02 | | T-P5-16 | BIZ | 全文案价格字样扫描 | 扫描报告 | 全端文案不含价格、购买、会员、升级字样（`FR-BILL-07`） | TD-28 | +| **T-P5-17** | DEV | **会员页静态权益展示 + 「上线提醒我」留资** | 页面 + 埋点 | **无价格、无购买按钮**；曝光数与留资率可查。验证**订阅意愿**（与 `T-P3-22` 验证的单次付费意愿是两件事） | **FR-BILL-12** | +| **T-P5-18** | OPS | **CLS 日志留存周期配置为 ≥ 6 个月** | 配置 + 截图 | 实际配置值可核验，非仅文档声明 | **CR-11** | +| **T-P5-19** | OPS | **熔断降级四档演练** | 演练记录 | 注入成本触发 60/80/90/100% 四档；在途任务未被中断；**配额净扣减 = 0** | **NFR-COST-02** | **M5 出口条件**：合规清单全绿 + **编号公示实机验证通过** + 压测达标 + 恢复演练完成 + 无 P0 缺陷。 @@ -414,5 +429,7 @@ M2 知识库 M3 报告闭环 M4 换装/发型 │ | 日期 | 版本 | 变更 | | --- | --- | --- | +| 2026-08-13 | v1.3 | **后端脚手架落地后的回写**。新增两项由真机实测暴露、原 WBS 完全未覆盖的任务：**`T-P1-24a` 思考模式按场景显式配置** —— `deepseek-v4-flash` **默认开启**思考模式，实测同一单句问答开启 13.5s、关闭 1.8s，思考 token 还按输出价计费，漏配会同时打破 `NFR-PERF-02b` 与成本模型；**`T-P1-25c` 峰谷单价按调用时刻计价** —— DeepSeek 自 2026-08-17 起高峰单价为空闲时段 2 倍，用单一均价记账会让 `ob_ai_call` 与真实账单差出近一倍，而它是 V2 定价的唯一依据。另：`T-P1-01`/`02`/`06`/`07`/`24`/`25` 已在 `meida_backend` 仓库交付并实测通过，各任务的完成状态见《Sprint 执行计划》§1.1 | +| 2026-08-13 | v1.2 | **文档一致性评审修订，补齐 9 项"需求已定但无任务认领"的缺口**。新增任务：`T-P1-12b` 短信验证码登录、`T-P1-12c` 短信防刷、`T-P1-16b` 清空我的照片、`T-P1-25b` **全局日成本熔断**（四档降级，验收含「配额净扣减 = 0」）、`T-P3-21` **报告结论认同/修正入口**、`T-P3-22` **全面报告预约留资**、`T-P5-17` 会员页留资、`T-P5-18` CLS 日志留存 ≥6 个月（`CR-11` 此前无人认领）、`T-P5-19` 熔断四档演练。其中 `T-P3-21`/`T-P3-22` 尤其关键 —— 前者是「结论认同率 > 70%、修正率 < 15%」的唯一数据来源，后者是 V1 唯一的商业化验证数据来源，**缺了会让 V1 白跑一遍**。另：**依赖图中的 M4 拆为 `M4-a` 换装/发型（可与 M3 并行）与 `M4-b` Agent 对话（须等 M2+M3）**，原图两处都标 M4 易误读为同一批工作；`T-P3-17` 注入预算 500→1400、`T-P4-03` 总输入 3700→4200；`T-P4-14` 明确输入校验须在预扣配额之前 | | 2026-08-13 | v1.1 | **关键路径转移**。备案已完成，原 `T-P0-01`~`T-P0-08` 申报类任务关闭，替换为备案后的落地与核实任务（模型清单核实、编号公示位实现、公示与网关路由同源校验）。§2.3 内容与素材生产升为新的关键路径，`T-P0-20` 顾问到岗与 `T-P0-21` 自采流水线成为全项目最优先任务，并要求输出**每周产能数据**用于倒排。配额相关任务去除支付语义（`T-P1-26` 强调 `tx_type` 字段使 V2 免迁移，新增 `T-P1-26b` 文案约束、`T-P5-15` 对账、`T-P5-16` 价格字样扫描）。诊断维度改 32。Phase 6 新增企业开发者认证、一键登录、**小范围真实收费灰度**，并明确 `T-P6-16` 定价的四项前置输入 | | 2026-08-13 | v1.0 | 首次输出。六个里程碑（M0~M5 为 V1，M6 为 V2+），Phase 0 定为备案与前置验证阶段并与开发并行 | diff --git a/docs/技术架构文档.md b/docs/技术架构文档.md index 0a0ff72..3bfc9f7 100644 --- a/docs/技术架构文档.md +++ b/docs/技术架构文档.md @@ -1,6 +1,6 @@ # 「美搭」技术架构文档 -> 版本：v1.0　｜　更新日期：2026-08-13　｜　状态：待技术评审 +> 版本：**v1.3**　｜　更新日期：2026-08-13　｜　状态：待技术评审 > > **本文的定位**：把产品需求翻译成可直接拆解为开发任务的技术方案。读完这份文档，应该能回答三个问题——系统由哪些部分组成、数据长什么样、每条关键链路怎么跑通。 > @@ -66,24 +66,29 @@ └───┬──────────┬──────────┬──────────┬──────────┬──────────┬───────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ -┌────────┐┌────────┐┌────────┐┌────────┐┌────────┐┌──────────────┐ -│华为服务 ││大模型 ││腾讯云AI ││自有换装 ││腾讯云 ││腾讯云基础设施 │ -│账号/推送││DeepSeek││人脸识别 ││发型服务 ││天御审核 ││COS/CDN/PG/ │ -│Push ││智谱GLM ││ ││(GPU) ││ ││Redis/CLS │ -└────────┘└────────┘└────────┘└────────┘└────────┘└──────────────┘ +┌────────┐┌────────┐┌────────┐┌────────┐┌────────┐┌────────┐┌──────────────┐ +│华为服务 ││大模型 ││腾讯云AI ││自有换装 ││腾讯云 ││腾讯云 ││腾讯云基础设施 │ +│账号/推送││DeepSeek││人脸识别 ││发型服务 ││天御审核 ││短信SMS ││COS/CDN/PG/ │ +│Push ││智谱GLM ││ ││(GPU) ││ ││ ││Redis/CLS │ +└────────┘└────────┘└────────┘└────────┘└────────┘└────────┘└──────────────┘ + +注：V1 不接入天气 API（TD-33），Agent 的天气类问题走「反问用户 + 城市月份推断气候区」降级 ``` **外部依赖及其失效影响**（每一个都要有降级方案，见 §13.4）： | 外部系统 | 用途 | 失效影响 | 降级策略 | | --- | --- | --- | --- | -| 华为 Account Kit | 登录 | 新用户无法注册 | 游客模式可继续体验非付费功能 | -| 华为 IAP | 支付（**V2 起**） | 无法购买 | 提示稍后再试，不影响已有权益。V1 不依赖此项 | +| 华为 Account Kit | 登录（通道一） | 该通道不可用 | **手机号验证码登录仍可用**（两条通道不得互相依赖）；游客模式可继续体验 | +| **腾讯云短信 SMS** | **登录（通道二，`TD-32`）** | 该通道不可用 | **华为账号登录仍可用**；登录页给出明确提示而非笼统报错 | | 华为 Push Kit | 任务完成通知 | 通知不到 | 应用内任务中心轮询兜底 | | DeepSeek / GLM | 文案生成、对话 | 报告与对话不可用 | 双供应商自动切换；均失败时报告排队重试，对话返回兜底话术 | | 腾讯云人脸识别 | 面部分析 | 报告无法生成面部维度 | 报告降级为「体型+色彩」子集，标注待补全 | | 自有换装服务 | 出图 | 换装不可用 | 任务转排队，不扣配额，超时退还 | | 腾讯云天御 | 内容审核 | **不可降级** | 审核失败一律按「拦截」处理（fail-close），宁可少发不可漏审 | +| 华为 IAP | 支付（**V2 起**） | 无法购买 | 提示稍后再试，不影响已有权益。**V1 不依赖此项** | + +> 🔑 **登录必须有两条互不依赖的通道**，这是 V1 唯一的单点故障防护。华为账号是唯一通道时，华为侧授权异常会让用户直接进不来产品；而一键登录已推至 V2（`TD-29`），所以手机号验证码是 V1 的必需项，不是可选项。 --- @@ -265,11 +270,11 @@ kb ← agent / report（读取） | 表 | 关键字段 | 说明 | | --- | --- | --- | -| `id_user` | `user_id` PK, `status`, `nickname`, `avatar_key`, `register_source`, `created_at`, `last_active_at`, `deleted_at` | 内部主键，与外部身份解耦 | -| `id_user_identity` | `user_id`, `provider`('huawei'), `union_id`, `open_id`, UNIQUE(`provider`,`union_id`) | 一个用户可有多个外部身份 | +| `id_user` | `user_id` PK, `status`('active'/'frozen'/'deleting'/'deleted'), `nickname`, `avatar_key`, `register_source`, `created_at`, `last_active_at`, `deleted_at` | 内部主键，与外部身份解耦。**手机号不存本表**，见下行 | +| `id_user_identity` | `user_id`, `provider`(**'huawei'/'phone'**), `union_id`, `open_id`, **`phone_enc`（AES 加密）, `phone_hash`（检索用）**, UNIQUE(`provider`,`union_id`) | 一个用户可有多个外部身份。**手机号作为一种 `provider` 存在本表，不在 `id_user` 冗余** —— 它是登录凭证而非用户属性，且便于统一加密与脱敏（`NFR-SEC-03`）。检索用 `phone_hash`，展示用解密后掩码 | | `id_guest` | `guest_id`, `device_fp`, `merged_to_user_id`, `created_at` | 游客数据，登录后合并 | | `id_device` | `device_id`, `user_id`, `push_token`, `os_version`, `last_seen_at` | 推送 Token 管理 | -| `id_consent` | `consent_id`, `user_id`, `consent_type`('terms'/'privacy'/'face'/'minor'), `doc_version`, `granted_at`, `revoked_at`, `client_ip`, `ua` | **合规留证**：人脸的单独同意必须独立成行 | +| `id_consent` | `consent_id`, `user_id`, `consent_type`, **`granted` bool**, `doc_version`, `granted_at`, `revoked_at`, `client_ip`, `ua` | **合规留证**：人脸的单独同意必须独立成行。枚举见下表 | | `id_session` | `session_id`, `user_id`, `refresh_token_hash`, `expire_at`, `revoked` | 刷新令牌服务端可撤销 | #### profile 域（画像与记忆） @@ -277,11 +282,21 @@ kb ← agent / report（读取） | 表 | 关键字段 | 说明 | | --- | --- | --- | | `pf_profile` | `profile_id`, `user_id`, `label`, `is_default` | **预留多档案**（帮家人诊断的场景），V1 只创建默认档案 | -| `pf_diagnosis` | `diagnosis_id`, `profile_id`, `source_report_id`, `dimensions` JSONB, `version`, `overall_confidence`, `created_at` | 34 个诊断维度的结构化结论；按版本追加，不覆盖 | -| `pf_memory` | `memory_id`, `user_id`, `layer`(L0~L5), `mem_key`, `mem_value` JSONB, `confidence` numeric, `status`('active'/'pending_confirm'/'archived'/'rejected'), `source`('explicit'/'implicit'/'report'/'behavior'), `evidence_ref`, `valid_from`, `last_reinforced_at`, `decay_after`, `created_at` | 记忆项主表；索引 (`user_id`,`layer`,`status`) | +| `pf_diagnosis` | `diagnosis_id`, `profile_id`, `source_report_id`, `dimensions` JSONB, `version`, `overall_confidence`, `created_at` | **32 个**诊断维度的结构化结论（字典见美学报告 §4，为唯一事实源；编号 33/34 已随 `TD-31` 移除且不再复用）；按版本追加，不覆盖 | +| `pf_memory` | `memory_id`, `user_id`, `layer`(L0~L5), `mem_key`, `mem_value` JSONB, `confidence` numeric, `status`, `source`, `evidence_ref`, `valid_from`, `last_reinforced_at`, `decay_after`, `created_at` | 记忆项主表；索引 (`user_id`,`layer`,`status`)。**`status` 与 `source` 的枚举取值以《用户系统与记忆系统-需求文档》§3.3 为唯一事实源**，见下表 | | `pf_memory_event` | `event_id`, `memory_id`, `action`('create'/'reinforce'/'decay'/'conflict'/'user_edit'/'delete'), `detail` JSONB, `created_at` | 记忆变更审计，支撑「我的记忆」页面的可解释性 | | `pf_memory_snapshot` | `user_id`, `snapshot` JSONB, `token_count`, `content_hash`, `built_at`, `expire_at` | 注入 LLM 的画像摘要缓存，避免每轮重算 | +**枚举取值（本轮对齐，此前架构与用户系统文档给了两套不兼容的枚举）** + +> ⚠️ 原架构表写 `status`=archived/rejected、`source`=explicit/implicit/report/behavior，与用户系统 §3.3 的枚举无法对应。**以用户系统文档为准**，因为它的取值承载了衰减与冲突消解的语义（`decayed`/`overridden` 必须可区分，否则 §3.6 的冲突消解无法实现）。 + +| 字段 | 取值 | 语义要点 | +| --- | --- | --- | +| `pf_memory.status` | `active` / `pending_confirm` / `decayed` / `overridden` / `deleted` | `decayed`（置信度衰减至 < 0.3，可恢复）与 `overridden`（被新证据覆盖）**必须区分**，前者可由用户恢复，后者不可 | +| `pf_memory.source` | `explicit_user_input` / `user_setting` / `report_vision` / `self_reported` / `behavior_inferred` / `llm_extracted` | 衰减规则只作用于 `behavior_inferred` 与 `llm_extracted`（用户系统 §3.5），因此**不能合并为笼统的 `implicit`** | +| `id_consent.consent_type` | `privacy`（隐私政策）/ `face`（**人脸，须独立成行**）/ `personalization`（个性化推荐）/ `push`（推送通知）/ `minor`（未成年人确认） | ⚠️ **`personalization` 不可省略**：用户系统 §3.10 要求记忆写入必须建立在该项授权之上，缺了它记忆系统就没有合规依据 | + #### report 域 | 表 | 关键字段 | 说明 | @@ -321,7 +336,7 @@ kb ← agent / report（读取） | 表 | 关键字段 | 说明 | | --- | --- | --- | -| `tk_task` | `task_id`, `user_id`, `task_type`('report'/'tryon'/'hairstyle'/'matting'/'render'), `status`, `progress`, `stage_text`, `idempotency_key` UNIQUE, `payload` JSONB, `error_code`, `retry_count`, `points_reserved`, `submitted_at`, `started_at`, `finished_at`, `eta_seconds` | **全系统唯一的长耗时任务视图**，前端任务中心直接读它 | +| `tk_task` | `task_id`, `user_id`, `task_type`('report'/'tryon'/'hairstyle'/'matting'/'render'), `status`, `progress`, `stage_text`, `idempotency_key` UNIQUE, `payload` JSONB, `error_code`, `retry_count`, **`quota_reserved`**, `submitted_at`, `started_at`, `finished_at`, `eta_seconds` | **全系统唯一的长耗时任务视图**，前端任务中心直接读它。⚠️ 字段名由 `points_reserved` 改为 **`quota_reserved`** —— V1 是配额不是点数，用 points 命名会在实现期误导 | #### billing 域（V1 为配额与计量，无支付） @@ -329,10 +344,12 @@ kb ← agent / report（读取） | 表 | 关键字段 | V1 | 说明 | | --- | --- | :--: | --- | -| `bl_wallet` | `user_id` PK, `balance`, `version`（乐观锁） | ✅ | V1 存「可用额度」，V2 语义扩展为点数余额。**同一张表，不改结构** | -| `bl_ledger` | `tx_id`, `user_id`, `delta`, `tx_type`, `reason`, `ref_type`, `ref_id`, `balance_after`, `idempotency_key` UNIQUE, `created_at` | ✅ | **流水是真相**，余额是缓存。`tx_type` V1 只用 `system_grant`/`consume`/`refund`，V2 增加 `purchase`/`gift` —— 这是 V1→V2 免迁移的关键 | -| `bl_quota` | `user_id`, `quota_key`, `period_key`, `used`, `limit_value` | ✅ | 周期配额计量（日/月/终身），按 `period_key` 自然重置，无需定时任务清零 | -| `bl_quota_rule` | `quota_key`, `period_type`, `base_limit`, `task_bonus_max`, `hard_cap` | ✅ | 配额规则配置化（`FR-BILL-04`），改配置不发版 | +| `bl_quota` | `user_id`, `quota_key`, `period_key`, `used`, **`bonus_granted`**, `updated_at`；UNIQUE(`user_id`,`quota_key`,`period_key`) | ✅ | **V1 扣减判定的唯一依据**。周期配额计量（日/月/终身），按 `period_key` 自然重置，**不要写定时清零任务**。`bonus_granted` 物化本周期已获任务奖励，避免每次判定都聚合流水 | +| `bl_quota_rule` | `quota_key`, `period_type`, `base_limit`, `task_bonus_max`, `hard_cap` | ✅ | 配额规则配置化（`FR-BILL-04`），改配置不发版。数值来源：产品方案 §3.2 配额表（唯一事实源） | +| `bl_ledger` | `tx_id`, `user_id`, `delta`, `tx_type`, `status`, `reason`, `ref_type`, `ref_id`, `balance_after`, `idempotency_key` UNIQUE, `created_at` | ✅ | **流水是真相**，但**不参与 V1 的判定**（判定看 `bl_quota`）。`tx_type` V1 用 `system_grant`/`consume`/`refund` **三种**，V2 增加 `purchase`/`gift` —— 这是 V1→V2 免迁移的关键 | +| `bl_wallet` | `user_id` PK, `balance`, `version`（乐观锁） | ✅ | ⚠️ **V1 仅用于「跨周期不清零」的额度**（如首次终身报告）；周期类额度一律走 `bl_quota`。V2 语义扩展为点数余额，**同一张表，不改结构** | + +> 🔑 **四张表的职责边界见 §7.4 开头**。这是最容易实现成"两套并行扣减逻辑"的地方，务必先读那一段。 | `bl_membership` | `user_id`, `level`, `valid_from`, `valid_to`, `source_order_id`, `auto_renew` | ❌ V2 | 会员 | | `bl_order` | `order_id`, `user_id`, `product_id`, `product_type`, `price_cents`, `platform`('huawei_iap'), `purchase_token` UNIQUE, `status`, `verified_at`, `raw_receipt` JSONB | ❌ V2 | `purchase_token` 唯一约束防重复发货（`TD-16`） | @@ -351,12 +368,12 @@ kb ← agent / report（读取） | 表 | 关键字段 | 说明 | | --- | --- | --- | -| `ob_ai_call` | `call_id`, `user_id`, `scene`, `provider`, `model`, `tokens_in/out/cached`, `latency_ms`, `cost_cents`, `success`, `error_code`, `ref_type`, `ref_id`, `created_at` | **成本归因的唯一数据源**，按月分区 | +| `ob_ai_call` | `call_id`, `user_id`, `scene`, `provider`, `model`, `prompt_id`, `prompt_version`, `tokens_in/out/cached`, `tokens_reasoning`, `latency_ms`, `cost_cents`, `rate_tier`, `success`, `error_code`, `ref_type`, `ref_id`, `created_at` | **成本归因的唯一数据源**，按月分区。`prompt_id`/`prompt_version` 使每次调用可复现（§8.1 要求 Prompt 版本化，缺这两列就无法回答「上周的报告是哪版 Prompt 生成的」）；`tokens_reasoning` 单独记思考模式 token（按输出价计费，混进 `tokens_out` 会掩盖开关思考模式的成本差异）；`rate_tier` 记录该次调用适用的峰谷档位，否则事后无法复核 `cost_cents` | | `ob_event` | `event_id`, `user_id`, `event_name`, `props` JSONB, `client_ts`, `server_ts` | 埋点事件，按月分区（`TD-23`） | ### 6.3 诊断维度的存储形态 -34 个诊断维度用 `pf_diagnosis.dimensions` JSONB 存储，但**每个维度都是结构化三元组**，不是自由文本： +**32 个**诊断维度（字典见《美学报告-需求文档》§4，为唯一事实源）用 `pf_diagnosis.dimensions` JSONB 存储，但**每个维度都是结构化三元组**，不是自由文本： ```json { @@ -435,7 +452,7 @@ kb ← agent / report（读取） | **分步可恢复** | 第 7~13 步的视觉分析结果落库为中间态，LLM 或渲染失败时**不需要重跑视觉分析**（也就不需要用户重新上传） | | **生成后校验不可跳过** | 校验失败最多重试 2 次（提高约束强度），仍失败则降级为「规则直出模板文案」，绝不放行违规内容 | | **等待体验** | 阶段文案随进度更新；预估时间基于历史 p50；超过阈值转为「后台生成 + 完成推送」，允许用户离开页面 | -| **幂等** | 相同 `idempotency_key` 重复提交返回同一 `task_id`，不重复扣点 | +| **幂等** | 相同 `idempotency_key` 重复提交返回同一 `task_id`，**不重复扣减配额** | ### 7.2 Agent 对话（含检索与画像注入） @@ -475,17 +492,28 @@ kb ← agent / report（读取） ⑨ 异步：偏好抽取 → 写入 L2 记忆（显式）/ 生成待确认候选（隐式） ``` -**Token 预算分配（必须硬性限制，否则成本会失控）**： +**Token 预算分配（必须硬性限制，否则成本会失控）** -| 部分 | 预算 | 说明 | -| --- | --- | --- | -| 系统提示词 | ≤ 800 | 固定不变，放在最前以最大化缓存命中 | -| 画像摘要 | ≤ 500 | 从记忆快照裁剪，按置信度与相关性排序 | -| 会话摘要 | ≤ 400 | 滚动压缩 | -| 检索知识 | ≤ 1500 | 重排后取前 N 条，超出则截断而非全塞 | -| 用户当前输入 | ≤ 500 | 超长提示精简 | -| **输入合计** | **≤ 3700** | | -| 输出 | ≤ 800 | 超长回答不利于阅读，也贵 | +> 🔒 **本表是 token 预算的唯一定义位置**。`FR-MEM-04`、`FR-AGT-03`、产品方案 §2.4.2、用户系统 §3.8、穿搭 Agent §3.5.2/§10.2、`T-P3-17` **一律引用本表，不得复述数值**。 +> +> ⚠️ **此前存在两套互相矛盾的口径，本轮已查明原因并修正**。原架构表写「会话摘要 ≤ 400、总输入 ≤ 3700」，用户系统 §3.8 写「会话上下文 ≤ 800、记忆注入合计 ≤ 1400」。**错在架构表**：用户系统的 800 是「**最近 6 轮原文 + 更早轮次的滚动摘要**」，而架构表只算了滚动摘要、漏掉了近轮原文。因此**以用户系统 §3.8 的分项为准，并修正总输入合计**。 + +| 层级 | 部分 | 预算 | 说明 | +| --- | --- | --- | --- | +| 总输入 | 系统提示词 | ≤ 800 | 固定不变，放最前以最大化缓存命中 | +| 总输入 | **记忆注入（小计）** | **≤ 1400** | 展开见下四行；这是 `FR-MEM-04` 的验收口径 | +| └ 记忆注入 | 画像摘要 L0/L1 | ≤ 250 | 模板化压缩，非 LLM 生成 | +| └ 记忆注入 | 偏好记忆 L2 | ≤ 150 | `confidence ≥ 0.5` 按置信度取 Top 15，**硬禁忌优先保留** | +| └ 记忆注入 | 事件记忆 L3（向量召回） | ≤ 200 | **V2 能力，V1 预算预留但不使用** | +| └ 记忆注入 | 会话上下文 L4 | ≤ 800 | = 最近 6 轮原文 ≤ 400 + 更早轮次滚动摘要 ≤ 400 | +| 总输入 | 检索知识 | ≤ 1500 | 重排后取前 N 条，超出则截断而非全塞 | +| 总输入 | 用户当前输入 | ≤ 500 | 超长提示精简 | +| **总输入合计** | | **≤ 4200** | `FR-AGT-03` 的验收口径；原 3700 因漏算近轮原文而偏低 | +| 输出 | | ≤ 800 | 超长回答不利于阅读，也贵 | + +**V1 实际用量**：L3 不启用，故记忆注入 ≤ 1200、总输入 ≤ 4000，留有余量。 + +**裁剪优先级（预算超限时按此顺序丢弃，不得报错）**：事件记忆 L3 → 滚动摘要尾部 → 检索知识低分项 → 偏好记忆低置信项 → 近轮原文最早的几轮。**硬禁忌与安全约束永不裁剪** —— 裁掉它们会导致推荐用户明确拒绝的品类，属 P0 缺陷（产品方案 §8.3.3 要求禁忌违反率为 0）。 **缓存前缀纪律**：系统提示词与稳定知识片段必须放在 prompt 头部且**不含时间戳、随机 ID、用户昵称等变量**，否则缓存永远不命中，输入成本翻数倍（`TD-04`）。 @@ -499,29 +527,63 @@ kb ← agent / report（读取） ⑤ 结果图审核（IMS） ⑥ 合规出口：水印「AI 生成」+ 写入元数据与内容编号 → 存 COS 用户内容桶 ⑦ commit 配额、记录成本、Push 通知 -⑧ 失败：区分可重试（网络/排队超时）与不可重试（输入非法/审核拒绝），后者立即退点 +⑧ 失败：区分可重试（网络/排队超时）与不可重试（输入非法/审核拒绝），后者立即退还配额 ``` **队列即容量**：`gpu` 队列的并发上限直接由 GPU 容量决定，并把「当前排队位次 + 预估等待」返回给用户。**不要让请求无限积压**——超过阈值直接拒绝新任务并提示稍后再试，这比让用户等 10 分钟体验更好。 ### 7.4 配额消耗（V1）与 IAP 支付（V2） -#### V1：配额三段式 +#### V1：四张表的职责边界（**必须先看这段，否则会实现成两套并行的扣减逻辑**） + +`billing` 域有四张表，此前文档没写清它们的关系，导致 `bl_quota.used` 与 `bl_wallet.balance` 看起来像两套重复机制。实际分工是： + +| 表 | 在 V1 的角色 | 是否参与 V1 的扣减判定 | +| --- | --- | --- | +| `bl_quota_rule` | **规则**：每个 `quota_key` 的周期类型、基础额度、任务奖励上限、防刷硬上限 | 提供判定用的阈值，配置化，改配置不发版 | +| `bl_quota` | **周期计数器**：`(user_id, quota_key, period_key)` 上的 `used` 与本周期已获得的 `bonus_granted` | ✅ **V1 的判定就在这张表上** | +| `bl_ledger` | **流水（真相）**：每一次发放、消耗、退还都留痕，供对账与 V2 定价分析 | ❌ 不参与判定，但**每次判定通过后必须写** | +| `bl_wallet` | **余额缓存**：V1 语义为「跨周期不清零的可累积额度」 | ⚠️ **V1 仅"首次终身"类额度用它**（如首次报告），周期类额度不用 | + +**一句话概括**：**V1 的判定看 `bl_quota`（周期计数器），V2 的判定才看 `bl_wallet`（点数余额）。`bl_ledger` 在两个版本里都只是流水。** 之所以 V1 就把 `bl_wallet`/`bl_ledger` 建起来，是为了 V2 上支付时不迁移数据（§6.2），不是因为 V1 需要它们做判定。 + +**判定公式中 `task_bonus` 的来源已明确**：不是从 `bl_ledger` 实时聚合（那样每次判定都要扫流水，且并发下不可靠），而是**在 `bl_quota` 上物化为 `bonus_granted` 字段**，发放任务奖励时同时递增它。判定公式因此是纯单行读： ``` -校验：GET 配额 → 判定 bl_quota.used < limit_value + task_bonus - ↓ （服务端硬校验，客户端提示仅为体验，FR-BILL-06） -预扣：reserve → bl_ledger 写 delta=-N, tx_type=consume, status=reserved - ↓ -任务执行（Celery，长耗时） - ↓ -成功：commit → 确认扣除，status=committed -失败：refund → 写反向流水 delta=+N, tx_type=refund（带 idempotency_key） +有效上限 = MIN( + bl_quota_rule.base_limit + bl_quota.bonus_granted, -- 基础额度 + 本周期已获奖励 + bl_quota_rule.hard_cap -- 防刷硬上限，任何情况不可超越 +) +放行条件 = bl_quota.used < 有效上限 +``` -发放：任务奖励 → bl_ledger 写 delta=+N, tx_type=system_grant +#### V1：配额消耗三段式 + +``` +① 熔断检查：全局日成本水位是否已达 100%？（NFR-COST-02） + ↓ 已熔断 → 直接拒绝，且【不得预扣】，返回"今日服务繁忙" +② 校验：SELECT ... FOR UPDATE 读 bl_quota 单行 → 按上方公式判定 + ↓ （服务端硬校验，客户端提示仅为体验，FR-BILL-06） +③ 预扣 reserve → bl_quota.used += N（同一事务内） + bl_ledger 写 delta=-N, tx_type=consume, status=reserved + ↓ +④ 任务执行（Celery，长耗时） + ↓ +成功：commit → 流水 status=committed（bl_quota.used 不变，已在③计入） +失败：refund → bl_quota.used -= N + bl_ledger 写反向流水 delta=+N, tx_type=refund（带 idempotency_key） + +发放：任务奖励 → bl_quota.bonus_granted += N（受 task_bonus_max 约束） + bl_ledger 写 delta=+N, tx_type=system_grant ↓ （同一任务同一周期幂等，FR-BILL-03） ``` +**三处最容易写错的地方**： + +1. **熔断必须在预扣之前**（步骤①在③之前）。顺序颠倒会导致平台自身限流却扣掉用户额度 —— 这是 `NFR-COST-02` 里「配额净扣减 = 0」那条验收标准要防的情况。 +2. **`bl_quota.used` 的增减必须与 `bl_ledger` 写入在同一个数据库事务里**，否则对账永远不平。 +3. **周期重置靠 `period_key` 自然切换，不要写定时清零任务**。`period_key` 形如 `2026-08-13`（日）/ `2026-08`（月）/ `lifetime`（终身），新周期首次访问时插入新行即可。定时清零在跨时区、补偿执行、任务漏跑时都会出错。 + **为什么预扣而不是直接扣**：长耗时任务可能失败，直接扣会产生「扣了额度没拿到结果」的客诉。先冻结再确认，失败自动释放。V1 虽然不涉及金钱，这个问题依然存在 —— **用户对"次数被白扣"的敏感度不比扣钱低**，而且 V1 没有客服退款兜底手段，只能靠机制保证。 **对账**：所有变更都写流水，余额可由流水重算校验（每日定时，不一致则告警）。V1 就要做，否则 V2 上支付时对账逻辑得从零开发且无历史数据验证。 @@ -646,12 +708,14 @@ get_memory_snapshot(user_id, budget_tokens) → 裁剪到预算内 → 缓存（hash 变更才重建） ``` -**写**： +**写**（置信度初值的唯一事实源是《用户系统与记忆系统-需求文档》§3.5，本处原写 0.95 与之冲突，已更正为 0.90）： ``` -显式（用户明确说的） → confidence=0.95，立即生效，回执告知用户「已记住」 -报告产出（机器诊断） → confidence=诊断置信度，写 L1 -行为推断（隐式） → 累积证据，达阈值生成 status='pending_confirm' - → 在合适时机征询确认，确认后才转 active +用户确认 / 设置页配置 → confidence=1.00 +对话中明确陈述 → confidence=0.90，立即生效，回执告知用户「已记住」 +报告产出（机器诊断） → confidence=诊断置信度（高置信维度 0.85 / 争议维度 0.65），写 L1 +自评问卷 → confidence=0.60 +行为推断（隐式） → confidence=0.50，累积证据达阈值生成 status='pending_confirm' + → 在合适时机征询确认，确认后才转 active（且 confidence 置 1.0） ``` **衰减与冲突**：定时任务按 `decay_after` 降低未被强化的记忆置信度；同 key 冲突时**显式 > 报告 > 隐式**，时间新 > 时间旧，并写 `pf_memory_event` 留痕。用户在「我的记忆」页面的编辑拥有最高优先级且不可被自动覆盖。 @@ -664,7 +728,7 @@ get_memory_snapshot(user_id, budget_tokens) | 项 | 约定 | | --- | --- | -| 基础路径 | `/api/v1`，大版本进路径 | +| 基础路径 | **规范写法为 `/api/v1`**，大版本进路径。`/v1/*` 作为等价别名由中间件重写到 `/api/v1/*`，两种写法返回完全一致的响应；文档、客户端与新代码一律写 `/api/v1`（别名只为兼容早期任务描述中的 `/v1`，不要在新代码里使用） | | 风格 | 面向资源的 REST；流式对话用 SSE（`text/event-stream`） | | 认证 | `Authorization: Bearer `（JWT，15 分钟）+ 刷新令牌（服务端可撤销） | | 幂等 | 写操作支持 `Idempotency-Key` 头，服务端 24 小时内保证同键同结果 | @@ -776,7 +840,11 @@ get_memory_snapshot(user_id, budget_tokens) ### 12.2 容量假设与压力点 -以 1 万 DAU 为规划基线（V1 实际远低于此，用于确认架构不会在早期就撞墙）： +**基线取 1 万 DAU**。与产品方案 §8.1.1 的口径关系需说明清楚，否则会被误读为架构容量低于业务目标： + +- 产品方案的 V1 业务目标是 **MAU 15 万**，且**明确不以 DAU 作为考核指标**（形象诊断是低频决策型工具，改用季度回访率）。 +- 低频工具的 DAU/MAU 通常在 5~10%，因此 MAU 15 万对应 DAU 约 **0.75~1.5 万** —— **1 万 DAU 基线与业务目标是吻合的**，不是保守估计。 +- 本基线的作用是确认架构不会在早期撞墙；实际压测值由 `T-P5-06` 确定，Agent 并发上限亦由此推导（穿搭 Agent §7.1）。 | 资源 | 估算 | 压力点 | | --- | --- | --- | @@ -794,13 +862,32 @@ get_memory_snapshot(user_id, budget_tokens) > ⚠️ **V1 不收费让这张表的地位更高，不是更低**（`TD-28`）。V1 没有收入，因此成本是唯一的财务变量；同时 `ob_ai_call` 是 **V2 定价的唯一数据来源** —— 单次真实成本与人均使用频次都从这里出。埋点缺失的功能，在 V2 定价时就是一个必须靠猜的空洞。**这一项不允许"先上线后补埋点"。** -**V1 的成本上限是可以事前算准的确定值**（这是不收费换来的好处）： +### 13.1 三个必须分开的成本口径 -``` -月度 AI 成本上限 = MAU × Σ(各功能日配额上限 × 单次成本 × 30) -``` +> ⚠️ **本节原有一处错误论证，已更正**。原文称「月度成本上限 = MAU × 单用户配额上限 × 单次成本，是可事前算准的确定值」。这不成立：**按人头发配额约束的是「单用户能用多少」，而总成本 = MAU × 人均，MAU 本身没有上限。** 配额防的是单用户刷爆，防不了总量涨爆。 -因为配额是服务端硬限制（`FR-BILL-06`），不存在超额路径，所以这是上限而非估计值。按 MAU 15 万、免费用户月成本上限 ¥8 计算，月度上限约 ¥12 万（产品方案 §5.3.1）。 +| 口径 | 公式 | MAU 15 万时 | 用途 | +| --- | --- | --- | --- | +| **理论最坏** | `MAU × 防刷硬上限成本(¥236/月)` | ≈ ¥3,540 万/月 | 只说明"配额不是预算工具"，无实际预算意义 | +| **预期成本** | `Σ(各功能月用量推算 × 单次成本)` | **¥7~12 万/月** | **唯一的预算口径**，含使用率假设 | +| **真实封顶** | 全局日成本熔断阈值 × 30 | **¥15 万/月** | **唯一与用户规模无关的硬闸门** | + +预期成本的完整算式与其隐含的使用率假设见产品方案 §5.3.1；单用户三档成本见产品方案 §5.2.1。**单一事实源在产品方案，本节不重复数值。** + +### 13.2 单位成本建模 + +> ⚠️ **LLM 单价自 2026-08-17 起分峰谷两档，本节的所有 `C_llm` 必须按调用时刻取价。** +> DeepSeek 高峰时段（北京时间 09:00-12:00、14:00-18:00）单价为空闲时段的 **2 倍**， +> 且新价目相对旧价目**输出侧涨约 2.25~4.5 倍**。两个直接后果： +> +> 1. **`ob_ai_call.cost_cents` 必须在调用当时算好落库**，不能事后按「当前单价」回算 —— +> 否则同一条记录在不同时间重算会得到不同结果，V2 定价的依据就不可复现。 +> 实现上由两套价目表 + 时段判定完成（`T-P1-25c`），并用 `rate_tier` 记录当次档位。 +> 2. **§13.1 的预期成本与熔断阈值需按新单价重算一次**。原数值基于旧单价推得， +> 而报告生成集中在白天高峰 —— 不重算会让熔断阈值落在错误的位置。 +> +> **可控杠杆有两个**：一是缓存前缀纪律（固定系统前缀命中缓存后输入侧大幅降价，已实测 +> 单次命中 128/240 输入 token）；二是把非实时的文案生成挪到空闲时段，直接省一半。 单位成本核算公式（数值需在 Phase 0 验证任务中实测填入，此处为建模框架）： @@ -808,15 +895,37 @@ get_memory_snapshot(user_id, budget_tokens) | --- | --- | --- | | 初级报告 | 人脸 API + 分割 API + 自建推理 + LLM + 审核 + 渲染 | `≈ C_face + C_seg + C_llm(in≈8k, out≈3k) + C_mod×n + C_render` | | 全面报告 | 初级 + 稠密关键点 + 更长文案 | `≈ 初级 × 3~4` | -| Agent 单轮 | LLM（缓存命中后输入成本大幅下降）+ 检索 + 双向审核 | `≈ C_llm(in≈3.7k 多数缓存, out≈0.8k) + C_mod×2` | +| Agent 单轮 | LLM（缓存命中后输入成本大幅下降）+ 检索 + 双向审核 | `≈ C_llm(in≈4.2k 多数缓存, out≈0.8k) + C_mod×2`。**思考模式须显式关闭**（`T-P1-24a`）：开启后思考 token 按输出价计费，实测同一问答耗时从 1.8s 涨到 13.5s | | 换装单次 | GPU 秒数 + 审核 + 存储 + CDN | `≈ gpu_seconds × 单价 + C_mod + C_storage` | | 抠图单件 | GPU 秒数（离线批量摊薄） | 批量跑，按批次成本 / 件数 | +| **短信验证码** | 单条约 ¥0.03~0.045（`TD-32`） | `发送条数 × 单价`。**量级上可忽略，但必须计量并告警** —— 被刷时它是直接的现金损失，且不像 GPU 成本那样有配额兜着 | -**必须设置的三道成本闸门**： +### 13.3 三道成本闸门（按拦截范围从大到小） -1. **场景级日预算**：某功能超预算自动降级（切轻量模型/暂停非核心功能），并告警。 -2. **用户级频控**：配额硬上限（服务端校验，`FR-BILL-06`），防单用户异常消耗。 -3. **日成本预警**：日成本环比突增超过阈值立即告警——通常意味着有 bug（重试风暴、缓存失效）或被刷。 +| # | 闸门 | 拦截范围 | 触发后行为 | 需求编号 | +| --- | --- | --- | --- | --- | +| 1 | **全局日成本熔断** | 平台总量 | **自动降级，不是仅告警** | `NFR-COST-02` | +| 2 | 场景级日预算 | 单个功能 | 该功能切轻量模型或暂停 | `NFR-COST-02` | +| 3 | 用户级配额 | 单个用户 | 服务端拒绝 | `FR-BILL-06` | + +**第 1 道是新增的，也是唯一真正封顶的一道**（原设计只有"预警"，见 §13.1 的更正）。实现要求： + +- **计数**：Redis 日累计成本键（`cost:daily:{yyyymmdd}`），由 LLM 网关与 GPU 任务在**成本产生后立即累加**，日切自动过期。落库对账以 `ob_ai_call` 为准，Redis 只做实时判定。 +- **分级降级顺序**（按"用户感知损失最小"排序，阈值百分比可配置）： + +| 日成本水位 | 动作 | 用户可感知的变化 | +| --- | --- | --- | +| 60% | 告警，不影响用户 | 无 | +| 80% | 停高清导出、停报告重新生成 | 两个低频次要功能不可用 | +| 90% | 停发型试戴；换装强制降画质 + 排队 | 次要生成能力不可用 | +| 100% | 仅保留**在途任务**与纯文本对话；新的生成类请求全部拒绝 | 「今日服务繁忙，请明天再试」 | + +- **在途任务必须放行**：成本已经付出，中断只会浪费掉且让用户白等。熔断只拦**新请求**。 +- **关键场景需显式豁免**：少数调用一旦失败会让整个链路无法继续（例如意图识别 —— 拿不到意图就无法路由， + 用户看到的是功能完全坏掉而不是降级）。这类场景在场景配置上标记为 `critical`，**不受熔断拒绝**， + 但仍照常计入日成本。豁免清单必须极短且逐个论证，否则熔断会被绕空。 +- **必须与配额解耦**：熔断拒绝的请求**不得扣减用户配额**（走 `refund` 流水，`FR-BILL-05`），否则用户会因平台原因损失额度。这是最容易写错的一处。 +- **必须可人工干预**：运营后台需有熔断状态查看与手动解除开关（`FR-ADM-*`），不能只能等日切。 --- @@ -876,7 +985,7 @@ get_memory_snapshot(user_id, budget_tokens) **必须能一键回答的三个问题**（这是可观测性的验收标准）： -1. 「某用户说他的报告生成失败了」→ 用 `user_id` 找到 task，看到失败在哪一步、错误码、是否已退点。 +1. 「某用户说他的报告生成失败了」→ 用 `user_id` 找到 task，看到失败在哪一步、错误码、**配额是否已退还**。 2. 「昨天成本涨了 3 倍」→ 按功能/模型分组的成本对比，定位到具体场景。 3. 「换装最近变慢了」→ 区分是排队变长（扩容）还是推理变慢（模型/资源）。 @@ -897,13 +1006,24 @@ meida/ │ ├─ matting/ # 抠图批处理 │ └─ tryon/ # 换装服务（改造纳管） ├─ packages/ -│ ├─ domain/ # 领域模型与业务规则（纯逻辑，无 IO，可纯单测） +│ ├─ domain/ # 领域模型与业务规则（纯逻辑，无 IO、无框架，可纯单测） +│ ├─ shared/ # 配置、日志、错误、DB、COS、可观测 │ ├─ llm/ # LLM 网关 +│ │ # ── 以下为 §4.1 的 11 个业务域，每域一个包 ── +│ ├─ identity/ # 账号与会话 +│ ├─ billing/ # 配额与计量 +│ ├─ task/ # 任务中心 +│ ├─ profile/ # 用户画像 +│ ├─ memory/ # 记忆系统 +│ ├─ kb/ # 知识库 │ ├─ retrieval/ # 混合检索 │ ├─ rules/ # 规则引擎 -│ ├─ memory/ # 记忆系统 -│ ├─ compliance/ # 审核 / 水印 / 元数据标识 -│ └─ shared/ # 配置、日志、错误、DB、COS、可观测 +│ ├─ report/ # 美学报告 +│ ├─ agent/ # 穿搭 Agent +│ ├─ tryon/ # 换装与发型编排 +│ ├─ wardrobe/ # 衣橱 +│ ├─ notify/ # 通知推送 +│ └─ compliance/ # 审核 / 水印 / 元数据标识 ├─ prompts/ # Prompt 模板（版本化，随代码走） ├─ migrations/ # Alembic ├─ tests/ @@ -915,6 +1035,20 @@ meida/ └─ client-harmony/ # 鸿蒙 ArkTS 工程 ``` +**包内约定**：每个业务域包统一为 `service.py`（用例编排，对外唯一入口）+ `repo.py`（该域自己的表访问） ++ 可选 `schemas.py`。§4.2 的「禁止直接查对方的表」因此落为一条可机检规则： +**跨域只允许 import 对方的 `service`，不允许 import 对方的 `repo`。** + +**三层的判别标准**（决定新代码该放哪一层）： + +| 层 | 判别标准 | 反例 | +| --- | --- | --- | +| `packages/domain` | 纯函数与不变量，**不 import 任何框架、不做 IO** | 把 SQLAlchemy 模型放进来 | +| `packages/<域>` | 该域的用例编排与自己的表访问 | 在 `agent/` 里直接读 `bl_quota` 表 | +| `apps/` | HTTP / Celery 的适配，**不含业务判断** | 在路由函数里写配额判定公式 | + +> 这三条边界由 import-linter 契约强制，不靠 code review。分层规则一旦只靠人守，第一次赶工就会破。 + ### 16.2 AI 辅助开发下的质量防线 既然主要由 AI 编码，人工 review 的带宽会成为瓶颈，因此**必须把规范变成机器可执行的检查**： @@ -1015,5 +1149,7 @@ meida/ | 日期 | 版本 | 变更 | | --- | --- | --- | +| 2026-08-13 | v1.3 | **脚手架落地后按实现回写，五处修正**。① **§16.1 仓库结构补全 11 个业务域包** —— 原树只列了 7 个 `packages/`，§4.1 定义的 11 个业务域在树里无处安放，实现时只能猜；现补全并加「包内约定」（每域 `service.py` + `repo.py`，跨域只许 import 对方 `service`）与三层判别标准表。② **§6.2 `ob_ai_call` 补 `prompt_id`/`prompt_version`/`tokens_reasoning`/`rate_tier` 四列** —— §8.1 要求 Prompt 版本化可复现，但表里没有版本列，等于要求做不到的事；思考 token 混进 `tokens_out` 会掩盖开关思考模式的成本差异。③ **§9.1 澄清基础路径** —— 正文写 `/api/v1`、任务描述写 `/v1`，实现两者都要能用；现明确 `/api/v1` 为规范写法、`/v1/*` 仅作兼容别名。④ **§13.2 新增峰谷计价约束** —— DeepSeek 自 8-17 起高峰单价翻倍且新价目输出侧涨 2.25~4.5 倍，成本须在调用当时算好落库（不可事后回算），§13.1 的预算与熔断阈值需按新价重算；Agent 单轮成本注明思考模式须显式关闭。⑤ **§13.3 补「关键场景显式豁免」** —— 意图识别这类调用失败会让链路整体不可用，须标记 `critical` 不受熔断拒绝，但仍计入成本；豁免清单必须极短，否则熔断被绕空 | +| 2026-08-13 | v1.2 | **文档一致性评审修订，其中三处是会直接卡住开发的实质缺陷**。① **§7.4 补齐 `billing` 域四张表的职责边界** —— `bl_quota` 与 `bl_wallet` 此前看起来像两套重复机制，`task_bonus` 的来源也没定义；现明确「V1 判定看 `bl_quota`、V2 判定看 `bl_wallet`、`bl_ledger` 两版都只是流水」，并把 `task_bonus` 物化为 `bl_quota.bonus_granted` 字段（避免每次判定聚合流水），补充三处最易写错的地方（熔断须在预扣之前、`used` 增减须与流水同事务、周期重置靠 `period_key` 而非定时清零）。② **§13 成本模型重写** —— 推翻「月度成本上限 = MAU × 单用户配额上限」这个错误论证（配额约束单用户，总成本 = MAU × 人均，MAU 无上限），改为「理论最坏 / 预期成本 / 真实封顶」三口径，并新增 **§13.3 四档熔断降级**（含在途任务放行、被熔断请求不得扣配额、可人工解除）。③ **§7.2 token 预算改为嵌套表**，合计 3700→**4200**（原表漏算会话近轮原文 400），并明确硬禁忌永不裁剪。另：`pf_memory.status`/`source`、`id_consent.consent_type` 枚举与用户系统对齐（`personalization` 不可省略，否则记忆写入无合规依据）；手机号存储位置明确为 `id_user_identity`；诊断维度 34→**32**；`points_reserved`→**`quota_reserved`**；外部依赖表补入腾讯云短信并说明登录双通道不得互相依赖；§12.2 说明 1 万 DAU 基线与 MAU 15 万目标的口径关系 | | 2026-08-13 | v1.1 | 按业务决策收口调整。**billing 域降级为「配额与计量」**：V1 移除支付、订单、会员、IAP；`bl_point_tx` 改名 `bl_ledger` 并新增 `tx_type` 字段，使 V1 配额账本与 V2 点数账本共用同一张表（V2 免数据迁移）；新增 `bl_quota_rule` 配额规则表。§7.4 拆为「V1 配额三段式」与「V2 IAP 支付」。§13 成本模型补充「V1 成本上限可事前算准」的公式，并强调 `ob_ai_call` 是 V2 定价的唯一数据来源、不允许后补。§19 风险登记：备案风险关闭，新增备案范围一致性、素材自采产能、顾问到岗三项风险 | | 2026-08-13 | v1.0 | 首次输出。确立「模块化单体 + 独立 AI 服务」架构、十个业务域数据模型、五条关键链路、统一合规出口、V1 单机 Docker Compose 部署与成本模型 | diff --git a/docs/技术选型与调研报告.md b/docs/技术选型与调研报告.md index bb45f02..aee60a3 100644 --- a/docs/技术选型与调研报告.md +++ b/docs/技术选型与调研报告.md @@ -1,6 +1,6 @@ # 技术选型与调研报告 -> 版本：v1.0　｜　调研截止日期：2026-08-13　｜　状态：已定稿（可执行） +> 版本：**v1.2**　｜　调研截止日期：2026-08-13　｜　状态：已定稿（可执行） > > 本文的作用是把散落在各需求文档中的「待确认事项」一次性收口。每一条都给出：**结论 → 理由 → 备选方案 → 触发切换的条件 → 信源**。 > @@ -17,7 +17,7 @@ | 前提 | 取值 | 对架构的影响 | | --- | --- | --- | -| 换装/发型服务归属 | **自有服务，源码可控，可改造** | 可以把它从「黑盒 HTTP 接口」升级为「受管控的内部推理服务」：加鉴权、改异步回调、独立扩容、埋成本点 | +| 换装/发型服务归属（**编号为 `TD-00`**） | **自有服务，源码可控，可改造** | 可以把它从「黑盒 HTTP 接口」升级为「受管控的内部推理服务」：加鉴权、改异步回调、独立扩容、埋成本点。改造要求见架构 §4.4，被 `FR-TRY-01` 等需求依赖 | | 团队规模 | 4~6 人（前端 + 后端 + 算法 + 产品/设计） | 不上微服务。V1 采用**模块化单体 + 独立 AI 能力服务**的两层结构 | | 后端技术栈 | **全 Python（FastAPI）** | 业务与 AI 同栈，模型侧代码可直接复用，无跨语言序列化成本 | | 云厂商 | **腾讯云为主** | 存储、审核、人脸能力优先用腾讯云；不足处允许跨云补齐（见 `TD-05`） | @@ -33,6 +33,7 @@ | 编号 | 议题 | 结论 | 状态 | | --- | --- | --- | --- | +| **TD-00** | **换装/发型服务的纳管改造** | 自有服务，源码可控；改造为受管控内部服务（鉴权 + 异步回调 + 成本埋点 + 独立扩容） | 已定，见 §0 与架构 §4.4 | | TD-01 | 客户端框架 | 鸿蒙原生 ArkTS + ArkUI（V1 单端） | 已定 | | TD-02 | 后端框架与运行时 | Python 3.12 + FastAPI + SQLAlchemy 2.0 + Pydantic v2 | 已定 | | TD-03 | 云基础设施 | 腾讯云：CVM + COS + CDN + PostgreSQL + Redis + CLS | 已定 | @@ -64,6 +65,8 @@ | TD-29 | 企业开发者资质 | V1 不依赖（不接 IAP）；一键登录降级为 P1 | 已定 | | TD-30 | 市场数据信源 | 已替换为国家统计局 / CNNIC / 华为 HDC 官方数据 | 已定 | | TD-31 | 五行/命理模块 | **不做**（V1 与 V2 均不纳入） | 已定 | +| **TD-32** | **短信验证码通道** | 腾讯云短信（SMS），与云厂商收口一致 | 已定，V1 必需 | +| **TD-33** | **天气数据源** | **V1 不接天气 API**，改为「用户告知 + 季节推断」降级 | 已定，V2 再评估 | --- @@ -324,7 +327,7 @@ **必须实现的能力**（这些是长耗时任务产品化的地基，不是可选项）： -- **幂等**：任务以业务幂等键（如 `tryon_task_id`）去重，重试不会重复扣点数、不会重复出图。 +- **幂等**：任务以业务幂等键（如 `tryon_task_id`）去重，重试不会重复扣减配额、不会重复出图。 - **状态机**：`pending → running → succeeded / failed / cancelled / timeout`，状态变更落库并可查询。 - **超时与重试**：区分可重试错误（网络、限流）与不可重试错误（输入非法、审核拒绝），后者立即失败并**退还点数**。 - **进度上报**：给前端可展示的阶段（排队中 / 分析中 / 生成中 / 后处理中）与预估剩余时间。 @@ -348,7 +351,11 @@ **理由**：需求文档里的漏斗指标（报告触发率、完成率、付费转化率）都是明确的、有限的、可预先定义的聚合，不需要即席探索能力。当指标需求变成「随时切任意维度」时再引入 ClickHouse。 -**必须从第一天就埋的事件**（漏斗断点一旦漏埋，数据就永远补不回来）：注册、授权同意、拍照上传、报告触发、报告完成、报告页各模块曝光与展开、分享、Agent 会话开始/轮次/满意度、换装发起/成功/失败、点数消耗、付费页曝光/下单/支付成功。 +**必须从第一天就埋的事件**（漏斗断点一旦漏埋，数据就永远补不回来）： + +**V1 必埋**：注册、授权同意、拍照上传、报告触发、报告完成、报告页各模块曝光与展开、**报告结论认同/修正**（`FR-RPT-19`）、分享、Agent 会话开始/轮次/满意度、换装发起/成功/失败、**配额消耗与退还**、**全面报告预约留资**（`FR-RPT-20`）、**会员页曝光与「上线提醒我」留资**（`FR-BILL-12`）、**熔断降级触发**。 + +**V2 才有（V1 无对应功能，不埋）**：付费页曝光、下单、支付成功、点数购买。 --- @@ -534,6 +541,56 @@ cos://meida-report/ # 报告产物：长图/PDF，含 AI 标识元数据 **实现取巧**：后台不做独立前端工程，用 FastAPI + 服务端渲染或现成 admin 方案，把工程量压到最小。前台体验投入优先给用户端。 +### TD-32　短信验证码通道：腾讯云短信 + +> 🆕 **本条是文档评审新发现的缺口**。`FR-ACC-04`（手机号验证码登录）是 **P0/V1 的登录兜底通道**，但此前 31 项技术决策中**没有短信服务商选型**，架构的外部依赖表、系统上下文图、成本模型里也都没有短信。这是"需求存在但无人认领"的典型，会在开发到登录模块时直接卡住。 + +**结论**：用**腾讯云短信（SMS）**。 + +**理由**： + +1. **与云厂商收口一致**（`TD-03`）。同账号、同 SDK 体系、同一套密钥管理与账单，不额外引入一家供应商的接入与对账成本。 +2. **短信是纯商品化能力**，各家在到达率与价格上差异很小，选型不值得花精力，跟随主云厂商是最省事的正确答案。 +3. 单条约 ¥0.03~0.045，V1 量级下**成本可忽略**，但仍需纳入成本模型以免被遗漏。 + +**为什么手机号通道不能省**（它不是"多一种登录方式"这么简单）： + +- **华为账号是唯一登录通道时，一旦华为侧授权异常或用户拒绝授权，用户直接无法进入产品**，没有任何兜底。 +- 一键登录已降级为 P1/V2（`TD-29`，需企业资质），因此 V1 的登录只有「华为账号授权」与「手机号验证码」两条，**后者是唯一的独立通道**。 + +**必须一并实现的防刷措施**（`NFR-SEC-05` 原文只提了"防刷"，未覆盖短信场景，已补）： + +| 措施 | 具体要求 | 不做的后果 | +| --- | --- | --- | +| 单号码频控 | 同一号码 60s 内 1 条、1 小时 ≤ 5 条、24 小时 ≤ 10 条 | 用户被短信轰炸，投诉与运营商处罚 | +| 单 IP / 设备频控 | 同 IP 24 小时 ≤ 20 条；同设备指纹 ≤ 10 条 | 被脚本批量刷，**短信费用是真金白银的直接损失** | +| 图形/行为验证 | 触发频控阈值后强制人机校验 | 同上 | +| 验证码本身 | 6 位数字，有效期 5 分钟，**校验失败 5 次即作废**，一次性使用 | 暴力枚举可撞开任意账号 | +| 号码脱敏 | 日志与后台一律掩码（`138****8888`），`phone_enc` 加密存储 | 违反 `NFR-SEC-03` | +| 发送量告警 | 日发送量环比突增告警 | 被刷时无人知晓，直到看账单 | + +**降级策略**：短信通道不可用时，**华为账号登录必须仍然可用**，登录页给出明确提示而非笼统报错。两条通道不得互相依赖。 + +### TD-33　天气数据源：V1 不接，改为降级方案 + +> 🆕 **本条同为评审新发现的缺口**。Agent 的意图类别含「天气适配」，典型场景直接演示了"明天 15 度有雨怎么穿"，知识库场景实体含温度带映射，L0 的城市字段用途还写着"天气定位"—— 但全部文档中**没有任何天气 API 的选型、来源与成本说明**。 + +**结论**：**V1 不接入天气 API**。Agent 遇到天气类问题时走以下降级路径： + +1. **优先让用户自己说**：「今天你那边大概多少度？下雨吗？」—— 一句反问即可拿到最准确的信息，用户成本极低。 +2. **按城市 + 日期做季节推断**：用 L0 的城市字段映射到气候区，结合当前月份推出温度带（如"上海 8 月 → 炎热潮湿"），给出季节性建议而不谎报具体天气。 +3. **绝不编造具体天气数值**。这是硬红线 —— 模型幻觉出一个"明天 18 度"会直接摧毁用户对整个产品专业性的信任，而这个错误用户第二天一定会发现。 + +**为什么 V1 不做**： + +1. **天气只是穿搭建议的一个输入变量，不是核心价值**。本产品的差异化在"基于你的体型与色彩的个性化建议"，不在天气预报，接入天气不改变竞争力。 +2. **投入产出比低**：要做对就得处理定位授权、城市映射、缓存策略、供应商配额与降级，是一条完整的工程链路；而"让用户说一句"这个降级方案的体验损失很小。 +3. **省掉一项定位权限**。为天气申请定位授权会拉高授权拒绝率，并增加隐私合规面（`CR-*`），代价明显超过收益。 + +**V2 再评估的触发条件**：若「知识缺口埋点」（`FR-AGT-11`）显示天气类 query 占比 **> 5%**，或主动推荐（`FR-AGT-18`）立项，则接入天气 API。届时优先考虑和主云厂商体系一致的方案，避免再增加一家供应商。 + +**必须同步修正的表述**：Agent 文档中「场景理解：理解场合/季节/**天气**/风格偏好」的 P0 描述已改为不含天气；L0 城市字段的用途改为「气候区推断与区域化内容」，不再写"天气定位"。 + --- ## 7. 业务决策收口（原「待业务输入」，2026-08-13 已全部关闭） @@ -558,7 +615,7 @@ cos://meida-report/ # 报告产物：长图/PDF，含 AI 标识元数据 **结论**：**全职**，而非外部按条计酬或顾问入股。 **理由**： -1. **规则库不是一次性交付物，而是需要持续迭代的资产**。800 条规则写完只是起点，之后要根据用户反馈与结论修正率反复校准。按条计酬的外部顾问在"交付完成"后就没有继续投入的动力，而这恰恰是质量提升最关键的阶段。 +1. **规则库不是一次性交付物，而是需要持续迭代的资产**。V1 的 400 条规则写完只是起点（长期目标 800~1200 条，见知识库 §9.1），之后要根据用户反馈与结论修正率反复校准。按条计酬的外部顾问在"交付完成"后就没有继续投入的动力，而这恰恰是质量提升最关键的阶段。 2. **顾问需要深度参与知识库后台的设计**。V1 就要做极简运营后台（`TD-25`），它的使用者就是顾问本人。全职顾问会天天用它，能持续反馈易用性问题；外部顾问只会在交付期短暂接触，很难提出有价值的改进。 3. **黄金评测集的标注需要口径一致**。100~200 例样本若由多位外部顾问分批标注，口径漂移几乎不可避免，而黄金集是所有质量指标的基准，一旦口径不稳，后续的准确率数字就失去意义。 @@ -707,5 +764,6 @@ cos://meida-report/ # 报告产物：长图/PDF，含 AI 标识元数据 | 日期 | 版本 | 变更 | | --- | --- | --- | +| 2026-08-13 | v1.2 | **文档一致性评审修订，补齐两个"需求存在但无人认领"的选型空洞**。**新增 `TD-32` 短信验证码通道**（腾讯云 SMS）—— `FR-ACC-04` 是 P0/V1 的登录兜底通道，但此前 31 项决策中没有短信选型，架构外部依赖表、系统上下文图、成本模型里也都没有它；一并给出六项防刷措施（短信是被刷时的直接现金损失，且没有配额兜底）与「两条登录通道不得互相依赖」的要求。**新增 `TD-33` 天气数据源** —— Agent 的意图类别含天气适配、典型场景直接演示温度降水，但全部文档没有天气 API 的来源与成本；结论是 **V1 不接**，改为「反问用户 + 城市月份推断气候区」，并立下硬红线**绝不编造具体天气数值**（模型幻觉出一个温度，用户第二天一定会发现）。**补 `TD-00` 定义** —— 换装/发型服务的纳管改造此前被 `FR-TRY-01` 与架构 §4.4 引用却从未编号定义。另：埋点清单拆分 V1 必埋与 V2 事件（V1 无支付，不应埋付费漏斗）；措辞「扣点数」→「扣减配额」；规则规模改为引用知识库 §9.1 | | 2026-08-13 | v1.1 | **业务决策全部收口，§7 由「待业务输入」改为「决策收口」**。六项结论：素材全部自采（`TD-26`）、顾问全职编制（`TD-27`）、V1 完全不收费改用配额限制（`TD-28`）、V1 不依赖企业开发者资质且一键登录降级 P1（`TD-29`）、市场数据替换为官方信源并纠正鸿蒙可触达口径（`TD-30`）、五行命理模块不做（`TD-31`）。另 `TD-19` 备案已办结，上线阻塞解除，转为持续义务。§8 冲突清单新增 5 条 | | 2026-08-13 | v1.0 | 首次输出。31 项技术决策收口，其中四项修正了既有文档的假设：客户端改鸿蒙原生 ArkTS（非 Uni-App-x）、人体关键点改自建 RTMPose（腾讯云接口已下线）、抠图改 BiRefNet（RMBG-2.0 非商用许可）、12 季色彩改自建色板（规避商标）。另有 6 项转入待业务输入 | diff --git a/docs/文档评审报告-2026-08-13.md b/docs/文档评审报告-2026-08-13.md new file mode 100644 index 0000000..3781a0c --- /dev/null +++ b/docs/文档评审报告-2026-08-13.md @@ -0,0 +1,230 @@ +# 「美搭」文档体系评审报告 + +> 评审日期：2026-08-13 ｜ 评审范围：`docs/` 目录全部 11 份文档（README + 10 份内容文档） +> 评审方法：逐份通读 + 跨文档事实交叉比对（数字、枚举、编号、状态）+ 按《开发任务拆解》§9.3 的要求做「需求 → 任务」反查 +> 本文性质：评审反馈，不修改任何被评文档；问题定位到文档与章节，供修订时对照 + +--- + +## 0. 总体结论 + +**这套文档体系的骨架是好的，可以进入评审流程；但有一批"数字口径"类的事实性冲突需要先修掉，否则评审会上会卡在事实核对而不是方案讨论上。** + +值得肯定的地方（这些做得比多数项目文档好，应保持）： + +- **四层结构与编号体系清晰**：FR/NFR/CR/TD/ADR/T/R 七套编号 + 「同一事实只在一处定义、其余引用编号」的纪律（README §4、§6），是这套文档能长期维护的前提。 +- **决策留痕完整**：每份文档有变更记录，技术选型报告 §8 有「与既有文档的冲突修正清单」，产品方案 §11 有已决策/待输入清单。本轮"备案完成、V1 不收费、素材自采"三个大转向在各文档间基本同步到位。 +- **验收标准可判定**：需求规格 §1.3 专门给出了"不可验收 vs 可验收"的对照写法，DoD（§1.4）把合规出口、配额三段式、埋点纳入完成定义。 +- **风险是真实践过的**：腾讯云人体关键点下线、RMBG-2.0 非商用许可、AI 标识元数据被 CDN 剥离，都是调研中实际撞出来的坑，文档如实记录并改了方案。 +- **对代理指标的诚实**：明确写出"预约 ≠ 付费"、V1 不收费意味着付费意愿无法被证伪（产品方案 §7.2.3、TD-28），没有自欺欺人。 + +但交叉比对发现：**v6.0/v1.1/v1.2 这轮大改版在"定性结论"上同步得很好，在"定量数字"上留下了不少残留矛盾**。下面按严重程度分三级列出。 + +--- + +## 1. P0：事实性冲突与错误（评审前必须修正） + +这类问题是"两个文档对同一事实给了不同答案"，不修正则下游（开发、测试、财务）必有一方做错。 + +### P0-1　V1 成本封顶的数字算不平（最重要的一条） + +**位置**：产品方案 §5.2.1、§5.3.1；技术架构 §13 + +- 产品方案 §5.3.1：「月度 AI 总成本（MAU 15 万口径）≤ **¥12 万/月**」，「单免费用户月度 AI 成本 ≤ **¥8**」，并声称「月度成本上限 = MAU × 单用户配额成本上限，**是可以事前算准的确定值**」。架构 §13 复述了同一口径。 +- 但 15 万 × ¥8 = **¥120 万**，与 ¥12 万相差 10 倍。两个数字不可能同时成立。 +- 再验算 ¥8 本身：按配额表基础额度（每日 3 次换装 ×¥0.5 + 3 次发型 ×¥0.2 + 10 轮对话 ×¥0.05 ≈ ¥2.6/日），若用户每日用满，月成本约 **¥78**；若按硬上限（8+6+40 次）算是 ¥246/月。¥8 只有在"月均活跃约 3 天"的使用率假设下才成立，但这个假设**没有写在任何文档里**。 +- 后果：这是 V1 唯一的财务锚点，且文档把它定性为"由配额硬性决定的确定上限"。按文中公式算出来的真硬上限（百万级/月）与文中给出的 ¥12 万相差两个数量级，**"成本可事前算准"这个论证目前不成立**。 + +**建议**：把两个口径分开写清楚——① 真·硬上限 = MAU × 配额硬上限 × 单次成本（数字会很大，但它才是"确定值"）；② 预期成本 = 硬上限 × 使用率假设（把活跃天数/功能渗透率的假设显式写出来，并标注为假设）。¥12 万和 ¥8 按口径②重新推导或修正。 + +### P0-2　诊断维度数：技术架构文档仍写 34 项 + +**位置**：技术架构 §6.2（`pf_diagnosis` 行注释「34 个诊断维度」）、§6.3（「34 个诊断维度用 JSONB 存储」） + +TD-31 已决定维度由 34 减为 **32**（删除五行分布、幸运色），美学报告 §4、需求规格 FR-RPT-06、README §0.1/§5、任务拆解 T-P0-25/T-P3-06 均已同步为 32，**只有技术架构文档两处遗漏**。这是"本轮决策同步"的明确漏网之鱼。 + +### P0-3　性能指标至少四处互相矛盾 + +同一指标在不同文档给出不同数值，且需求规格 §4.1 并未被其他文档遵守为单一事实源： + +| 指标 | 需求规格 §4.1 / 架构 §12.1 | 产品方案 §8.3.1 | 模块文档 | 冲突 | +| --- | --- | --- | --- | --- | +| 初级报告 P95 | **< 90s**（NFR-PERF-03） | **< 60s** | 美学报告 §10.2：< 60s | 90 vs 60 | +| 全面报告 P95 | **< 180s**（NFR-PERF-04） | **< 5min（300s）** | 美学报告 §10.2：≤ 5min | 180 vs 300 | +| 换装出图 P95 | **< 40s**（NFR-PERF-05，不含排队） | **< 320s** | 产品方案 §2.1.1：前端超时 ≥ 320s | 40 vs 320 | +| Agent 整轮 P95 | **< 8s**（NFR-PERF-02） | — | 穿搭 Agent §7.1/§8.3：**< 15s** | 8 vs 15 | +| 系统可用性 | ≥ 99.5%（NFR-REL-01、架构 §12.1） | **> 99.9%** | — | 停机预算差 5 倍 | + +换装一条特别需要说明：40s 与 320s 可能分别是"改造后目标"与"当前接口现实"，但没有任何文档写明这层关系，FR-TRY-01 的验收标准（p95 < 40s）按现有接口实测很可能直接不达标。 + +**建议**：性能指标只保留需求规格 §4.1 一处定义，其余文档改为引用；换装/发型补充"现状基线（T-P0-13/14 实测）→ 目标值"的两段式表述。 + +### P0-4　记忆注入的 token 预算有两套互相矛盾的口径 + +**位置**：产品方案 §2.4.2、用户系统 §3.8、穿搭 Agent §3.5.2 vs 需求规格 FR-MEM-04、架构 §7.2、穿搭 Agent §10.2、任务拆解 T-P3-17 + +- 口径 A（≤1400）：画像 ≤250 + 偏好 ≤150 + 事件召回 ≤200 + 会话 ≤800（产品方案、用户系统、Agent §3.5.2 一致）。 +- 口径 B：架构 §7.2 与 Agent §10.2 的预算表为「画像摘要 ≤500、会话摘要 ≤400」（总输入 ≤3700 的分解）；FR-MEM-04 验收标准写「注入 token ≤ 500」，T-P3-17 照抄。 +- 直接冲突点：**会话摘要 800 vs 400**；**记忆注入合计 1400 vs 500**。验收标准（FR-MEM-04）与需求原文（用户系统 §3.8）不一致，测试不知道该按哪个写。 + +**建议**：在架构 §7.2 定义唯一的预算分解（建议明确"记忆注入预算"与"总输入预算 3700"的包含关系），FR-MEM-04 与其余文档全部引用该处。 + +### P0-5　人脸原图保留期：2 小时 vs 24 小时 + +**位置**：合规方案 §2.1.2/§4.1、CR-02、架构 §7.1/§11.2、任务拆解 T-P1-27 = **≤ 2 小时**；产品方案 §7.1.3、美学报告 §9.1 = **≤ 24h 仅用于任务重试** + +这是合规红线参数，两套说法直接冲突。"24h 用于任务重试"与"处理后显式删除、桶级 2 小时兜底"是两种不同的设计（前者意味着原图要留存到任务结束）。按"下层优先"原则应以合规方案/CR-02 的 2 小时为准，修正产品方案与美学报告；若确实需要重试窗口，则合规方案要补充论证。 + +### P0-6　配额流水类型：两处写"两种"，两处写"三种" + +**位置**：需求规格 §2.9 架构约束、产品方案 §3.3 = V1 只用 `system_grant` + `consume` **两种**；用户系统 §2.4.2、架构 §6.2 = `system_grant` / `consume` / `refund` **三种** + +`refund` 是预扣三段式（FR-BILL-05）的必需类型，需求规格与产品方案的表述属于漏写。按"表结构真相在架构"的原则，应以三种为准，修正需求规格 §2.9 与产品方案 §3.3。 + +### P0-7　美学报告文档内的价格残留（与同节注释自相矛盾） + +**位置**：美学报告 §2.5、§2.1 + +- §2.5 正文 bullet 仍写「预览卡片（模糊化目录截图 + 内容清单 + **预计价格**）」、埋点记录含「**点击价格档位**」；紧随其后的 ⚠️ 注释明确说这两项"已移除"。同一节内自相矛盾。 +- §2.1 分级总览表「价格」行仍写全面报告「**单次 ¥29.9**」，与 §2.5「全部为占位草案，待定」及"V1 全线不出现价格"的纪律（FR-BILL-07、TD-28）冲突。 + +**建议**：删除 §2.5 正文中的「预计价格」「点击价格档位」，§2.1 的 ¥29.9 改为"待定（V2 按真实数据定价）"。 + +### P0-8　全面报告"40+ 项维度"与 32 项维度字典矛盾 + +**位置**：产品方案 §2.2.1（「8 项核心 / **40+ 项完整**」）、美学报告 §2.1（同）vs 美学报告 §4 维度字典（**共 32 项**）、README §5 + +字典总共 32 项，全面报告不可能覆盖 40+ 项。这是五行模块移除（34→32）之前就遗留的旧口径。另外"初级 8 项核心"与字典中初级打 ✅ 的维度数（约 15 项）也对不上——建议把分级表改为"初级覆盖 X 项 / 全面覆盖全部 32 项"的准确口径，或明确"8 项"指的是首屏核心展示数。 + +### P0-9　语音输入在穿搭 Agent 文档中被列为 P0 + +**位置**：穿搭 Agent §2.2（P0 能力范围含「文字对话（**语音输入转文字**）」）、§2.1（能力总览「文字/语音多模态输入」标 P0） + +FR-AGT-17 与 TD-14 均明确语音输入为 **P1 / V2**（Core Speech Kit），本文 §9.1/§9.2 的阶段划分也把语音放在 Phase 2。§2.2 属于改版残留，与需求规格直接冲突。 + +### P0-10　画像/记忆/同意的数据结构与规则在架构与用户系统间不一致 + +**位置**：技术架构 §6.2、§8.4 vs 用户系统 §2.2、§3.3、§3.5 + +| 项 | 架构文档 | 用户系统文档 | +| --- | --- | --- | +| `pf_memory.status` 枚举 | active / pending_confirm / **archived / rejected** | active / pending_confirm / **decayed / overridden / deleted** | +| `pf_memory.source` 枚举 | explicit / implicit / report / behavior | explicit_user_input / user_setting / report_vision / self_reported / behavior_inferred / llm_extracted | +| 显式陈述初始置信度 | **0.95**（§8.4） | **0.90**（§3.5；产品方案 §2.4.2 同为 0.9） | +| 同意类型枚举 | terms / privacy / face / **minor** | 隐私政策 / 人脸 / **个性化推荐 / 推送通知** | +| 手机号存储 | `id_user` 字段清单中**无 phone**，`id_user_identity` 仅示例 huawei | 用户主表含 `phone`（加密存储） | + +其中同意类型枚举的偏差有合规后果：用户系统 §3.10 要求记忆写入建立在「个性化推荐」授权之上，但架构的 `id_consent` 枚举里没有这一项。建议以用户系统文档的语义为准修订架构 §6.2，并补齐手机号的存储位置说明。 + +### P0-11　准确率门槛两套数值 + +**位置**：FR-RPT-05 与 T-P0-10/11（体型 ≥80%、季型 ≥75%）vs 美学报告 §9.4、产品方案 §8.3.3（体型 ≥85%、季型 ≥80%）；FR-AGT-02（意图识别 ≥85%）vs 穿搭 Agent §8.2（>90%） + +可能是"Phase 0 验证门槛"与"上线质量门槛"的区分，但没有任何文档写明这层关系。建议显式标注两档（如：验证门槛 80/75，上线门槛 85/80），否则 Phase 0 验收与上线验收会打架。 + +--- + +## 2. P1：覆盖缺口（需求 → 任务反查发现） + +按任务拆解 §9.3 的要求做了 P0/CR 需求反查，以下缺口会直接影响执行： + +### P1-1　手机号验证码登录：无开发任务、无短信通道选型（最实际的缺口） + +- FR-ACC-04 是 P0/V1（登录兜底通道），但任务拆解 Phase 1 §3.2（T-P1-11~18）**只有华为账号登录任务，没有手机号验证码任务**。 +- 更大范围看：技术选型 31 项决策中**没有短信服务商选型**；架构 §2 外部依赖表与系统上下文图均无短信通道；成本模型 §13 未计短信成本；NFR-SEC-05 防刷未提短信轰炸防护。 +- 建议：补一项短信通道选型决策（TD-32）+ 一个开发任务（验证码下发、校验、限频、防刷），并在外部依赖表中登记降级策略。 + +### P1-2　全面报告「预约留资」入口无 WBS 任务 + +产品方案 §2.2.3 与 §6.1.2 均要求 V1 做「全面报告预约入口 + 埋点」，**这是 V1 唯一的商业化验证指标（预约率 ≥8% 决策门槛）的数据来源**；FR-RPT-15 验收标准也含"V1 仅做预约留资"。但任务拆解 Phase 3（T-P3-01~20）没有对应任务。漏掉它，V1 上线后连"要不要做付费报告"都回答不了。 + +### P1-3　会员页静态展示 + 「上线提醒我」留资：无 FR、无任务 + +产品方案 §2.8（🅿️ 区）与 §3.4 均要求 V1 交付，但需求规格中无对应 FR 编号，WBS 无任务。建议补 FR-BILL-xx（或 FR-ACC-07 扩展）与 Phase 5 任务。 + +### P1-4　报告结论的反馈与修正入口无 FR + +产品方案 §8.1.2/§8.1.4 的核心质量指标——**报告结论认同率 >70%、结论修正率 <15%**——依赖"用户主动确认/修正"的采集入口（美学报告 §7.2「不准？修正一下」、§9.4 反馈入口）。需求规格中没有对应 FR（FR-RPT-10 的验收不含此项），WBS 中 T-P4-11 只覆盖 Agent 反馈。指标没有数据来源就等于没有指标。 + +### P1-5　游客配额未进入配额表，FR-ACC-02 验收不可判定 + +游客额度（1 次换装 / 1 次试戴 / 1 次报告 / 3 次对话）只出现在产品方案 §2.4.1 与用户系统 §2.1 的叙述中，**没有进入配额表**（产品方案 §3.2 / 用户系统 §2.4.1 均只有注册用户行），违反自定的"单一事实来源"纪律。同时 FR-ACC-02 的验收标准「体验流程中被允许的部分」不可判定，建议把游客额度补入配额表并在 FR-ACC-02 引用。 + +### P1-6　天气数据源完全未选型 + +Agent 的意图类别含「天气适配」（穿搭 Agent §3.2）、典型场景 §4.4 直接演示"明天 15 度有雨怎么穿"、知识库场景实体含温度带映射（§3.2 ⑥）、L0 城市字段的用途写明"天气定位"——但全部文档中**没有天气 API 的来源、选型与成本说明**。V1 的 Agent 要回答天气类问题就需要它。建议补一项选型决策（或明确 V1 天气问题降级为"让用户告知天气"）。 + +### P1-7　「清空照片」入口无 FR + +用户系统 §2.6 与产品方案 §2.4.1 均承诺"清空照片"作为账号生命周期能力，需求规格无对应 FR（FR-ACC-09 注销、FR-ACC-10 导出之外缺少"清空照片"），合规检查清单 §5.3 也未覆盖。涉及人脸数据删除，建议补 FR 并纳入合规清单。 + +### P1-8　配额模型中 `bl_quota` 与 `bl_wallet`/`bl_ledger` 的关系未说清 + +架构 §6.2 同时存在周期配额表（`bl_quota` + `bl_quota_rule`）与余额账本（`bl_wallet` + `bl_ledger`），§7.4 校验公式为 `bl_quota.used < limit_value + task_bonus`——但 `task_bonus` 从哪里来（是 `bl_ledger` 中 system_grant 的周期聚合？）、`bl_wallet.balance` 在 V1 纯配额模式下代表什么，没有定义。两套机制并存但职责边界模糊，开发时会卡住。建议在架构 §7.4 补一段"V1 配额判定数据流"的明确说明。 + +### P1-9　两个编号/归属问题 + +- **TD-00 被引用但从未定义**：需求规格 FR-TRY-01 依赖列写「TD-00 改造」、架构 §4.4 写「（TD-00 前提）」，但技术选型报告的决策总表从 TD-01 开始。§0「已确认的项目前提」中的"换装/发型服务自有可控"应编号化为 TD-00。 +- **CR-11 日志留存 ≥6 个月**无明确落地任务（T-P1-08 只含日志脱敏，CLS 留存周期配置无人认领），建议在 T-P1-04 或 T-P1-08 的验收标准中补上。 + +--- + +## 3. P2：一致性与维护性问题（不阻塞评审，但应一并修） + +| # | 问题 | 位置 | 说明 | +| --- | --- | --- | --- | +| P2-1 | **五份文档头部版本号滞留 v1.0** | 需求规格、技术架构、技术选型、合规方案、任务拆解的页首 | 五份文档的变更记录均已升至 v1.1，README §8 也按 v1.1 引用，但页首仍写 v1.0。本轮新增的五份文档全部中招，建议统一刷新 | +| P2-2 | README §8 遗漏一份文档 | README §8「九份文档全部更新」 | 内容文档实为 **10 份**，表格 9 行漏了《穿搭 Agent-需求文档》（当天同样更新至 v1.2） | +| P2-3 | 文档状态口径不一 | README §7 vs 各文档页首/页尾 | README 写「产品需求已定稿」，但产品方案、美学报告、用户系统、知识库、Agent 五份文档自身状态均为「待评审」 | +| P2-4 | "点数/扣点/计费"措辞残留 | 合规 §2.4.1（"不消耗点数/退点"）、架构 `tk_task.points_reserved` 字段名、架构 §7.1（"不重复扣点"）、FR-TASK-05、TD-11、产品方案 §2.7（"不重复计费"）、TD-23 埋点清单含"点数消耗/付费页曝光/下单/支付成功" | V1 已统一为"配额"语义，这些 V2 词汇残留会造成实现期误解；TD-23 的 V2 事件建议标注版本 | +| P2-5 | 枚举计数错误 | 知识库 §3.1 ⑤「8 脸型映射」vs 详情与美学报告 §4 均为 **7 种脸型**；§3.2 ④「局部特征 12 项」实际列了 **13 项** | 小数字错误，但这类错误多了会损害文档可信度 | +| P2-6 | 知识库规模口径需单一事实源 | 单品：知识库 §3.1「冷启动 800~1500」、§9「长期 800 / V1 硬指标 300」、产品方案 §2.5.2「800 条（≥400 可试穿）」、§2.8「300 件」；规则：知识库 §3.1「800~1200」、§9 表「第一版 800」、§9 文末分期「V1 400」、产品方案 §2.5.2「800」、§2.8「400」 | 产品方案 §2.5.2 的"第一版目标量级"列与 §2.8 直接矛盾；知识库 §9 表格与其自己的分期建议矛盾。建议统一为：V1 = 规则 400 / 单品 300 tryon_ready / 方案 100，长期目标另列 | +| P2-7 | 黄金集规模口径需分列 | 知识库 §7「200 条」、美学报告 §9.4「100 例」、FR-KB-11「≥100」、FR-AGT-05「100 例」、FR-RPT-07「30 例」、产品方案 §6.1.2「200 条」、知识库 §5.1.1「100~200 例」 | 各数字可能对应不同子集（检索/规则/Agent/报告），但没有一处说清。建议在 FR-KB-11 或知识库 §7 定义各子集规模，其余引用 | +| P2-8 | 若干净期承诺与"按产能倒排"原则冲突 | 产品方案 §4.3.3「1-2 个月上线 MVP」、§6.1 标题「Phase 1：MVP（1-2 个月）」、§9.3「1 个月内…正式上线」 | 本轮已把排期原则改为"不按人日估算、按实测产能倒排"（知识库 §5.1 还专门删了"3~4 周"估算），这几处时间盒是改版前残留，建议改为以里程碑出口条件表述 | +| P2-9 | 其他小项 | ① 架构 §12.2 容量基线 1 万 DAU < 产品方案 §8.1.1 目标档 DAU 2 万，建议对齐或说明假设；② 穿搭 Agent §7.1「1000+ 并发对话」相对容量基线缺乏依据；③ FR-TASK-04「推送到达率 ≥90%」未定义分母（全体用户还是已授权用户，TD-17 指出通知授权默认关闭）；④ 产品方案 §9.1.4 仍列「市场数据信源补齐」待办、§10.4.1 仍挂三条"待确认"行业报告，与 §4.1 已完成信源替换矛盾；⑤ 美学报告 §2.1「首次不限」与配额表「首次 1 次（终身）」措辞歧义；⑥ README §0.3「其余 20 项决策」与产品方案 §11.1 实际 21 行；⑦ 任务拆解 §1 依赖图中 M4 编号同时指"换装/发型"与"Agent 对话"两块，易误读；⑧ 需求规格 §1.3 示例（p95 < 90s）与产品方案 §2.2.1（≤60s）矛盾，同 P0-3 | — | + +--- + +## 4. 修订建议与处理顺序 + +**第一优先（评审会前）**：P0-1（成本口径）与 P0-3（性能指标）。这两条会被任何认真读文档的人第一时间发现，且都涉及"哪个文档是单一事实源"的问题——正好借修订把纪律落实： + +| 事实 | 建议的唯一定义位置 | 其余文档 | +| --- | --- | --- | +| 性能指标 | 需求规格 §4.1 | 产品方案 §8.3.1、各模块文档改为引用 | +| 配额数值（含游客） | 产品方案 §3.2 | 用户系统 §2.4.1 引用 | +| Token 预算 | 架构 §7.2 | FR-MEM-04、Agent §3.5.2/§10.2、用户系统 §3.8 引用 | +| 诊断维度数与字典 | 美学报告 §4 | 架构 §6.2/§6.3、README §5 引用 | +| 知识库规模目标 | 知识库 §9 | 产品方案 §2.5.2/§2.8 引用 | +| 黄金集规模 | 知识库 §7 或 FR-KB-11 | 其余引用 | +| 准确率门槛 | 美学报告 §9.4（区分验证档/上线档） | FR-RPT-05、产品方案 §8.3.3 引用 | +| 人脸原图保留期 | 合规方案 §2.1.2 / CR-02 | 产品方案 §7.1.3、美学报告 §9.1 引用 | + +**第二优先（进入开发前）**：P1-1（短信通道）、P1-2（预约留资任务）、P1-8（配额数据流）。这三项会直接卡住开发或让 V1 失去关键数据。 + +**第三优先（随下一轮文档更新）**：P0 其余项与全部 P2。建议按 README §6 的变更留痕规范逐份修订并登记。 + +**流程建议**：把"数字一致性走查"加入文档评审 checklist——本轮的问题高度集中在数字（维度数、预算数、成本数、性能数、规模数），人工通读很难避免，建议在每次大改版后专门做一次"同一数字全局搜索"（如搜 `34`、`500`、`1400`、`90s`、`300`）。 + +--- + +## 5. 附：评审覆盖清单 + +| 文档 | 版本（自称） | 实际应为 | 主要问题分布 | +| --- | --- | --- | --- | +| README | — | — | P2-2、P2-3、P2-8⑥ | +| 产品方案 | v6.0 | v6.0 ✓ | P0-1、P0-3、P0-4、P0-5、P0-6、P0-8、P2-4、P2-6、P2-8、P2-9 | +| 需求规格说明 | v1.0（页首滞留） | v1.1 | P0-3、P0-4、P0-6、P0-11、P1-1~P1-7、P2-1 | +| 美学报告-需求文档 | v1.2 | v1.2 ✓ | P0-5、P0-7、P0-8、P0-11、P2-9⑤ | +| 穿搭Agent-需求文档 | v1.2 | v1.2 ✓ | P0-3、P0-4、P0-9、P0-11、P2-9② | +| 用户系统与记忆系统-需求文档 | v1.2 | v1.2 ✓ | P0-4、P0-6、P0-10（作为正确口径基准） | +| 美学知识库-建设方案 | v1.2 | v1.2 ✓ | P2-5、P2-6、P2-7 | +| 技术架构文档 | v1.0（页首滞留） | v1.1 | P0-1、P0-2、P0-3、P0-4、P0-10、P1-8、P1-9、P2-1、P2-4、P2-9① | +| 技术选型与调研报告 | v1.0（页首滞留） | v1.1 | P1-1（缺短信选型）、P1-6（缺天气选型）、P1-9（TD-00）、P2-1、P2-4 | +| 合规与安全方案 | v1.0（页首滞留） | v1.1 | P0-5（作为正确口径基准）、P2-1、P2-4 | +| 开发任务拆解 | v1.0（页首滞留） | v1.1 | P1-1、P1-2、P1-3、P1-4、P1-9、P2-1、P2-9⑦ | + +--- + +**评审人**：AI 辅助评审 +**说明**：本报告仅基于文档文本的交叉比对，未验证文档与真实世界的一致性（如备案材料内容、接口实际表现）。P0-1 涉及的成本推算过程已在 §1 中给出算式，修订时可直接复算。 diff --git a/docs/用户系统与记忆系统-需求文档.md b/docs/用户系统与记忆系统-需求文档.md index 8a33630..1f5680b 100644 --- a/docs/用户系统与记忆系统-需求文档.md +++ b/docs/用户系统与记忆系统-需求文档.md @@ -113,19 +113,11 @@ **V1 的解法：完全不收费，用配额限制控成本**（`TD-28`）。 -#### 2.4.1 V1 配额表（唯一生效的一张表） +#### 2.4.1 V1 配额表 -所有用户共用同一套配额，无会员、无点数购买。 +> 🔗 **配额数值的唯一定义位置是《产品方案》§3.2**（含**游客额度**一列）。本节不再复述数值，避免出现第二套口径。此前游客额度只写在 §2.1 的叙述里、没进配额表，导致 `FR-ACC-02` 的验收标准无法判定 —— 已在产品方案 §3.2 补入。 -| 能力 | 基础额度 | 任务可额外获得 | 硬上限（防刷） | -|------|---------|--------------|--------------| -| 初级美学报告（首次） | 1 次（终身） | — | — | -| 报告重新生成 | 每 30 天 1 次 | +1 次/月 | 每日 ≤ 2 | -| 换装试穿 | 每日 3 次 | +3 次/日 | 每日 ≤ 8 | -| 发型 / 发色试戴 | 每日 3 次 | +2 次/日 | 每日 ≤ 6 | -| AI 对话 | 每日 10 轮 | +10 轮/日 | 每日 ≤ 40 | -| 记忆条数 | 200 条 | — | — | -| 高清导出 | 每日 1 次 | — | 每日 ≤ 3 | +所有注册用户共用同一套配额，无会员、无点数购买；游客另有一套**设备维度的终身额度**（不是每日额度）。 **任务奖励额度**（全部不涉及金钱）：每日签到、完善画像资料、给报告结论打反馈、邀请好友、分享报告长图。 @@ -319,13 +311,17 @@ **Token 预算是硬约束**，不能把全部记忆塞进提示词。策略： -| 阶段 | 处理 | 预算 | -|------|------|------| -| 画像摘要 | L0 + L1 压缩为固定结构短文本（模板化，非 LLM 生成） | ≤ 250 token | -| 偏好摘要 | L2 中 `confidence ≥ 0.5` 的项，按置信度排序取 Top 15 | ≤ 150 token | -| 事件召回 | 按当前 query 向量检索 L3，取 Top 3~5 条摘要 | ≤ 200 token | -| 会话上下文 | L4 最近 6 轮原文 + 更早轮次的滚动摘要 | ≤ 800 token | -| **合计** | — | **≤ 1400 token** | +> 🔗 **本表的分项已被采纳为全局唯一事实源**，完整预算表（含系统提示词、检索知识、用户输入与总输入合计 ≤ 4200）见《技术架构文档》§7.2。本表只管「记忆注入」这一段。 + +| 阶段 | 处理 | 预算 | V1 是否启用 | +|------|------|------|-----------| +| 画像摘要 | L0 + L1 压缩为固定结构短文本（模板化，非 LLM 生成） | ≤ 250 token | ✅ | +| 偏好摘要 | L2 中 `confidence ≥ 0.5` 的项，按置信度排序取 Top 15 | ≤ 150 token | ✅ | +| 事件召回 | 按当前 query 向量检索 L3，取 Top 3~5 条摘要 | ≤ 200 token | ❌ V2 | +| 会话上下文 | L4 最近 6 轮原文（≤ 400）+ 更早轮次的滚动摘要（≤ 400） | ≤ 800 token | ✅ | +| **记忆注入合计** | — | **≤ 1400 token**（**V1 实际 ≤ 1200**） | — | + +**裁剪时硬禁忌永不丢弃**（`FR-MEM-04`）—— 裁掉它会导致推荐用户明确拒绝的品类，属 P0 缺陷。完整裁剪优先级见架构 §7.2。 画像摘要示例（注入 Agent 系统提示的实际形态）： @@ -471,6 +467,11 @@ **作者**：产品团队 **状态**：待评审 **变更说明**： +- v1.2 rev.2（2026-08-13）：文档一致性评审修订 + - **§3.8 的记忆注入分项预算被采纳为全局唯一事实源**。评审发现架构 §7.2 与本节存在两套口径（会话 400 vs 800、合计 3700 vs 1400），**错在架构表** —— 本节的 800 是「最近 6 轮原文 + 更早轮次滚动摘要」，架构表只算了滚动摘要、漏掉近轮原文。故以本节分项为准，架构侧总输入合计由 3700 修正为 **4200**；`FR-MEM-04` 的「≤ 500」为误写，已改为 ≤ 1400（V1 实际 ≤ 1200，L3 为 V2 能力） + - **§2.4.1 配额数值改为引用产品方案 §3.2**，不再复述。同时**游客额度已补入产品方案 §3.2 的配额表**（此前只写在本文 §2.1 的叙述里，导致 `FR-ACC-02` 的验收标准无法判定），并明确它是**设备维度的终身额度而非每日额度** + - **§3.3 / §3.5 的记忆枚举与置信度初值被采纳为唯一事实源**：架构原写的 `status`=archived/rejected、`source`=explicit/implicit/report/behavior 无法承载衰减与冲突消解语义（`decayed` 可恢复、`overridden` 不可恢复必须区分），已按本文修订；显式陈述置信度以本文的 **0.90** 为准（架构原写 0.95） + - `id_consent` 的同意类型补入 **`personalization`（个性化推荐）** —— 本文 §3.10 要求记忆写入建立在该项授权之上，而架构枚举里原先没有这一项，属**有合规后果**的遗漏 - v1.2（2026-08-13）：业务决策收口，§6 已无 V1 遗留待确认项 - **§2.4 重构为「V1 只有配额，没有付费」**（`TD-28`）：拆为「§2.4.1 V1 配额表（唯一生效）」与「§2.4.2 V2 权益规划（仅架构预留）」。给出 V1 配额与任务奖励额度的具体数值，以及三条纪律（服务端硬限制、文案不出现价格字样、禁止静默扣减）。说明配额账本与点数账本共用同一张表，V2 上支付免数据迁移 - **§2.1 登录方式调整**（`TD-29`）：一键登录由 P0 降为 **P1 并推至 V2**（需企业资质，属体验优化非能力缺口）；V1 用「华为账号授权登录 + 手机号验证码」双通道。强调证书指纹双套配置漏配时"调试包正常、发布包失败"的表现 diff --git a/docs/穿搭Agent-需求文档.md b/docs/穿搭Agent-需求文档.md index 3783c9d..3857537 100644 --- a/docs/穿搭Agent-需求文档.md +++ b/docs/穿搭Agent-需求文档.md @@ -27,31 +27,42 @@ ### 2.1 能力总览 -| 能力模块 | 描述 | 优先级 | -|---------|------|--------| -| 自然语言对话 | 文字/语音多模态输入，流式回复 | P0 | -| 意图识别 | 识别用户穿搭意图（咨询/搭配/风格/场景） | P0 | -| 场景理解 | 理解场合/季节/天气/风格偏好 | P0 | -| 知识检索 | 基于美学知识库给出专业建议 | P0 | -| 个性化推荐 | 基于用户画像和历史偏好推荐 | P1 | -| 能力联动 | 调用换装/换发型能力生成预览 | P1 | -| 上下文记忆 | 多轮对话状态跟踪 | P1 | -| 多模态输入 | 图片输入（穿搭照片/单品图） | P2 | +> 🔗 优先级与版本归属的**唯一事实源是《需求规格说明》§2.4**（`FR-AGT-01`~`18`）。本表与之对齐。 -### 2.2 第一版（P0）能力范围 -- 文字对话（语音输入转文字） +| 能力模块 | 描述 | 优先级 | 版本 | 编号 | +|---------|------|--------|------|------| +| 自然语言对话 | **文字输入**，流式回复 | P0 | V1 | `FR-AGT-01` | +| 意图识别 | 识别用户穿搭意图（咨询/搭配/风格/场景/越界） | P0 | V1 | `FR-AGT-02` | +| 场景理解 | 理解场合/季节/风格偏好 | P0 | V1 | `FR-AGT-02` | +| 知识检索 | 基于美学知识库给出专业建议 | P0 | V1 | `FR-AGT-04` | +| 个性化（画像注入） | 读取 L1 画像与 L2 禁忌作为硬约束 | **P0** | **V1** | `FR-AGT-03` | +| 上下文记忆 | 多轮会话滚动摘要 | **P0** | **V1** | `FR-AGT-09` | +| **语音输入** | 语音转文字（鸿蒙 Core Speech Kit） | **P1** | **V2** | `FR-AGT-17` | +| 能力联动 | 调用换装/换发型能力生成预览 | P1 | V2 | `FR-AGT-14/15` | +| 「为什么推荐」解释链 | 追溯到知识库路径与规则 ID | P1 | V2 | `FR-AGT-13` | +| 多模态输入 | 图片输入（穿搭照片/单品图） | P1 | V2 | `FR-AGT-16` | +| 主动推荐 | 天气/日程驱动 | P2 | V3 | `FR-AGT-18` | + +### 2.2 第一版（V1 / P0）能力范围 + +- **文字对话**（**不含语音** —— 语音是 `FR-AGT-17`，P1/V2，见 §9.2 阶段划分） - 穿搭咨询与建议 - 场景化搭配方案 - 基础知识问答（色彩/版型/风格） -- 单轮 + 简单多轮对话 +- 单轮 + 多轮对话（含会话滚动摘要） - **画像注入**：读取美学报告产出的 L1 画像与 L2 禁忌，作为回答的硬约束 - **知识库混合检索**：规则前置 + 向量召回（见 §3.4.2），保证不给出违反美学规则与用户禁忌的建议 +- **越界拒答**：医疗、身材贬损、他人评价三类 +- **输入输出双向审核**（fail-close） + +> ⚠️ **本节原将「语音输入转文字」列为 P0，属改版残留，已更正**。语音依赖鸿蒙 Core Speech Kit（`TD-14`），定为 P1/V2。 ### 2.3 后续版本（P1/P2）能力规划 +- **语音输入**（`FR-AGT-17`） - 图片输入理解（评价用户穿搭照片） - 联动换装/换发型预览 -- 深度个性化（用户画像学习） -- 长期上下文记忆 +- 深度个性化（隐式行为推断） +- 长期事件记忆（L3 向量召回） - 主动推荐（基于天气/日程） --- @@ -61,10 +72,10 @@ ### 3.1 对话交互 #### 3.1.1 输入方式 -- **文字输入**：支持中文自然语言，单条消息 ≤ 500 字 -- **语音输入**：语音转文字（鸿蒙系统语音能力或第三方 ASR） -- **快捷入口**：预设常见问题快捷按钮 -- **图片输入**（P2）：支持上传穿搭照片/单品图 +- **文字输入**（P0/V1）：支持中文自然语言，单条消息 ≤ 500 字 +- **快捷入口**（P0/V1）：预设常见问题快捷按钮 +- **语音输入**（**P1/V2**，`FR-AGT-17`）：语音转文字，用鸿蒙 Core Speech Kit（`TD-14`）；识别失败可切文字 +- **图片输入**（P1/V2，`FR-AGT-16`）：支持上传穿搭照片/单品图 #### 3.1.2 输出方式 - **流式文字回复**：逐字输出，提升体验 @@ -90,7 +101,7 @@ Agent 需识别以下用户意图类别： | **风格建议** | "我想走法式优雅风格""适合微胖女生的风格" | 风格定位 + 推荐 | | **色彩咨询** | "黄皮适合什么颜色？""红配绿好看吗？" | 色彩知识解答 | | **身材修饰** | "腿粗怎么穿？""小个子怎么显高？" | 身材优化建议 | -| **天气适配** | "下雨天穿什么？""15度怎么穿？" | 天气场景建议 | +| **天气适配** | "下雨天穿什么？""15度怎么穿？" | 天气场景建议。⚠️ **V1 不接天气 API**（`TD-33`）：优先反问用户当地天气，或按城市 + 月份推断气候区，**绝不编造具体温度与降水** | | **发型建议** | "圆脸适合什么发型？""换个发型建议" | 发型推荐（可联动） | | **穿搭评价**（P2） | "帮我看看这身搭配怎么样？" | 图片理解 + 评价 | | **闲聊/其他** | "你好""你是谁" | 友好回复 + 引导 | @@ -102,7 +113,7 @@ Agent 需从用户输入中提取以下场景维度： - **场合**：职场/面试/约会/聚会/婚礼/旅行/日常/运动 - **季节**：春/夏/秋/冬 -- **天气**：晴/阴/雨/雪/温度区间 +- **天气**：晴/阴/雨/雪/温度区间 —— **只能来自用户自述**，V1 不接天气 API（`TD-33`） - **风格偏好**：职业/休闲/优雅/甜美/酷帅/法式/韩系/日系 - **身材特征**：身高/体重/体型（H/A/V/O/X 型） - **肤色**：冷色调/暖色调/中性 @@ -164,7 +175,7 @@ Agent 需从用户输入中提取以下场景维度： | 层级 | 内容 | 用途 | |------|------|------| -| L0 身份档案 | 性别/生日/身高体重/职业/城市 | 硬约束 + 天气定位 | +| L0 身份档案 | 性别/生日/身高体重/职业/城市 | 硬约束 + **气候区推断与区域化内容**（V1 不做天气定位，`TD-33`） | | L1 美学画像 | 体型/脸型/肤色/季型/量感/直曲/风格/核心诉求（**来自美学报告**） | 系统提示核心，决定建议精度 | | L2 偏好与禁忌 | 偏好风格、颜色、品类；禁忌项 | 检索硬过滤 + 排序加权 | | L3 事件记忆 | 试穿、收藏、采纳/拒绝、历史对话摘要 | 按 query 语义召回 Top 3~5 | @@ -172,14 +183,14 @@ Agent 需从用户输入中提取以下场景维度： #### 3.5.2 注入策略与 token 预算 -不能把全部记忆塞进提示词，预算如下（合计 ≤1400 token）： +不能把全部记忆塞进提示词。**记忆注入合计 ≤1400 token（V1 实际 ≤1200）**，完整预算表（含检索知识与总输入合计）见《技术架构文档》§7.2，为唯一事实源： -| 内容 | 处理方式 | 预算 | -|------|---------|------| -| 画像摘要（L0+L1） | 模板化压缩，非 LLM 生成，画像未变时缓存复用 | ≤250 token | -| 偏好摘要（L2） | `confidence ≥ 0.5` 项按置信度取 Top 15 | ≤150 token | -| 事件召回（L3） | 向量检索 Top 3~5 条摘要 | ≤200 token | -| 会话上下文（L4） | 最近 6 轮原文 + 更早轮次滚动摘要 | ≤800 token | +| 内容 | 处理方式 | 预算 | V1 | +|------|---------|------|-----| +| 画像摘要（L0+L1） | 模板化压缩，非 LLM 生成，画像未变时缓存复用 | ≤250 token | ✅ | +| 偏好摘要（L2） | `confidence ≥ 0.5` 项按置信度取 Top 15 | ≤150 token | ✅ | +| 事件召回（L3） | 向量检索 Top 3~5 条摘要 | ≤200 token | ❌ V2 | +| 会话上下文（L4） | 最近 6 轮原文（≤400）+ 更早轮次滚动摘要（≤400） | ≤800 token | ✅ | 画像摘要注入示例： @@ -267,6 +278,8 @@ Agent：从休闲风转优雅风，可以循序渐进： ### 4.4 场景四：天气适配 +> ⚠️ **注意本例的前提**：温度与降水是**用户自己说出来的**，Agent 只是据此给建议。V1 不接天气 API（`TD-33`），因此 Agent **不会也不得主动声称**"明天你那边 15 度有雨"。若用户只问"明天怎么穿"而未告知天气，正确行为是**反问**（"你那边大概多少度？会下雨吗？"）或按城市 + 月份给气候区级别的建议，**绝不编造具体数值**。 + ``` 用户：明天15度，有雨，怎么穿？ Agent：15度雨天穿搭建议： @@ -390,10 +403,13 @@ Agent 推荐发型（基于脸型知识） ## 7. 非功能需求 ### 7.1 性能需求 -- **首字响应时间**：< 2 秒（流式输出首字） -- **完整回复时间**：< 15 秒 -- **并发支持**：支持 1000+ 并发对话 -- **可用性**：> 99.5% + +> 🔗 性能指标的唯一定义位置是《需求规格说明》§4.1。本节所列已与之对齐（本节的 15s 被采纳为 `NFR-PERF-02b`，原 `NFR-PERF-02` 的 8s 因不可达而废弃）。 + +- **首字响应时间**：< 2s（P95，`NFR-PERF-02`）—— 流式输出下这是唯一体验关键项 +- **完整回复时间**：< 15s（P95，`NFR-PERF-02b`） +- **可用性**：≥ 99.5%（`NFR-REL-01`） +- **并发支持**：**按容量基线推算而非拍板** —— 架构 §12.2 的 V1 容量基线为 1 万 DAU，对话峰值并发按该基线推导（原「1000+ 并发」无推导依据，已废弃；实际值由 `T-P5-14` 压测确定） ### 7.2 体验需求 - 流式输出，避免长时间空白等待 @@ -426,15 +442,15 @@ Agent 推荐发型（基于脸型知识） - **联动转化率**：对话 → 试穿的转化率 > 20% ### 8.2 质量指标 -- **意图识别准确率**：> 90% +- **意图识别准确率**：**验证门槛 ≥ 85% / 上线门槛 ≥ 90%**（两档口径的定义见《美学报告-需求文档》§9.4；`FR-AGT-02`） - **场景理解准确率**：> 85% - **回复相关性**：> 4.0/5 - **知识准确性**：> 95% - **违规率**：< 0.1% ### 8.3 技术指标 -- **首字延迟**：< 2s（P95） -- **完整回复延迟**：< 15s（P95） +- **首字延迟**：< 2s（P95，`NFR-PERF-02`） +- **完整回复延迟**：< 15s（P95，`NFR-PERF-02b`） - **错误率**：< 1% - **崩溃率**：< 0.1% @@ -493,7 +509,7 @@ Agent 推荐发型（基于脸型知识） | 约束 | 说明 | 依据 | |------|------|------| -| Token 预算硬性分配 | 系统提示词 ≤ 800、画像摘要 ≤ 500、会话摘要 ≤ 400、检索知识 ≤ 1500、用户输入 ≤ 500，**输入合计 ≤ 3700**，输出 ≤ 800。超限按优先级裁剪而非报错 | `FR-AGT-03`、架构 §7.2 | +| Token 预算硬性分配 | **完整预算表见架构 §7.2（唯一事实源）**：输入合计 ≤ 4200（V1 实际 ≤ 4000），其中记忆注入 ≤ 1400、检索知识 ≤ 1500、系统提示词 ≤ 800、用户输入 ≤ 500；输出 ≤ 800。超限按既定优先级裁剪而非报错，**硬禁忌永不裁剪**。原本节所列「画像 ≤500 / 会话 ≤400 / 合计 3700」已废弃 | `FR-AGT-03`、架构 §7.2 | | 每条回答必须可复盘 | `ag_message` 需存 `retrieval_trace`（检索轨迹）与 `rule_hits`（命中规则 ID）。没有这两个字段，「为什么这么答」永远查不清 | `FR-AGT-09` | | 越界意图必须正确拒答 | 医疗诊断、身材贬损、评价他人、身份推断（收入/职业层级）均需拒答。这类约束要同时写入系统 Prompt、规则库禁忌用词表、生成后校验三处 | `CR-12`、合规方案 §3 | | Agent 回复需 AI 生成显式标识 | 会话界面固定位置提示「内容由 AI 生成」 | `CR-05` | @@ -510,6 +526,12 @@ Agent 推荐发型（基于脸型知识） **作者**：产品团队 **状态**：待评审 **变更说明**： +- v1.2 rev.2（2026-08-13）：文档一致性评审修订 + - **语音输入由 P0 改为 P1/V2**：§2.1 能力总览与 §2.2 P0 范围原将「语音输入转文字」列为 P0，与 `FR-AGT-17`、`TD-14` 及本文 §9.2 的阶段划分直接冲突，属改版残留。§2.1 表格补「版本」与「编号」两列，全表与需求规格 §2.4 对齐（画像注入与上下文记忆同时由 P1 提升为 P0/V1，因它们本就是 `FR-AGT-03`/`FR-AGT-09`） + - **天气类问题明确不得编造数值**（`TD-33`）：V1 不接天气 API，Agent 只能反问用户或按城市 + 月份推断气候区。§4.4 的示例补充前提说明（温度是用户自己说的），§3.3.1 标注天气维度只能来自用户自述，§3.5 的 L0 城市字段用途由「天气定位」改为「气候区推断」 + - **token 预算与性能指标改为引用唯一事实源**：§3.5.2 与 §10.2 不再自列数值（§10.2 原写「画像 ≤500 / 会话 ≤400 / 合计 3700」已废弃）；§7.1 与 §8.3 引用 `NFR-PERF-*`，本文的「整轮 15s」被采纳为 `NFR-PERF-02b`（原 `NFR-PERF-02` 的 8s 不可达） + - **删除无推导依据的「1000+ 并发对话」**，改为按架构 §12.2 的容量基线推导、由 `T-P5-06` 压测确定 + - §8.2 意图识别准确率拆为验证门槛 ≥85% / 上线门槛 ≥90%（两档定义见美学报告 §9.4） - v1.2（2026-08-13）：§10 待确认事项全部收口 —— 大模型定为 DeepSeek + GLM 双路由并自建网关（明确不走云平台 MaaS 中转，因备案需模型厂商合作证明）；语音用鸿蒙 Core Speech Kit；审核用腾讯云 IMS/TMS 双向且 fail-close；补充 token 预算硬性分配、缓存前缀纪律、回答可复盘字段、越界拒答三处落点等实现约束 - v1.1：明确 Agent 与记忆系统、知识库的依赖边界；§3.4 改为规则前置的混合检索链路并补充防幻觉红线；§3.5 改为记忆读取与注入策略（含 token 预算与画像摘要示例）；补充 Phase 1 的画像注入、生成后校验、知识缺口埋点等任务 - v1.0：初始版本 diff --git a/docs/美学报告-需求文档.md b/docs/美学报告-需求文档.md index 5abb4a6..7da7334 100644 --- a/docs/美学报告-需求文档.md +++ b/docs/美学报告-需求文档.md @@ -34,17 +34,17 @@ | 维度 | 初级报告「形象速测」 | 全面报告「形象深度诊断」 | |------|---------------------|------------------------| | **上线版本** | V1（第一版即上线） | V2（第一版**不做**，仅做占位与意愿收集） | -| **价格** | 免费 | 付费（V2 起，单次 ¥29.9，会员优惠价见 §2.5） | +| **价格** | 免费 | **付费（V2 起，定价待定）** —— 原「单次 ¥29.9」为改版前残留，已废弃。V1 全线不出现任何价格（`FR-BILL-07`），V2 按 V1 实测数据定价（`T-P6-16`） | | **输入** | 1 张正面全身照 + 4 项基础问卷 | 全身正/侧面 + 面部特写 + 完整问卷（12~15 项） | -| **诊断维度** | 8 项核心维度 | 40+ 项完整维度 | +| **诊断维度** | **覆盖 21 项**（10 项完整输出 + 11 项粗判/部分），**首屏突出展示 8 项核心结论** | **覆盖全部 32 项** | | **色彩精度** | 四季粗判（春/夏/秋/冬）+ 8 色色板 | 十二季细分（如柔夏型）+ 完整色板（最佳色 24+/中性色/避雷色） | | **发型内容** | 3 条要点建议 | 独立发型专项报告（约 8 小节） | | **场景方案** | 1 个主场景 | 4+ 场景配色公式与完整搭配 | | **推荐搭配** | 1 套（可一键试穿） | 8~12 套（含单品清单与试穿入口） | | **篇幅** | 1~2 屏 | 15~25 屏 | -| **生成时长** | ≤ 60s（前台等待） | ≤ 5min（异步任务 + 完成推送） | +| **生成时长** | p95 < 90s（`NFR-PERF-03`，p50 < 45s） | p95 < 180s（`NFR-PERF-04`，V2 指标） | | **导出** | 分享长图（1 屏） | 分享长图 + PDF 完整版 | -| **免费额度** | 首次不限 + 每 30 天可重新生成 1 次 | 按次购买 / 会员权益 | +| **免费额度** | **首次 1 次（终身）+ 每 30 天可重新生成 1 次**（配额表见产品方案 §3.2，为唯一事实源；原「首次不限」表述有歧义，已更正） | V2 起按次购买 / 会员权益 | | **核心目的** | 拿到画像、建立信任、驱动首次试穿 | 交付专业价值、完成付费转化 | ### 2.2 初级报告内容（V1 交付范围） @@ -171,10 +171,11 @@ **第一版（V1）明确不做支付**，但要做**付费意愿验证**，这是本节最重要的产品决策： - V1 上线内容：仅初级报告，完全免费，无支付、无订单、无发票链路 -- V1 保留入口：初级报告结果页底部展示「全面报告」预览卡片（模糊化目录截图 + 内容清单 + 预计价格），点击后： +- V1 保留入口：初级报告结果页底部展示「全面报告」预览卡片（**模糊化目录截图 + 内容清单，不含价格**），点击后： - 弹出「即将上线，抢先预约」→ 用户点击即**留资 + 埋点** - - 记录：预约用户数 / 预约率 / 停留时长 / 点击价格档位 -- 决策门槛：若预约率 ≥ 8%，V2 立即开发付费全面报告；若 < 3%，重新评估定价与内容形态 + - 记录：预约用户数 / 预约率 / 卡片停留时长 / 目录各章节的点击分布（**不含任何价格相关埋点**） +- 决策门槛：若预约率 ≥ 8%，V2 立即开发付费全面报告；若 < 3%，重新评估内容形态 +- ⚠️ **预约率不等于付费意愿**，预约到实付的衰减通常很大。因此 V2 定价前必须先做**小范围真实收费灰度**（`T-P6-03b`），不得仅凭预约率全量定价 > ⚠️ **V1 的预览卡片不得展示具体价格**。原设计中的「预计价格 / 点击价格档位」已移除 —— V1 全产品线不出现任何价格与购买字样（产品方案 §3.2 纪律二），否则会污染 V2 的定价空间，也会让用户形成"处处收费"的第一印象。预约卡片只展示**内容清单与模糊化目录截图**，收集"想要"的意愿，不收集"愿意付多少"。 > @@ -359,6 +360,15 @@ > ~~`#33 五行分布`、`#34 幸运色`~~ 已于 2026-08-13 移除（`TD-31`），维度总数由 34 项减为 **32 项**。编号 33/34 **不再复用**，避免历史数据与文档交叉引用错位。 +**按上表逐列统计（§2.1 分级表与 `FR-RPT-06` 的口径来源）**： + +| 分级 | 完整输出 | 粗判 / 部分 / 仅标签 | 不输出 | 覆盖合计 | +|------|:------:|:-----------------:|:-----:|:------:| +| 初级报告 | 10 项 | 11 项 | 11 项 | **21 / 32** | +| 全面报告（V2） | 32 项 | 0 | 0 | **32 / 32** | + +> ⚠️ **原「初级 8 项核心 / 全面 40+ 项」的口径已废弃**：字典总共只有 32 项，不存在 40+；「8 项」指的是**结果页首屏突出展示的核心结论数**，不是覆盖的维度数，两者不是一回事，此前被混用。 + > 每个维度的输出必须携带 `confidence`（0~1）与 `source`（`vision` / `self_reported` / `rule` / `llm`），低置信维度在报告中以"参考"语气呈现，并允许用户手动修正。用户修正后置信度置为 1.0 且标记 `user_confirmed`。 --- @@ -427,12 +437,12 @@ - **⑤ 规则引擎先于 ⑦ LLM 生成**：硬结论（体型策略、色板、避雷项）由规则引擎产出，LLM 只负责组织语言与解释，不允许 LLM 自由发挥核心结论。这是保证专业准确性、避免幻觉的关键设计。 - **⑧ 一致性校验不可省**：至少校验三项——推荐色是否在最佳色板内、推荐单品是否命中用户禁忌项、结论之间是否自相矛盾（如同时推荐"紧身"与"避免紧身"）。校验失败则重试该章节生成。 - **⑪ 素材绑定是闭环前提**：报告推荐的每套搭配必须绑定知识库中 `tryon_ready = true` 的白底单品图，否则"一键试穿"按钮不展示（详见 [知识库方案](./美学知识库-建设方案.md) 素材规范）。 -- **全面报告必须异步**：生成时长 ≤ 5min，采用任务中心 + 完成推送，用户可退出 App。初级报告可前台等待，但同样进任务队列，避免页面销毁导致任务丢失。 +- **全面报告必须异步**：生成时长按 `NFR-PERF-04`，采用任务中心 + 完成推送，用户可退出 App。初级报告可前台等待，但同样进任务队列，避免页面销毁导致任务丢失。 - **失败降级**：视觉分析部分失败时（如面部照缺失），跳过相关维度而非整体失败，报告中标注"该维度暂未诊断，补充照片可解锁"。 ### 6.3 生成中的等待体验 -换装接口最长 320s、发型 120s、全面报告 ≤ 5min，长耗时是本产品的固有特征，必须产品化处理： +换装与发型的现状耗时可达数十秒到数分钟（现状基线待 `T-P0-13`/`T-P0-14` 实测，见需求规格 §4.1.1），报告生成按 `NFR-PERF-03`/`04`。**长耗时是本产品的固有特征，必须产品化处理**： - 分析步骤可视化：`识别人像 → 测算体型 → 分析面部 → 采样色彩 → 匹配色板 → 生成方案`，逐步点亮 - 展示已等待秒数 + 预计剩余 @@ -498,7 +508,7 @@ ### 9.1 隐私与数据安全（人脸属敏感个人信息，最高优先级） - **单独授权**：人脸信息处理必须独立于通用隐私协议单独弹窗授权，不可默认勾选 -- **最小化**：只存储派生特征与结论，**原始人脸照片处理完即删**（保留期 ≤ 24h 仅用于任务重试），报告中展示的分析图为脱敏处理版本 +- **最小化**：只存储派生特征与结论，**原始人脸照片处理完即显式删除，临时桶生命周期 ≤ 2 小时兜底**（唯一事实源：`CR-02` 与《合规与安全方案》§2.1.2；本节原写「≤ 24h 仅用于任务重试」已废弃 —— 2 小时已覆盖重试窗口，24h 只是白担合规风险），报告中展示的分析图为脱敏处理版本 - **不用于训练**：明确承诺用户照片不用于模型训练，并在协议中写明 - **加密**：传输 HTTPS，存储加密，OSS 签名链接短时效 - **可删除可导出**：用户可一键删除全部报告与画像数据，可导出个人数据副本 @@ -522,10 +532,27 @@ - **`birthday` 字段用途收窄**：仅用于生日权益与年龄段判断（影响风格建议的适龄性），**不得用于任何命理推算**。字段本身保留，但推算逻辑不实现 ### 9.4 准确性保障 -- 建立 **100 例黄金评测集**（由专业形象顾问标注体型/脸型/季型/风格），每次算法或知识库更新回归测试 -- 目标准确率：体型 ≥ 85%、脸型 ≥ 80%、四季季型 ≥ 80%、十二季细分 ≥ 65%（细分季型本身专业争议大，需通过话术弱化绝对性） + +> 🔒 **本节是诊断准确率门槛的唯一定义位置**。产品方案 §8.3.3、`FR-RPT-05`、`T-P0-10`/`T-P0-11` 一律引用本表。 + +- 建立 **100 例黄金评测集**（由全职形象顾问标注体型/脸型/季型/风格），每次算法或知识库更新回归测试 + +**准确率门槛分两档，此前文档间的数值冲突全部源于没有区分这两档**： + +| 维度 | ① Phase 0 验证门槛 | ② 上线质量门槛 | 十二季细分 | +|------|-----------------|-------------|----------| +| 体型识别 | ≥ 80% | ≥ 85% | — | +| 四季季型 | ≥ 75% | ≥ 80% | 上线门槛 ≥ 65% | +| 脸型识别 | ≥ 75% | ≥ 80% | — | + +**两档的判定后果完全不同，这是必须分开的原因**： + +- **① 验证门槛（`T-P0-10`/`T-P0-11`，小样本）**：回答"这条技术路线走不走得通"。**不达标 → 切换技术方案**（`TD-05` 关键点方案、`TD-06` 色彩方案的备选路径），而不是继续调参。 +- **② 上线门槛（黄金集全量回归）**：回答"这个结论能不能给用户看"。**不达标 → 该维度降级**为「仅供参考」话术或直接不展示，**而不是延期上线** —— 单一维度不应阻塞整个产品。 +- **十二季细分 ≥ 65% 只有上线门槛，没有验证门槛**：它本身专业争议就大，不作为技术路线的判据，且必须通过话术弱化绝对性。 + - 用户修正数据作为长期评测样本回流 -- 报告内提供「结论不准反馈」入口，反馈进入人工抽查 +- 报告内提供「结论不准反馈」入口，反馈进入人工抽查（对应 `FR-RPT-19`，见需求规格 §2.2） ### 9.5 成本控制 - 单份初级报告成本目标 ≤ ¥0.30（视觉分析 + LLM 生成），全面报告 ≤ ¥2.00 @@ -553,8 +580,8 @@ ### 10.2 质量指标 - 报告生成成功率 > 97% -- 初级报告 P95 生成时长 < 60s，全面报告 P95 < 5min -- 结论修正率 < 15%（用户主动修正维度数 / 总维度数） +- 生成时长：**初级 p95 < 90s（`NFR-PERF-03`）、全面 p95 < 180s（`NFR-PERF-04`）** —— 性能指标的唯一定义位置是《需求规格说明》§4.1，原「初级 < 60s / 全面 < 5min」已废弃 +- 结论修正率 < 15%（用户主动修正维度数 / 总维度数）—— **数据来源是 `FR-RPT-19` 的修正入口埋点，缺它则本指标无法计算** - 报告满意度评分 > 4.2/5 - 首屏结论"有用"投票率 > 70% @@ -606,6 +633,13 @@ **作者**：产品团队 **状态**：待评审 **变更说明**： +- v1.2 rev.2（2026-08-13）：文档一致性评审修订 + - **§9.4 升为诊断准确率门槛的唯一事实源，并拆为「Phase 0 验证门槛 / 上线质量门槛」两档**。此前文档间的数值冲突（体型 80 vs 85、季型 75 vs 80）全部源于没区分这两档 —— 两者的**判定后果完全不同**：验证门槛不达标 → 切换技术方案；上线门槛不达标 → 该维度降级为「仅供参考」或不展示，**而不是延期上线**（单一维度不应阻塞整个产品） + - **清除全部价格残留**：§2.1 分级表的「单次 ¥29.9」、§2.5 正文的「预计价格」与埋点「点击价格档位」全部删除 —— 这三处与紧随其后的 ⚠️ 注释（说明该项"已移除"）自相矛盾 + - **§2.1 与 §4 维度覆盖改为准确口径**：初级覆盖 **21/32 项**（10 项完整 + 11 项粗判），全面覆盖 **32 项**；原「初级 8 项核心 / 全面 40+ 项」中的 40+ 在字典里根本不存在，「8 项」实指首屏突出展示的核心结论数，两者此前被混用。§4 新增逐列统计表 + - **§9.1 人脸原图保留期由「≤ 24h 仅用于任务重试」改为「处理完即删 + 临时桶 2 小时兜底」**，以 `CR-02` 与合规方案 §2.1.2 为准 + - §2.1 与 §10.2 生成时长改为引用 `NFR-PERF-03/04`（初级 90s、全面 180s），原「60s / 5min」废弃；§2.1 免费额度「首次不限」改为「首次 1 次（终身）」消除歧义 + - §2.5 补充「预约率 ≠ 付费意愿」的提醒与 V2 收费灰度前置要求；§9.4 反馈入口关联到新增的 `FR-RPT-19` - v1.2（2026-08-13）：业务决策收口，§11 已无遗留待确认项 - **五行/幸运色模块整体移除**（`TD-31`）：诊断维度由 34 项减为 **32 项**，编号 33/34 不再复用；§9.3 由「命理模块的合规处理」改为「不做 + 越界拒答」；`birthday` 用途收窄为生日权益与年龄段判断 - **§2.5 移除价格展示**：V1 预约卡片不得出现任何价格与档位（原设计含「预计价格」「点击价格档位」），价格敏感度改用线下访谈采集；V2 定价表全部改为占位，并列明定价的三个前提 diff --git a/docs/美学知识库-建设方案.md b/docs/美学知识库-建设方案.md index 417db03..9bd5986 100644 --- a/docs/美学知识库-建设方案.md +++ b/docs/美学知识库-建设方案.md @@ -63,20 +63,24 @@ ### 3.1 分类总览 -| # | 类目 | 定位 | 主要模态 | 冷启动目标量级 | -|---|------|------|---------|--------------| -| 1 | 单品 Item | 服饰单品的属性化定义 | 结构化 + 图像 | 800~1500 条 | -| 2 | 色彩 Color | 颜色体系与季型色板 | 数值 + 结构化 + 图像 | 12 季 × 30 色 ≈ 400 色 | -| 3 | 风格 Style | 风格体系与识别特征 | 文本 + 结构化 + 图像 | 9 基因型 + 20 潮流风格 | -| 4 | 身材 Body | 体型与局部特征的修饰策略 | 结构化 + 文本 + 图示 | 5 体型 × 12 局部特征 | -| 5 | 面部与发型 Face & Hair | 脸型/量感/直曲 与发型适配 | 结构化 + 图像 | 60 发型 + 8 脸型映射 | -| 6 | 场景 Occasion | 场合着装规范与温度带 | 结构化 + 文本 | 20 场景 × 4 季 | -| 7 | 材质 Material | 面料特性与季节适配 | 结构化 + 文本 | 40~60 种 | -| 8 | 配饰 Accessory | 配饰搭配规则 | 结构化 + 图像 | 8 品类 × 规则 | -| 9 | 妆容 Makeup | 与季型联动的妆容方案 | 结构化 + 文本 + 色值 | 12 季 × 3 部位 | -| 10 | 搭配法则 Rule | 可执行的 IF-THEN 规则 | 结构化（规则引擎） | 800~1200 条 | -| 11 | 搭配方案 Outfit | 成套 look（召回主单元） | 结构化 + 图像 | 300~500 套 | -| 12 | 趋势 Trend | 时效性流行趋势 | 文本 + 图像 | 每季 30~50 条 | +> 🔒 **规模数值的唯一定义位置是本文 §9**。下表的「长期目标」列与「V1 硬指标」列必须与 §9 一致；产品方案 §2.5.2 / §2.8 **一律引用 §9，不得复述**。此前四处文档给出过互相矛盾的规模数字（单品 800/400/300、规则 800~1200/800/400），已在本轮收口。 + +| # | 类目 | 定位 | 主要模态 | **V1 硬指标** | 长期目标 | +|---|------|------|---------|:-----------:|--------| +| 1 | 单品 Item | 服饰单品的属性化定义 | 结构化 + 图像 | **300 件 `tryon_ready`** | 800~1500 条 | +| 2 | 色彩 Color | 颜色体系与季型色板 | 数值 + 结构化 + 图像 | 12 季 × 30 色 ≈ 400 色 | 同 | +| 3 | 风格 Style | 风格体系与识别特征 | 文本 + 结构化 + 图像 | 9 基因型 + 20 潮流风格 | 同 | +| 4 | 身材 Body | 体型与局部特征的修饰策略 | 结构化 + 文本 + 图示 | 5 体型 × **13 局部特征** | 同 | +| 5 | 面部与发型 Face & Hair | 脸型/量感/直曲 与发型适配 | 结构化 + 图像 | 60 发型 + **7 脸型映射** | 同 | +| 6 | 场景 Occasion | 场合着装规范与温度带 | 结构化 + 文本 | 20 场景 × 4 季 | 同 | +| 7 | 材质 Material | 面料特性与季节适配 | 结构化 + 文本 | 40~60 种 | 同 | +| 8 | 配饰 Accessory | 配饰搭配规则 | 结构化 + 图像 | 8 品类 × 规则 | 同 | +| 9 | 妆容 Makeup | 与季型联动的妆容方案 | 结构化 + 文本 + 色值 | 12 季 × 3 部位 | 同 | +| 10 | 搭配法则 Rule | 可执行的 IF-THEN 规则 | 结构化（规则引擎） | **400 条** | 800~1200 条 | +| 11 | 搭配方案 Outfit | 成套 look（召回主单元） | 结构化 + 图像 | **100 套** | 300~500 套 | +| 12 | 趋势 Trend | 时效性流行趋势 | 文本 + 图像 | 每季 30~50 条 | 同 | + +> ⚠️ **两处计数错误已更正**：脸型是 **7 种**（鹅蛋/圆/方/长/心形/菱形/梨形，与美学报告 §4 维度 #8 一致），原写「8 脸型」；局部特征实际列了 **13 项**（见 §3.2 ④），原写「12 项」。 > 扩展类目（V3 电商阶段）：品牌 Brand、商品 SKU、价格与渠道。 @@ -158,7 +162,7 @@ #### ④ 身材 Body - **整体体型 5 型**：O 苹果、A 梨、X 沙漏、T 倒三角、H 矩形 -- **局部特征 12 项**：溜肩、平肩、宽肩、窄肩、短颈、长颈、粗手臂、小腹、宽臀、长腰、短腰、粗腿、腿型（直/O/X） +- **局部特征 13 项**：溜肩、平肩、宽肩、窄肩、短颈、长颈、粗手臂、小腹、宽臀、长腰、短腰、粗腿、腿型（直/O/X） - 每项字段：判定标准（可量化的比例阈值）、视觉目标（如"视觉重心上移"）、推荐策略、推荐单品属性组合、明确避免项、图示 - **需求映射**：显高 / 显瘦 / 显白 / 遮肉 / 修饰肩颈 → 各自的策略集合 - 文案红线：所有描述使用中性表述（"下半身量感偏大"而非"腿粗"） @@ -374,29 +378,29 @@ Agent 和报告推荐的实际交付物是"成套 look"，而非零散规则。 ### 5.1 五个阶段 -| 阶段 | 内容 | 产出 | 人力与周期 | +| 阶段 | 内容 | **V1 产出**（规模见 §9.1） | 人力 | |------|------|------|-----------| -| **P0 本体定义** | 定义 12 类实体的字段、枚举值、关系；建立属性字典 | Schema 文档 + 数据库表 | 产品 + 架构，1 周 | -| **P1 专家冷启动** | **全职形象顾问**撰写核心规则、色板、风格定义；产品整理场景模板 | 800 条规则 + 12 季色板 + 9 型风格 + 20 场景 | **全职顾问 1 人** + 产品 1 人，按实际产能倒排 | -| **P2 素材生产** | **自采**：采购 → 拍摄 → 抠图 → 属性标注；60 款发型补齐标签 | V1 目标 **300 件 `tryon_ready`** + 60 发型标签 | 运营 2 人，产能待 `T-P0-21` 实测 | -| **P3 方案组装** | 由规则 + 单品组合出成套 look，顾问审核 | 300~500 套 Outfit | 顾问 + 运营，2 周 | -| **P4 半自动扩充** | LLM 从专业书籍/公开资料抽取候选知识 → **人工审核后入库** | 规则与文本扩充至 2000+ 条 | 持续 | +| **P0 本体定义** | 定义 12 类实体的字段、枚举值、关系；建立属性字典 | Schema 文档 + 数据库表 | 产品 + 架构 + **顾问评审**（须在建表前） | +| **P1 专家冷启动** | **全职形象顾问**撰写核心规则、色板、风格定义；产品整理场景模板 | **400 条规则** + 12 季色板 + 9 型风格 + 20 场景 | **全职顾问 1 人** + 产品 1 人，按实测产能倒排 | +| **P2 素材生产** | **自采**：采购 → 拍摄 → 抠图 → 属性标注；60 款发型补齐标签 | **300 件 `tryon_ready`** + 60 发型标签 | 运营 2 人，产能待 `T-P0-21` 实测 | +| **P3 方案组装** | 由规则 + 单品组合出成套 look，顾问审核 | **100 套 Outfit** | 顾问 + 运营 | +| **P4 半自动扩充** | LLM 从专业书籍/公开资料抽取候选知识 → **人工审核后入库** | V2 起持续扩充至长期目标 | 持续 | -> **关键判断**：P1（专家冷启动）不可跳过、不可用大模型代替。这 800 条规则是产品专业性的地基，也是唯一无法被竞品快速复制的资产。用 LLM 生成规则再让顾问审核，效率高于纯人工，但**审核环节是准确率红线，不可省略**。 +> **关键判断**：P1（专家冷启动）不可跳过、不可用大模型代替。这批规则是产品专业性的地基，也是唯一无法被竞品快速复制的资产。用 LLM 生成规则再让顾问审核，效率高于纯人工，但**审核环节是准确率红线，不可省略**。 -> ⚠️ **两处口径修正**：① 原「800+ 单品」是长期目标，**V1 的硬指标是 300 件 `tryon_ready`**（与产品方案 §7.1.5、`FR-KB-08` 对齐）；② 原「3~4 周」「3 周」的周期估算已删除 —— 全职顾问与自采流水线的实际产能需由 `T-P0-20`/`T-P0-21` 实测后倒排，凭估算排期在这两项上风险最高。 +> ⚠️ **本表已删除全部周期估算**（原有「1 周」「2 周」「3~4 周」）。全职顾问与自采流水线的实际产能需由 `T-P0-20`/`T-P0-21` 实测后倒排 —— **凭估算排期在这两项上风险最高**，因为它们是备案解除后唯一无法靠 AI 辅助开发压缩的工序。 #### 5.1.1 全职形象顾问的工作流（`TD-27` 落地方案） -**为什么是全职而非外部按条计酬**：规则库不是一次性交付物。800 条写完只是起点，之后要根据用户反馈与结论修正率反复校准 —— 而按条计酬的外部顾问在"交付完成"后就没有继续投入的动力，恰恰错过质量提升最关键的阶段。另外黄金评测集若由多位外部顾问分批标注，口径漂移几乎不可避免，而黄金集是所有质量指标的基准，口径一旦不稳，后续准确率数字就失去意义。 +**为什么是全职而非外部按条计酬**：规则库不是一次性交付物。V1 的 400 条写完只是起点，之后要根据用户反馈与结论修正率反复校准 —— 而按条计酬的外部顾问在"交付完成"后就没有继续投入的动力，恰恰错过质量提升最关键的阶段。另外黄金评测集若由多位外部顾问分批标注，口径漂移几乎不可避免，而黄金集是所有质量指标的基准，口径一旦不稳，后续准确率数字就失去意义。 **顾问的四项职责（按投入顺序）**： | # | 职责 | 交付物 | 与开发的接口 | |---|------|-------|------------| | 1 | 本体 Schema 评审 | 修订意见 | 到岗第一件事。字段设计错了后面全要返工，**必须在建表前完成** | -| 2 | 规则库撰写与校准 | 800 条规则（含 `is_hard` 标记与解释链） | 通过运营后台自行录入，不经工程转录 | -| 3 | 黄金评测集标注 | 100~200 例标注样本 | 单人标注保证口径一致 | +| 2 | 规则库撰写与校准 | **V1 400 条**，长期 800~1200 条（含 `is_hard` 标记与解释链） | 通过运营后台自行录入，不经工程转录 | +| 3 | 黄金评测集标注 | **330 例，分四个子集**（见 §7 黄金集子集表） | 单人标注保证口径一致 | | 4 | 持续校准 | 按结论修正率与用户反馈迭代规则 | 长期职责，是全职的主要理由 | **这对运营后台提出了更高要求**：顾问是后台的**日常使用者**而非偶尔录入者。因此后台的易用性直接决定规则库产能 —— 一个难用的后台会让顾问的有效产出打对折。这是 `TD-25` 把极简后台从 Phase 2 提前到 V1 的核心原因，也意味着后台应在顾问到岗后**根据其真实使用反馈快速迭代**，不能一次交付就不管。 @@ -482,9 +486,22 @@ Agent 和报告推荐的实际交付物是"成套 look"，而非零散规则。 ## 7. 质量保障 +#### 黄金集的四个子集（🔒 唯一事实源） + +> 此前七处文档给出过 200 / 100 / 30 等不同数字，看似矛盾，实际是**四个用途不同的子集**，但没有一处说清它们的关系。下表明确定义，`FR-KB-11`、`FR-AGT-05`、`FR-RPT-07`、美学报告 §9.4、产品方案 §6.1.2 **一律引用本表**。 + +| 子集 | 规模 | 用途 | 标注内容 | 引用编号 | +|------|:----:|------|---------|---------| +| ① **检索黄金集** | **100 条** query | 校验混合检索的 Top-5 命中率 ≥ 80% | query → 期望命中的知识条目 ID | `FR-KB-11`、`FR-AGT-04` | +| ② **Agent 问答黄金集** | **100 例** 对话 | 校验回答质量与**禁忌违反数 = 0** | 问题 → 标准答案要点 + 红线项 | `FR-AGT-05` | +| ③ **诊断黄金集** | **100 例** 人像 | 校验体型/脸型/季型准确率（两档门槛见美学报告 §9.4） | 照片 → 顾问标注的各维度真值 | `FR-RPT-05` | +| ④ **报告结构黄金集** | **30 例** 报告 | 校验报告结构完整性、术语释义覆盖、无贬损表述 | 输入 → 期望的章节与字段完整性 | `FR-RPT-07` | +| **合计** | **330 例** | — | **全部由全职顾问单人标注**，保证口径一致（`TD-27`） | — | + +**为什么必须分开而不是合成一个大集**：四者的失败后果完全不同 —— ①②退化说明知识库或检索有问题，③退化说明视觉算法有问题，④退化说明生成链路有问题。合成一个集会让"准确率下降了"这句话失去可操作性，定位不到该修哪里。 + | 机制 | 说明 | |------|------| -| **黄金评测集** | 200 条问答（含 100 条画像化场景题），由顾问给出标准答案与红线项 | | **准确率门槛** | 知识准确性 ≥ 95%；禁忌项违反率 = 0（红线，任何一例都要阻断发布） | | **回归测试** | 每次知识库版本发布前全量跑黄金集，不达标不发布 | | **一致性校验** | 入库流水线校验：枚举值合法性、色值与图像一致性、规则冲突检测、孤儿实体检测 | @@ -511,20 +528,29 @@ Agent 和报告推荐的实际交付物是"成套 look"，而非零散规则。 ## 9. 规模与成本估算 -| 项目 | 第一版目标 | 说明 | -|------|-----------|------| -| 规则条目 | 800 条 | 覆盖 5 体型 × 12 局部 × 主要场景 | -| 单品实体 | 长期 800 条；**V1 硬指标 300 条 `tryon_ready`** | 试穿闭环的最小可用量；全部自采（`TD-26`） | -| 搭配方案 | 300 套 | 覆盖 4 场景 × 12 季型的基本组合 | -| 色彩条目 | 400 色 + 12 套色板 | — | -| 发型标签 | 60 款全量打标 | 补齐现有发型库 | -| 文本知识块 | 1500 块 | 用于 RAG | -| 图像资产 | 2000 张 | 含单品/look/发型/图示 | -| 人力投入 | **全职顾问 1 人**（`TD-27`）+ 内容运营 2 人 + 开发 1.5 人月（后台） | 预估 12~18 万元；**另需计入单品采购与棚拍成本**（自采模式新增，`TD-26`） | -| 自采单品成本 | 300 件 × 单件采购均价 + 棚拍与抠图人工 | ⚠️ 需在 `T-P0-21` 跑通流水线后按实际单件成本核算 | -| 存储与检索成本 | 月度 < ¥2000 | 向量库 + 对象存储 + CDN | +### 9.1 知识库规模（🔒 唯一事实源） -> 分期建议：V1 只需**规则 400 条 + 单品 300 条 + 方案 100 套 + 发型 60 款打标 + 12 套色板**即可支撑初级报告与基础对话，其余在 V2 补齐。不要为了知识库的完整性阻塞首版上线。 +> 全项目引用本表。产品方案 §2.5.2 / §2.8、`FR-KB-*`、`T-P2-*` **不得复述数值**。此前「第一版目标」列与文末「分期建议」自相矛盾（规则 800 vs 400、方案 300 vs 100），已合并为下表两列。 + +| 项目 | **V1 硬指标**（上线门槛） | 长期目标 | 说明 | +|------|:---------------------:|--------|------| +| 规则条目 | **400 条** | 800~1200 条 | V1 覆盖 5 体型 × 主要场景；长期覆盖 5 体型 × 13 局部 × 场景 | +| 单品实体 | **300 件 `tryon_ready`** | 800~1500 条 | 试穿闭环的最小可用量；全部自采（`TD-26`） | +| 搭配方案 | **100 套** | 300~500 套 | V1 覆盖 4 场景 × 主要季型；长期覆盖 4 场景 × 12 季型 | +| 色彩条目 | 400 色 + 12 套色板 | 同 | 一次做完，无需分期 | +| 发型标签 | 60 款全量打标 | 同 | 补齐现有发型库，一次做完 | +| 文本知识块 | 800 块 | 1500 块 | 用于 RAG | +| 图像资产 | 1000 张 | 2000 张 | 含单品/look/发型/图示 | + +**为什么 V1 只做这些就够**：规则 400 条 + 单品 300 件 + 方案 100 套 + 发型 60 款打标 + 12 套色板即可支撑初级报告与基础对话。**不要为了知识库的完整性阻塞首版上线** —— 知识库是持续运营的资产，V1 的目标是跑通"生产 → 检索 → 建议 → 试穿"的闭环，而不是把库填满。 + +### 9.2 成本估算 + +| 项目 | 估算 | 说明 | +|------|------|------| +| 人力投入 | **全职顾问 1 人**（`TD-27`）+ 内容运营 2 人 + 开发 1.5 人月（后台） | 预估 ¥12~18 万 | +| 自采单品成本 | 300 件 × 单件采购均价 + 棚拍与抠图人工 | ⚠️ 需在 `T-P0-21` 跑通流水线后按实际单件成本核算（自采模式新增，`TD-26`） | +| 存储与检索成本 | 月度 < ¥2000 | 向量库 + 对象存储 + CDN | --- @@ -581,6 +607,11 @@ Agent 和报告推荐的实际交付物是"成套 look"，而非零散规则。 - **§5.1.1 新增「全职形象顾问工作流」**（`TD-27`）：顾问定为**全职编制**，四项职责按投入顺序排列（本体 Schema 评审须在建表前完成 → 规则库撰写 → 黄金集标注 → 持续校准）。指出顾问是运营后台的日常使用者，后台易用性直接决定规则库产能 - **§5.1 修正两处口径**：V1 单品硬指标由「800+」改为**300 件 `tryon_ready`**；删除「3~4 周」等周期估算，改为按 `T-P0-20`/`T-P0-21` 实测产能倒排 - §9 成本估算新增自采单品采购与棚拍成本项 +- v1.2 rev.2（2026-08-13）：文档一致性评审修订 + - **§9.1 升为知识库规模的唯一事实源**，并拆为「V1 硬指标」与「长期目标」两列。此前四处文档给出五套互相矛盾的数字（单品 800~1500 / 800 / 400 / 300，规则 800~1200 / 800 / 400），且本文 §9 表格与其自己的文末分期建议就自相矛盾。现统一为 **V1 = 规则 400 / 单品 300 `tryon_ready` / 方案 100**，长期目标另列 + - **§7 黄金集拆为四个子集共 330 例**（检索 100 / Agent 问答 100 / 诊断 100 / 报告结构 30）。此前七处文档的 200/100/30 看似矛盾，实为不同子集但无一处说清。**分开的理由是四者的失败后果完全不同**：①②退化指向知识库或检索、③指向视觉算法、④指向生成链路 —— 合成一个集会让"准确率下降了"失去可操作性 + - **修正两处计数错误**：脸型 8 种→**7 种**（与美学报告 §4 维度 #8 一致）；局部特征 12 项→**13 项**（按 §3.2 ④ 实际列举数） + - **§5.1 删除全部周期估算**（原「1 周」「2 周」），与「按实测产能倒排」的排期原则统一 - v1.1（2026-08-13）：§10 待确认事项收口，10 项确认、2 项转入业务输入；关键变更三处 —— ① 抠图明确用 BiRefNet 并**禁用 RMBG-2.0**（非商用许可）；② 12 季色彩体系改为**自建色板 + 规避 CMB/四季色彩商标**，不引进外部授权；③ 知识库管理后台从 Phase 2 **提前到 V1 极简版**。另补充硬约束强制校验、解释链事实不得由 LLM 生成、版本号驱动缓存失效等实现约束 - v1.0（2026-08-11）：初始版本 diff --git a/docs/需求规格说明.md b/docs/需求规格说明.md index 918accd..77232ce 100644 --- a/docs/需求规格说明.md +++ b/docs/需求规格说明.md @@ -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 | 首次建立统一需求编号体系，收拢五份需求文档 | diff --git a/docs/鸿蒙美搭-智能穿搭美学助手-产品方案.md b/docs/鸿蒙美搭-智能穿搭美学助手-产品方案.md index 7a30abc..54ba456 100644 --- a/docs/鸿蒙美搭-智能穿搭美学助手-产品方案.md +++ b/docs/鸿蒙美搭-智能穿搭美学助手-产品方案.md @@ -234,7 +234,7 @@ | 上线版本 | **V1** | **V2**（V1 仅做占位入口） | | 价格 | 免费 | 付费（**定价待 V2 按真实数据确定**，见 §5.0） | | 输入 | 1 张全身照 + 4 项问卷 | 全身正/侧 + 面部特写 + 12~15 项问卷 | -| 诊断维度 | 8 项核心 | 40+ 项完整 | +| 诊断维度 | **覆盖 21 / 32 项**（首屏突出 8 项核心结论） | **覆盖全部 32 项** | | 色彩精度 | 四季粗判 + 8 色色板 | 十二季细分 + 24+ 色完整色板 | | 发型内容 | 3 条要点 | 独立发型专项报告（8 小节） | | 场景方案 | 1 个 | 4+ 个（含配色公式） | @@ -314,7 +314,7 @@ V1 不做支付链路，在初级报告结果页保留「全面报告」预览 - **隐式推断需确认**：同属性连续 3 次拒绝 → 生成待确认候选 → 恰当时机征询"看起来你不太喜欢露肩款？"，用户确认后才生效 - **用户偏好高于专业结论**：专业判定与用户喜好冲突时，**按用户喜好执行 + 附加专业提示**（不说教） - **可见可控**：「我的记忆」页面可查看、修改、删除每条记忆，并可一键关闭个性化推荐（合规刚需 + 信任基础） -- **注入有预算**：画像摘要 ≤250 token + 偏好 ≤150 + 事件召回 ≤200 + 会话 ≤800，合计 ≤1400 token，不做无脑全量拼接 +- **注入有预算**：记忆注入合计 ≤1400 token（V1 实际 ≤1200，事件召回为 V2 能力），不做无脑全量拼接。**完整分项预算见《技术架构文档》§7.2（唯一事实源）** ### 2.5 美学知识库（详见独立文档） @@ -335,20 +335,22 @@ V1 不做支付链路，在初级报告结果页保留「全面报告」预览 #### 2.5.2 知识分类：12 类实体 -| 类目 | 内容 | 第一版目标量级 | -|------|------|--------------| -| ① 单品 Item | 品类树 + 廓形/领型/袖型/腰线/长度/图案/正式度/量感/直曲等属性 | 800 条（≥400 条可试穿） | -| ② 色彩 Color | 色名 + HEX/HSL/**Lab** + 冷暖/明度/彩度 + 季型归属 + 配色关系 | 400 色 + 12 套色板 | -| ③ 风格 Style | 9 型基因风格 + 20+ 潮流风格（法式/韩系/清冷/老钱风…） | 29 条 | -| ④ 身材 Body | 5 体型 + 12 局部特征（溜肩/短颈/长短腰…）→ 修饰策略 | 60 组映射 | -| ⑤ 面部与发型 | 脸型/三庭五眼/量感/直曲 × 发长/卷度/刘海/发色 适配矩阵 | 60 款发型全量打标 | -| ⑥ 场景 Occasion | 20 场景 × Dress Code × 温度带（8 档）× 天气 | 80 组 | -| ⑦ 材质 Material | 垂感/挺括/透气/保暖/易皱/光泽 + 季节与季型适配 | 40~60 种 | -| ⑧ 配饰 Accessory | 8 品类的量感、材质、颜色、佩戴位置规则 | — | -| ⑨ 妆容 Makeup | 12 季型 × 底妆/眼妆/唇妆 色值方案 | 36 组 | -| ⑩ 搭配法则 Rule | 结构化 IF-THEN 规则（供规则引擎执行） | **800 条（核心资产）** | -| ⑪ 搭配方案 Outfit | 成套 look（单品组合 + 配色公式 + 适配画像 + 试穿素材） | 300 套 | -| ⑫ 趋势 Trend | 时效性流行趋势，独立库、月更、过期降权 | 每季 30~50 条 | +> 🔗 **规模数值的唯一定义位置是《美学知识库-建设方案》§9.1**（区分「V1 硬指标」与「长期目标」两列）。本表只列内容构成，**不复述规模** —— 此前本表的「第一版目标量级」与本文 §2.8、知识库 §9 三处互相矛盾（单品 800/300、规则 800/400、方案 300/100）。 + +| 类目 | 内容 | +|------|------| +| ① 单品 Item | 品类树 + 廓形/领型/袖型/腰线/长度/图案/正式度/量感/直曲等属性 | +| ② 色彩 Color | 色名 + HEX/HSL/**Lab** + 冷暖/明度/彩度 + 季型归属 + 配色关系 | +| ③ 风格 Style | 9 型基因风格 + 20+ 潮流风格（法式/韩系/清冷/老钱风…） | +| ④ 身材 Body | 5 体型 + **13 局部特征**（溜肩/短颈/长短腰…）→ 修饰策略 | +| ⑤ 面部与发型 | **7 种脸型**/三庭五眼/量感/直曲 × 发长/卷度/刘海/发色 适配矩阵 | +| ⑥ 场景 Occasion | 20 场景 × Dress Code × 温度带（8 档）。**天气来自用户自述**，V1 不接天气 API（`TD-33`） | +| ⑦ 材质 Material | 垂感/挺括/透气/保暖/易皱/光泽 + 季节与季型适配 | +| ⑧ 配饰 Accessory | 8 品类的量感、材质、颜色、佩戴位置规则 | +| ⑨ 妆容 Makeup | 12 季型 × 底妆/眼妆/唇妆 色值方案 | +| ⑩ 搭配法则 Rule | 结构化 IF-THEN 规则（供规则引擎执行）—— **核心资产** | +| ⑪ 搭配方案 Outfit | 成套 look（单品组合 + 配色公式 + 适配画像 + 试穿素材） | +| ⑫ 趋势 Trend | 时效性流行趋势，独立库、月更、过期降权 | #### 2.5.3 模态构成：7 种模态 @@ -390,7 +392,7 @@ V1 不做支付链路，在初级报告结果页保留「全面报告」预览 - 所有 AI 生成走**异步任务队列**，返回 `task_id`，前端轮询或长连接获取状态 - 用户可最小化任务、退出页面甚至退出 App，完成后**推送通知**召回 -- 任务中心统一展示进行中/已完成/失败任务，失败可一键重试（不重复计费） +- 任务中心统一展示进行中/已完成/失败任务，失败可一键重试（**不重复扣减配额**） - 生成过程**步骤可视化**（识别人像 → 测算体型 → 分析面部 → 采样色彩 → 生成方案），并展示已等待秒数 - 等待期填充内容：美学小知识卡、报告样例、热门搭配 - 端侧**前置质量校验**（是否人像/单人/全身/清晰/光线），不合格直接拦截，既省成本又省用户时间 @@ -436,21 +438,31 @@ V1 不做支付链路，在初级报告结果页保留「全面报告」预览 原方案设定"会员 ¥9.9/月 = 无限换装"，在成本上不成立：换装是长耗时 GPU 推理（几十秒到几分钟），单次成本在角到元量级，重度用户单月可消耗数十元，**会员越活跃越亏损**。 -**V1 的解法比点数制更彻底：干脆不收费，只限量**（`TD-28`）。不收费就没有"付费用户应该无限用"的压力，配额可以是纯粹的硬限制，月度成本上限因此变成可以事前算准的确定值（§5.3.1）。点数制留给 V2 —— 届时有了 V1 的真实成本数据，点数消耗比才有依据。 +**V1 的解法比点数制更彻底：干脆不收费，只限量**（`TD-28`）。不收费就没有"付费用户应该无限用"的压力，配额可以设得紧、熔断可以设得狠，不必担心损害已付费用户的权益。点数制留给 V2 —— 届时有了 V1 的真实成本数据，点数消耗比才有依据。 + +> ⚠️ **但要澄清一个常见误解**：配额**不等于**总成本封顶。配额约束单个用户，总成本 = MAU × 人均，而 MAU 无上限。真正封顶的是**全局日成本熔断**（`NFR-COST-02`），详见 §5.3.1。 ### 3.2 V1 配额设计（唯一在 V1 生效的一张表） -V1 无付费、无会员、无点数购买，**所有用户使用同一套配额**。额度用尽后只有两条路：等自然恢复，或做任务换额度。 +V1 无付费、无会员、无点数购买，**所有注册用户使用同一套配额**。额度用尽后只有两条路：等自然恢复，或做任务换额度。 -| 能力 | 基础额度 | 可通过任务额外获得 | 硬上限（防刷） | -|------|---------|------------------|--------------| -| 初级美学报告（首次） | 1 次（终身） | — | — | -| 报告重新生成 | 每 30 天 1 次 | +1 次/月 | 每日 ≤ 2 | -| 换装试穿 | **每日 3 次** | +3 次/日 | 每日 ≤ 8 | -| 发型 / 发色试戴 | **每日 3 次** | +2 次/日 | 每日 ≤ 6 | -| AI 对话 | **每日 10 轮** | +10 轮/日 | 每日 ≤ 40 | -| 记忆条数 | 200 条 | — | — | -| 高清导出 | 每日 1 次 | — | 每日 ≤ 3 | +> 🔒 **本表是 V1 全部配额数值的唯一定义位置**（含游客）。`FR-ACC-02`、`FR-BILL-*`、用户系统 §2.4.1、`bl_quota_rule` 的初始化数据**一律引用本表**。 + +| 能力 | **游客**（设备维度，终身） | 注册用户基础额度 | 可通过任务额外获得 | 硬上限（防刷） | +|------|:---------------------:|---------|------------------|--------------| +| 初级美学报告（首次） | **1 次** | 1 次（终身） | — | — | +| 报告重新生成 | ❌ | 每 30 天 1 次 | +1 次/月 | 每日 ≤ 2 | +| 换装试穿 | **1 次** | **每日 3 次** | +3 次/日 | 每日 ≤ 8 | +| 发型 / 发色试戴 | **1 次** | **每日 3 次** | +2 次/日 | 每日 ≤ 6 | +| AI 对话 | **3 轮** | **每日 10 轮** | +10 轮/日 | 每日 ≤ 40 | +| 记忆条数 | 不写入长期记忆 | 200 条 | — | — | +| 高清导出 | ❌ | 每日 1 次 | — | 每日 ≤ 3 | + +**游客配额的三个要点**： + +1. **是终身额度，不是每日额度** —— 游客额度的目的是"让人尝一口就想注册"，每日恢复会让相当一部分用户永远不注册。 +2. **按设备维度计量**（设备指纹 + 匿名 ID），因此**必然可以被清数据绕过**。这是可接受的：游客额度极小，绕过的收益低于用户重装 App 的成本，不值得为它上强风控。 +3. **额度用尽必须是"引导登录"而非"静默失败"** —— 这是游客模式唯一的转化时机，做成一个报错就白费了。 **任务奖励额度的获取方式**（全部不涉及金钱）：每日签到、完善画像资料、给报告结论打反馈、邀请好友、分享报告长图。 @@ -476,7 +488,7 @@ V1 无付费、无会员、无点数购买，**所有用户使用同一套配额 | 高清导出 / 去水印 | ❌ | ✅ | ✅ | - **点数消耗与获取、扣减顺序**：V2 设计时确定。架构上已按「reserve → commit / refund 预扣三段式」预留（见《技术架构文档》§7.4），保证长耗时任务不会出现"扣了额度但没交付"。 -- **V1 与 V2 的衔接**：V1 的「配额账本」与 V2 的「点数账本」是同一张表的两种用法 —— V1 只有系统发放与消耗两种流水类型，V2 增加购买与赠送类型。这样 V2 不需要数据迁移。 +- **V1 与 V2 的衔接**：V1 的「配额账本」与 V2 的「点数账本」是同一张表的两种用法 —— V1 有 `system_grant`（系统发放）、`consume`（消耗）、`refund`（退还）**三种**流水类型，V2 增加 `purchase`（购买）与 `gift`（赠送）。这样 V2 不需要数据迁移。`refund` 不可省略：预扣三段式与熔断退还额度都依赖它。 ### 3.4 第一版的计量要求（不可裁剪） @@ -554,7 +566,7 @@ V1 不收费，但**计量是 V1 最重要的隐性交付物**，它决定 V2 | 资产 | 为什么难复制 | 投入方式 | |------|------------|---------| -| **美学知识库**（800 条专家规则 + 12 套色板 + 适配矩阵） | 需要专业形象顾问长期投入，无法靠大模型生成后直接使用 | 顾问合作 + 人审流水线 | +| **美学知识库**（专家规则 + 12 套色板 + 适配矩阵，规模见知识库 §9.1） | 需要专业形象顾问长期投入，无法靠大模型生成后直接使用 | **全职顾问**（`TD-27`）+ 人审流水线 | | **用户画像与记忆资产** | 数据随使用时长复利增长，用户迁移成本高 | 报告 + 记忆系统 | | **可试穿素材库**（白底单品图 + 属性标注） | 需要采集、抠图、标注的重投入，且是"建议→预览"闭环的唯一入口 | 素材运营流水线 | @@ -568,11 +580,13 @@ V1 不收费，但**计量是 V1 最重要的隐性交付物**，它决定 V2 - **形象档案化**：报告版本化 + 前后对比，把一次性内容变成长期资产 #### 4.3.3 快速迭代 -- **MVP 优先**：1-2 个月上线 MVP +- **MVP 优先**：以**里程碑出口条件**衡量进度，不承诺日历周期（见 §6 与《开发任务拆解》） - **用户反馈**：快速收集用户反馈 - **数据驱动**：基于数据优化产品 - **小步快跑**：持续快速迭代 +> ⚠️ **原「1-2 个月上线 MVP」已删除**。本项目的排期原则已改为「**不按人日估算，按实测产能倒排**」（`TD-27`、`T-P0-20`/`T-P0-21`）—— 关键路径是内容与素材生产，而它的产能必须先测出来才能倒排。在测出产能前给出日历承诺，只会得到一个必然被打破的承诺。 + --- ## 5. 商业模式 @@ -642,7 +656,17 @@ V1 不收费，但**计量是 V1 最重要的隐性交付物**，它决定 V2 | 初级美学报告 | ≤ ¥0.30 | 视觉分析 + LLM 生成 | | 全面美学报告 | ≤ ¥2.00 | 章节多、输出 token 大 | | Agent 单轮对话 | ≤ ¥0.05 | 含 RAG 检索 | -| **免费用户月成本上限** | **≤ ¥8** | 按每日 3 次换装 + 3 次发型 + 10 轮对话的额度上限倒推 | +| 高清导出 | ≤ ¥0.02 | 服务端渲染 | + +**单用户月度成本必须分三档说清，不能只给一个数**（此前只写「≤ ¥8」，既算不出来也误导了成本封顶的论证）： + +| 档位 | 口径 | 单用户月成本 | 用途 | +|------|------|------------|------| +| ① 物理上限 | 防刷硬上限**天天打满**（8 换装 + 6 发型 + 40 对话 + 2 报告重生成 + 3 导出 = ¥7.86/日） | **≈ ¥236** | 单用户成本的绝对天花板，任何用户都不可能超过 | +| ② 重度用户 | 基础额度 + 任务奖励天天用满（6 + 5 + 20 = ¥5.0/日） | **≈ ¥150** | 极少数深度用户的实际量级 | +| ③ 人均预期 | 由 §8.2.2 用量推算 ÷ MAU 反算 | **≈ ¥0.8** | **预算口径**，含使用率假设，见 §5.3.1 | + +**①②③ 相差两个数量级不是矛盾，而是「配额上限」与「实际使用率」的差别** —— 绝大多数用户远远用不满额度。做预算必须用 ③，谈风险必须看 ①。 **成本控制手段**：端侧预检拦截无效请求、结构化结论走规则引擎不走 LLM、LLM 固定前缀设计以最大化 Prompt 缓存命中（输入成本可降至 1/5~1/30）、相同参数结果缓存、模板化减少输出 token、分级画质、免费用户错峰排队、GPU 实例按需启停。 @@ -683,12 +707,23 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 | 项 | V1 目标 | 说明 | |---|---------|------| -| 月度 AI 总成本（MAU 15 万口径） | **≤ ¥12 万/月** | 由配额上限硬性决定，不随用户行为失控 | -| 单免费用户月度 AI 成本 | ≤ ¥8 | 见 §5.2.1，配额倒推 | +| 月度 AI 总成本（MAU 15 万口径） | **¥7~12 万/月（预期，含假设）** | 由 §8.2.2 用量推算 × §5.2.1 单次成本得出，**不是硬上限** | +| 单用户月度 AI 成本（人均） | ≈ ¥0.8 | §5.2.1 档位③；物理上限为 ¥236，见该表 | +| **日成本熔断阈值** | **¥5,000/日** | **这才是真正的成本封顶机制**，见下方 | | 知识库一次性建设投入 | ¥12~18 万 | 含全职顾问、素材自采、抠图标注 | | **必须采齐的数据** | 单次真实成本 / 人均使用频次 / 预约率 | **这是 V1 唯一的"商业产出"** | -**成本封顶为什么能成立**：配额是硬限制而非软提示 —— 额度用尽时服务端直接拒绝，不存在超额消耗的路径。因此月度成本上限 = MAU × 单用户配额成本上限，是可以事前算准的确定值，而不是需要事后控制的风险项。这是"不收费"换来的一个额外好处：不收费就没有"付费用户应该无限用"的压力。 +**¥7~12 万是怎么来的**（可复算）：报告 3~5 万份 × ¥0.3 + 试穿 8~12 万次 × ¥0.5 + 发型 4~6 万次 × ¥0.2 + 对话 30~50 万轮 × ¥0.05 = **¥7.2~11.2 万/月**。 + +**它隐含一条必须写明的假设**：人均每月约 1 次试穿 + 几轮对话。这与本产品「低频决策型工具」的定位一致（也正是 §8.1.1 用季度回访率而非 DAU 考核的原因），但**它是假设，不是保证** —— V1 上线后由 `ob_ai_call` 实测校准，这是 `T-P1-25` 计量埋点不可裁剪的直接原因。 + +> ⚠️ **此处原有一个错误论证，已更正**：原文称「月度成本上限 = MAU × 单用户配额成本上限，是可以事前算准的确定值」。**这个推理不成立**，有两个漏洞： +> ① 数字算不平 —— 15 万 × ¥8 = ¥120 万，与 ¥12 万差 10 倍； +> ② **更根本的是，按人头发配额封不住总成本**。配额约束的是「单个用户能用多少」，而总成本 = MAU × 人均，**MAU 没有上限**。用户涨到 50 万、或人均使用强度超出假设 5 倍，成本都会线性上涨且没有任何天花板。配额防的是"单个用户刷爆"，防不了"总量涨爆"。 + +**真正让成本封顶的是全局日成本熔断**（`NFR-COST-02`，V1 必须实现）：平台当日累计 AI 成本触及阈值时，系统**自动降级而非仅告警** —— 依次关闭非核心 AI 能力（先停高清导出与报告重生成 → 再停发型 → 最后只保留已付出成本的在途任务），并向用户展示「今日服务繁忙，请明天再试」。这是唯一与用户规模无关的硬闸门，也是"不收费"模式下唯一可靠的止损手段。 + +**"不收费"确实带来一个真实的成本好处**，但不是"上限可算准"：不收费就没有"付费用户应该无限用"的预期压力，因此配额可以设得紧、熔断可以设得狠，**不必担心因限流而损害已付费用户的权益**。这在 V2 收费后会变成一个真实的两难。 #### 5.3.2 V2 起的盈利预测 @@ -752,7 +787,9 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 **Phase 0 出口条件**（已按备案完成调整）：六项技术验证有明确结论；本体 Schema 与发型打标完成；全职顾问到岗且规则库产出节奏可测算；自采流水线跑通首批 20 件单品；**备案编号公示位已在端上预留**。 -### 6.1 Phase 1：MVP（1-2 个月） +### 6.1 Phase 1 = V1：MVP + +> **周期以出口条件衡量，不设日历周期**（原「1-2 个月」已删除，理由见 §4.3.3）。里程碑与依赖关系见《开发任务拆解》§1。 #### 6.1.1 目标 - 验证市场需求 @@ -803,7 +840,7 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - [ ] 单品素材 300 件（含白底试穿图）+ 抠图流水线 - [ ] 搭配方案 100 套（含试穿素材绑定） - [ ] 混合检索链路（硬过滤 + 向量召回 + 重排） - - [ ] 黄金评测集 200 条 + 回归测试脚本 + - [ ] 黄金评测集 **330 例，分四个子集**（检索 100 / Agent 问答 100 / 诊断 100 / 报告结构 30，见知识库 §7）+ 回归测试脚本 - [ ] **Agent 基础能力** - [ ] 大模型选型与对接、流式输出 @@ -831,7 +868,7 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - 用户反馈报告、技术验证报告 - **单用户成本报告与付费意愿验证结论**（V2 定价依据） -### 6.2 Phase 2 = V2：核心功能完善与商业化（2-3 个月） +### 6.2 Phase 2 = V2：核心功能完善与商业化 > **本阶段即 V2**。所有付费能力都在这里，**不属于 V1 范围**（`TD-28`）。 @@ -869,7 +906,7 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - [ ] 一衣多搭、衣橱体检、缺口建议 - [ ] **知识库扩充** - - [ ] 规则扩充至 800 条、方案至 300 套、素材至 800 件 + - [ ] 知识库规模由 V1 硬指标扩充至长期目标（规则 800~1200 条 / 方案 300~500 套 / 单品 800~1500 件，见知识库 §9.1） - [ ] **知识库管理后台**（增删改查 + 审核工作流 + 版本对比 + 效果看板） - [ ] 知识缺口周报机制 - [ ] 图谱层与「为什么推荐」解释链 @@ -894,7 +931,7 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - 知识库管理后台完整版 - **基于真实数据重做的财务模型与定价**（替代 §5.3.2 中已废弃的季度预测） -### 6.3 Phase 3：多端扩展（3-4 个月） +### 6.3 Phase 3：多端扩展 #### 6.3.1 目标 - 扩展多端（iOS / Android），**届时重新评估跨端方案**（保留鸿蒙原生另起跨端工程 / Uni-App-x / Flutter），判断依据是那时的鸿蒙生态成熟度与团队构成（`TD-01`、`T-P6-15`） @@ -974,7 +1011,8 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - **风险描述**：用户照片数据可能泄露或滥用；人脸信息处理不合规将面临监管处罚与下架风险 - **应对措施**： - 人脸信息**单独授权**，不可默认勾选，可单独撤回 - - 原始照片处理完即删（保留 ≤24h 仅用于任务重试），只保留派生特征与结论 + - **原始照片处理完即显式删除，临时桶生命周期 ≤ 2 小时兜底**，只保留派生特征与结论（唯一事实源：`CR-02` 与《合规与安全方案》§2.1.2） + - ⚠️ 原文写「保留 ≤24h 仅用于任务重试」**已废弃**，与本文 §7.3.4、`CR-02` 冲突。2 小时已足够覆盖重试窗口（最长任务 320s，重试上限 3 次），**24h 只是白担合规风险** —— 保留期越长，"存储的人脸信息数量"越可能被认定为非零，进而触发 10 万人备案义务 - 明确承诺照片不用于模型训练，并写入隐私政策 - 数据加密传输与存储，OSS 签名链接短时效 - 分享长图默认"结论版"（不含照片），降低泄露面 @@ -1192,21 +1230,30 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 | Agent 对话轮次 | 30~50 万轮/月 | LLM 成本主项 | #### 8.2.3 成本指标（新增，与收入指标同等重要） -- **单用户月度 AI 成本**：免费用户 ≤ ¥8，会员 ≤ ¥20 -- **单次成本**：换装 ≤ ¥0.50 / 发型 ≤ ¥0.20 / 初级报告 ≤ ¥0.30 / 全面报告 ≤ ¥2.00 / 对话 ≤ ¥0.05 +- **单次成本**：换装 ≤ ¥0.50 / 发型 ≤ ¥0.20 / 初级报告 ≤ ¥0.30 / 全面报告 ≤ ¥2.00 / 对话 ≤ ¥0.05（单一事实源：§5.2.1） +- **人均月度 AI 成本**：≈ ¥0.8（预期值，上线后按 `ob_ai_call` 实测校准；三档口径见 §5.2.1） +- **日成本**：≤ ¥4,000/日为健康区间，触及 **¥5,000/日自动熔断降级**（`NFR-COST-02`） - **无效调用率**（被预检拦截前的浪费调用）：< 5% - **缓存命中率**：> 20% -- **毛利率**：> 60%（V2 起考核） +- **毛利率**：> 60%（V2 起考核，V1 无收入不适用） ### 8.3 技术指标 #### 8.3.1 性能指标 -- **接口响应**：换装 <320s（P95），发型 <120s（P95） -- **报告生成**：初级 <60s（P95），全面 <5min（P95） -- **Agent 首字延迟**：<2s（P95） -- **知识库检索**：硬过滤 <50ms，向量召回 <200ms（P95） -- **系统可用性**：>99.9% -- **错误率**：<0.1% + +> 🔗 **性能指标的唯一定义位置是《需求规格说明》§4.1**（编号 `NFR-PERF-01`~`08`、`NFR-REL-01`）。本节不再复述数值，避免出现第二套口径。 + +本轮收口时修正了本节原有的四处数值，理由记录如下： + +| 原值 | 现口径 | 修正理由 | +|------|--------|---------| +| 初级报告 < 60s | `NFR-PERF-03`：p95 < 90s | 视觉分析 + LLM + 渲染串行，60s 过紧 | +| 全面报告 < 5min | `NFR-PERF-04`：p95 < 180s | 且明确为 V2 指标，V2 立项时重新基线 | +| 换装 < 320s | `NFR-PERF-05`：**两段式**（现状基线 → 40s 优化目标） | 320s 是现状、40s 是目标，两者不是同一件事，须分开表达 | +| 系统可用性 > 99.9% | `NFR-REL-01`：**≥ 99.5%** | **V1 单可用区 Docker Compose 部署，无跨区冗余，99.9% 在架构上无法兑现** | + +- **Agent 首字延迟 < 2s** 是唯一在体验上关键的延迟指标（输出为流式），整轮完成时间见 `NFR-PERF-02b` +- **错误率**：< 0.1% #### 8.3.2 质量指标 - **崩溃率**：<0.1% @@ -1219,7 +1266,18 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - **合规审计**：100% 通过 - **用户禁忌项违反率**：**0**（推荐了用户明确拒绝的品类/风格，视为 P0 缺陷） - **知识准确率**：≥ 95%（黄金评测集） -- **诊断准确率**：体型 ≥85%、脸型 ≥80%、四季季型 ≥80% + +**诊断准确率必须分两档，此前两套数值互相冲突的根源就是没区分它们**（单一事实源：《美学报告-需求文档》§9.4）： + +| 指标 | ① Phase 0 验证门槛 | ② 上线质量门槛 | 两档的作用不同 | +|------|-----------------|-------------|--------------| +| 体型识别 | ≥ 80% | ≥ 85% | ①判断"这条技术路线是否走得通"（不达标就换方案）；②判断"能否交付给用户" | +| 四季季型 | ≥ 75% | ≥ 80% | 同上 | +| 脸型识别 | ≥ 75% | ≥ 80% | 同上 | +| 意图识别 | ≥ 85% | ≥ 90% | 同上 | + +- ①由 `T-P0-10`/`T-P0-11` 在 Phase 0 用小样本验证，**未达标则触发方案切换**（`TD-05`/`TD-06` 的备选路径） +- ②由上线前黄金集全量回归验收，**未达标则该维度降级为"仅供参考"或不展示**，而不是延期上线 --- @@ -1265,7 +1323,7 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - [ ] 目标用户访谈（重点验证：是否愿意为形象报告付费、心理价位） - [ ] 需求验证 - [ ] 竞品分析 -- [ ] 市场数据信源补齐（§4.1 待办） +- [x] ~~市场数据信源补齐~~ —— **已完成**（`TD-30`）：§4.1 已全部替换为国家统计局、CNNIC、华为 HDC 2026 的可核实数据 ### 9.2 2 周内完成 @@ -1288,7 +1346,9 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 - [ ] 运营计划 - [ ] 预算规划 -### 9.3 1 个月内 +### 9.3 后续（按里程碑出口条件推进，不设日历周期） + +> 原标题「1 个月内」已删除 —— 与「按实测产能倒排」的排期原则冲突（见 §4.3.3）。下列内容对应《开发任务拆解》的 M1~M5，各里程碑的出口条件见该文档。 #### 9.3.1 MVP 开发 - [ ] 接口集成（换装/发型） @@ -1391,10 +1451,17 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 ### 10.4 参考资料 -#### 10.4.1 行业报告（待补齐信源） -- 《2025年中国时尚电商行业报告》——待确认发布机构与时间 -- 《AI美妆行业发展趋势白皮书》——待确认发布机构与时间 -- 《鸿蒙生态发展报告》——待确认发布机构与时间 +#### 10.4.1 数据信源（已收口） + +> ⚠️ 原列的三条「待确认发布机构与时间」的行业报告**已全部删除**（`TD-30`）。它们无法核实来源，属于不可引用的数据。§4.1 已改用下列可核实的官方信源： + +| 信源 | 用途 | 出处 | +|------|------|------| +| 国家统计局 | 服装与化妆品零售大盘 | 官方统计公报 | +| CNNIC 第 57 次《中国互联网络发展状况统计报告》 | 生成式 AI 用户规模与普及率 | CNNIC 官网 | +| 华为 HDC 2026 | HarmonyOS 终端规模（**可触达基数口径**，非含 IoT 的生态总数） | 华为官方发布 | + +**引用纪律**：凡属本方案推算的数字，必须显式标注「推算」并给出推算口径，**不与官方数据混排**。 #### 10.4.2 合规法规依据 @@ -1451,6 +1518,9 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 | 19 | 华为 IAP 与企业开发者资质 | ✅ V1 不接支付，IAP 不涉及；一键登录降级为 P1，V1 用华为账号授权登录 + 手机号验证码 | `TD-29` | | 20 | 市场数据信源 | ✅ **已全部替换为官方可核实信源**（国家统计局、CNNIC、华为 HDC 2026）；并据此下调用户规模目标 | `TD-30`、§4.1、§8.1.1 | | 21 | 五行/命理模块 | ✅ **不做**（V1 与 V2 均不纳入），规避应用市场审核风险 | `TD-31` | +| 22 | 短信验证码通道 | ✅ **腾讯云短信**，与云厂商收口一致。**V1 必需** —— 它是华为账号之外唯一的独立登录通道（一键登录已推 V2），须配套三重频控与刷量告警 | `TD-32`、`FR-ACC-04/14` | +| 23 | 天气数据源 | ✅ **V1 不接天气 API**。Agent 遇天气问题时反问用户或按城市月份推断气候区，**绝不编造具体温度与降水**。省掉一项定位权限与一条工程链路 | `TD-33` | +| 24 | 成本封顶机制 | ✅ **配额不封顶总成本**（总成本 = MAU × 人均，MAU 无上限），真正封顶的是**全局日成本熔断**（四档自动降级，非仅告警） | `NFR-COST-02`、§5.3.1 | ### 11.2 仍待业务输入 @@ -1462,12 +1532,23 @@ V1 不接入支付，因此**本节对 V1 不产生任何影响**。但 V2 定 --- -**文档版本**：v6.0 +**文档版本**：v6.1 **创建日期**：2026-08-04 **更新日期**：2026-08-13 **作者**：产品团队 **状态**：待评审 **变更说明**： +- v6.1（2026-08-13）：文档一致性评审修订（见《文档评审报告-2026-08-13》） + - **§5.2.1 / §5.3.1 成本口径彻底重写，并推翻一个错误论证**。原文称「月度成本上限 = MAU × 单用户配额成本上限，是可事前算准的确定值」，有两个漏洞：① 数字算不平（15 万 × ¥8 = ¥120 万 ≠ ¥12 万）；② **更根本的是，按人头发配额封不住总成本** —— 配额约束单用户，而总成本 = MAU × 人均，MAU 无上限。现改为：单用户成本分**物理上限 ¥236 / 重度 ¥150 / 人均预期 ¥0.8** 三档；总成本 ¥7~12 万定性为**预期值（含使用率假设）而非硬上限**，并给出可复算的算式；**新增「全局日成本熔断」为唯一真正的封顶机制**（`NFR-COST-02`，四档自动降级，非仅告警） + - **§8.3.1 性能指标改为引用 `NFR-PERF-*`**，不再自成一套。连带修正四处：初级报告 60s→90s、全面报告 5min→180s、换装改「现状基线 → 目标值」两段式、**可用性 99.9%→99.5%**（V1 单可用区无冗余，99.9% 在架构上无法兑现） + - **§8.3.3 诊断准确率拆为「Phase 0 验证门槛 / 上线质量门槛」两档**，此前两套数值冲突的根源就是没区分这两档（两者的失败后果完全不同：前者触发换方案，后者触发维度降级） + - **§3.2 配额表补入「游客」列并升为唯一事实源**，此前游客额度只写在正文叙述里，导致 `FR-ACC-02` 无法验收 + - **§2.2.1 维度覆盖改为准确口径**：初级覆盖 21/32 项（首屏突出 8 项核心结论），全面覆盖 32 项。原「8 项核心 / 40+ 项完整」中的 40+ 在字典里根本不存在 + - **§7.1.4 人脸原图保留期由 ≤24h 改为「处理完即删 + 临时桶 2 小时兜底」**，与本文 §7.3.4、`CR-02` 统一（2 小时已覆盖重试窗口，24h 只是白担合规风险） + - **§2.5.2 / §4.3.1 / §6.1.2 知识库规模改为引用知识库 §9.1**；黄金集改为「330 例分四子集」 + - **删除全部日历周期承诺**（§4.3.3「1-2 个月」、§6.1/§6.2/§6.3 标题周期、§9.3「1 个月内」），与「按实测产能倒排」的排期原则统一 + - **§11.1 决策表新增 3 项**（`TD-32` 短信通道、`TD-33` 天气数据源、成本封顶机制），共 24 项 + - 措辞收口：「不重复计费」→「不重复扣减配额」；流水类型由「两种」更正为「三种」（`refund` 不可省略）；§10.4.1 三条无出处行业报告删除 - v6.0（2026-08-13）：业务决策全部收口，商业模式与市场数据重做 - **§5.0 新增「V1 不收费，只限量」**：V1 不接入任何支付能力，会员/点数/付费报告全部推到 V2。连带简化：无 IAP、无 30% 抽成、无交易类合规材料，billing 域降级为「配额账本 + 消耗流水」（`TD-28`、`TD-29`） - **§3 权益设计重构**：拆为「§3.2 V1 配额设计（唯一生效）」+「§3.3 V2 权益规划（仅架构预留）」+「§3.4 计量要求（不可裁剪）」。明确三条纪律：配额是服务端硬限制、V1 文案不出现价格字样、禁止静默扣减