# 虚拟试衣运营后台前端 PRD

## 1. 文档信息

- 文档类型：前端产品需求文档（PRD）
- 文档目标：为一个新的前端项目提供可落地的信息架构、页面范围、接口映射、状态机与交付边界
- 适用对象：前端开发、前端负责人、交互设计、项目协作方
- 基准后端：当前仓库 `FastAPI + Temporal + SQLite + SQLAlchemy` 实现
- 文档基线日期：2026-03-27

## 2. 文档原则

本 PRD 严格基于当前后端代码和已验证逻辑编写，不假设后端存在未实现的能力。

这意味着：

- 已在当前后端中存在的 API 和状态，前端一期可以按真实联调设计
- 当前后端不存在的资源库、列表、登录等能力，只能写成占位模块或二期依赖
- 所有图像处理步骤当前仍为 mock，资产 URI 可能是 `mock://...`
- 人工修订稿当前不是二进制上传，而是通过 `uploaded_uri` 登记一个离线修订结果

## 3. 当前后端真实能力摘要

### 3.1 已存在的业务流程

- 低端全自动流程：`auto_basic`
- 中端半自动流程：`semi_pro`
- 中端审核决策：`approve`、`rerun_scene`、`rerun_face`、`rerun_fusion`
- 中端人工修订回流：
  - 注册离线修订稿
  - 查询单线版本链
  - 确认继续流水线

### 3.2 已存在的关键状态

- 客户层级：`low`、`mid`
- 服务模式：`auto_basic`、`semi_pro`
- 订单状态：`created`、`running`、`waiting_review`、`succeeded`、`failed`、`cancelled`
- 审核任务状态：`pending`、`revision_uploaded`、`submitted`
- 关键步骤：`prepare_model`、`tryon`、`scene`、`texture`、`face`、`fusion`、`qc`、`review`、`export`

### 3.3 已存在的 API

- `POST /api/v1/orders`
- `GET /api/v1/orders/{order_id}`
- `GET /api/v1/orders/{order_id}/assets`
- `POST /api/v1/orders/{order_id}/revisions`
- `GET /api/v1/orders/{order_id}/revisions`
- `GET /api/v1/reviews/pending`
- `POST /api/v1/reviews/{order_id}/submit`
- `POST /api/v1/reviews/{order_id}/confirm-revision`
- `GET /api/v1/workflows/{order_id}`

### 3.4 当前后端明确缺失的能力

- 订单列表接口
- 订单搜索/分页/筛选接口
- workflow 列表接口
- 模特库接口
- 场景库接口
- 服装库接口
- 登录、用户、角色、权限接口
- 真实文件上传接口
- 真实对象存储预览 URL

## 4. 产品目标

本前端项目的目标不是只做一个审核页，而是建立一个可扩展的运营后台前端壳子，首期重点覆盖以下两类核心用户：

- 提交任务的人：业务、运营、协作人员
- 审核任务的人：审核员、质检、人工修订协作人员

前端一期目标：

- 提供一个完整的后台导航与路由结构
- 让提单工作台能够基于现有后端真实创建订单
- 让审核工作台完整联调当前后端审核链路
- 让单订单详情与流程详情具备真实查看能力
- 为资源库、登录权限等未来能力预留清晰的信息架构

非目标：

- 一期不实现登录与权限
- 一期不实现真实资源库联调
- 一期不实现真实文件上传
- 一期不重构后端接口

## 5. 用户角色

### 5.1 提单员

职责：

- 创建订单
- 选择客户层级与服务模式
- 选择模特、场景、服装资源
- 提交任务并查看订单结果

### 5.2 审核员

职责：

- 查看待审核订单
- 决定 `approve` 或 `rerun_*`
- 发起人工修订稿登记
- 确认人工修订后的继续流水线

### 5.3 运营查看者

职责：

- 查看订单状态
- 查看流程执行状态
- 排查失败订单
- 跳转到详情页和审核页

### 5.4 系统管理员

首版仅预留，不实现真实能力。

未来职责：

- 用户管理
- 角色管理
- 权限管理
- 系统配置

## 6. 一期信息架构

### 6.1 一级导航

- `订单总览`
- `提单工作台`
- `审核工作台`
- `流程追踪`
- `资源库`
- `系统设置`

### 6.2 页面树

- `/orders`
- `/orders/:orderId`
- `/submit-workbench`
- `/reviews/workbench`
- `/workflows`
- `/workflows/:orderId`
- `/libraries/models`
- `/libraries/scenes`
- `/libraries/garments`
- `/settings`
- `/login`

### 6.3 首页策略

- 默认首页为 `/orders`
- 该页面作为后台默认入口
- 审核工作台为高频业务页，但不是默认首页
- 从订单总览可以跳转到订单详情和审核工作台

## 7. 模块说明

## 7.1 订单总览

### 页面目标

- 提供订单浏览和搜索入口
- 承接系统默认首页
- 支持跳转到订单详情
- 支持跳转到审核工作台

### 页面组件

- 顶部筛选区
- 订单搜索框
- 订单列表表格
- 状态标签
- 快速动作列
- 空状态与异常状态

### 用户路径

1. 进入首页
2. 搜索订单或浏览列表
3. 查看订单状态
4. 跳转订单详情或审核工作台

### 当前后端支撑情况

`不足`

原因：

- 当前没有订单列表接口
- 当前没有分页、筛选、搜索接口

### 一期实现策略

- 页面保留为正式模块
- 首版可采用以下过渡方式之一：
  - 订单号直达查询
  - 最近访问订单缓存
  - 前端 mock 数据演示

### 后端依赖

- 新增订单列表接口
- 新增订单筛选/搜索接口

## 7.2 提单工作台

### 页面目标

- 为业务或运营提供单独的任务提交工作台
- 支持创建新订单
- 为未来资源库接入预留完整交互结构

### 页面组件

- 客户层级选择
- 服务模式选择
- 模特选择区
- 场景选择区
- 服装选择区
- pose 输入区
- 参数预览卡
- 提交按钮
- 提交结果反馈

### 用户路径

1. 选择客户层级
2. 选择服务模式
3. 选择模特/场景/服装
4. 检查参数摘要
5. 提交订单
6. 跳转到订单详情页

### 当前后端支撑情况

`部分支撑`

已存在能力：

- `POST /api/v1/orders`

缺口：

- 模特、场景、服装没有查询接口

### 一期实现策略

- 表单提交真实联调
- 模特/场景/服装选择器采用占位方式实现：
  - mock 列表
  - 本地 JSON
  - 手动输入资源 ID

### 业务校验

前端必须内置当前后端的模式约束：

- `low` 只能配 `auto_basic`
- `mid` 只能配 `semi_pro`

### 提交成功行为

- 展示后端返回的 `order_id`
- 展示后端返回的 `workflow_id`
- 自动跳转 `/orders/:orderId`

## 7.3 审核工作台

### 页面目标

- 集中处理所有待审核订单
- 让审核员高效执行审核和人工修订回流

### 页面组件

- 待审核队列
- 订单切换区
- 当前资产主视图区
- 版本链区
- 审核动作区
- 人工修订区
- 流程摘要区
- 提交结果反馈

### 核心动作

- `approve`
- `rerun_scene`
- `rerun_face`
- `rerun_fusion`
- `注册人工修订稿`
- `确认继续流水线`

### 用户路径

1. 进入审核工作台
2. 从待审核队列选择订单
3. 查看订单详情、资产与版本链
4. 执行审核决定或人工修订回流动作
5. 页面刷新队列状态

### 当前后端支撑情况

`完整支撑`

### 已有接口

- `GET /api/v1/reviews/pending`
- `GET /api/v1/orders/{order_id}`
- `GET /api/v1/orders/{order_id}/assets`
- `GET /api/v1/orders/{order_id}/revisions`
- `GET /api/v1/workflows/{order_id}`
- `POST /api/v1/reviews/{order_id}/submit`
- `POST /api/v1/orders/{order_id}/revisions`
- `POST /api/v1/reviews/{order_id}/confirm-revision`

### 关键规则

- `pending` 状态显示标准审核动作
- `revision_uploaded` 状态必须突出“确认继续流水线”
- signal 失败时订单仍应停留在队列中，前端不得乐观删除
- 修订链在确认继续后仍可继续查看

## 7.4 订单详情

### 页面目标

- 提供订单全量上下文的稳定承载页
- 成为订单总览、审核页、流程页的共享详情入口

### 页面组件

- 订单基础信息卡
- 当前状态卡
- 最终结果区
- 资产列表
- 修订版本链
- workflow 摘要
- 跳转动作区

### 用户路径

1. 从任意入口进入订单详情
2. 查看订单当前状态
3. 查看资产与版本链
4. 查看流程摘要
5. 需要时跳转审核或流程详情

### 当前后端支撑情况

`较完整`

### 已有接口

- `GET /api/v1/orders/{order_id}`
- `GET /api/v1/orders/{order_id}/assets`
- `GET /api/v1/orders/{order_id}/revisions`
- `GET /api/v1/workflows/{order_id}`

### 页面规则

- 修订链接口 404 表示没有修订链，不应渲染为系统异常
- 资产为空应显示业务空态
- 最终资产可能为空，直到流程真正完成

## 7.5 流程追踪

### 页面目标

- 让运营或技术查看单订单 workflow 执行细节
- 用于排查当前步骤、失败步骤和流程回流情况

### 页面组件

- 订单号查询输入
- 流程状态卡
- 步骤时间线
- 错误信息区
- 步骤详情展开区

### 页面拆分

- `/workflows`：首版做轻量查询入口
- `/workflows/:orderId`：首版真实联调页面

### 当前后端支撑情况

`部分支撑`

已存在：

- `GET /api/v1/workflows/{order_id}`

缺口：

- 缺少 workflow 列表接口

### 一期实现策略

- 流程详情页真实联调
- 流程首页做订单号查询入口，而非完整列表页

## 7.6 资源库中心

### 子模块

- 模特库
- 场景库
- 服装库

### 页面目标

- 提供未来资源域浏览入口
- 为提单工作台资源选择器提供同一套信息结构

### 页面组件

- 列表或卡片视图
- 资源搜索
- 标签筛选
- 资源详情抽屉
- “选中并回填提单工作台”交互预留

### 当前后端支撑情况

`无`

### 一期实现策略

- 只做页面结构、路由与 mock 数据演示
- 页面必须明确提示“当前为占位模块，待后端资源库接口补齐后联调”

### 未来后端需求

- 模特库列表接口
- 模特详情接口
- 场景库列表接口
- 场景详情接口
- 服装库列表接口
- 服装详情接口

## 7.7 系统设置与登录预留

### 页面目标

- 为未来登录权限与后台治理能力预留路由和导航位置

### 当前后端支撑情况

`无`

### 一期实现策略

- 只保留页面壳子或占位页
- 不纳入一期真实验收

## 8. 接口映射

## 8.1 创建订单

### 请求

`POST /api/v1/orders`

请求字段：

- `customer_level`
- `service_mode`
- `model_id`
- `pose_id`
- `garment_asset_id`
- `scene_ref_asset_id`

### 响应

- `order_id`
- `workflow_id`
- `status`

### 前端用途

- 提单工作台提交订单

## 8.2 订单详情

### 请求

`GET /api/v1/orders/{order_id}`

### 关键响应字段

- `order_id`
- `customer_level`
- `service_mode`
- `status`
- `model_id`
- `pose_id`
- `garment_asset_id`
- `scene_ref_asset_id`
- `final_asset_id`
- `current_revision_asset_id`
- `current_revision_version`
- `revision_count`
- `review_task_status`
- `workflow_id`
- `current_step`
- `final_asset`

### 前端用途

- 订单详情页
- 审核工作台右侧上下文

## 8.3 订单资产

### 请求

`GET /api/v1/orders/{order_id}/assets`

### 关键响应字段

- `id`
- `order_id`
- `parent_asset_id`
- `root_asset_id`
- `version_no`
- `is_current_version`
- `asset_type`
- `step_name`
- `uri`
- `metadata_json`

### 前端用途

- 订单详情资产区
- 审核工作台主图与资产列表

## 8.4 待审核列表

### 请求

`GET /api/v1/reviews/pending`

### 关键响应字段

- `review_task_id`
- `order_id`
- `workflow_id`
- `current_step`
- `review_status`
- `latest_revision_asset_id`
- `revision_count`
- `created_at`

### 前端用途

- 审核工作台左侧队列

## 8.5 审核提交

### 请求

`POST /api/v1/reviews/{order_id}/submit`

### 请求字段

- `decision`
- `reviewer_id`
- `selected_asset_id`
- `comment`

### 支持的 decision

- `approve`
- `rerun_scene`
- `rerun_face`
- `rerun_fusion`

### 前端用途

- 审核工作台动作区

## 8.6 注册人工修订稿

### 请求

`POST /api/v1/orders/{order_id}/revisions`

### 请求字段

- `parent_asset_id`
- `uploaded_uri`
- `reviewer_id`
- `comment`

### 响应字段

- `order_id`
- `asset_id`
- `parent_asset_id`
- `root_asset_id`
- `version_no`
- `review_task_status`

### 前端用途

- 审核工作台人工修订上传区

## 8.7 查询修订链

### 请求

`GET /api/v1/orders/{order_id}/revisions`

### 响应结构

- `order_id`
- `items[]`

每个 `item` 包含：

- `asset_id`
- `parent_asset_id`
- `root_asset_id`
- `version_no`
- `is_current_version`
- `asset_type`
- `uri`
- `created_at`

### 前端用途

- 审核工作台版本链
- 订单详情版本链

## 8.8 确认继续流水线

### 请求

`POST /api/v1/reviews/{order_id}/confirm-revision`

### 请求字段

- `reviewer_id`
- `comment`

### 响应字段

- `order_id`
- `workflow_id`
- `revision_asset_id`
- `decision`
- `status`

### 前端用途

- 审核工作台“确认继续流水线”动作

## 8.9 workflow 状态

### 请求

`GET /api/v1/workflows/{order_id}`

### 关键响应字段

- `order_id`
- `workflow_id`
- `workflow_type`
- `workflow_status`
- `current_step`
- `latest_revision_asset_id`
- `latest_revision_version`
- `pending_manual_confirm`
- `steps[]`

### 前端用途

- 审核工作台流程摘要
- 订单详情流程摘要
- 流程追踪详情页

## 9. 页面状态机

## 9.1 提单工作台

- `未填写`
- `填写中`
- `前端校验失败`
- `提交中`
- `提交成功`
- `提交失败`

页面规则：

- 提交成功后必须跳转订单详情
- 提交失败必须保留当前表单内容

## 9.2 审核工作台

- 队列状态：
  - `pending`
  - `revision_uploaded`
- 订单状态：
  - `waiting_review`
  - `running`
  - `succeeded`
  - `failed`

页面规则：

- `pending` 显示标准审核动作
- `revision_uploaded` 必须突出“确认继续流水线”
- signal 失败时不得从前端移除队列项

## 9.3 订单详情

- `加载中`
- `订单存在`
- `资产为空`
- `存在修订链`
- `流程已完成`
- `流程失败`

页面规则：

- 无修订链不是异常
- 无最终图不是异常

## 9.4 流程追踪

- `待查询`
- `查询中`
- `查询成功`
- `workflow 不存在`
- `workflow 失败`

## 9.5 资源库占位模块

- `mock 列表态`
- `空数据态`
- `未接后端提示态`

## 10. 一期与二期边界

## 10.1 一期真实可交付

- 后台导航壳子
- 提单工作台
- 审核工作台
- 订单详情页
- 流程详情页 `/workflows/:orderId`
- 登录与系统设置路由预留

## 10.2 一期占位交付

- 订单总览列表
- 流程追踪首页列表
- 模特库
- 场景库
- 服装库
- 登录页真实鉴权
- 权限控制

## 10.3 二期依赖后端补齐后再推进

- 订单列表/搜索/分页
- workflow 列表
- 模特库真实联调
- 场景库真实联调
- 服装库真实联调
- 真实文件上传
- 对象存储预览
- 登录与权限系统

## 11. 前端技术建议

本节不是强制技术选型，而是为了让新项目起步更稳。

建议：

- 使用独立前端项目，不内嵌到当前后端仓库
- 使用模块化路由结构
- 为“真实联调模块”和“占位模块”明确分目录
- 将 API 层、状态机、页面组件分层
- 对 `review_status`、`workflow_status`、`current_step` 建立统一枚举映射
- 对 mock 资源库数据和真实 API 数据使用统一视图模型，避免未来切换时重写页面

## 12. 验收标准

## 12.1 一期必须满足

- 能从提单工作台提交订单并跳转详情
- 能在审核工作台查看待审核队列
- 能执行 `approve`
- 能执行 `rerun_scene / rerun_face / rerun_fusion`
- 能登记人工修订稿
- 能确认继续流水线
- 能在订单详情页查看资产、修订链、workflow 摘要
- 能在流程详情页查看步骤历史

## 12.2 一期允许不满足

- 首页订单列表真实联调
- 资源库真实联调
- 登录和权限
- 真实图片上传与预览

## 13. 风险与依赖

### 13.1 主要风险

- 首页默认是订单总览，但后端暂时没有订单列表接口
- 提单工作台依赖资源 ID，但资源库接口尚不存在
- 资产 URI 仍可能是 mock 地址，前端无法保证真实图片预览
- 登录权限未实现，首版只能按受信环境假设推进

### 13.2 协作依赖

前端一期推进过程中，需要后端后续补充以下能力，才能让后台从“可用”走向“完整”：

- 订单列表接口
- workflow 列表接口
- 资源库接口
- 上传接口
- 权限接口

## 14. 结论

这个前端项目现在就可以启动，但必须明确区分两类模块：

- 可按当前后端真实联调的模块
- 只能先做壳子和占位的模块

当前最值得优先落地的是：

1. 提单工作台
2. 审核工作台
3. 订单详情
4. 流程详情页

订单总览、流程首页、资源库中心与权限系统，则应在前端一期中保留结构，但以“占位模块”或“后端依赖模块”的方式写入项目范围。