# AI有声书 v2 - 团队运营手册

> 由 CCteam-creator 自动生成
> 此文件让 team-lead 的团队知识在上下文压缩后仍然保持

## Team-Lead 控制平面

- team-lead = 主对话，不是生成的 agent
- team-lead 负责用户对齐、范围控制、任务分解和阶段推进
- team-lead 维护项目全局真相：主 `task_plan.md`、`decisions.md` 和此 `CLAUDE.md`

## 团队花名册

| 名称 | 角色 | 模型 | 核心能力 |
|------|------|------|---------|
| frontend-dev | 前端开发 | sonnet | uniapp Vue 3 前端优化 |
| backend-dev | 后端开发 | sonnet | Node.js/Express API + WebSocket |
| reviewer | 代码审查 | sonnet | 安全/质量/性能审查（只读） |

## 任务下发协议

### 消息送达时序（关键）
`SendMessage` 只在接收方 idle 时送达——**无法**打断进行中的任务。

### TaskCreate 描述格式
TaskCreate 描述：一句话范围 + 验收标准 + `.plans/` 路径。

## 状态检查

| 要检查什么 | 怎么做 |
|-----------|--------|
| 全局概览 | `TaskList` — 所有任务、负责人、阻塞情况一览 |
| 快速扫描 | 并行读取各 agent 的 `progress.md` |
| 深入了解 | 读 agent 的 `findings.md`（索引）→ 再看具体任务文件夹 |

## 文档索引（知识库）

| 文档 | 位置 | 维护者 |
|------|------|--------|
| 导航地图 | .plans/audiobook-v2-ux/docs/index.md | custodian |
| 架构 | .plans/audiobook-v2-ux/docs/architecture.md | team-lead, devs |
| API 契约 | .plans/audiobook-v2-ux/docs/api-contracts.md | devs |
| 不变量 | .plans/audiobook-v2-ux/docs/invariants.md | team-lead, reviewer |

## 审查维度

| # | 维度 | 权重 | STRONG 表现 | WEAK 表现 |
|---|------|------|-----------|-----------|
| RD-1 | 产品深度 | 高 | 涵盖真实用户边界情况（空状态、错误恢复） | 仅开心路径 |
| RD-2 | 代码质量 | 高 | 函数<50行，文件<800行，错误处理明确 | 大函数，吞异常 |
| RD-3 | 前端性能 | 中 | 无不必要重渲染，有 memoization | 频繁重渲染 |
| RD-4 | 文档同步 | 高 | API/架构变更同步更新 docs/ | 文档漂移 |

## 核心协议

| 协议 | 触发时机 | 操作 |
|------|---------|------|
| 代码审查 | 大功能/新模块完成 | dev 在 findings.md 写改动摘要，发给 reviewer |
| 阶段推进 | 阶段完成 | 开发完：等 reviewer [OK]/[WARN] |
| **核心业务回归** | 修改 `book-generator` / `langgraph` / `tts` / `book-generator 前端页面` **或** 发布上线前 | 跑 `./scripts/run-core-business-test.sh`，链路必须全绿 |

## 运维红线
禁止 `docker rm` / `docker volume rm` / `docker system prune` / `rm -rf` —— 释放端口只准 `docker stop`，用户没明说"删掉/移除/扔了"前不许删任何东西。

## 核心业务测试

业务核心链路 = **书籍 大纲 → 内容 → 音频**。每次改动相关模块、每次发布上线前都必须跑通。

**强制规范详见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)** —— 一句话原则："修改 → 跑核心业务测试 → 通过 → 提交 → 跑核心业务测试 → 通过 → 推送/发布"。

```bash
./scripts/run-core-business-test.sh    # 自动起服务并跑
# 或服务已起好：
SKIP_SERVER=1 ./scripts/run-core-business-test.sh
# Windows:
scripts\run-core-business-test.bat
```

测试用例：`tests/e2e/core-business/book-core-flow.spec.ts`，9 个 CORE-* 用例覆盖 API + UI 完整链路。失败立即定位修复，禁止"应该没问题"放行。

### git hooks（每位开发者本地安装一次）

```bash
./scripts/install-hooks.sh
```

装好后：`git commit` 检测到核心业务改动自动跑测试；`git push` 强制跑一次。紧急绕过用 `--no-verify`（PR 描述里说明）。

## 优化项目索引

详见 `.plans/audiobook-v2-ux/task_plan.md`

| 优先级 | 数量 | 代表项 |
|--------|------|--------|
| P0 必须优化 | 3 | 按钮合并、轮询超时、首页最近收听 |
| P1 重要优化 | 5 | 简洁模式、睡眠定时器、骨架屏、一键生成 |
| P2 体验提升 | 6 | 封面升级、手势切换、我的页动态化 |
| P3 锦上添花 | 4 | 热词缓存、歌词时间轴、确认弹窗 |