# 审核优先运营台设计文档

日期：2026-03-27

## 1. 背景

当前项目是一个 `FastAPI + Temporal + SQLite + SQLAlchemy` 的图片流水线 MVP，支持：

- 低端自动流程 `auto_basic`
- 中端半自动流程 `semi_pro`
- 订单创建、订单详情、资产查询、待审核列表、审核提交、workflow 状态查询
- `approve / rerun_scene / rerun_face / rerun_fusion` 审核信号
- 面向人工审核节点的扩展设计：人工导出、离线修订、上传新副本并确认回流

本次目标不是实现完整前端系统，而是为当前后端能力设计一个可落地的桌面端运营页面原型，服务内部审核人员。

## 2. 设计目标

- 优先支持审核员处理 `waiting_review` 订单
- 让审核员先看图，再结合流程信息做决策
- 在单页内完成：选单、看图、流程判断、提交审核
- 在人工审核节点支持“导出原图 -> 离线修改 -> 上传新副本 -> 确认继续流水线”
- 保留新建订单入口，但不干扰审核主任务

## 3. 用户与使用场景

目标用户是内部运营/审核人员，主要在桌面端使用。

核心任务链路：

1. 从待审核队列中找到当前需要处理的订单
2. 查看候选图、最终图和历史版本
3. 结合 workflow 当前步骤、历史步骤与异常信息判断结果
4. 提交 `approve` 或 `rerun_*`
5. 进入下一单继续审核

扩展任务链路：

1. 在人工审核节点导出当前候选图
2. 线下修订后上传为新的副本版本
3. 在页面内检查新副本是否正确
4. 手动点击“确认继续流水线”，从审核后的下一段继续
5. 如需再次修订，则基于最新副本继续形成单线版本链

## 4. 信息架构

页面采用三栏结构，强调“详情审核”而不是“总览监控”。

### 左侧：待审核队列

- 搜索
- 快速筛选：全部、待审核、超时、高优先级、最近更新
- 订单卡片列表

每条卡片至少展示：

- `order_id`
- `service_mode`
- 当前步骤
- 等待时长
- 异常标记
- 人工介入标签：`可人工介入`、`待确认回流`、`修订中`

左侧只负责选单，不直接执行审核动作。

### 中央：大图审核区

中央是页面视觉核心，采用看图优先布局。

包括：

- 顶部状态条
- 主图预览区
- 版本链带：`原候选 -> 修订 v2 -> 修订 v3 -> 当前版本`
- 候选图 / 最终图 / 历史版本切换
- 缩略图带
- 局部放大检查

这个区域必须拿到页面最大面积，用于判断面部、纹理、融合边缘等细节。

### 右侧：审核与流程侧栏

右侧分为两块：

- 上半区：审核动作面板
- 下半区：压缩版流程时间线

审核动作包括：

- `approve`
- `rerun_scene`
- `rerun_face`
- `rerun_fusion`
- 审核备注
- `导出原图`
- `上传修订稿`
- `确认继续流水线`

流程侧栏展示：

- 当前步骤
- 关键 step 历史
- 最近重跑节点
- 错误信息 / 异常状态
- 人工修订记录：版本号、备注、上传时间、确认继续时间

### 顶部：订单状态条

顶部只保留最关键的信息：

- 订单号
- 客户层级
- 服务模式
- 当前步骤
- 状态
- SLA / 异常提醒
- 当前版本号
- 人工修订链次数

### 新建订单入口

保留在页面右上角，以按钮进入弹窗或二级页，不占据首页主区域。

## 5. 交互设计

### 主交互节奏

`左侧选单 -> 中央看图 -> 右侧做决定 -> 队列进入下一单或返回列表`

### 队列交互

- 点击订单卡片后，中央与右侧联动刷新
- 不打开新页面，不跳转
- 当前选中卡片需要强视觉高亮

### 图片查看交互

- 默认展示主图 + 缩略图带
- 主图和版本链联动，支持查看原候选、最新修订版、历史修订版
- 支持在候选图、最终图、历史版本之间切换
- 支持局部放大检查
- 每张图需要有状态标签，例如：`QC 候选`、`历史版本`、`当前选中`

### 人工修订交互

- 仅在中高端流程的人工审核节点展示
- 点击 `导出原图` 后导出当前选中版本用于线下修订
- 点击 `上传修订稿` 后创建一个新的副本版本，而不是覆盖原候选
- 上传成功后不自动开跑，订单进入 `待确认回流`
- 审核员确认新副本无误后，点击 `确认继续流水线`
- 回流从人工审核后的下一段继续，不再让审核员选择 `rerun_*`
- 多轮人工修订采用单线版本链，只保留一个继续流转的最新版本

### 审核动作交互

- `approve` 是唯一主 CTA
- `rerun_*` 是次级动作，与通过操作明显区分
- 执行 `rerun_*` 时要求填写备注
- 如果存在多张候选图，`approve` 前必须明确选中提交对象

### 流程查看交互

- 右侧默认展示摘要版时间线
- 重点体现：当前节点、失败节点、重跑来源
- 在人工修订模式下补充“修订记录”摘要
- 需要时可展开完整 step 历史

### 新建订单交互

- 从顶部按钮打开
- 不抢首页视觉焦点
- 表单字段直接对应当前后端 `CreateOrderRequest`

## 6. 视觉方向

页面风格应为：`专业、冷静、偏高密度` 的内部工作台。

### 视觉原则

- 中央主图区优先级最高
- 使用中性色为主，搭配单一强调色和语义状态色
- 通过分区背景、边框和留白建立左右区域层次
- 不使用花哨装饰和重营销化语言

### 状态表达

- `approve` 使用唯一主强调色
- `rerun_*` 使用次级语义动作样式
- 异常、超时、失败步骤在队列和顶部状态条中直接标红提示
- step 时间线使用统一状态编码：已完成、处理中、等待审核、失败、重跑来源

### 动效原则

- 仅保留短过渡反馈
- 不使用重动画
- 重点反馈：切换订单、切换图片、审核提交状态变化
- 在人工修订链中，版本切换和“待确认回流”需要有显式状态反馈

## 7. 数据映射

页面建立在当前已有 API 能力之上。

### 左侧队列

来源：

- 待审核列表接口

### 顶部状态条

来源组合：

- 订单详情
- workflow 当前状态
- 最新副本版本元数据

### 中央图片区

来源：

- 订单资产接口
- 人工修订版本链接口 / 版本元数据

### 右侧流程区

来源：

- workflow 状态接口

### 审核动作

来源：

- 审核提交接口
- 导出资产接口
- 修订稿上传接口
- 人工确认继续接口

`approve` 与 `rerun_*` 复用同一提交接口，仅决策参数不同。

人工修订能力需要把“资产版本”和“流程推进”拆成两类操作：

- 资产操作：导出、上传新副本、查看版本链
- 流程操作：确认继续流水线

## 8. 异常与边界处理

- 资产为空时，显示“暂无候选图 / 等待流程产出”
- workflow 拉取失败时，右侧流程区单独报错，不阻塞中央图片区
- 审核提交失败时，在右侧动作区就近展示错误
- 订单异常或失败时，队列卡片与顶部状态条同步显式标记
- 切换订单时，如果备注已编辑未提交，需要提示是否放弃
- 触发 `rerun_*` 后，页面进入“已发起重跑，等待流程推进”的过渡状态
- 导出失败时，仅动作区报错，不影响当前订单浏览
- 上传失败时，不创建新版本节点，仍停留在当前版本
- 上传成功但未确认继续时，队列中明确标记 `待确认回流`
- 确认继续失败时，保留最新副本版本，允许重试，不回退版本链
- 同一订单支持多轮人工修订，但只保留一条线性继续链，不允许并行分支

## 9. 本次原型范围

本次原型只覆盖一个桌面端单页：

- 待审核队列
- 详情审核区
- 流程时间线
- 资产预览
- 新建订单入口
- 人工修订回流模式下的版本链与动作区

不包含：

- 登录
- 多页后台结构
- 真实前端联调
- 响应式移动端适配

## 10. 原型验收标准

原型应回答以下问题：

1. 审核员能否快速找到待处理订单
2. 进入详情后能否高效看图并做决策
3. 流程与异常信息是否足够支持审核判断
4. 页面主视觉是否明确体现“看图优先、审核优先”
5. 人工修订后能否清楚看见版本链、待确认状态和继续入口

## 11. 推荐原型结构

推荐使用单页桌面运营台结构：

- 左 280px：队列栏
- 中 1.25x 主区：大图审核区
- 右 280-320px：审核动作 + 压缩流程区

这是当前最匹配项目能力与用户偏好的结构。

## 12. 人工修订状态机

建议将人工介入抽象成 4 个显式状态：

- `可人工介入`
- `修订上传完成`
- `待确认回流`
- `已回流继续`

状态规则：

- `可人工介入` 时允许导出原图和上传修订稿
- `修订上传完成 / 待确认回流` 时不允许再上传并行版本
- `待确认回流` 时右侧主按钮固定为 `确认继续流水线`
- `已回流继续` 后保留完整版本链供回看，后续若再次进入人工审核，则从最新版本继续生成下一版