audio_codebuddy/CONTRIBUTING.md

⛔ 必读：贡献与发布规范

每位开发者每次修改 / 提交 / 发布前必读。 不按规范执行导致的核心业务回归事故，由当事人承担。

---

🚦 一句话原则

修改 → 跑核心业务测试 → 通过 → 提交 → 跑一次完整核心业务测试 → 通过 → 推送/发布

---

1. 什么是"核心业务"

本项目的产品核心链路 = "书籍 大纲 → 内容 → 音频" 端到端流程。

步骤	涉及 API	涉及前端
创建书	POST /api/book-generator/langgraph/books	pages/book-generator/create.vue
生成大纲	POST /api/book-generator/langgraph/books/:id/outline	pages/book-generator/detail.vue
生成内容	POST /api/book-generator/langgraph/books/:id/chapters	pages/book-generator/detail.vue
生成音频	POST /api/book-generator/langgraph/books/:id/audio	pages/book-generator/detail.vue
播放/查看	GET /api/book-generator/langgraph/books/:id 等	pages/book-generator/{index,detail,chapter-detail}.vue

任何用户能感知到的功能缺陷，几乎全部会落在这条链路上。

---

2. 强制时机表

场景	必跑？	命令
改了 server/src/modules/book-generator/** 任何文件	✅ 必须	./scripts/run-core-business-test.sh
改了 my-uniapp-vue3/src/pages/book-generator/** 任何文件	✅ 必须	./scripts/run-core-business-test.sh
改了 my-uniapp-vue3/src/utils/book-generator-api.ts	✅ 必须	./scripts/run-core-business-test.sh
改了 server/prisma/schema.prisma（Book / BookChapter 表）	✅ 必须	./scripts/run-core-business-test.sh
提交前（commit）	✅ 必须（hook 已强制）	git commit 自动跑
推送前（push）	✅ 必须（hook 已强制）	git push 自动跑
部署/发布前	✅ 必须	./scripts/run-core-business-test.sh 或 cd server && npm run test:core
改了无关文件	⚪ 可选，但建议跑	同上

识别"改动是否触发必跑"的方法：

git diff --name-only HEAD~5 | grep -E "(book-generator|book-generator-api|schema.prisma)"
# 有输出 = 触发必跑

---

3. 执行命令速查

3.1 一键脚本（推荐）

# 自动起后端+前端再跑测试
./scripts/run-core-business-test.sh

# 服务已起好（快）
SKIP_SERVER=1 ./scripts/run-core-business-test.sh

# Windows
scripts\run-core-business-test.bat

3.2 直接调 playwright

npx playwright test --project=core-business --config=tests/playwright.config.ts

3.3 npm script（cd server 后）

cd server && npm run test:core

---

4. 核心业务测试是什么

位置： tests/e2e/core-business/book-core-flow.spec.ts

用例清单：

#	名称	类型	验证点
CORE-1	预估字数与时长	API	/api/book-generator/langgraph/estimate 返回 audioMinutes.avg > 0
CORE-2	创建书籍（fast-path）	API	POST /books 立即返回 outlining + bookId
CORE-3	大纲+内容：轮询直到 chapters 有真实内容	API	轮询直到 chapters[*].genStage === 'content_completed'
CORE-4	触发音频生成（best-effort）	API	POST /audio + 轮询 audio-status 全部完成
CORE-5	书籍至少完成内容阶段	API	校验 genStage >= content_completed
CORE-6~9	列表/创建/详情/章节详情页能加载	UI	hash 路由 + #app 根可见

参考时长： 健康环境 3 ~ 5 分钟（含真实 LLM + TTS 调用）。

完整说明： tests/e2e/core-business/README.md

---

5. 失败处理流程

测试失败
  │
  ├─ 看 tests/test-results/report/index.html (HTML 报告)
  ├─ 看 tests/test-results/results.json  (结构化结果)
  │
  ├─ 失败的是 CORE-1~3, 5~9（API / UI）
  │   └─ 大概率是后端接口契约或前端渲染问题 → 修代码，重新跑
  │
  ├─ 失败的是 CORE-4（音频）
  │   ├─ 真实环境（生产 / 健康 staging）：必查 TTS Provider
  │   │   ├─ 阿里的 CosyVoice / 百炼 TTS 配额？
  │   │   ├─ OSS bucket 写权限？
  │   │   └─ 详见 server/logs/tts.log
  │   └─ 本地开发环境（mock TTS）：可能是环境问题，可跳过
  │       └─ test.skip() 已写入，warn 即可
  │
  └─ 一直超时（> 10 分钟都没过）
      └─ 检查：
          ├─ 后端 tsx watch 是否在反复重启？
          ├─ 数据库是否可达？(tests/global-setup.ts 会验)
          ├─ LLM API 配额 / 网络？
          └─ 看 server/logs/server.log [LangGraph] 段

强制： 失败立即定位并修复，不允许"应该没问题"放行。修复后重跑测试直到通过。

---

6. Git Hooks 安装（强烈推荐）

仓库提供 git hooks，提交 / 推送前自动检查。

# 安装（一次）
./scripts/install-hooks.sh

# 卸载（如果你需要绕过）
./scripts/install-hooks.sh --uninstall

装好后：

• pre-commit：检测到改了核心业务文件时，自动跑核心测试（≈3 分钟）
• pre-push：永远跑一次完整核心测试

⚠️ 如果你必须紧急绕过（hotfix / 撤回到旧版本）：

git commit --no-verify   # 跳过 pre-commit
git push --no-verify     # 跳过 pre-push

绕过等于背着责任提交，请在 PR 描述里写明原因。

---

7. 发布前清单

#	检查项	通过标准
1	./scripts/run-core-business-test.sh	8 passed, 0 failed
2	cd server && npm run test:unit	全部 pass
3	cd server && npm run build && npm start 烟测	/health 返回 200
4	部署后 curl <线上>/api/book-generator/langgraph/books/{任意bookId}	返回 code:0 或 code:404（不是 500）
5	部署后 curl <线上>/<某个 audioUrl>	200 + content-length > 1024

详细步骤见 AUTO_DEPLOY.md。

---

8. 违反规范的后果

• 核心业务回归进了线上 → 当事人 + reviewer 一起回滚，承担事故责任
• 跳过测试直接发布 → 代码合并 PR 需要 reviewer 在评论区确认"已跑测试"

---

9. 新人入职清单

• 读完本文
• 跑一次 ./scripts/run-core-business-test.sh 看绿色 8 pass
• 安装 ./scripts/install-hooks.sh
• 看 tests/e2e/core-business/README.md 了解每个 CORE-* 用例
• 看 .plans/audiobook-v2-ux/docs/invariants.md 了解业务不变量

---

如果本文档与 AUTO_DEPLOY.md / CLAUDE.md 冲突，以本文档为准。