# 后端服务文档扩展计划

> **创建日期**：2025-01-27  
> **状态**：已完成 ✅

---

## 任务目标

根据数据库设计文档，补充缺失的核心业务服务文档，完善后端技术文档体系。

---

## 执行步骤

### Step 1: 需求分析 ✅

分析 `docs/需求/database-design.md`，识别出以下缺失的服务：

**核心业务服务（高优先级）**：

1. user-service.md - 用户管理服务
2. resource-service.md - 资源管理服务
3. video-service.md - 视频管理服务
4. timeline-service.md - 时间轴管理服务
5. comment-service.md - 评论协作服务

**媒体处理服务（中优先级）**：6. sound-service.md - 音效管理服务 7. subtitle-service.md - 字幕管理服务 8. voiceover-service.md - 配音管理服务

**扩展功能服务（低优先级）**：9. notification-service.md - 通知服务 10. template-service.md - 模板管理服务

### Step 2: 创建核心服务文档 ✅

按优先级创建了 5 个核心业务服务文档：

#### 1. user-service.md ✅

- 用户注册和登录（JWT 认证）
- 用户信息管理
- 订阅管理（free/pro/enterprise）
- AI 积分管理
- 会话管理

#### 2. resource-service.md ✅

- 资源 CRUD 操作
- 资源分类（角色/场景/道具）
- 资源与分镜关联
- 素材市场功能
- AI 生成资源管理

#### 3. video-service.md ✅

- 视频 CRUD 操作
- 6 种视频生成类型（img2video/text2video/keyframe/fusion/replace/real）
- 视频状态跟踪（pending/processing/completed/failed）
- 视频时间轴位置管理
- AI 生成视频集成

#### 4. timeline-service.md ✅

- 时间轴轨道管理（6 种轨道类型）
- 时间轴项管理
- 轨道排序和显示控制
- 时间范围查询
- 时间冲突检测

#### 5. comment-service.md ✅

- 多态评论（项目/分镜/视频/音效/字幕/配音/时间轴项）
- 回复功能（父子评论）
- @ 提及功能
- 评论解决状态管理
- 时间轴位置标记

### Step 3: 更新相关文档 ✅

更新了 `docs/需求/backend/README.md`：

- 在"核心服务设计"表格中添加 5 个新服务
- 调整服务列表顺序，按业务逻辑分组（用户→文件夹→项目→剧本→附件→分镜→资源→视频→时间轴→评论→AI→导出）
- 更新文档版本号：v1.0 → v1.1
- 添加变更记录章节

---

## 文档特点

每个服务文档包含：

1. **服务概述**：职责和功能范围
2. **核心功能**：详细功能列表
3. **服务实现**：完整的 Python + FastAPI 代码
4. **API 接口**：RESTful API 定义和示例
5. **数据模型**：SQLAlchemy 模型和 Pydantic Schema

---

## 技术亮点

### 1. 资源服务

- 支持素材市场（公开资源、定价、下载统计）
- 文件去重（checksum）
- AI 生成资源管理
- 多种资源类型（角色/场景/道具）

### 2. 视频服务

- 6 种视频生成类型
- 完整的状态跟踪流程
- 时间轴集成
- AI 任务回调机制

### 3. 时间轴服务

- 多轨道编辑（6 种轨道类型）
- 时间冲突检测算法
- 拖拽排序支持
- 时间范围查询（GiST 索引）

### 4. 评论服务

- 多态关联（7 种评论对象）
- @ 提及自动提取和通知
- 评论解决流程
- 时间轴位置标记

### 5. 用户服务

- JWT 认证和授权
- 订阅分级（免费版/专业版/企业版）
- AI 积分系统
- 会话管理（Refresh Token）

---

## 文件清单

### 新增文件

- `docs/需求/backend/04-services/user-service.md`
- `docs/需求/backend/04-services/resource-service.md`
- `docs/需求/backend/04-services/video-service.md`
- `docs/需求/backend/04-services/timeline-service.md`
- `docs/需求/backend/04-services/comment-service.md`
- `docs/计划/backend-services-expansion.md`（本文档）

### 修改文件

- `docs/需求/backend/README.md`（v1.0 → v1.1）

---

## 后续建议

### 短期（本周）

创建中优先级的媒体处理服务：

- sound-service.md - 音效管理服务
- subtitle-service.md - 字幕管理服务
- voiceover-service.md - 配音管理服务

### 中期（本月）

创建扩展功能服务：

- notification-service.md - 通知服务
- template-service.md - 模板管理服务

### 长期（下月）

完善基础设施文档：

- 补充 08-storage.md（文件存储方案）
- 补充 09-ai-integration.md（AI 服务集成）
- 补充 11-performance.md（性能优化策略）
- 补充 12-security.md（安全设计）

---

## 总结

本次更新成功补充了 5 个核心业务服务文档，完善了后端技术文档体系。所有文档遵循统一的格式规范，包含完整的代码示例和 API 定义，可直接用于开发参考。

**完成度**：

- 核心业务服务：5/5 ✅（100%）
- 媒体处理服务：0/3 ⏳（待完成）
- 扩展功能服务：0/2 ⏳（待完成）

---

**创建者**：AI Assistant  
**审核者**：待审核  
**状态**：已完成 ✅