meida/docs/试衣间与发型设计-产品方案.md

试衣间与发型设计 · 产品与技术方案

2026-08-29 ｜ 状态：Phase A 已交付（客户端直连内测版）｜ 关联：《产品方案》§2.1/§10.1、《技术架构文档》§4.4/§7.3/§9.3、《合规与安全方案》

1. 背景与调研结论

新增两个 P0 功能：试衣间（换装试穿） 与 发型设计（试戴 + 换发色）。开发前完成四路调研，结论如下。

1.1 对接目标：自有线上服务（唯一正确选择）

候选	结论
meida.xiangsilian.com（换装 + 发型）	✅ 采用。《产品方案》§2.1 明确指定；接口实测可用；发型 60 款在线
puton.huimeimeta.com（老 H5 试衣间）	❌ 素材 81% 失效（OSS 桶转私有），接口体系不同，放弃
puton-master 代码（桌面 Web 试衣间）	仅作交互参考：品类互斥选择、批量模式、「上衣+下装」组合逻辑可借鉴；UI 与接口层不可复用

1.2 线上服务实测契约（2026-08-29 实测）

换装 POST https://meida.xiangsilian.com/change_cloth_base64（JSON，图片 Base64）：

字段	说明
human_img	必填，人物照片 Base64
cloth_img	上衣图 Base64（仅传 human=单图编辑）
kuzi_img	裤子图；传了必须同时传 cloth_img
change_desc	提示词，空=工作流默认

• 同步返回 {ret:0, data:"<OSS签名URL>"}，须 ret===0 && data 判成功；耗时几十秒~几分钟，客户端超时须 ≥320s；建议图片长边压到 1024~2048。
• 健康检查 GET /health；Swagger 在线试调 /docs。

发型（同源 /hair/api 前缀，multipart/form-data，全部实测通过）：

• GET /hair/api/hairstyles → 60 款 {id, name, image_url}（image_url 为同源相对路径）；
• POST /hair/api/change-hair：image(File) + hairstyle_id → 结果直接内嵌 Base64 Data URL，实测 1056×1584 约 5.3s；
• POST /hair/api/change-hair-color：image + rgb（字符串化数组 "[255, 0, 0]"，不是 hex）+ ratio(0~1，默认 0.9)，实测 ~6s；
• ⚠️ 发型接口不收 WebP（换装接口收）。App 侧统一转 JPEG 再传。

1.3 素材盘点

• 发型库：60 款在线可用（GET /hair/api/hairstyles 直接拉，无需内置）；
• 服装库：不可用——fitting-room-assets 里服装仅 2 张且是模特上身图；reference/cloth_pic 15 张平铺图格式标准但有品牌 logo，只做开发联调、不内置发布。Phase A 服装图由用户现场上传/拍摄；内置服装库依赖素材生产管线（抠图标准化 + tryon_ready 审核，见 §6）；
• 模特：不用内置——按合规要求「仅限本人照片」，用户上传/拍摄自己的全身照。

1.4 与架构文档的冲突与裁决

《技术架构文档》§10.1.4 要求「接口无认证，禁止客户端直连，必须服务端代理」；但后端 tryon 域目前只有骨架（无 tr_task 表、无路由、无 GPU worker）。裁决为两阶段：

• Phase A（本次交付，内测版）：客户端直连线上服务。边界：仅限内测/调试构建，不公开放量；结果图不落库、不提供分享出口；不接入配额扣减（个人页配额卡保持只读展示）。目的是先把功能与体验跑起来、验证效果与耗时基线（T-P0-13/14）。
• Phase B（正式版前置）：后端补齐 tryon 域（表 + 5 个 §9.3 端点 + gpu worker + 八步链路），App 切到 /api/v1/tryon/* 代理，届时接入配额三段式、IMS 审核、AI 水印 + 内容编号、COS 转存。Phase B 未完成的构建不得对外发布（合规红线：结果图必须带显式 AI 水印 + 隐式标识）。

2. 功能设计

2.1 入口

首页新增两张入口卡：「试衣间」（换装试穿）、「发型设计」（试戴 + 换发色），与「生成我的形象报告」「AI 穿搭顾问」并列。

2.2 试衣间流程（对齐产品方案 §2.1.1 七步）

1. 上传/拍摄本人正面全身照（页面明示合规提示：仅限本人照片）；
2. 上传/拍摄上衣图（必选）、裤子图（可选；选了裤子才走上下装流程）；
3. 可选提示词（高级，默认折叠）；
4. 点「开始试穿」→ 长等待态（显示已等待秒数 + 阶段文案，超时 320s）；
5. 结果页：原图/结果左右对比（点按切换）、保存到相册、再来一次。

Phase A 不做：内置服装库、批量模式、专题试衣间、购买链接（这些依赖素材管线与电商对接，见 §6）。

2.3 发型设计流程（对齐产品方案 §2.1.2）

1. 上传/拍摄面部特写（肩部以上，正对镜头）；
2. 发型网格（在线拉 60 款，缩略图 + 名称）；
3. 点选即试戴（5~10s，进度条）；结果与原图点按切换对比；
4. 满意后可继续「换发色」：预设色板（自然黑/深棕/栗色/蜜茶/亚麻灰/酒红等 8 色）+ 强度滑杆（0~1，默认 0.9），换色作用于当前结果图；
5. 保存到相册 / 换一张重试。

2.4 异常与降级

• 换装：400 参数错误提示重拍/换图；502/503/504 提示「服务繁忙稍后重试」；超时（>320s）主动中止并提示；
• 发型：HTTP 400 按服务端 message 原样提示（「请上传图片」「请选择发型」等）；失败保留当前图不覆盖；
• 两页均在生成前校验：已选照片、已选单品/发型，不满足则按钮禁用。

3. App 技术方案（Phase A 已实现）

ets/core/TryonApi.ets      # 线上服务直连封装（换装 JSON+Base64 / 发型 multipart）
ets/core/ImageCodec.ets    # 选图 → 压长边 ≤1600 → JPEG(85%) → Base64/ArrayBuffer
ets/pages/TryonPage.ets    # 试衣间
ets/pages/HairDesignPage.ets # 发型设计
HomePage.ets               # +2 入口卡；main_pages.json +2 路由

• 图片压缩：解码时按 desiredSize 缩到长边 1600，重编码 JPEG quality=85，Base64 体积可控（~300KB 级）；
• 超时：换装 readTimeout=320000ms；发型 readTimeout=120000ms；
• 结果展示：换装返回 OSS URL 直接 Image 加载；发型返回 Base64 Data URL 解码为 PixelMap 展示；
• 保存相册：结果先写 cacheDir，再 photoAccessHelper.showAssetsCreationDialog（免权限弹系统确认）；
• 不在 Phase A 做：配额扣减、任务中心、水印、分享、历史记录（线上服务无客户端可用的历史接口）。

4. 验收标准（Phase A）

1. 构建绿（assembleHap）；真机两页全流程可跑通；
2. 换装：全身照 + 上衣（±裤子）出图，等待有秒数反馈，失败有明确提示；
3. 发型：60 款列表加载、试戴 ≤15s 出图、换发色生效、可保存相册；
4. 两页均有「仅限本人照片」合规提示；
5. 实测数据回填：换装 P50 耗时、发型试戴 P50 耗时（喂给 T-P0-13/14 基线）。

5. Phase B 清单（正式版前置，未做）

1. 后端 tryon 域：tr_task/tr_favorite 表、POST /api/v1/tryon/tasks 等 5 端点（架构 §9.3）、gpu 队列 worker、八步链路（§7.3）；
2. 线上服务八项改造（§4.4：鉴权、任务化、幂等键、并发上限、gpu_seconds 埋点、OSS→COS、前置校验、版本号）；
3. App 切代理接口，接入配额三段式（tryon 3/3/8、hairstyle 3/2/6）与消耗前剩余提示；
4. 合规出口：IMS 审核 + 「AI 生成」显式水印 + EXIF 隐式标识 + 27 位内容编号 + COS 用户桶转存（《合规与安全方案》CR-05/06）；
5. 素材管线：服装抠图标准化 → tryon_ready 审核 → 内置服装库；60 款发型人工打适配标签（1~2 人日，T-P0-24）；
6. Agent 联动（P1/V2）：对话卡片「试穿此搭配」「试戴此发型」带参跳转本两页（参数预留见 §7）。

6. 素材生产需求（给运营/算法）

• 内置服装库目标 ≥300 件 tryon_ready（架构风险线）：拍摄 SOP（平铺白底、单品完整、无 logo 遮挡）→ matting-svc 抠图 → 运营审核；
• 模特图不需要生产（合规限定本人照片）；
• reference/cloth_pic 仅作开发联调测试集，禁止内置（品牌 logo 版权风险）。

7. 预留：Agent 联动参数（Phase B 用，本次已留口子）

两页 aboutToAppear 读取 router.getParams()：TryonPage 支持 {cloth_img?, kuzi_img?, change_desc?}（base64/本地路径）；HairDesignPage 支持 {hairstyle_id?}。当前 Agent 卡片按钮未做（V2），参数先留。