save

2026-08-13 23:10:49 +08:00
parent d784d4ae15
commit e31755e343
11 changed files with 4063 additions and 305 deletions
@@ -30,12 +30,17 @@

 ### 2.1 账号与登录

-| 方式 | 优先级 | 说明 |
-|------|-------|------|
-| **华为账号一键登录** | P0（鸿蒙首发主路径） | 首发平台原生能力，转化率最高，V1 必须支持 |
-| 手机号 + 验证码 | P0 | 通用兜底，跨端一致 |
-| **游客模式** | P0 | 未登录即可体验核心功能，降低首启流失 |
-| 微信 / Apple 登录 | P2 | 多端扩展阶段接入 |
+| 方式 | 优先级 | 版本 | 说明 |
+|------|-------|:----:|------|
+| **华为账号授权登录**（UnionID/OpenID） | P0（鸿蒙首发主路径） | V1 | 标准 OAuth 授权，**无特殊资质门槛** |
+| 手机号 + 验证码 | P0 | V1 | 通用兜底，覆盖不愿授权华为账号的用户 |
+| **游客模式** | P0 | V1 | 未登录即可体验核心功能，降低首启流失 |
+| ⏸ 华为账号**一键登录**（直接获取绑定手机号） | **P1（降级）** | **V2** | ⚠️ 需**企业开发者资质** + `quickLoginMobilePhone` scope。V1 不做（`TD-29`） |
+| 微信 / Apple 登录 | P2 | V2+ | 多端扩展阶段接入 |
+
+> **为什么一键登录从 P0 降为 P1**：它需要企业开发者资质与额外 scope 申请，而它带来的收益只是"少输一次验证码"——**这是体验优化，不是能力缺口**。为它阻塞 V1 排期不值得。登录模块按多方式抽象设计，资质到位后补上属于纯增量改动（`TD-29`）。
+>
+> **仍需保留的前置项**：AGC 的 **SHA256 证书指纹需配置两套**（调试证书与发布证书），且指纹添加后最迟 25 小时生效。这与资质等级无关，漏配会导致登录**在发布包中直接失败而调试包正常** —— 这是个高频踩坑点，必须写入发布手册。

 #### 游客模式与数据迁移（关键设计）

@@ -58,10 +63,10 @@
 | `huawei_open_id` | string | 华为账号标识 |
 | `nickname` / `avatar` | string | 昵称、头像 |
 | `gender` | enum | 女 / 男 / 不便告知 |
-| `birthday` | date | 生日（用于色彩、五行、生日权益） |
-| `member_level` | enum | free / member / premium |
-| `member_expire_at` | datetime | 会员到期时间 |
-| `points_balance` | int | 权益点数余额（见 §2.4） |
+| `birthday` | date | 生日。**用途限于生日权益与年龄段判断**，五行推算已取消（`TD-31`） |
+| `member_level` | enum | free / member / premium。**V1 恒为 `free`**，字段预留 |
+| `member_expire_at` | datetime | 会员到期时间。**V1 恒为空**，字段预留 |
+| ~~`points_balance`~~ | — | **不放在主表**。余额统一存 `bl_wallet.balance`，以 `bl_ledger` 流水为真相（架构 §6.2）。在主表冗余余额会引入两处数据不一致的风险，而余额是最不能出错的字段 |
 | `register_channel` | string | 注册渠道（归因） |
 | `status` | enum | active / frozen / deleting / deleted |
 | `created_at` / `last_active_at` | datetime | — |
@@ -91,48 +96,73 @@
 │   ├─ 发型记录
 │   └─ 收藏夹（搭配 / 发型 / 单品 / 色板）
 ├─ 我的衣橱（V2）
-├─ 会员中心（权益、点数、订单）
+├─ 我的额度（剩余次数、任务换额度）   ← V1；无价格与购买入口
+│   └─ 会员中心（权益、点数、订单）    ← V2
 ├─ 设置
 │   ├─ 隐私与授权管理（单项开关、撤回）
 │   ├─ 数据管理（导出个人数据 / 清空照片 / 注销账号）
-│   ├─ 内容偏好（关闭五行模块、关闭个性化推荐）
+│   ├─ 内容偏好（关闭个性化推荐）
+│   ├─ 关于（**模型名称 + 备案编号公示**，合规必需）
 │   └─ 通知设置
 └─ 帮助与反馈
 ```

-### 2.4 会员与权益（含点数制改造）
+### 2.4 权益设计：V1 只有配额，没有付费

-**现存风险**：原方案"会员 ¥9.9/月 = 无限换装"在成本上不成立。换装单次为长耗时 GPU 推理（几十秒到几分钟），单次成本量级在角到元，重度用户一个月可轻松消耗数十元，会员越活跃越亏损。
+**原方案的成本风险**："会员 ¥9.9/月 = 无限换装"在成本上不成立 —— 换装是长耗时 GPU 推理，单次成本在角到元量级，重度用户一个月可消耗数十元，**会员越活跃越亏损**。

-**改造方案：基础权益 + 点数制**
+**V1 的解法：完全不收费，用配额限制控成本**（`TD-28`）。

-| 权益项 | 免费 | 会员 ¥9.9/月 | 高级 ¥29.9/月 |
-|--------|------|-------------|--------------|
-| 每日免费换装 | 3 次 | 10 次 | 20 次 |
-| 每日免费试戴发型 | 3 次 | 10 次 | 20 次 |
+#### 2.4.1 V1 配额表（唯一生效的一张表）
+
+所有用户共用同一套配额，无会员、无点数购买。
+
+| 能力 | 基础额度 | 任务可额外获得 | 硬上限（防刷） |
+|------|---------|--------------|--------------|
+| 初级美学报告（首次） | 1 次（终身） | — | — |
+| 报告重新生成 | 每 30 天 1 次 | +1 次/月 | 每日 ≤ 2 |
+| 换装试穿 | 每日 3 次 | +3 次/日 | 每日 ≤ 8 |
+| 发型 / 发色试戴 | 每日 3 次 | +2 次/日 | 每日 ≤ 6 |
+| AI 对话 | 每日 10 轮 | +10 轮/日 | 每日 ≤ 40 |
+| 记忆条数 | 200 条 | — | — |
+| 高清导出 | 每日 1 次 | — | 每日 ≤ 3 |
+
+**任务奖励额度**（全部不涉及金钱）：每日签到、完善画像资料、给报告结论打反馈、邀请好友、分享报告长图。
+
+**三条不可违反的纪律**：
+
+1. **额度是服务端硬限制**（`FR-BILL-06`）—— 服务端校验后直接拒绝，不存在绕过路径。这是成本可事前算准的前提。
+2. **文案中不出现任何价格或购买字样**（`FR-BILL-07`）—— 额度用尽的提示是「今日额度已用完，明天再来，或做个任务多换 3 次」，**不是**「升级会员解锁」。V1 出现价格暗示会污染 V2 的定价空间，也会让用户觉得这是个处处收费的产品。
+3. **每次消耗前置提示剩余量**，禁止静默扣减。
+
+#### 2.4.2 V2 权益规划（仅作架构预留，V1 不实现）
+
+> ⚠️ 下表价格全部为**占位**，需按 V1 采集的真实数据重算（`TD-16`、`T-P6-16`）。
+
+| 权益项 | 免费 | 会员 | 高级 |
+|--------|------|------|------|
+| 每日换装 / 发型 | 3 次 | 10 次 | 20 次 |
 | 每日 AI 对话 | 10 轮 | 100 轮 | 不限（防刷上限） |
-| 月度权益点数 | 0 | 300 点 | 1000 点 |
+| 月度权益点数 | 0 | 待定 | 待定 |
 | 初级美学报告 | 每 30 天 1 次 | 每 7 天 1 次 | 不限（每日 ≤3） |
-| 全面美学报告（V2） | 单次 ¥29.9 | 单次 ¥19.9 | 含 1 次/季 |
-| 广告 | 有 | 无 | 无 |
-| 我的衣橱容量（V2） | 20 件 | 200 件 | 不限 |
-| 记忆条数上限 | 50 条 | 500 条 | 不限 |
+| 全面美学报告 | 单次付费 | 折扣价 | 含 1 次/季 |
+| 我的衣橱容量 | 20 件 | 200 件 | 不限 |
+| 记忆条数上限 | 200 条 | 500 条 | 不限 |
 | 高清导出 / 去水印 | ❌ | ✅ | ✅ |

- **点数消耗**：换装 10 点/次、发型 5 点/次、全面报告 200 点、高清重绘 20 点
- **点数获取**：会员月度赠送、签到、邀请好友、观看激励广告、单独购买（¥6 = 100 点）
- **免费额度与点数关系**：先扣免费次数，用尽后扣点数，点数不足才引导付费
- 每次消耗都要有明确的前置提示（"本次将消耗 10 点，剩余 290 点"），禁止静默扣费
+**V1 → V2 免数据迁移的关键设计**：配额账本与点数账本是**同一张表**（`bl_wallet` + `bl_ledger`）。V1 只使用 `system_grant` / `consume` / `refund` 三种 `tx_type`，V2 增加 `purchase` / `gift`。消耗侧的预扣三段式逻辑完全复用，V2 只需新增「购买」这一条发放路径（架构 §6.2、§7.4）。

-> V1 落地范围：**只做免费额度与计量**（记录每次调用的成本与次数），会员/点数/支付在 V2 开启。V1 期间用埋点数据校准真实单用户成本，再定价。
+### 2.5 配额与计量（V1 最重要的隐性交付物）

-### 2.5 配额与计量
-
- 所有 AI 能力调用统一走**配额中心**：`check(user_id, ability) → allow/deny + 扣减方式`
- 每次调用落 `usage_log`：`user_id / ability / cost_estimate / duration / result / trace_id`
- 失败调用不扣额度（区分用户侧失败与服务端失败）
+- 所有 AI 能力调用统一走**配额中心**：`check(user_id, ability) → allow/deny`，**服务端校验，客户端提示仅为体验**
+- 消耗采用**预扣三段式**：`reserve`（冻结）→ `commit`（确认）/ `refund`（退还）。长耗时任务可能失败，直接扣会产生「扣了次数没拿到结果」的客诉 —— **V1 没有客服退款兜底手段，只能靠机制保证**
+- 每次调用落 `ob_ai_call`：`user_id / scene / provider / model / tokens / duration / cost / result / trace_id`
+- 每次额度变动落 `bl_ledger` 流水，余额可由流水重算校验，**每日自动对账，不一致告警**
+- 失败调用不扣额度（区分用户侧失败与服务端失败）；**预检拦截发生在预扣之前**，不合格照片不消耗额度
 - 风控：设备维度 + 账号维度 + IP 维度三重限流，异常账号冻结并进人工审核

+> ⚠️ **为什么 V1 不收费反而让计量更重要**：V1 没有收入，成本是唯一的财务变量；同时 `ob_ai_call` 与 `bl_ledger` 是 **V2 定价的唯一数据来源** —— 单次真实成本与人均使用频次都从这里出。**埋点缺失的功能，在 V2 定价时就是一个必须靠猜的空洞**。这一项不允许「先上线后补埋点」（`NFR-COST-01`、`FR-BILL-08`）。
+
 ### 2.6 账号生命周期

 | 操作 | 处理 |
@@ -314,15 +344,17 @@

 ### 3.9 存储与技术形态

+> 选型结论见《[技术选型与调研报告](./技术选型与调研报告.md)》`TD-02`/`TD-08`；表结构见《[技术架构文档](./技术架构文档.md)》§5.2。
+
 | 数据 | 存储 | 说明 |
 |------|------|------|
-| L0 / L1 / L2 结构化画像 | 关系型数据库 | 强一致、可索引、可审计 |
-| L3 事件与对话摘要 | 关系库 + 向量库 | 向量库用于语义召回 |
-| L4 会话状态 | KV 缓存（带 TTL） | 高频读写 |
-| L5 衣橱单品 | 关系库 + 对象存储（图片）+ 图像向量 | 支持图搜与属性筛选 |
-| 变更审计 | 追加写日志表 | 记录每次记忆变更的 before/after 与操作者 |
+| L0 / L1 / L2 结构化画像 | PostgreSQL | 强一致、可索引、可审计 |
+| L3 事件与对话摘要 | PostgreSQL + pgvector | 同一库内完成硬过滤与语义召回，不引入专用向量库 |
+| L4 会话状态 | Redis（带 TTL） | 高频读写 |
+| L5 衣橱单品 | PostgreSQL + COS（图片）+ pgvector（图像向量） | 支持图搜与属性筛选 |
+| 变更审计 | 追加写日志表 `memory_audit` | 记录每次记忆变更的 before/after 与操作者 |

- 端侧缓存画像摘要，支持弱网/离线时的基础个性化展示
+- 端侧仅缓存画像**摘要**，支持弱网/离线时的基础个性化展示；**不缓存记忆明文**（含体型尺寸等敏感项）
 - 所有记忆读写走统一 `MemoryService`，禁止各业务模块直连表，保证冲突消解与审计逻辑唯一

 ### 3.10 隐私与合规
@@ -372,9 +404,11 @@

 ### 5.1 用户系统
 - 游客 → 注册转化率 > 25%
- 华为账号一键登录占比 > 60%（首发平台）
+- **华为账号授权登录占比 > 60%**（首发平台；一键登录 V1 不做，故不考核其占比）
 - 登录成功率 > 99%，注销请求处理时效 100% 达标
 - 人脸授权通过率 > 60%
+- **配额对账差异 = 0**（每日校验余额与流水一致性）
+- **额度耗尽提示中出现价格字样的次数 = 0**（`FR-BILL-07` 的红线，发版前全文案扫描）

 ### 5.2 记忆系统
 | 指标 | 目标 | 意义 |
@@ -390,25 +424,70 @@

 ---

-## 6. 待确认事项
+## 6. 待确认事项（已收口）

- [ ] 华为账号登录的接入方式与 Uni-App-x 兼容性验证
- [ ] 游客数据迁移的边界情况（多设备、换机、重装）处理方案
- [ ] 向量库选型（自建 / 云服务）与成本评估
- [ ] 会员点数制的最终定价与点数消耗比（依赖 V1 真实成本数据）
- [ ] 隐式记忆推断的阈值与确认时机的 A/B 方案
- [ ] 记忆数据保留时长与法务确认（L3 事件建议 180 天）
- [ ] 是否支持家庭/多人档案（一个账号多个形象档案，如帮家人做诊断）——影响数据模型，建议 V1 预留 `profile_id` 字段
- [ ] 端侧记忆缓存的加密方案
+### 6.1 已确认
+
+| 原待确认项 | 结论 | 依据 |
+|-----------|------|------|
+| 华为账号登录接入方式 | 客户端改为**鸿蒙原生 ArkTS**，直接使用 **Account Kit**（`@kit.AccountKit`），不再涉及跨端框架兼容性问题。主登录取 UnionID/OpenID | `TD-01`、`TD-15` |
+| 用户主标识 | 内部主键用自有 `user_id`（雪花 ID），UnionID 存独立映射表。**不用手机号或 UnionID 做主键**，否则将来接入其他登录方式很难改 | 架构 §6.2 |
+| 向量库选型 | **PostgreSQL + pgvector**，不引入专用向量库。规模在十万级向量，且我们的检索是「强过滤 + 弱语义」，硬过滤与向量召回可在同一条 SQL 完成 | `TD-08` |
+| 记忆数据保留时长 | 对话原文 90 天；L3/L4 摘要 180 天；报告与画像随账号存续；注销后 7 日内彻底删除 | `CR-03`、合规方案 §4.3 |
+| 多形象档案 | V1 **仅预留 `pf_profile.profile_id`** 并创建默认档案，不做 UI | `FR-ACC-12` |
+| 端侧记忆缓存加密 | V1 **端侧不缓存记忆明文**。记忆快照在服务端组装与缓存（Redis），端侧只持有展示所需的片段。这样既避免端侧加密方案的复杂度，也减少泄露面 | 架构 §10 |
+| 记忆快照的性能方案 | 服务端 `pf_memory_snapshot` 表 + Redis 缓存，按 `content_hash` 变更才重建；记忆写入时按 `user_id` 主动失效 | 架构 §8.4 |
+
+| **V1 是否收费** | **完全不收费**（`TD-28`）。无会员、无点数购买、无 IAP。用配额硬限制控成本，额度用尽只有「等恢复」与「做任务换额度」两条路径，文案不出现价格字样 | `TD-28`、`FR-BILL-07` |
+| **登录方式** | V1 用「华为账号授权登录 + 手机号验证码」双通道；**一键登录降级为 P1 推至 V2**（需企业资质，属体验优化非能力缺口） | `TD-29`、`FR-ACC-13` |
+| **余额字段位置** | 余额存 `bl_wallet`，**不在 `user` 主表冗余** `points_balance`；以 `bl_ledger` 流水为真相 | 架构 §6.2 |
+| **配额账本与点数账本的关系** | **同一张表**。V1 用 `system_grant`/`consume`/`refund` 三种 `tx_type`，V2 增加 `purchase`/`gift`，V2 上支付**无需数据迁移** | 架构 §6.2、§7.4 |
+
+### 6.2 仍待业务输入
+
+本文档的待确认事项**已全部收口**，无遗留项。
+
+唯一保留的开放项属于 V2 范畴，且需 V1 数据支撑：
+
+- [ ] 隐式记忆推断的阈值与确认时机 A/B 方案 —— V2 功能（`FR-MEM-08`），需 V1 行为数据支撑
+- [ ] V2 定价与点数消耗比 —— 依赖 V1 的真实成本与频次数据，并需按 IAP 抽成后的到账口径计算（`T-P6-16`）
+
+### 6.3 本轮补充的关键约束
+
+| 约束 | 说明 | 依据 |
+|------|------|------|
+| 一键登录有资质门槛 | 华为账号一键登录（获取绑定手机号）**仅支持企业开发者**、仅面向中国大陆用户，需申请 `quickLoginMobilePhone` scope，且服务端必须部署在中国大陆。**已据此降级为 P1 推至 V2**（`TD-29`） | `TD-15` |
+| **证书指纹配置** | AGC 需配置 SHA256 证书指纹，**调试证书与发布证书是两套**，指纹添加后最迟 25 小时生效（改 `versionCode` 可加速）。⚠️ 漏配的表现是**调试包登录正常、发布包登录失败**，很容易在临上线时才暴露。必须写入发布手册 | `TD-15` |
+| ~~虚拟商品必须走 IAP~~ | **V1 不适用**（不接支付）。V2 起：会员、点数、全面报告均属虚拟商品，鸿蒙上必须接入 IAP Kit 并签署联运协议；Payment Kit 明确不支持虚拟商品；服务端必须做收据二次校验，`purchase_token` 唯一约束防重复发货 | `TD-16`、`FR-BILL-09` |
+| 配额消耗采用预扣三段式 | `reserve`（冻结）→ `commit`（确认）/ `refund`（退还）。长耗时任务可能失败，直接扣会产生「扣了次数没结果」的客诉 —— **V1 无客服退款兜底，只能靠机制保证**。所有变更写流水，余额可由流水重算对账 | `FR-BILL-05`、架构 §7.4 |
+| 游客合并策略 | 合并操作幂等；多设备场景以先登录设备为准并给用户明确提示 | `FR-ACC-03` |
+| **备案编号需在设置页公示** | 「设置 → 关于」固定展示模型名称与备案编号，入口硬编码不可隐藏，且展示内容须与 LLM 网关实际路由同源 | `CR-08`、合规方案 §2.2.4 |

 ---

-**文档版本**：v1.0
+**文档版本**：v1.2
 **创建日期**：2026-08-11
+**更新日期**：2026-08-13
 **作者**：产品团队
 **状态**：待评审
+**变更说明**：
+- 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 用「华为账号授权登录 + 手机号验证码」双通道。强调证书指纹双套配置漏配时"调试包正常、发布包失败"的表现
+  - **§2.2 移除主表 `points_balance` 字段**：余额统一存 `bl_wallet`，避免两处数据不一致；`member_level`/`member_expire_at` 保留为预留字段。`birthday` 用途收窄，五行推算已取消（`TD-31`）
+  - **§2.5 强化计量要求**：说明 V1 不收费反而让计量更重要 —— `ob_ai_call` 与 `bl_ledger` 是 V2 定价的唯一数据来源，不允许"先上线后补埋点"
+  - §2.3 用户中心新增「我的额度」与「关于（备案编号公示）」，移除五行模块开关
+  - §5.1 新增两项红线指标：配额对账差异 = 0、额度提示中价格字样出现次数 = 0
+- v1.1（2026-08-13）：§6 待确认事项收口，7 项确认、3 项转入业务输入；补充一键登录的企业开发者资质门槛与 scope 申请要求、证书指纹双套配置、虚拟商品强制 IAP 与抽成影响、点数预扣三段式；明确向量库为 pgvector、端侧不缓存记忆明文
+- v1.0（2026-08-11）：初始版本
+
 **关联文档**：
+- [文档索引](./README.md)
+- [需求规格说明](./需求规格说明.md)（本文需求对应 `FR-ACC-*`、`FR-MEM-*`、`FR-BILL-*`）
 - [美搭 · 智能穿搭美学助手 产品方案](./鸿蒙美搭-智能穿搭美学助手-产品方案.md)
+- [技术架构文档](./技术架构文档.md)（数据模型见 §6.2，记忆读写见 §8.4，配额与支付链路见 §7.4）
+- [技术选型与调研报告](./技术选型与调研报告.md)
+- [合规与安全方案](./合规与安全方案.md)
 - [美学报告需求文档](./美学报告-需求文档.md)
 - [穿搭 Agent 需求文档](./穿搭Agent-需求文档.md)
 - [美学知识库建设方案](./美学知识库-建设方案.md)