audio_codebuddy/.plans/audiobook-v2-ux/backend-dev/findings.md

backend-dev - 发现记录

工作中发现的问题和技术要点。

---

OPT-08: 一键完整生成 API

实现的文件

1. server/src/modules/book-generator/book-generator.service.ts - 编排服务

   • BatchGenerationOrchestrator 类：按顺序执行各生成步骤
   • 支持的步骤：generate_content, generate_audio, merge_audio, generate_video, merge_video
   • 取消标志管理：支持用户随时取消任务
   • 实时进度推送：通过 WebSocket 发送 batch_generation_progress 事件

2. server/src/modules/book-generator/book-generator.controller.ts - API 路由

   • POST /api/book-generator/books/:id/batch-generate - 启动批量生成
   • POST /api/book-generator/books/:id/batch-generate/cancel - 取消任务
   • GET /api/book-generator/books/:id/batch-generate/status - 查询任务状态

3. server/src/app.ts - 路由挂载

   • 新增 bookGeneratorRoutes 导入和挂载

实现要点

• 内容生成步骤复用 langGraphGenerator.generate() 接口
• 音频/视频生成复用现有的 bookStore.generateChapterAudioById() 和 createVideoProjectFromBook() 接口
• 通过轮询方式监控子任务完成状态
• 取消机制使用内存标志，已完成步骤保留

注意事项

• 批量生成任务存储在内存 Map 中，服务重启后会丢失运行状态
• 视频合并步骤简化处理（直接使用第一个子章节视频）
• 最大等待时间为 60 分钟（内容/音频/视频生成各自）

---

OPT-12: 意见反馈 API

实现的文件

1. server/src/modules/feedback/feedback.service.ts - 反馈服务

   • FeedbackInput 接口：定义输入参数
   • submitFeedback() 方法：保存反馈到数据库
   • 使用 uuid 作为反馈 ID

2. server/src/modules/feedback/feedback.controller.ts - 反馈控制器

   • POST /api/feedback - 提交反馈接口
   • 参数验证：type, title, content 必填
   • type 只能是 suggestion, bug, other

3. server/prisma/schema.prisma - 数据模型

   • 新增 Feedback 模型
   • 字段：id, type, title, content, contact, screenshotUrls, status, createdAt, updatedAt

4. server/src/app.ts - 路由挂载

   • 新增 feedbackRoutes 导入和挂载

API 规范

• 端点：POST /api/feedback

• Request:

  {
  "type": "suggestion|bug|other",
  "title": "string",
  "content": "string",
  "contact": "string",
  "screenshotUrls": ["string"]
  }
  

• Response:

  {
  "code": 0,
  "message": "success",
  "data": {
    "id": "uuid",
    "status": "submitted"
  }
  }
  

后续步骤

• 运行 npx prisma generate 生成客户端
• 运行 npx prisma db push 更新数据库表

---