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

> 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），参数先留。