# 开发流程
**本文引用的文件**
- [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)
## 目录
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["应用入口
main.ts"]
FE_Store["状态管理
Pinia Store"]
FE_Pages["页面组件
pages/*"]
FE_Utils["工具库
utils/*"]
end
subgraph "后端(Koa)"
BE_App["应用入口
app.ts"]
BE_Modules["业务模块
modules/*"]
BE_Services["服务层
services/*"]
BE_DB["数据库
MongoDB + Prisma"]
end
subgraph "文档与计划"
Docs["API文档
docs/API.md"]
Plan["开发计划
.plans/audiobook-v2-ux/*"]
DBDoc["数据库结构
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["需求分析
确定优先级与范围"]
Analyze --> Review["设计评审
前后端接口契约确认"]
Review --> Dev["开发实现
前端组件/后端模块"]
Dev --> TestPlan["测试计划
参考 feature_list.json"]
TestPlan --> UnitTest["单元/接口测试"]
UnitTest --> E2E["端到端测试
覆盖关键流程"]
E2E --> Deploy["部署验证
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
字段/索引/约束"] --> 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)