# 存储机制 **本文引用的文件** - [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts) - [book-generator.types.ts](file://server/src/modules/book-generator/book-generator.types.ts) - [stage-manager.ts](file://server/src/modules/book-generator/stage-manager.ts) - [index.ts](file://server/src/models/index.ts) - [schema.prisma](file://server/prisma/schema.prisma) - [cache.ts](file://server/src/middleware/cache.ts) - [redis.service.ts](file://server/src/services/redis.service.ts) - [storage.service.ts](file://server/src/services/storage.service.ts) - [book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts) - [fault-tolerance.ts](file://server/src/modules/book-generator/fault-tolerance.ts) ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考量](#性能考量) 8. [故障排查指南](#故障排查指南) 9. [结论](#结论) 10. [附录](#附录) ## 简介 本文件系统性阐述“书籍生成”模块的存储机制设计与实现，覆盖数据存储策略、缓存机制、持久化方案、数据生命周期与清理策略、并发访问控制、与数据库的交互与事务处理、数据一致性保障、异常处理与重试机制，以及性能优化与最佳实践。读者可据此理解如何读取/更新存储数据、如何处理异常、如何进行性能优化与运维。 ## 项目结构 围绕“书籍生成”的存储相关文件主要分布在以下位置： - 存储实现：server/src/modules/book-generator/book-generator.store.ts - 类型定义：server/src/modules/book-generator/book-generator.types.ts - 阶段管理与状态机：server/src/modules/book-generator/stage-manager.ts - 数据库连接与Prisma：server/src/models/index.ts、server/prisma/schema.prisma - 缓存中间件与Redis：server/src/middleware/cache.ts、server/src/services/redis.service.ts - 统一存储服务（OSS/本地）：server/src/services/storage.service.ts - 控制器入口：server/src/modules/book-generator/book-generator.controller.ts - 容错与监控：server/src/modules/book-generator/fault-tolerance.ts ```mermaid graph TB subgraph "应用层" C["book-generator.controller.ts
路由与任务编排"] end subgraph "业务层" S["book-generator.store.ts
存储接口与领域逻辑"] SM["stage-manager.ts
阶段安全推进/回退"] FT["fault-tolerance.ts
重试/超时/监控"] end subgraph "基础设施" PRISMA["schema.prisma
数据库模型"] DB["MySQL
PrismaClient"] REDIS["Redis
缓存"] OSS["OSS/本地存储
storage.service.ts"] end C --> S S --> SM S --> PRISMA PRISMA --> DB C --> REDIS S --> REDIS S --> OSS FT --> S ``` 图表来源 - [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199) - [book-generator.store.ts:1-1073](file://server/src/modules/book-generator/book-generator.store.ts#L1-L1073) - [stage-manager.ts:1-202](file://server/src/modules/book-generator/stage-manager.ts#L1-L202) - [schema.prisma:130-192](file://server/prisma/schema.prisma#L130-L192) - [redis.service.ts:1-53](file://server/src/services/redis.service.ts#L1-L53) - [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278) 章节来源 - [book-generator.store.ts:1-1073](file://server/src/modules/book-generator/book-generator.store.ts#L1-L1073) - [book-generator.types.ts:1-226](file://server/src/modules/book-generator/book-generator.types.ts#L1-L226) - [stage-manager.ts:1-202](file://server/src/modules/book-generator/stage-manager.ts#L1-L202) - [index.ts:1-15](file://server/src/models/index.ts#L1-L15) - [schema.prisma:130-192](file://server/prisma/schema.prisma#L130-L192) - [cache.ts:1-97](file://server/src/middleware/cache.ts#L1-L97) - [redis.service.ts:1-53](file://server/src/services/redis.service.ts#L1-L53) - [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278) - [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199) - [fault-tolerance.ts:1-388](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L388) ## 核心组件 - 存储类 BookStore：提供书籍、章节、大纲、元数据的CRUD与状态推进；负责将数据库记录转换为领域对象；提供批量创建、章节树构建、发布/取消发布等能力。 - 阶段管理器 Stage Manager：基于线性阶段模型的安全推进/回退，配合乐观锁与资源清理规则，确保状态迁移合法与幂等。 - 缓存中间件与Redis：提供HTTP响应缓存、键空间清理、常用查询缓存等能力，降低数据库压力。 - 统一存储服务 StorageService：抽象OSS与本地存储，支持上传/下载/删除/签名URL等操作，便于切换与测试。 - 容错与监控 Fault Tolerance：AI调用重试、节点超时控制、进度监控、自动恢复，保障生成任务的稳定性。 章节来源 - [book-generator.store.ts:163-1073](file://server/src/modules/book-generator/book-generator.store.ts#L163-L1073) - [stage-manager.ts:100-198](file://server/src/modules/book-generator/stage-manager.ts#L100-L198) - [cache.ts:13-97](file://server/src/middleware/cache.ts#L13-L97) - [redis.service.ts:1-53](file://server/src/services/redis.service.ts#L1-L53) - [storage.service.ts:13-278](file://server/src/services/storage.service.ts#L13-L278) - [fault-tolerance.ts:67-324](file://server/src/modules/book-generator/fault-tolerance.ts#L67-L324) ## 架构总览 存储架构采用“领域服务+数据库+缓存+外部存储”的分层设计： - 领域服务（BookStore）封装业务语义与状态机，屏蔽底层细节。 - 数据库（Prisma + MySQL）持久化书籍、章节、生成阶段、元数据等。 - 缓存（Redis）用于热点数据与响应缓存，提升读性能。 - 外部存储（OSS/本地）用于音频/视频/封面等大文件的落地与访问。 ```mermaid sequenceDiagram participant Client as "客户端" participant Ctrl as "控制器
book-generator.controller.ts" participant Store as "存储服务
book-generator.store.ts" participant Stage as "阶段管理
stage-manager.ts" participant DB as "数据库
Prisma/MySQL" participant Cache as "缓存
Redis" participant OSS as "存储服务
storage.service.ts" Client->>Ctrl : "POST /api/book-generator/books/ : id/batch-generate" Ctrl->>Store : "创建批量生成任务" Store->>DB : "查询/更新书籍与章节状态" Store->>Stage : "推进章节状态安全推进" Store->>OSS : "生成音频并上传" OSS-->>Store : "返回URL" Store->>DB : "写入音频URL/时长/阶段" Store-->>Ctrl : "任务信息" Ctrl-->>Client : "任务已启动" Note over Cache,DB : "读路径可命中Redis缓存" ``` 图表来源 - [book-generator.controller.ts:24-119](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L119) - [book-generator.store.ts:758-897](file://server/src/modules/book-generator/book-generator.store.ts#L758-L897) - [stage-manager.ts:158-198](file://server/src/modules/book-generator/stage-manager.ts#L158-L198) - [redis.service.ts:52-103](file://server/src/services/redis.service.ts#L52-L103) - [storage.service.ts:43-93](file://server/src/services/storage.service.ts#L43-L93) ## 详细组件分析 ### 数据类型与存储结构 - 书籍（Book）：包含基础信息、生成阶段、进度、是否发布、章节列表、大纲、元数据、错误信息等。 - 章节（Chapter）：包含章节内容、摘要、字数、生成阶段、生成时间、音频/视频URL与时长、是否公开等。 - 大纲（BookOutline）：树形结构的章/节/小节规划，支持从数据库章节记录重建。 - 生成阶段（BookGenStage/ChapterGenStage）：线性阶段模型，用于统一推进与回退。 - 任务（GenerateTask）：批量生成任务的进度、状态、重试次数等。 章节来源 - [book-generator.types.ts:8-139](file://server/src/modules/book-generator/book-generator.types.ts#L8-L139) ### 数据库模型与字段 - Book：包含用户ID、标题、副标题、描述、受众、风格、书籍规模、总章节数、预估字数、进度、是否发布、大纲JSON、前言/后记、错误信息、失败阶段、生成阶段、分析结果等。 - BookChapter：包含书籍ID、父子关系、层级、序号、标题、摘要、关键知识点、预估字数、正文、字数、内容错误、生成时间、音频/视频URL与时长、是否公开、生成阶段、歌词等。 - VideoProject、Draft、TokenUsage等模型与书籍生成间接相关。 章节来源 - [schema.prisma:130-192](file://server/prisma/schema.prisma#L130-L192) ### 存储类 BookStore 的职责与实现 - 书籍与章节的创建、查询、更新、删除。 - 章节树构建：从数据库记录重建大纲树（章→节→小节）。 - 发布/取消发布：事务性更新书籍与章节公开状态。 - 音频生成：异步生成并回调更新章节音频URL与时长，推进阶段。 - 章节内容重生成：LLM调用+清理失败状态+推进阶段。 - 状态推进与回退：委托阶段管理器执行安全推进/回退与资源清理。 ```mermaid classDiagram class BookStore { +create(data) +getById(id, filterPublic, userId) +getAllByUser(userId, includePublic) +getPublicBooks() +update(id, data) +delete(id) +createChapter(data) +createChapters(bookId, chapters) +createChapterItem(bookIdNum, item, parentId, level) +createChapterItems(bookIdNum, items, parentId, level) +updateChapter(bookId, number, data) +updateChapterById(id, data) +getChapters(bookId) +getChapterTree(bookId) +countCompletedChapters(bookId) +publishAlbum(bookId) +unpublishAlbum(bookId) +togglePublish(bookId) +generateChapterAudio(bookId, chapterNumber, userId) +generateChapterAudioById(chapterId, userId) +generateSingleChapterContent(bookId, chapterId) -toBook(dbBook, excludeContent) -buildOutlineFromChapters(chapters) } class StageManager { +advanceChapter(chapterId, targetStage) +regenerateChapter(chapterId, targetStage) +safeTransitionChapter(chapterId, currentStage, targetStage) +getCleanupForChapterRegression(targetStage) } BookStore --> StageManager : "推进/回退阶段" ``` 图表来源 - [book-generator.store.ts:163-1073](file://server/src/modules/book-generator/book-generator.store.ts#L163-L1073) - [stage-manager.ts:100-198](file://server/src/modules/book-generator/stage-manager.ts#L100-L198) 章节来源 - [book-generator.store.ts:244-1073](file://server/src/modules/book-generator/book-generator.store.ts#L244-L1073) - [stage-manager.ts:100-198](file://server/src/modules/book-generator/stage-manager.ts#L100-L198) ### 缓存机制与并发控制 - 缓存中间件：支持自定义键生成器、命中/未命中标记、TTL控制；当Redis不可用时自动降级。 - 常用缓存配置：用户信息、音色列表、书籍详情、热门书籍、会员权益等。 - 并发控制：阶段推进采用乐观锁（updateMany + genStage条件），避免竞态；音频生成回调在存储层内幂等更新。 ```mermaid flowchart TD Start(["进入缓存中间件"]) --> CheckRedis["Redis可用?"] CheckRedis --> |否| Next["直接执行请求"] CheckRedis --> |是| GenKey["生成缓存键"] GenKey --> GetCache["Redis GET"] GetCache --> Hit{"命中?"} Hit --> |是| ReturnCache["返回缓存并设置X-Cache: HIT"] Hit --> |否| ExecReq["执行请求"] ExecReq --> RespOK{"状态码==200且有body?"} RespOK --> |是| SetCache["Redis SET TTL"] RespOK --> |否| SkipCache["跳过缓存"] SetCache --> ReturnResp["返回响应并设置X-Cache: MISS"] SkipCache --> ReturnResp Next --> ReturnResp ``` 图表来源 - [cache.ts:13-47](file://server/src/middleware/cache.ts#L13-L47) 章节来源 - [cache.ts:13-97](file://server/src/middleware/cache.ts#L13-L97) - [redis.service.ts:43-103](file://server/src/services/redis.service.ts#L43-L103) ### 数据持久化与事务处理 - 数据库连接：PrismaClient初始化与连接管理。 - 事务：发布/取消发布使用事务，确保书籍与章节状态一致。 - 乐观锁：阶段推进使用updateMany + 条件字段，失败时查询实际状态并做幂等处理。 章节来源 - [index.ts:5-13](file://server/src/models/index.ts#L5-L13) - [book-generator.store.ts:700-754](file://server/src/modules/book-generator/book-generator.store.ts#L700-L754) - [stage-manager.ts:118-146](file://server/src/modules/book-generator/stage-manager.ts#L118-L146) ### 生命周期管理与数据清理策略 - 阶段回退清理：当目标阶段低于音频/视频完成阶段时，自动清空对应资源字段（URL/时长）。 - 任务清理：批量生成任务运行期间占用内存Map，完成后清理。 - 缓存清理：提供按前缀删除缓存的能力。 章节来源 - [stage-manager.ts:75-92](file://server/src/modules/book-generator/stage-manager.ts#L75-L92) - [book-generator.controller.ts:15-16](file://server/src/modules/book-generator/book-generator.controller.ts#L15-L16) ### 与数据库的交互与一致性 - 读路径：支持按用户过滤、按公开状态过滤、按发布时间排序；详情页可选择排除章节内容以减少传输。 - 写路径：统一使用Prisma ORM，事务包裹关键操作；阶段推进采用乐观锁；错误信息写入errorMsg字段便于追踪。 - 一致性：通过阶段模型与资源清理规则，确保状态与资源的一致性；发布/取消发布事务保证原子性。 章节来源 - [book-generator.store.ts:282-331](file://server/src/modules/book-generator/book-generator.store.ts#L282-L331) - [book-generator.store.ts:700-754](file://server/src/modules/book-generator/book-generator.store.ts#L700-L754) - [stage-manager.ts:118-146](file://server/src/modules/book-generator/stage-manager.ts#L118-L146) ### 异常处理与重试机制 - AI调用重试：指数退避，最多3次；失败记录到errorMsg并通知用户。 - 节点超时：超时后通知用户并尝试自动恢复。 - 进度监控：长时间无进度发出警告，必要时自动恢复。 - 音频生成失败：回退到上一阶段并自动重试最多3次。 章节来源 - [fault-tolerance.ts:67-122](file://server/src/modules/book-generator/fault-tolerance.ts#L67-L122) - [fault-tolerance.ts:130-179](file://server/src/modules/book-generator/fault-tolerance.ts#L130-L179) - [fault-tolerance.ts:187-260](file://server/src/modules/book-generator/fault-tolerance.ts#L187-L260) - [book-generator.store.ts:872-896](file://server/src/modules/book-generator/book-generator.store.ts#L872-L896) ### 代码示例（路径指引） - 读取书籍详情（含大纲树）：[getById:282-331](file://server/src/modules/book-generator/book-generator.store.ts#L282-L331) - 更新章节内容并推进阶段：[updateChapter:579-613](file://server/src/modules/book-generator/book-generator.store.ts#L579-L613) - 生成章节音频并回调更新：[generateChapterAudio:759-793](file://server/src/modules/book-generator/book-generator.store.ts#L759-L793) - 按ID生成音频（带并发保护与重试）：[generateChapterAudioById:800-897](file://server/src/modules/book-generator/book-generator.store.ts#L800-L897) - 推进章节阶段（安全推进）：[advanceChapter:158-179](file://server/src/modules/book-generator/stage-manager.ts#L158-L179) - 回退到上游阶段（清理下游资源）：[regenerateChapter:188-198](file://server/src/modules/book-generator/stage-manager.ts#L188-L198) - 发布书籍（事务）：[publishAlbum:700-714](file://server/src/modules/book-generator/book-generator.store.ts#L700-L714) - 上传音频文件（OSS/本地）：[uploadAudio:43-49](file://server/src/services/storage.service.ts#L43-L49) - 缓存中间件使用：[createCache:13-47](file://server/src/middleware/cache.ts#L13-L47) ## 依赖关系分析 ```mermaid graph LR CTRL["book-generator.controller.ts"] --> STORE["book-generator.store.ts"] STORE --> STAGE["stage-manager.ts"] STORE --> PRISMA["schema.prisma"] PRISMA --> MYSQL["MySQL"] CTRL --> REDIS["redis.service.ts"] STORE --> REDIS STORE --> OSS["storage.service.ts"] FT["fault-tolerance.ts"] --> STORE ``` 图表来源 - [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199) - [book-generator.store.ts:1-1073](file://server/src/modules/book-generator/book-generator.store.ts#L1-L1073) - [stage-manager.ts:1-202](file://server/src/modules/book-generator/stage-manager.ts#L1-L202) - [schema.prisma:130-192](file://server/prisma/schema.prisma#L130-L192) - [redis.service.ts:1-53](file://server/src/services/redis.service.ts#L1-L53) - [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278) - [fault-tolerance.ts:1-388](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L388) 章节来源 - [book-generator.store.ts:1-1073](file://server/src/modules/book-generator/book-generator.store.ts#L1-L1073) - [stage-manager.ts:1-202](file://server/src/modules/book-generator/stage-manager.ts#L1-L202) - [schema.prisma:130-192](file://server/prisma/schema.prisma#L130-L192) - [redis.service.ts:1-53](file://server/src/services/redis.service.ts#L1-L53) - [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278) - [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199) - [fault-tolerance.ts:1-388](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L388) ## 性能考量 - 读性能 - 使用Redis缓存热点数据（书籍详情、热门书籍、音色列表等），合理设置TTL。 - 详情页可选择排除章节内容，减少传输与序列化开销。 - 写性能 - 批量创建章节使用upsert，避免重复创建与唯一约束冲突。 - 阶段推进采用乐观锁，减少锁竞争。 - I/O与存储 - 音频/视频等大文件走OSS/本地存储，数据库仅存URL与时长。 - 上传/下载/签名URL按需使用，避免不必要的网络往返。 - 并发与一致性 - 阶段推进严格遵循转移矩阵与乐观锁，避免竞态。 - 音频生成回调在存储层幂等更新，避免重复写入。 [本节为通用性能建议，无需特定文件引用] ## 故障排查指南 - 阶段推进失败 - 检查当前阶段与目标阶段是否在转移矩阵内；确认乐观锁条件匹配。 - 若状态已被其他调用改变，查询实际状态并做幂等处理。 - 音频生成异常 - 查看errorMsg字段定位失败原因；检查回调是否触发；必要时重试。 - 若多次失败，回退到上游阶段并自动重试。 - 缓存问题 - Redis不可用时会自动降级；可通过clearCache按前缀清理。 - 检查缓存键生成器与TTL配置是否合理。 - 数据库连接 - 确认Prisma连接成功；检查数据库权限与网络连通性。 章节来源 - [stage-manager.ts:100-146](file://server/src/modules/book-generator/stage-manager.ts#L100-L146) - [book-generator.store.ts:872-896](file://server/src/modules/book-generator/book-generator.store.ts#L872-L896) - [cache.ts:54-61](file://server/src/middleware/cache.ts#L54-L61) - [index.ts:5-13](file://server/src/models/index.ts#L5-L13) ## 结论 该存储机制以领域服务为核心，结合线性阶段模型、乐观锁与资源清理规则，实现了高一致性与可维护性的数据流；通过Redis缓存与统一存储抽象，兼顾性能与可移植性；借助容错与监控体系，提升了生成任务的稳定性与可观测性。建议在生产环境中持续优化缓存命中率、控制阶段推进频率、规范错误日志与告警策略。 [本节为总结性内容，无需特定文件引用] ## 附录 ### 常见问题与最佳实践 - 如何正确推进阶段 - 使用advanceChapter推进到下一阶段；回退使用regenerateChapter并清理下游资源。 - 如何避免重复生成 - 在generateChapterAudioById中先检查当前阶段，若已在目标阶段则跳过。 - 如何清理缓存 - 使用clearCache(keyPrefix)按前缀清理；或在写操作后主动清理相关键。 - 如何切换存储介质 - 通过环境变量切换STORAGE_TYPE，统一使用storageService的上传/下载接口。 章节来源 - [stage-manager.ts:158-198](file://server/src/modules/book-generator/stage-manager.ts#L158-L198) - [book-generator.store.ts:800-836](file://server/src/modules/book-generator/book-generator.store.ts#L800-L836) - [cache.ts:54-61](file://server/src/middleware/cache.ts#L54-L61) - [storage.service.ts:17-28](file://server/src/services/storage.service.ts#L17-L28)