hs-data/docs/08-迭代与发布.md

迭代与发布流程

平台如何一版一版往前走:迭代单元、闭环流程、PRD 文档演进、版本方案、发布收尾清单。 关联:产品/IA docs/01;角色边界 docs/05;"改动同步文档"见根 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。新模块动工前,先在 §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。