feat: bootstrap auto virtual tryon admin frontend

2026-03-27-frontend-admin-prd.md

@@ -0,0 +1,846 @@
+# 虚拟试衣运营后台前端 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. 流程详情页
+
+订单总览、流程首页、资源库中心与权限系统，则应在前端一期中保留结构，但以“占位模块”或“后端依赖模块”的方式写入项目范围。