# 迭代与发布流程

> 平台如何一版一版往前走:迭代单元、闭环流程、PRD 文档演进、版本方案、发布收尾清单。
> 关联:产品/IA [docs/01](01-产品需求-MVP.md);角色边界 [docs/05](05-agent协作准则.md);"改动同步文档"见根 [CLAUDE.md](../CLAUDE.md) 规则 6。

## 1. 迭代单元:端到端垂直切片

按能力域**一个个把模块做到端到端可用**(拼团漏斗为范本),**不先铺框架**。每个切片 = 一个 L2 分析模型或 L3 报表,从取数口径 → 页面 → 验收一条龙,每次都产出**可上线、可汇报**的成果,风险小。

## 2. 闭环流程(每个切片走同一条流水线)

1. **需求登记** → `docs/01` 路线图/状态表(或 issue)。
2. **PRD 先行** → 动工前先写清/对齐平台级状态 + 模块级详规(对应 CLAUDE.md 规则 1"先想清楚")。
3. **实现** → `feature-xxx` 分支 → 测试 → PR 合 `feature`。
4. **收尾** → `CHANGELOG`(规则 5)+ 同步文档(规则 6)。
5. **上线** → `/look`。
6. **定期** → `/docs-check` 扫漂移。

> **铁律:PRD 先行**——先文档对齐、再写代码。拼团漏斗是"边做边补文档",以后新模块不要再这样,避免漂移。

## 3. PRD 文档的两层结构与演进

- **平台级 PRD**(`docs/01`,保留):定位、IA(5 能力域)、路线图、全局约束(数据现实/访问权限)、**各模块"可用/待开发"状态总表**。精简、稳定、少改。
- **模块级 PRD**(`docs/prd/<模块>.md`,按需新增):每个端到端模块一份详规(定义/口径/时间能力/页面/验收,即现在 `docs/01` §4 的形态)。`docs/01` 只留一句定位 + 链接。

**现状(已落地)**:`docs/01` §4 已收敛为**模块索引表**;拼团漏斗详规独立成册 [`docs/prd/拼团漏斗.md`](prd/拼团漏斗.md)。新模块动工前,先在 §4 表登记 + 建对应 `docs/prd/<模块>.md`(**PRD 先行**,见 §2 与 CLAUDE.md 规则 7)。

## 4. 版本方案

内部工具、单一部署、暂无外部消费方 → **版本号是里程碑标记,不是依赖管理**,不上严格 SemVer。

| 阶段 | 版本 | 规则 |
|---|---|---|
| MVP 内网迭代(现在) | **—(未打号)** | 靠 CHANGELOG 日期 + git SHA;关键状态可 `git tag`(如 `mvp-拼团漏斗`) |
| 切 `release`(首个稳定内网版) | **v1.0** | 平台第一个正式版 |
| 每上线**一个新能力域模块** | **minor +1**(v1.1、v1.2…) | 如 v1.1 加留存、v1.2 加看板 |
| 模块内修复/小改/文案 | **不 bump** | CHANGELOG 记即可 |
| 平台级大重构(IA 翻修等) | **major +1**(v2.0) | 罕见 |

**例外**:`apps/api` 将来**对外供数**时,单独走标准 SemVer(契约不兼容 → major,兼容加端点/字段 → minor,修复 → patch);在此之前跟随平台里程碑。

**真相源**:`git tag` 是已发布版本的权威;PRD 版本栏、CHANGELOG 只镜像它。

## 5. 三层记录,各管各的(别混)

| 层 | 管什么 | 粒度 | 给谁看 |
|---|---|---|---|
| `CHANGELOG.md` | **每次**落地改动(代码/文档) | 细,按日期 | 研发 |
| `docs/01` 修订记录 | **产品/规格级**变更 | 粗,按日期,里程碑行标版本 | 产品/需求方 |
| `git tag` + PRD 版本栏 | **里程碑**(版本号) | 只在 bump 点 | 汇报 |

一次版本变更三层都留痕,但粒度不同:CHANGELOG 可能记 20 条、PRD 修订记录记 1 条、tag 打 1 个。

## 6. 发布收尾清单(版本 bump = 新模块上线时跑一遍)

1. **模块详规**写好(`docs/prd/<模块>.md`,或未拆前加 §)。
2. `docs/01` **状态总表**(§2.1/§2.2)→ 该模块"可用";**路线图**(§5)→ 已交付;§3/§8 纳入。
3. `docs/01` **版本栏 + 更新日期** → 新版本。
4. `docs/01` **修订记录**加一行,版本列标 `vX.Y`。
5. `CHANGELOG` 记(日期 + "发布 vX.Y")。
6. `git tag vX.Y`。
7. `package.json` 版本对齐(切 `release` 起)。

**非版本的规格小改**:照规则 6 更对应段 + 更新日期 + 修订记录加一条日期行(**版本列留空**);纯内部实现改动不动 PRD。