# 开发流程

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [FEATURE_CHECKLIST.md](file://FEATURE_CHECKLIST.md)
- [DEPLOY.md](file://DEPLOY.md)
- [docs/API.md](file://docs/API.md)
- [docs/database-structure.md](file://docs/database-structure.md)
- [优化开发计划.md](file://优化开发计划.md)
- [开发计划-第二期.md](file://开发计划-第二期.md)
- [Bug 修复总结.md](file://Bug 修复总结.md)
- [PROJECT_SUMMARY.md](file://PROJECT_SUMMARY.md)
- [feature_list.json](file://feature_list.json)
- [.plans/audiobook-v2-ux/task_plan.md](file://.plans/audiobook-v2-ux/task_plan.md)
- [.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md](file://.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md)
- [.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md](file://.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md)
</cite>

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

## 引言
本开发流程文档面向AI有声书生成平台，围绕“功能开发流程、API开发流程、数据库变更流程”以及“开发计划制定、任务分解、进度跟踪”，结合仓库中的实际计划、接口文档、数据库结构与优化实践，提供可落地的流程规范与模板，帮助团队高效协作、降低风险、保障质量。

## 项目结构
项目采用前后端分离架构，后端以Koa + TypeScript + MongoDB为主，前端使用uni-app + Vue 3 + TypeScript，配合Prisma进行数据库建模与迁移。文档与计划文件集中于根目录与docs目录，便于版本化管理与评审。

```mermaid
graph TB
subgraph "前端(uni-app)"
FE_App["应用入口<br/>main.ts"]
FE_Store["状态管理<br/>Pinia Store"]
FE_Pages["页面组件<br/>pages/*"]
FE_Utils["工具库<br/>utils/*"]
end
subgraph "后端(Koa)"
BE_App["应用入口<br/>app.ts"]
BE_Modules["业务模块<br/>modules/*"]
BE_Services["服务层<br/>services/*"]
BE_DB["数据库<br/>MongoDB + Prisma"]
end
subgraph "文档与计划"
Docs["API文档<br/>docs/API.md"]
Plan["开发计划<br/>.plans/audiobook-v2-ux/*"]
DBDoc["数据库结构<br/>docs/database-structure.md"]
end
FE_Pages --> FE_Store
FE_Pages --> FE_Utils
FE_Pages --> BE_App
BE_App --> BE_Modules
BE_Modules --> BE_Services
BE_Services --> BE_DB
Docs --> BE_App
Plan --> FE_Pages
Plan --> BE_App
DBDoc --> BE_DB
```

图表来源
- [README.md:31-52](file://README.md#L31-L52)
- [docs/API.md:1-499](file://docs/API.md#L1-L499)
- [docs/database-structure.md:1-402](file://docs/database-structure.md#L1-L402)
- [.plans/audiobook-v2-ux/task_plan.md:1-108](file://.plans/audiobook-v2-ux/task_plan.md#L1-L108)

章节来源
- [README.md:31-52](file://README.md#L31-L52)
- [docs/API.md:1-499](file://docs/API.md#L1-L499)
- [docs/database-structure.md:1-402](file://docs/database-structure.md#L1-L402)
- [.plans/audiobook-v2-ux/task_plan.md:1-108](file://.plans/audiobook-v2-ux/task_plan.md#L1-L108)

## 核心组件
- 前端组件
  - 页面层：pages/*（播放器、历史记录、书籍生成、搜索、收藏、设置等）
  - 状态层：Pinia Store（用户、音频、播放器状态）
  - 工具层：请求封装、WebSocket工具、存储与配置
- 后端组件
  - 控制器与服务：modules/* 与 services/*
  - 中间件：鉴权、错误处理、限流、安全
  - 数据模型：Prisma Schema + 迁移脚本
- 文档与计划
  - API契约：docs/API.md
  - 数据库结构：docs/database-structure.md
  - 优化计划：.plans/audiobook-v2-ux/*

章节来源
- [FEATURE_CHECKLIST.md:1-150](file://FEATURE_CHECKLIST.md#L1-L150)
- [开发计划-第二期.md:41-67](file://开发计划-第二期.md#L41-L67)
- [优化开发计划.md:42-399](file://优化开发计划.md#L42-L399)

## 架构总览
系统采用“书籍体系 + 学习路径体系”的双轨内容管理架构，后端通过模块化服务提供TTS、音频、视频、分享、播放记录、收藏、专辑等功能；前端通过页面与状态管理实现播放器、生成流程、搜索与分类、收藏与设置等体验优化。

```mermaid
graph TB
subgraph "前端页面"
Index["首页"]
Player["播放器"]
History["历史记录"]
Generator["书籍生成"]
Search["搜索"]
Favorites["收藏"]
Settings["设置"]
end
subgraph "后端模块"
Auth["认证模块"]
TTS["TTS模块"]
Audio["音频模块"]
Video["视频生成模块"]
Share["分享模块"]
PlayerMod["播放记录/偏好模块"]
Fav["收藏模块"]
Album["专辑模块"]
end
Index --> Player
Player --> Audio
Player --> PlayerMod
History --> Audio
Generator --> TTS
Generator --> Audio
Search --> Audio
Favorites --> Fav
Settings --> PlayerMod
Share --> Audio
Album --> Audio
```

图表来源
- [docs/database-structure.md:20-160](file://docs/database-structure.md#L20-L160)
- [docs/API.md:13-499](file://docs/API.md#L13-L499)
- [开发计划-第二期.md:71-117](file://开发计划-第二期.md#L71-L117)

## 详细组件分析

### 功能开发流程（需求分析→设计评审→开发实现→测试验证）
- 需求分析
  - 以“.plans/audiobook-v2-ux/task_plan.md”为依据，明确优化项优先级与范围，避免改动核心业务逻辑。
  - 参考“优化开发计划.md”中的“优化项分布”与“实施路线图”，拆解每日任务。
- 设计评审
  - 前后端负责人在“task_plan.md”中明确分工与接口契约，确保WebSocket事件、API路径与状态字段一致。
- 开发实现
  - 前端：按页面维度进行组件级开发，遵循“极简改动、增量实施”原则。
  - 后端：按模块开发，确保接口幂等与错误处理一致。
- 测试验证
  - 使用“feature_list.json”中的测试步骤进行端到端验证，覆盖功能、性能与兼容性。

```mermaid
flowchart TD
Start(["开始"]) --> Analyze["需求分析<br/>确定优先级与范围"]
Analyze --> Review["设计评审<br/>前后端接口契约确认"]
Review --> Dev["开发实现<br/>前端组件/后端模块"]
Dev --> TestPlan["测试计划<br/>参考 feature_list.json"]
TestPlan --> UnitTest["单元/接口测试"]
UnitTest --> E2E["端到端测试<br/>覆盖关键流程"]
E2E --> Deploy["部署验证<br/>DEPLOY.md"]
Deploy --> Done(["完成"])
```

图表来源
- [.plans/audiobook-v2-ux/task_plan.md:33-66](file://.plans/audiobook-v2-ux/task_plan.md#L33-L66)
- [优化开发计划.md:331-364](file://优化开发计划.md#L331-L364)
- [feature_list.json:1-683](file://feature_list.json#L1-L683)
- [DEPLOY.md:10-160](file://DEPLOY.md#L10-L160)

章节来源
- [.plans/audiobook-v2-ux/task_plan.md:1-108](file://.plans/audiobook-v2-ux/task_plan.md#L1-L108)
- [优化开发计划.md:331-364](file://优化开发计划.md#L331-L364)
- [feature_list.json:1-683](file://feature_list.json#L1-L683)
- [DEPLOY.md:10-160](file://DEPLOY.md#L10-L160)

### API开发流程（接口设计→文档编写→联调测试）
- 接口设计
  - 参考“docs/API.md”中的模块划分与接口定义，确保统一响应格式与错误码。
  - 优化项“OPT-08 一键完整生成”新增编排接口，需在“docs/API.md”中补充。
- 文档编写
  - 使用“docs/API.md”作为统一API契约，前后端共同维护。
- 联调测试
  - 前端：在“task-opt02”中明确WebSocket事件监听与超时移除。
  - 后端：在“PLAN.md”中定义WebSocket事件格式与推送时机。

```mermaid
sequenceDiagram
participant FE as "前端页面"
participant WS as "WebSocket服务"
participant BE as "后端服务"
FE->>WS : 建立连接 /ws
BE-->>WS : 生成完成事件
WS-->>FE : 推送 audio_generation_complete
FE->>FE : 更新章节状态/进度
FE->>BE : 轮询/查询可选
BE-->>FE : 最终状态
```

图表来源
- [.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md:18-38](file://.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md#L18-L38)
- [.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32](file://.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md#L12-L32)

章节来源
- [docs/API.md:13-499](file://docs/API.md#L13-L499)
- [.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md:1-38](file://.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md#L1-L38)
- [.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:1-32](file://.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md#L1-L32)

### 数据库变更流程（Schema设计→迁移脚本→数据迁移）
- Schema设计
  - 参考“docs/database-structure.md”中的表结构与索引设计，确保字段含义与约束清晰。
- 迁移脚本
  - 使用Prisma迁移（server/prisma/migrations），遵循“不可破坏性”与“幂等性”。
- 数据迁移
  - 对于历史数据，提供迁移脚本与校验步骤，确保数据一致性。

```mermaid
flowchart TD
Design["设计Schema<br/>字段/索引/约束"] --> Migrate["生成迁移脚本"]
Migrate --> Apply["应用迁移"]
Apply --> Verify["数据校验与回归测试"]
Verify --> Release["上线发布"]
```

图表来源
- [docs/database-structure.md:345-402](file://docs/database-structure.md#L345-L402)
- [开发计划-第二期.md:120-200](file://开发计划-第二期.md#L120-L200)

章节来源
- [docs/database-structure.md:345-402](file://docs/database-structure.md#L345-L402)
- [开发计划-第二期.md:120-200](file://开发计划-第二期.md#L120-L200)

### 开发计划制定（功能优先级、时间估算、资源分配）
- 优先级与范围
  - P0：必须修复（轮询超时、按钮合并、首页最近收听）
  - P1：重要优化（简洁模式、睡眠定时、骨架屏、生成按钮固定、一键完整生成）
  - P2/P3：体验提升与锦上添花
- 时间估算与实施路线图
  - 参考“优化开发计划.md”的“实施路线图”，按阶段分配工时与人员。
- 资源分配
  - 前后端协同：WebSocket事件、编排接口、反馈提交接口等跨模块任务。

章节来源
- [优化开发计划.md:19-399](file://优化开发计划.md#L19-L399)
- [.plans/audiobook-v2-ux/task_plan.md:33-108](file://.plans/audiobook-v2-ux/task_plan.md#L33-L108)

### 任务分解（Story Points、开发周期、里程碑设置）
- Story Points
  - 以“小时”为粒度估算（如OPT-02：2h；OPT-08：4h），便于迭代排期。
- 开发周期
  - 第一阶段（P0）：3天；第二阶段（P1）：5天；第三阶段（P2）：2天；第四阶段（P3）：1天。
- 里程碑
  - 每阶段末尾设置阶段性交付，结合“feature_list.json”的测试步骤进行验收。

章节来源
- [优化开发计划.md:331-364](file://优化开发计划.md#L331-L364)
- [feature_list.json:1-683](file://feature_list.json#L1-L683)

### 进度跟踪（每日站会、迭代回顾、风险评估）
- 每日站会
  - 明确当日目标（如OPT-02超时修复），核对状态与阻塞项。
- 迭代回顾
  - 以“.plans/audiobook-v2-ux/task_plan.md”为依据，回顾阶段成果与遗留问题。
- 风险评估
  - 前端兼容性（H5/小程序）、后端WebSocket稳定性、接口幂等性与错误处理。

章节来源
- [.plans/audiobook-v2-ux/task_plan.md:105-108](file://.plans/audiobook-v2-ux/task_plan.md#L105-L108)
- [Bug 修复总结.md:228-242](file://Bug 修复总结.md#L228-L242)

### 新功能开发模板
- 需求与范围
  - 明确功能目标、涉及页面、预估工时与风险。
- 接口设计
  - 参考“docs/API.md”，定义请求/响应格式与错误码。
- 前端实现
  - 页面组件、状态管理、工具类（如WebSocket工具）。
- 后端实现
  - 控制器、服务、中间件与数据库操作。
- 测试与验收
  - 使用“feature_list.json”中的测试步骤进行端到端验证。

章节来源
- [docs/API.md:13-499](file://docs/API.md#L13-L499)
- [feature_list.json:1-683](file://feature_list.json#L1-L683)

### Bug修复流程
- 识别与分类
  - 依据“Bug 修复总结.md”中的优先级（高/中/低）进行分类。
- 修复与验证
  - 前端：状态管理、请求封装、定时器清理等。
  - 后端：统一错误处理、接口幂等、资源释放。
- 回归测试
  - 使用“feature_list.json”中的测试步骤进行回归验证。

章节来源
- [Bug 修复总结.md:1-264](file://Bug 修复总结.md#L1-L264)
- [feature_list.json:1-683](file://feature_list.json#L1-L683)

### 紧急变更处理机制
- 快速评估
  - 评估影响范围与风险，必要时冻结相关分支。
- 快速修复
  - 前后端协同，优先保证接口兼容与错误处理。
- 快速验证
  - 使用最小化测试集验证，确保不引入新问题。
- 发布与回滚
  - 通过“DEPLOY.md”中的部署流程快速发布，必要时回滚。

章节来源
- [DEPLOY.md:10-160](file://DEPLOY.md#L10-L160)
- [Bug 修复总结.md:228-242](file://Bug 修复总结.md#L228-L242)

## 依赖分析
- 前端依赖后端API与WebSocket事件，需严格遵循契约。
- 后端模块之间通过服务层解耦，控制器负责路由与参数校验。
- 数据库变更需与API版本同步，确保迁移脚本与接口兼容。

```mermaid
graph LR
FE_Index["首页"] --> BE_Player["播放记录/偏好"]
FE_Player["播放器"] --> BE_Audio["音频模块"]
FE_Gen["书籍生成"] --> BE_TTS["TTS模块"]
FE_WS["WebSocket工具"] --> BE_WS["WebSocket服务"]
BE_TTS --> BE_DB["数据库"]
BE_Player --> BE_DB
```

图表来源
- [docs/API.md:13-499](file://docs/API.md#L13-L499)
- [.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32](file://.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md#L12-L32)

章节来源
- [docs/API.md:13-499](file://docs/API.md#L13-L499)
- [.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32](file://.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md#L12-L32)

## 性能考虑
- 前端
  - 骨架屏、图片懒加载、虚拟滚动、过渡动画，提升首屏与滚动性能。
- 后端
  - 并行任务处理、限流与安全中间件、统一错误处理与日志记录。
- 数据库
  - 合理索引设计（如用户+状态、专辑+音频顺序），避免全表扫描。

章节来源
- [开发计划-第二期.md:253-265](file://开发计划-第二期.md#L253-L265)
- [docs/database-structure.md:345-402](file://docs/database-structure.md#L345-L402)

## 故障排查指南
- 后端无法启动
  - 检查端口占用、环境变量、PM2状态与日志。
- 前端无法访问
  - 检查Nginx配置、静态文件权限与缓存。
- 数据库连接失败
  - 检查MySQL服务状态与连接配置。
- WebSocket连接异常
  - 核对事件格式与推送时机，确保前后端契约一致。

章节来源
- [DEPLOY.md:199-250](file://DEPLOY.md#L199-L250)
- [.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md:18-38](file://.plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md#L18-L38)
- [.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32](file://.plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md#L12-L32)

## 结论
本流程文档以仓库中的计划、接口与数据库文档为基础，结合优化实践，提供了从需求到发布的全流程规范。通过明确的优先级、任务分解与进度跟踪机制，配合严格的测试与故障排查流程，能够有效提升团队协作效率与交付质量。

## 附录
- 快速参考
  - API契约：docs/API.md
  - 数据库结构：docs/database-structure.md
  - 部署流程：DEPLOY.md
  - 优化计划：.plans/audiobook-v2-ux/task_plan.md
  - 测试清单：feature_list.json

章节来源
- [docs/API.md:1-499](file://docs/API.md#L1-L499)
- [docs/database-structure.md:1-402](file://docs/database-structure.md#L1-L402)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [.plans/audiobook-v2-ux/task_plan.md:1-108](file://.plans/audiobook-v2-ux/task_plan.md#L1-L108)
- [feature_list.json:1-683](file://feature_list.json#L1-L683)