Home Esplora Aiuto
Accedi
caojunfei
/
audio_codebuddy
1
0
Forka 0
File Problemi 0 Pull Requests 0 Wiki
Albero (Tree): 678c7d8813
Rami (Branch) Tag
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
数据库设计
/
内容数据模型
/
书籍模型(Book).md

书籍模型(Book).md 17 KB
Cronologia Originale

书籍模型(Book)

本文引用的文件

  • schema.prisma
  • book-generator.types.ts
  • book-generator.store.ts
  • stage-manager.ts
  • book-generator.controller.ts
  • book-generator.service.ts
  • utils.ts
  • index.ts

目录

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

简介

本文件面向AI有声书生成平台的“书籍模型(Book)”，系统化阐述其核心字段设计、分类维度、状态管理机制、进度与统计指标、与用户及章节的关联关系，并提供创建、更新、查询的API使用示例与最佳实践。文档严格基于仓库现有代码与类型定义，确保技术准确性与可追溯性。

项目结构

围绕Book模型的关键代码分布在以下位置：

  • 数据库模型定义：Prisma Schema（包含Book与BookChapter的字段、索引与关系）
  • 类型与状态：book-generator.types.ts（定义Book/Chapter状态枚举、阶段、请求/响应结构）
  • 存储与业务：book-generator.store.ts（持久化、章节树构建、发布控制、进度统计）
  • 状态机与阶段推进：stage-manager.ts（章节线性阶段的安全转移与资源清理）
  • 控制器与服务：book-generator.controller.ts（批量生成API）、book-generator.service.ts（编排器与步骤执行）

  • 工具与LLM：utils.ts（字数统计）、LLM服务（统一AI调用适配）

    graph TB
subgraph "模型定义"
PRISMA["Prisma Schema<br/>Book/BookChapter 字段与关系"]
end
subgraph "类型与状态"
TYPES["book-generator.types.ts<br/>Book/Chapter 类型与阶段枚举"]
STAGE["stage-manager.ts<br/>章节阶段安全转移"]
end
subgraph "存储与业务"
STORE["book-generator.store.ts<br/>持久化/章节树/发布/统计"]
end
subgraph "控制器与服务"
CTRL["book-generator.controller.ts<br/>批量生成API"]
SVC["book-generator.service.ts<br/>编排器与步骤执行"]
end
subgraph "工具与AI"
UTIL["utils.ts<br/>字数统计/进度常量"]
LLM["LLM服务<br/>统一AI调用适配"]
end
PRISMA --> STORE
TYPES --> STORE
TYPES --> STAGE
STORE --> CTRL
STORE --> SVC
CTRL --> SVC
UTIL --> STORE
LLM --> STORE

图表来源

  • schema.prisma
  • book-generator.types.ts
  • stage-manager.ts
  • book-generator.store.ts
  • book-generator.controller.ts
  • book-generator.service.ts
  • utils.ts
  • index.ts

章节来源

  • schema.prisma
  • book-generator.types.ts
  • book-generator.store.ts
  • stage-manager.ts
  • book-generator.controller.ts
  • book-generator.service.ts
  • utils.ts
  • index.ts

核心组件

  • 数据模型(Book/BookChapter)
    • 字段覆盖：元数据(title/subtitle/description/coverUrl)、分类(targetAudience/style/bookScale)、状态(genStage/status/failedStage)、进度(progress/totalChapters)、关联(userId/chapters)等
    • 关系：一对多(章节树)，索引覆盖常用查询路径
  • 类型与阶段
    • BookGenStage/ChapterGenStage线性阶段模型，支持前进推进与回退重试
    • BookStatus/ChapterStatus用于上层状态表达
  • 存储与业务
    • BookStore负责创建/查询/更新/删除、章节树构建、发布/取消发布、统计完成章节数
  • 状态机与编排
    • safeTransition/advanceChapter/regenerateChapter保证状态转移合法性与资源清理
    • BatchGenerationOrchestrator按步骤编排内容/音频/视频生成与合并

章节来源

  • schema.prisma
  • book-generator.types.ts
  • book-generator.store.ts
  • stage-manager.ts
  • book-generator.service.ts

架构总览

Book模型贯穿“类型定义—状态机—存储—控制器—服务—AI工具”的完整链路，形成从元数据到内容、音频、视频的端到端生成体系。

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "控制器<br/>book-generator.controller.ts"
participant Orchestrator as "编排器<br/>book-generator.service.ts"
participant Store as "存储层<br/>book-generator.store.ts"
participant Stage as "状态机<br/>stage-manager.ts"
participant LLM as "LLM服务<br/>index.ts"
Client->>Ctrl : POST /books/ : id/batch-generate
Ctrl->>Orchestrator : 创建并启动编排任务
Orchestrator->>Store : 读取书籍与章节树
Orchestrator->>LLM : 调用AI生成内容
LLM-->>Orchestrator : 返回内容片段
Orchestrator->>Store : 更新章节内容与阶段
Orchestrator->>Stage : advanceChapter/安全转移
Stage-->>Orchestrator : 状态更新确认
Orchestrator-->>Ctrl : 推送进度/完成
Ctrl-->>Client : 返回任务状态

图表来源

  • book-generator.controller.ts
  • book-generator.service.ts
  • book-generator.store.ts
  • stage-manager.ts
  • index.ts

详细组件分析

数据模型与字段语义

  • 元数据字段
    • title：书名，必填
    • subtitle：副标题，可选
    • description：书籍描述/用户输入，必填
    • coverUrl：封面URL，可选
  • 分类字段
    • targetAudience：目标受众，默认值“通用”
    • style：写作风格，默认值“专业严谨”
    • bookScale：书籍规模，默认值“标准教程”
  • 状态与进度
    • genStage：书籍生成阶段，默认“draft”
    • status：书籍状态，默认“draft”
    • failedStage：失败阶段标识，可空
    • progress：生成进度百分比，默认0
    • totalChapters：总章节数，默认10
    • estimatedWords：预估总字数，默认0
  • 内容与元数据
    • outlineJson：大纲JSON，可空
    • foreword/afterword：前言/后记，可空
    • bookAnalysis：AI规划结果，可空
  • 关联关系
    • userId：创建者ID，可空（兼容游客场景）
    • chapters：章节集合（三级树：章/节/小节）
  • 索引与约束
    • 常用索引：(userId,status)、(createdAt)等，便于查询与排序

章节来源

  • schema.prisma

类型定义与阶段模型

  • BookGenStage（线性阶段）
    • draft → outlining → outline_completed → content_generating → content_completed → audio_generating → audio_completed → video_generating → video_completed → failed
  • ChapterGenStage（线性阶段）
    • idle → outline_completed → content_generating → content_completed → audio_generating → audio_completed → video_generating → video_completed → failed
  • BookStatus/ChapterStatus
    • 用于上层状态表达与UI展示，与genStage存在映射关系

章节来源

  • book-generator.types.ts

章节树与书籍阶段计算

  • 章节树构建
    • 依据level与number排序，自底向上组织为章→节→小节
    • 支持按bookId+number+level精确查找
  • 书籍阶段计算
    • 书籍阶段=min(所有章节genStage)映射到对应书籍阶段
    • 例如：任一章节处于content_generating，则书籍阶段为content_generating

章节来源

  • book-generator.store.ts

状态机与安全转移

  • 转移矩阵
    • 严格限定合法转移方向，禁止无序回退
    • 支持失败回退至上游阶段或重试
  • 资源清理
    • 当目标阶段低于音频/视频完成阶段时，自动清理下游资源字段

  • 前进与回退

    • advanceChapter：仅允许前进

    • regenerateChapter：允许回退并清理下游资源

      flowchart TD
Start(["进入安全转移"]) --> CheckAllowed["检查是否在允许转移矩阵内"]
CheckAllowed --> |否| Error["抛出非法转移错误"]
CheckAllowed --> |是| CalcClean["计算目标阶段所需清理的下游资源"]
CalcClean --> Optimistic["乐观锁更新：校验当前阶段并写入目标阶段"]
Optimistic --> Conflict{"更新命中数量=0？"}
Conflict --> |是| FetchActual["查询实际阶段"]
FetchActual --> SameStage{"实际阶段=目标阶段？"}
SameStage --> |是| Skip["跳过已处于目标阶段"]
SameStage --> |否| RegenCheck{"当前阶段为failed且非idle？"}
RegenCheck --> |是| Skip
RegenCheck --> |否| Warn["记录警告但不中断"]
Conflict --> |否| Done(["完成"])

图表来源

  • stage-manager.ts

章节来源

  • stage-manager.ts

存储与业务能力

  • 创建/查询/更新/删除
    • create：初始化默认值（genStage/status/progress等）
    • getById：返回完整章节树与可选公开音频过滤
    • update：支持outline对象转outlineJson
    • delete：删除书籍
  • 章节管理
    • createChapter/createChapters/createChapterItem：支持upsert避免重复
    • updateChapter/updateChapterById：更新内容、字数、阶段、错误信息、媒体URL等
  • 发布与公开
    • publishAlbum/unpublishAlbum/togglePublish：批量公开/取消公开有音频的章节
  • 统计
    • countCompletedChapters：统计video_completed的完成章节数

章节来源

  • book-generator.store.ts

API使用示例与最佳实践

  • 批量生成（推荐）
    • POST /api/book-generator/books/:id/batch-generate
    • Body可选steps：generate_content/generate_audio/merge_audio/generate_video/merge_video
    • 幂等：若已有运行中任务会拒绝重复启动
    • 取消：POST /api/book-generator/books/:id/batch-generate/cancel
    • 查询状态：GET /api/book-generator/books/:id/batch-generate/status
  • 单步推进（谨慎）
    • 通过advanceChapter/regenerateChapter在服务层推进/回退章节阶段
    • 注意：仅允许前进或回退到上游阶段，避免破坏下游资源一致性
  • 最佳实践
    • 先设置bookScale与totalChapters，再启动批量生成
    • 使用getById时结合filterPublic与userId，控制音频可见性
    • 在UI侧以progress与genStage双维度展示状态，提升透明度

章节来源

  • book-generator.controller.ts
  • book-generator.service.ts
  • stage-manager.ts

生成流程与进度计算

  • 进度常量（参考）
    • OUTLINE_DONE、SECTIONS_DONE、SUBSECTIONS_DONE、CONTENT_START、CONTENT_END、FOREWORD_DONE、AFTERWORD_DONE
  • 编排器步骤
    • generate_content：LangGraph生成内容，轮询等待叶节点全部content_completed
    • generate_audio：为叶节点生成音频，轮询等待全部音频完成
    • merge_audio：按父节点合并音频（多层级场景）
    • generate_video：为叶节点生成视频，轮询等待全部视频完成
    • merge_video：按父节点合并视频（多层级场景）

  • 进度推进

    • 每步按比例推进，最终置100并更新书籍progress

      sequenceDiagram
participant Orchestrator as "编排器"
participant Content as "内容生成"
participant Audio as "音频生成"
participant MergeA as "音频合并"
participant Video as "视频生成"
participant MergeV as "视频合并"
Orchestrator->>Content : generate_content
Content-->>Orchestrator : progress 15~95%
Orchestrator->>Audio : generate_audio
Audio-->>Orchestrator : progress 20~95%
Orchestrator->>MergeA : merge_audio
MergeA-->>Orchestrator : progress 20~95%
Orchestrator->>Video : generate_video
Video-->>Orchestrator : progress 20~95%
Orchestrator->>MergeV : merge_video
MergeV-->>Orchestrator : progress 100%

图表来源

  • book-generator.service.ts
  • utils.ts

章节来源

  • book-generator.service.ts
  • utils.ts

依赖分析

  • Book与BookChapter：一对多，章节树形结构，支持三级嵌套
  • BookStore依赖Prisma与LLM服务，负责数据持久化与AI生成编排
  • stage-manager提供跨模块的状态安全推进

  • controller/service解耦，便于扩展与测试

    erDiagram
BOOK {
int id PK
int userId
string title
string subtitle
text description
string coverUrl
string targetAudience
string style
string bookScale
int totalChapters
int estimatedWords
int progress
boolean isPublished
text outlineJson
text foreword
text afterword
text errorMsg
string failedStage
string genStage
string status
text bookAnalysis
datetime createdAt
datetime updatedAt
}
BOOKCHAPTER {
int id PK
int bookId FK
int parentId
int level
int number
string title
text summary
text keyPoints
int estimatedWords
longtext content
int wordCount
text contentError
datetime generatedAt
string audioUrl
int audioDuration
string videoUrl
int videoDuration
boolean isPublic
string genStage
text lrcLyrics
string status
datetime createdAt
datetime updatedAt
}
BOOK ||--o{ BOOKCHAPTER : "chapters"

图表来源

  • schema.prisma

章节来源

  • schema.prisma

性能考虑

  • 章节树查询与排序：按(level,number)排序，避免N+1查询
  • 乐观锁更新：减少并发冲突带来的重试成本
  • 轮询等待：合理设置检查间隔与超时，避免长时间占用连接
  • LLM调用：使用流式/异步回调，降低阻塞时间
  • 发布批量更新：使用事务一次性更新书籍与章节公开状态

故障排查指南

  • 状态转移失败
    • 检查当前genStage与目标阶段是否在允许转移矩阵内
    • 若出现“已处于目标阶段”或“已在failed状态”，属预期保护，无需报错
  • 生成超时
    • 检查LangGraph生成是否正常完成，或是否存在failed阶段
    • 确认叶节点content_completed数量与总数一致
  • 音频/视频未生成
    • 确认叶节点audioUrl/videoUrl是否为空，检查对应生成步骤是否完成
  • 发布异常
    • 确认书籍是否具备有音频的章节，检查事务是否成功

章节来源

  • stage-manager.ts
  • book-generator.service.ts
  • book-generator.store.ts

结论

Book模型以线性阶段驱动的强一致状态机为核心，结合章节树与批量编排，实现了从大纲到内容、音频、视频的全链路自动化生成。通过Prisma模型约束、类型定义与安全转移机制，确保了数据完整性与业务正确性；配合控制器与服务层的幂等与可观测性设计，为上层UI提供了稳定可靠的API支撑。

附录

  • 术语
    • genStage：线性生成阶段（章节/书籍）
    • status：上层状态（draft/planning/generating/completed/failed/interrupted）
    • progress：0-100的进度百分比
    • totalChapters：总章节数
    • bookScale：书籍规模（影响字数与章节数量）
  • 常用查询建议
    • 按用户与状态筛选：利用( userId, status )索引
    • 获取最新书籍：按updatedAt/id降序
    • 获取公开书籍：isPublished=true且章节存在audioUrl