# 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:
  ```json
  {
    "type": "suggestion|bug|other",
    "title": "string",
    "content": "string",
    "contact": "string",
    "screenshotUrls": ["string"]
  }
  ```
- Response:
  ```json
  {
    "code": 0,
    "message": "success",
    "data": {
      "id": "uuid",
      "status": "submitted"
    }
  }
  ```

### 后续步骤

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

---