feat(workflow-run): implement resumable generation orchestration

frontend/src/entities/index.ts

@@ -56,8 +56,9 @@ export type {
 export type { MediaReference } from './media'
 
 /* 工作流 —— 节点与运行状态都由前端管理 */
-export { WORKFLOW_STEP_ORDER } from './workflow-run'
+export { createWorkflowRunStore, WORKFLOW_STEP_ORDER } from './workflow-run'
 export type {
+  CreateWorkflowRunStoreOptions,
   CreateWorkflowRunInput,
   ExportStatus,
   GenerationStatus,
@@ -68,6 +69,7 @@ export type {
   WorkflowRevision,
   WorkflowRevisionStatus,
   WorkflowRun,
+  WorkflowRunStore,
   WorkflowRunPurpose,
   WorkflowRunStatus,
 } from './workflow-run'

frontend/src/entities/workflow-run/constants.ts

@@ -0,0 +1,19 @@
+export const WORKFLOW_DRIVERS = ['ai', 'manual'] as const
+export const WORKFLOW_PURPOSES = ['create_character', 'add_action'] as const
+export const WORKFLOW_RUN_STATUSES = ['active', 'interrupted', 'completed', 'failed'] as const
+export const WORKFLOW_REVISION_STATUSES = ['active', 'completed', 'failed', 'abandoned'] as const
+export const GENERATION_STATUSES = ['not_started', 'in_progress', 'completed', 'failed'] as const
+export const EXPORT_STATUSES = ['not_exported', 'exporting', 'exported', 'failed'] as const
+export const WORKFLOW_STEP_STATUSES = ['locked', 'available', 'active', 'passed', 'failed'] as const
+
+/** 当前工作流的固定顺序，也是恢复校验与进度展示的唯一顺序来源。 */
+export const WORKFLOW_STEP_ORDER = [
+  'character-setup',
+  'character-template',
+  'template-candidate',
+  'action-setup',
+  'first-frame',
+  'complete-animation',
+  'review',
+  'export',
+] as const

frontend/src/entities/workflow-run/index.ts

@@ -1,143 +1,93 @@
 import type { Generation } from '../generation'
+import {
+  EXPORT_STATUSES,
+  GENERATION_STATUSES,
+  WORKFLOW_DRIVERS,
+  WORKFLOW_PURPOSES,
+  WORKFLOW_REVISION_STATUSES,
+  WORKFLOW_RUN_STATUSES,
+  WORKFLOW_STEP_ORDER,
+  WORKFLOW_STEP_STATUSES,
+} from './constants'
 
-/** Quick Start 与手动工作流只改变输入方式，共用同一种运行模型。 */
-export type WorkflowDriver = 'ai' | 'manual'
+export { WORKFLOW_STEP_ORDER } from './constants'
 
-/** 创建 WorkflowRun 时要完成的用户意图。 */
-export type WorkflowRunPurpose = 'create_character' | 'add_action'
-
-/**
- * 流程步骤类型的唯一标准顺序；它不是后端 Workflow 或 Execution 定义。
- * 某个 Revision 已进入执行线的步骤顺序，由 WorkflowRevision.nodes 的数组位置表达。
- */
-export const WORKFLOW_STEP_ORDER = [
-  'character-setup',
-  'character-template',
-  'template-candidate',
-  'action-setup',
-  'first-frame',
-  'complete-animation',
-  'review',
-  'export',
-] as const
-
-/** 前端流程步骤类型，与 WORKFLOW_STEP_ORDER 的成员保持一致。 */
+export type WorkflowDriver = (typeof WORKFLOW_DRIVERS)[number]
+export type WorkflowRunPurpose = (typeof WORKFLOW_PURPOSES)[number]
 export type WorkflowStepType = (typeof WORKFLOW_STEP_ORDER)[number]
+export type WorkflowStepStatus = (typeof WORKFLOW_STEP_STATUSES)[number]
+export type WorkflowRevisionStatus = (typeof WORKFLOW_REVISION_STATUSES)[number]
+export type WorkflowRunStatus = (typeof WORKFLOW_RUN_STATUSES)[number]
+export type GenerationStatus = (typeof GENERATION_STATUSES)[number]
+export type ExportStatus = (typeof EXPORT_STATUSES)[number]
 
-/**
- * 步骤的可用性和执行结果；不直接复用后端任务状态。
- * locked/available 表示尚未执行，active 表示当前页面阶段，passed/failed 表示结果。
- */
-export type WorkflowStepStatus = 'locked' | 'available' | 'active' | 'passed' | 'failed'
-
-/**
- * 单个版本的生命周期。
- * abandoned 表示停止沿用但仍保留为历史。
- */
-export type WorkflowRevisionStatus = 'active' | 'completed' | 'failed' | 'abandoned'
-
-/**
- * 整次流程的汇总状态。
- * interrupted 只表示用户主动停止自动推进：历史仍保留且可只读查看，它不等于 failed 或 completed。
- * 后端生成任务是否真正停止是独立问题；从历史重启成功后可重新进入 active。
- */
-export type WorkflowRunStatus = 'active' | 'interrupted' | 'completed' | 'failed'
-
-/**
- * 当前版本在生成阶段的汇总状态；素材准备期间为 not_started。
- * 它是版本级别的汇总，不是单次生成任务的状态——后者是 TaskStatus。
- */
-export type GenerationStatus = 'not_started' | 'in_progress' | 'completed' | 'failed'
-
-/** 当前版本在导出阶段的汇总状态。 */
-export type ExportStatus = 'not_exported' | 'exporting' | 'exported' | 'failed'
-
-/**
- * 一个 Revision 中已经进入执行线的流程步骤。
- * 步骤自身不重复保存顺序；其在 nodes 中的数组位置就是该版本的执行顺序。
- */
+/** 一次流程步骤的可恢复快照，不包含页面显示状态。 */
 export interface WorkflowStep {
-  /** 只用于编排和页面定位，不作为业务 ID 发送给后端。 */
+  /** 只用于前端编排和定位，不发送给后端。 */
   id: string
   type: WorkflowStepType
   status: WorkflowStepStatus
-  /** 进入步骤时保存的输入快照。 */
   input: unknown
-  /** 步骤完成后的结果或引用；尚无结果时为 null。 */
   output: unknown
-  /**
-   * 本步骤已提交、结果尚未写回 output 的 Generation ID；没有在途任务时为 null。
-   * 它由前端随 WorkflowRun 一起维护，据此查回在途任务的状态，因而不会在同一次
-   * 前端运行中重复发起生成。是否写入浏览器存储属于前端实现，不形成后端契约。
-   * Generation 本身不认识步骤，反向关联不存在。
-   *
-   * 字段名沿用后端的 task_id。步骤类型不能从 Generation.type 反推——后端只有
-   * character_image 和 character_action 两种，本步骤是哪一步以 WorkflowStep.type 为准。
-   */
+  /** 已提交但尚未写回结果的生成任务。 */
   taskId: Generation['id'] | null
-  /** 该步骤沿用或依赖的步骤 ID，用于版本来源追踪，不代表后端执行依赖。 */
+  /** 请求已开始但后端任务 ID 尚未返回时的本地防重标识。 */
+  submissionId: string | null
+  /** 失败步骤必须提供原因，其他状态必须为 null。 */
+  error: string | null
+  /** 新版本沿用的历史步骤，用于解释版本来源。 */
   referenceStepIds: string[]
 }
 
-/**
- * 一次页面执行版本；当前版本会推进，从旧步骤重开则追加新版本。
- *
- * MVP 只走单条执行线：revisions 恒为一个成员，basedOnRevisionId 与 restartStepId 恒为 null。
- * 「从历史步骤重开并保留旧版本」尚未进入产品定义，结构先留出位置但不实现，
- * 避免真要做时改动波及 WorkflowRun 的持久化形状。
- */
+/** 一次可回看的流程版本。重开历史步骤时追加新版本，不覆盖旧版本。 */
 export interface WorkflowRevision {
   id: string
-  /** 首次创建的版本没有来源，因此为 null。 */
   basedOnRevisionId: string | null
-  /** 在来源版本中选择的重启步骤 ID；非重启创建的版本为 null。 */
   restartStepId: string | null
   status: WorkflowRevisionStatus
-  /**
-   * 已进入当前执行线的步骤；数组位置是该版本步骤顺序的唯一来源。
-   * 尚未推进到的后续步骤可以不存在；完整步骤类型顺序以 WORKFLOW_STEP_ORDER 为准。
-   */
   steps: WorkflowStep[]
   generationStatus: GenerationStatus
   exportStatus: ExportStatus
   createdAt: string
 }
 
-/**
- * 一次由前端推进的页面流程。
- * 步骤推进和运行状态都由前端管理；后端不读取、不推进、也不持久化 WorkflowRun。
- * 后端只处理生成任务，并在用户最终确认时持久化角色与动作资产。
- */
-export interface WorkflowRun {
+/** 两种创作目的共用的运行字段。 */
+interface WorkflowRunBase {
   id: string
   projectId: string
-  /** 已关联的 Character ID；角色尚未创建或确认时为 null。 */
-  characterId: string | null
-  /** 已有角色加动作时的目标造型；新建角色时为 null。 */
-  outfitId: string | null
-  purpose: WorkflowRunPurpose
   driver: WorkflowDriver
   status: WorkflowRunStatus
-  /** 当前可编辑版本 ID；必须能在 revisions 中找到。 */
+  /** 当前可继续编辑的版本，必须存在于 revisions 中。 */
   currentRevisionId: string
-  /** 按创建顺序保存的全部版本；历史版本保留用于只读查看和重启。 */
+  /** 按创建时间排列；历史版本只读，重开时追加新版本。 */
   revisions: WorkflowRevision[]
-  /** Quick Start 的规范化提示词；空白输入或手动模式无提示词时为 null。 */
   prompt: string | null
 }
 
-/** 两种入口共享的创建字段。 */
+/**
+ * 一次前端创作流程，后端不读取、推进或持久化该结构。
+ * 新建角色允许稍后补齐角色引用；给已有角色添加动作必须从创建起就绑定角色和造型。
+ */
+export type WorkflowRun = WorkflowRunBase &
+  (
+    | {
+        purpose: 'create_character'
+        characterId: string | null
+        outfitId: string | null
+      }
+    | {
+        purpose: 'add_action'
+        characterId: string
+        outfitId: string
+      }
+  )
+
 interface CreateWorkflowRunInputBase {
   projectId: string
   driver: WorkflowDriver
-  /** Quick Start 的自然语言需求；提交时去除首尾空白，空字符串按 null 保存。 */
   prompt?: string
 }
 
-/**
- * 创建 WorkflowRun 的输入。
- * add_action 分支把已有角色、造型、母版和基准帧设为必填，避免创建无法恢复的半成品运行。
- */
 export type CreateWorkflowRunInput = CreateWorkflowRunInputBase &
   (
     | {
@@ -155,3 +105,6 @@ export type CreateWorkflowRunInput = CreateWorkflowRunInputBase &
         baseFrameUrls: readonly string[]
       }
   )
+
+export { createWorkflowRunStore } from './store'
+export type { CreateWorkflowRunStoreOptions, WorkflowRunStore } from './store'