# 阶段管理器

<cite>
**本文引用的文件**
- [stage-manager.ts](file://server/src/modules/book-generator/stage-manager.ts)
- [book-generator.types.ts](file://server/src/modules/book-generator/book-generator.types.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.ts)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)
- [book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
- [graph.ts](file://server/src/modules/book-generator/graph.ts)
- [sequential.strategy.ts](file://server/src/modules/book-generator/strategies/sequential.strategy.ts)
- [one-step-outline.strategy.ts](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts)
- [per-chapter.strategy.ts](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts)
- [status-system-redesign.md](file://status-system-redesign.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向“阶段管理器”的技术文档，聚焦于书籍生成流水线中的阶段划分、阶段间依赖关系、状态跟踪与推进机制。文档从代码层面梳理阶段管理器如何协调内容生成、音频生成、音频合并、视频生成与视频合并等任务，如何通过安全状态转移与乐观锁保证并发一致性，以及如何基于书籍/章节两级状态实现联动推进与回退。同时提供新增阶段、配置参数、监控进度与故障恢复的最佳实践与示例路径。

## 项目结构
围绕阶段管理器的关键文件组织如下：
- 阶段定义与安全转移：stage-manager.ts
- 类型与数据模型：book-generator.types.ts
- 编排与执行：book-generator.service.ts
- 存储与状态计算：book-generator.store.ts
- 控制器与接口：book-generator.controller.ts
- LangGraph 状态与工作流：graph.ts
- 生成策略（工作流形态）：sequential/one-step-outline/per-chapter 策略
- 状态系统设计与迁移规则：status-system-redesign.md

```mermaid
graph TB
subgraph "阶段管理与编排"
SM["stage-manager.ts<br/>安全转移/阶段索引/清理规则"]
GS["book-generator.service.ts<br/>批量编排/步骤执行/进度推送"]
BS["book-generator.store.ts<br/>书籍/章节状态计算/回调推进"]
CTRL["book-generator.controller.ts<br/>REST API/任务生命周期"]
end
subgraph "LangGraph 工作流"
G["graph.ts<br/>GraphState/进度reducer"]
STR1["sequential.strategy.ts"]
STR2["one-step-outline.strategy.ts"]
STR3["per-chapter.strategy.ts"]
end
subgraph "类型与状态"
TYPES["book-generator.types.ts<br/>BookGenStage/ChapterGenStage"]
SYS["status-system-redesign.md<br/>阶段索引/转移规则/映射"]
end
CTRL --> GS
GS --> SM
GS --> BS
BS --> SM
GS --> G
G --> STR1
G --> STR2
G --> STR3
SM --> TYPES
BS --> TYPES
SYS --> SM
SYS --> BS
```

图表来源
- [stage-manager.ts:1-202](file://server/src/modules/book-generator/stage-manager.ts#L1-L202)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [book-generator.store.ts:1-1073](file://server/src/modules/book-generator/book-generator.store.ts#L1-L1073)
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)
- [graph.ts:1-83](file://server/src/modules/book-generator/graph.ts#L1-L83)
- [sequential.strategy.ts:1-60](file://server/src/modules/book-generator/strategies/sequential.strategy.ts#L1-L60)
- [one-step-outline.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L1-L56)
- [per-chapter.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L1-L56)
- [book-generator.types.ts:1-226](file://server/src/modules/book-generator/book-generator.types.ts#L1-L226)
- [status-system-redesign.md:48-195](file://status-system-redesign.md#L48-L195)

章节来源
- [stage-manager.ts:1-202](file://server/src/modules/book-generator/stage-manager.ts#L1-L202)
- [book-generator.types.ts:1-226](file://server/src/modules/book-generator/book-generator.types.ts#L1-L226)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [book-generator.store.ts:1-1073](file://server/src/modules/book-generator/book-generator.store.ts#L1-L1073)
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)
- [graph.ts:1-83](file://server/src/modules/book-generator/graph.ts#L1-L83)
- [sequential.strategy.ts:1-60](file://server/src/modules/book-generator/strategies/sequential.strategy.ts#L1-L60)
- [one-step-outline.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L1-L56)
- [per-chapter.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L1-L56)
- [status-system-redesign.md:48-195](file://status-system-redesign.md#L48-L195)

## 核心组件
- 阶段类型与索引
  - 书籍阶段：draft → outlining → outline_completed → content_generating → content_completed → audio_generating → audio_completed → video_generating → video_completed → failed
  - 章节阶段：idle → outline_completed → content_generating → content_completed → audio_generating → audio_completed → video_generating → video_completed → failed
  - 阶段索引用于比较大小，确保只能正向推进，避免跳跃
- 安全状态转移
  - 基于转移矩阵验证目标状态合法性
  - 使用乐观锁（where 条件匹配当前 genStage）写入目标状态
  - 回退时根据目标阶段决定清理下游资源（音频/视频 URL 与时长）
- 书籍/章节状态联动
  - 书籍 genStage 由“所有子章节最低阶段”映射而来，体现“短板效应”
  - 章节支持前进与回退，回退时自动清理下游资源，失败重试可回到对应上游阶段
- 编排与执行
  - 批量编排器按步骤顺序执行：内容生成 → 音频生成 → 音频合并 → 视频生成 → 视频合并
  - 每步执行包含进度推送、取消检查、超时轮询与失败处理
- 存储与回调
  - 生成回调中先更新 URL/时长，再推进到完成态，确保数据一致性
  - 自动重试与失败回退，提升鲁棒性

章节来源
- [stage-manager.ts:12-53](file://server/src/modules/book-generator/stage-manager.ts#L12-L53)
- [book-generator.types.ts:8-30](file://server/src/modules/book-generator/book-generator.types.ts#L8-L30)
- [book-generator.store.ts:19-60](file://server/src/modules/book-generator/book-generator.store.ts#L19-L60)
- [book-generator.service.ts:15-143](file://server/src/modules/book-generator/book-generator.service.ts#L15-L143)
- [book-generator.store.ts:800-897](file://server/src/modules/book-generator/book-generator.store.ts#L800-L897)

## 架构总览
阶段管理器贯穿“控制器 → 编排器 → 存储/服务 → 数据库”的链路，并通过 LangGraph 工作流驱动内容生成。整体交互如下：

```mermaid
sequenceDiagram
participant C as "客户端"
participant Ctrl as "控制器(book-generator.controller)"
participant Orchestrator as "编排器(BatchGenerationOrchestrator)"
participant StageMgr as "阶段管理器(stage-manager)"
participant Store as "存储(BookStore)"
participant DB as "数据库(Prisma)"
C->>Ctrl : POST /books/ : id/batch-generate
Ctrl->>Orchestrator : 创建并启动任务
Orchestrator->>Store : 获取书籍/章节树
Orchestrator->>StageMgr : advanceChapter()/regenerateChapter()
StageMgr->>DB : 乐观锁更新(genStage)
DB-->>StageMgr : 更新结果
StageMgr-->>Orchestrator : 状态变更
Orchestrator->>Store : 回调推进/更新URL/时长
Store->>DB : 更新章节字段
DB-->>Store : 成功
Store-->>Orchestrator : 状态同步
Orchestrator-->>Ctrl : 推送进度/完成
Ctrl-->>C : 返回任务状态
```

图表来源
- [book-generator.controller.ts:24-119](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L119)
- [book-generator.service.ts:45-143](file://server/src/modules/book-generator/book-generator.service.ts#L45-L143)
- [stage-manager.ts:100-147](file://server/src/modules/book-generator/stage-manager.ts#L100-L147)
- [book-generator.store.ts:800-897](file://server/src/modules/book-generator/book-generator.store.ts#L800-L897)

## 详细组件分析

### 阶段管理器（stage-manager.ts）
- 目标
  - 提供线性阶段模型与安全转移能力
  - 通过索引比较与转移矩阵控制前进/回退
  - 通过清理规则在回退时清除下游资源
- 关键点
  - 章节阶段索引数组与索引函数
  - 转移矩阵定义允许的前进/回退/失败路径
  - 安全转移函数：校验 → 计算清理 → 乐观锁写入 → 冲突处理
  - 前进/重新生成封装：限制前进方向、回退走重新生成

```mermaid
flowchart TD
Start(["进入 safeTransitionChapter"]) --> CheckAllowed["检查转移矩阵"]
CheckAllowed --> Allowed{"允许转移？"}
Allowed -- 否 --> ThrowErr["抛出非法转移错误"]
Allowed -- 是 --> CalcClean["计算回退清理规则"]
CalcClean --> Optimistic["乐观锁更新 genStage + 清理字段"]
Optimistic --> Count{"更新影响行数 > 0？"}
Count -- 否 --> Conflict["查询实际状态/告警/跳过"]
Count -- 是 --> Done(["完成"])
```

图表来源
- [stage-manager.ts:100-147](file://server/src/modules/book-generator/stage-manager.ts#L100-L147)
- [stage-manager.ts:75-92](file://server/src/modules/book-generator/stage-manager.ts#L75-L92)

章节来源
- [stage-manager.ts:39-92](file://server/src/modules/book-generator/stage-manager.ts#L39-L92)
- [stage-manager.ts:100-198](file://server/src/modules/book-generator/stage-manager.ts#L100-L198)

### 书籍/章节类型与状态映射（book-generator.types.ts, status-system-redesign.md）
- 类型定义
  - 书籍阶段与章节阶段枚举
  - 书籍/章节数据结构、任务结构、请求/响应结构
- 状态映射与规则
  - 阶段索引顺序与比较
  - 书籍阶段由“最低章节阶段”映射而来
  - 章节支持前进、回退、重新生成、失败重试与资源清理

```mermaid
flowchart TD
LeafStages["所有子章节 genStage"] --> MinIdx["取最小索引"]
MinIdx --> MapBook["映射到书籍阶段"]
MapBook --> BookStage["Book.genStage"]
```

图表来源
- [book-generator.types.ts:8-30](file://server/src/modules/book-generator/book-generator.types.ts#L8-L30)
- [book-generator.store.ts:19-60](file://server/src/modules/book-generator/book-generator.store.ts#L19-L60)
- [status-system-redesign.md:48-67](file://status-system-redesign.md#L48-L67)

章节来源
- [book-generator.types.ts:8-30](file://server/src/modules/book-generator/book-generator.types.ts#L8-L30)
- [book-generator.store.ts:19-60](file://server/src/modules/book-generator/book-generator.store.ts#L19-L60)
- [status-system-redesign.md:48-195](file://status-system-redesign.md#L48-L195)

### 编排器与执行流程（book-generator.service.ts）
- 目标
  - 按步骤顺序执行生成流水线，推送进度，支持取消
- 关键点
  - 步骤：generate_content → generate_audio → merge_audio → generate_video → merge_video
  - 每步包含轮询检查、进度计算、取消检查、超时处理
  - 与阶段管理器协作：推进/回退章节状态，更新 URL/时长

```mermaid
sequenceDiagram
participant O as "编排器"
participant S as "阶段管理器"
participant A as "音频服务"
participant V as "视频服务"
O->>O : 执行 generate_content
O->>O : 执行 generate_audio
O->>S : advanceChapter(voice_generating)
O->>A : 异步生成音频(回调更新URL/时长)
A-->>O : 回调推进到 voice_completed
O->>S : advanceChapter(video_generating)
O->>V : 异步生成视频(成功/失败)
V-->>O : 成功/失败
O->>S : 成功→advanceChapter(video_completed) / 失败→regenerateChapter(failed)
O->>O : 执行 merge_audio / merge_video
```

图表来源
- [book-generator.service.ts:77-536](file://server/src/modules/book-generator/book-generator.service.ts#L77-L536)
- [stage-manager.ts:158-198](file://server/src/modules/book-generator/stage-manager.ts#L158-L198)
- [book-generator.store.ts:800-897](file://server/src/modules/book-generator/book-generator.store.ts#L800-L897)

章节来源
- [book-generator.service.ts:45-536](file://server/src/modules/book-generator/book-generator.service.ts#L45-L536)

### 存储与回调推进（book-generator.store.ts）
- 目标
  - 提供书籍/章节 CRUD、树形结构构建、状态计算与回调推进
- 关键点
  - 回调中先更新音频/视频 URL 与时长，再推进到完成态
  - 失败时回退到上游阶段并自动重试（带指数退避）
  - 生成单章内容时，根据上下文构建提示词并推进状态

```mermaid
sequenceDiagram
participant Gen as "音频生成"
participant Store as "BookStore"
participant DB as "数据库"
participant SM as "阶段管理器"
Gen->>Store : generateChapterAudioById(chapterId)
Store->>SM : advanceChapter(audio_generating)
Gen->>DB : 更新 audioUrl/audioDuration
DB-->>Gen : 成功
Gen->>SM : advanceChapter(audio_completed)
SM-->>Gen : 完成
```

图表来源
- [book-generator.store.ts:800-897](file://server/src/modules/book-generator/book-generator.store.ts#L800-L897)
- [stage-manager.ts:158-198](file://server/src/modules/book-generator/stage-manager.ts#L158-L198)

章节来源
- [book-generator.store.ts:800-1010](file://server/src/modules/book-generator/book-generator.store.ts#L800-L1010)

### 控制器与任务生命周期（book-generator.controller.ts）
- 目标
  - 提供批量生成、取消、状态查询的 REST API
- 关键点
  - 任务去重与运行中状态管理
  - 后台异步执行，完成后推送完成事件

章节来源
- [book-generator.controller.ts:24-199](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L199)

### LangGraph 工作流与策略（graph.ts, strategies/*.ts）
- 目标
  - 通过 GraphState 管理进度、完成章节、失败章节等状态
  - 通过不同策略驱动内容生成：串行、一步大纲+并行内容、逐章内聚
- 关键点
  - 进度 reducer 只增不减，章节完成数累加
  - 策略选择影响内容生成的并发与调用次数

章节来源
- [graph.ts:23-82](file://server/src/modules/book-generator/graph.ts#L23-L82)
- [sequential.strategy.ts:21-59](file://server/src/modules/book-generator/strategies/sequential.strategy.ts#L21-L59)
- [one-step-outline.strategy.ts:21-55](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L21-L55)
- [per-chapter.strategy.ts:21-55](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L21-L55)

## 依赖分析
- 组件耦合
  - 编排器依赖阶段管理器与存储
  - 存储依赖阶段管理器与数据库
  - 控制器依赖编排器与 WebSocket 推送
  - 策略与工作流解耦，通过 GraphState 与 reducer 协同
- 外部依赖
  - Prisma ORM
  - LangGraph 状态图
  - WebSocket 推送（进度/完成）

```mermaid
graph LR
Controller["book-generator.controller.ts"] --> Service["book-generator.service.ts"]
Service --> StageMgr["stage-manager.ts"]
Service --> Store["book-generator.store.ts"]
Store --> StageMgr
Service --> Graph["graph.ts"]
Graph --> Strategies["strategies/*.ts"]
StageMgr --> Types["book-generator.types.ts"]
Store --> Types
```

图表来源
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [stage-manager.ts:1-202](file://server/src/modules/book-generator/stage-manager.ts#L1-L202)
- [book-generator.store.ts:1-1073](file://server/src/modules/book-generator/book-generator.store.ts#L1-L1073)
- [graph.ts:1-83](file://server/src/modules/book-generator/graph.ts#L1-L83)
- [sequential.strategy.ts:1-60](file://server/src/modules/book-generator/strategies/sequential.strategy.ts#L1-L60)
- [one-step-outline.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L1-L56)
- [per-chapter.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L1-L56)
- [book-generator.types.ts:1-226](file://server/src/modules/book-generator/book-generator.types.ts#L1-L226)

## 性能考虑
- 并发与批处理
  - 音频/视频生成采用异步并行，减少端到端时间
  - 合并阶段按父节点分组，降低 I/O 压力
- 轮询与超时
  - 每步设置合理超时与检查间隔，避免长时间占用
- 进度与日志
  - 逐步推进进度并输出关键节点日志，便于定位瓶颈
- 调用次数优化
  - 策略选择影响 LLM 调用次数，可根据规模权衡

## 故障排查指南
- 常见问题
  - 状态冲突：乐观锁更新影响行数为 0，需检查并发与状态竞争
  - 回退清理：回退到上游阶段应自动清理下游资源（音频/视频 URL 与时长）
  - 失败重试：音频失败自动回退到内容完成并重试，必要时手动触发重新生成
  - 取消任务：通过取消标志中断执行，清理运行中任务
- 定位方法
  - 查看控制器运行中任务映射，确认是否存在重复任务
  - 检查编排器每步进度与错误日志
  - 核对阶段管理器的安全转移日志与数据库最终状态

章节来源
- [stage-manager.ts:123-146](file://server/src/modules/book-generator/stage-manager.ts#L123-L146)
- [book-generator.store.ts:872-896](file://server/src/modules/book-generator/book-generator.store.ts#L872-L896)
- [book-generator.controller.ts:64-98](file://server/src/modules/book-generator/book-generator.controller.ts#L64-L98)

## 结论
阶段管理器通过线性阶段模型、安全转移与乐观锁、书籍/章节联动推进与回退机制，有效保障了复杂生成流水线的正确性与可观测性。结合 LangGraph 工作流与多种生成策略，系统在可扩展性与性能之间取得平衡。建议在新增阶段或调整策略时，严格遵循转移矩阵与清理规则，确保状态一致性与数据完整性。

## 附录

### 如何添加新的生成阶段
- 定义阶段类型
  - 在类型定义文件中增加新阶段枚举值
  - 示例路径：[book-generator.types.ts:8-30](file://server/src/modules/book-generator/book-generator.types.ts#L8-L30)
- 阶段索引与映射
  - 在阶段管理器中维护阶段索引数组与索引函数
  - 示例路径：[stage-manager.ts:39-53](file://server/src/modules/book-generator/stage-manager.ts#L39-L53)
- 转移矩阵与清理规则
  - 在转移矩阵中声明允许的前进/回退路径
  - 在清理规则中定义回退时的资源清理逻辑
  - 示例路径：[stage-manager.ts:57-92](file://server/src/modules/book-generator/stage-manager.ts#L57-L92)
- 安全转移与推进
  - 使用安全转移函数进行状态变更
  - 示例路径：[stage-manager.ts:100-147](file://server/src/modules/book-generator/stage-manager.ts#L100-L147)
- 书籍阶段映射
  - 更新书籍阶段映射逻辑，确保“最低章节阶段”正确映射
  - 示例路径：[book-generator.store.ts:19-60](file://server/src/modules/book-generator/book-generator.store.ts#L19-L60)

### 如何配置阶段参数
- 生成配置
  - 模型、温度、最大 token、章节字数范围、重试策略等
  - 示例路径：[book-generator.types.ts:187-199](file://server/src/modules/book-generator/book-generator.types.ts#L187-L199)
- 策略选择
  - 根据规模与并发需求选择策略：串行/一步大纲+并行/逐章内聚
  - 示例路径：[sequential.strategy.ts:21-59](file://server/src/modules/book-generator/strategies/sequential.strategy.ts#L21-L59), [one-step-outline.strategy.ts:21-55](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L21-L55), [per-chapter.strategy.ts:21-55](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L21-L55)

### 如何监控阶段执行进度
- 控制器接口
  - 批量生成、取消、状态查询接口
  - 示例路径：[book-generator.controller.ts:24-199](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L199)
- 编排器进度
  - 每步执行推送进度，包含步骤名称、百分比与消息
  - 示例路径：[book-generator.service.ts:59-117](file://server/src/modules/book-generator/book-generator.service.ts#L59-L117)

### 阶段优化策略与最佳实践
- 优化策略
  - 选择合适的生成策略以降低 LLM 调用次数
  - 合理设置轮询间隔与超时，平衡实时性与资源消耗
  - 在失败时自动回退并重试，避免人工干预
- 最佳实践
  - 严格遵守阶段索引与转移矩阵，禁止跳跃与逆向推进
  - 回退时务必清理下游资源，防止脏数据
  - 使用回调推进完成态，确保数据一致性
  - 通过 WebSocket 推送进度，提升用户体验