audio_codebuddy/.qoder/repowiki/zh/content/开发指南/开发流程.md

开发流程

本文引用的文件

• README.md
• FEATURE_CHECKLIST.md
• DEPLOY.md
• docs/API.md
• docs/database-structure.md
• 优化开发计划.md
• 开发计划-第二期.md
• Bug 修复总结.md
• PROJECT_SUMMARY.md
• feature_list.json
• .plans/audiobook-v2-ux/task_plan.md
• .plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md
• .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目录，便于版本化管理与评审。

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
• docs/API.md:1-499
• docs/database-structure.md:1-402
• .plans/audiobook-v2-ux/task_plan.md:1-108

章节来源

• README.md:31-52
• docs/API.md:1-499
• docs/database-structure.md:1-402
• .plans/audiobook-v2-ux/task_plan.md:1-108

核心组件

• 前端组件
  • 页面层：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
• 开发计划-第二期.md:41-67
• 优化开发计划.md:42-399

架构总览

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

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
• docs/API.md:13-499
• 开发计划-第二期.md:71-117

详细组件分析

功能开发流程（需求分析→设计评审→开发实现→测试验证）

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

• 测试验证

  • 使用“feature_list.json”中的测试步骤进行端到端验证，覆盖功能、性能与兼容性。

    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
• 优化开发计划.md:331-364
• feature_list.json:1-683
• DEPLOY.md:10-160

章节来源

• .plans/audiobook-v2-ux/task_plan.md:1-108
• 优化开发计划.md:331-364
• feature_list.json:1-683
• DEPLOY.md:10-160

API开发流程（接口设计→文档编写→联调测试）

• 接口设计
  • 参考“docs/API.md”中的模块划分与接口定义，确保统一响应格式与错误码。
  • 优化项“OPT-08 一键完整生成”新增编排接口，需在“docs/API.md”中补充。
• 文档编写
  • 使用“docs/API.md”作为统一API契约，前后端共同维护。

• 联调测试

  • 前端：在“task-opt02”中明确WebSocket事件监听与超时移除。

  • 后端：在“PLAN.md”中定义WebSocket事件格式与推送时机。

    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
• .plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32

章节来源

• docs/API.md:13-499
• .plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md:1-38
• .plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:1-32

数据库变更流程（Schema设计→迁移脚本→数据迁移）

• Schema设计
  • 参考“docs/database-structure.md”中的表结构与索引设计，确保字段含义与约束清晰。
• 迁移脚本
  • 使用Prisma迁移（server/prisma/migrations），遵循“不可破坏性”与“幂等性”。

• 数据迁移

  • 对于历史数据，提供迁移脚本与校验步骤，确保数据一致性。

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

图表来源

• docs/database-structure.md:345-402
• 开发计划-第二期.md:120-200

章节来源

• docs/database-structure.md:345-402
• 开发计划-第二期.md:120-200

开发计划制定（功能优先级、时间估算、资源分配）

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

章节来源

• 优化开发计划.md:19-399
• .plans/audiobook-v2-ux/task_plan.md:33-108

任务分解（Story Points、开发周期、里程碑设置）

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

章节来源

• 优化开发计划.md:331-364
• feature_list.json:1-683

进度跟踪（每日站会、迭代回顾、风险评估）

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

章节来源

• .plans/audiobook-v2-ux/task_plan.md:105-108
• Bug 修复总结.md:228-242

新功能开发模板

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

章节来源

• docs/API.md:13-499
• feature_list.json:1-683

Bug修复流程

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

章节来源

• Bug 修复总结.md:1-264
• feature_list.json:1-683

紧急变更处理机制

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

章节来源

• DEPLOY.md:10-160
• Bug 修复总结.md:228-242

依赖分析

• 前端依赖后端API与WebSocket事件，需严格遵循契约。
• 后端模块之间通过服务层解耦，控制器负责路由与参数校验。

• 数据库变更需与API版本同步，确保迁移脚本与接口兼容。

  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
• .plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32

章节来源

• docs/API.md:13-499
• .plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32

性能考虑

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

章节来源

• 开发计划-第二期.md:253-265
• docs/database-structure.md:345-402

故障排查指南

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

章节来源

• DEPLOY.md:199-250
• .plans/audiobook-v2-ux/frontend-dev/task-opt02/task_plan.md:18-38
• .plans/audiobook-v2-ux/backend-dev/task-opt02/PLAN.md:12-32

结论

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

附录

• 快速参考
  • 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
• docs/database-structure.md:1-402
• DEPLOY.md:1-251
• .plans/audiobook-v2-ux/task_plan.md:1-108
• feature_list.json:1-683