# ⛔ 必读：贡献与发布规范

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

---

## 🚦 一句话原则

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

---

## 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` |
| 改了无关文件 | ⚪ 可选，但建议跑 | 同上 |

**识别"改动是否触发必跑"的方法：**
```bash
git diff --name-only HEAD~5 | grep -E "(book-generator|book-generator-api|schema.prisma)"
# 有输出 = 触发必跑
```

---

## 3. 执行命令速查

### 3.1 一键脚本（推荐）
```bash
# 自动起后端+前端再跑测试
./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
```bash
npx playwright test --project=core-business --config=tests/playwright.config.ts
```

### 3.3 npm script（cd server 后）
```bash
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，提交 / 推送前自动检查。

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

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

装好后：

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

⚠️ 如果你必须紧急绕过（hotfix / 撤回到旧版本）：
```bash
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` 冲突，以本文档为准。**