docs(adr): 补齐 ADR-0005(直接切换,不并行、不迁移)

This commit is contained in:
zh 2026-09-23 11:03:42 +08:00
parent 85fab9daf5
commit 6fb5310ece
2 changed files with 46 additions and 1 deletions

View File

@ -0,0 +1,45 @@
# ADR-0005:直接切换,不并行、不迁移
- **状态**:已接受
- **日期**:2026-09-23
- **决策人**:技术负责人
- **相关**:任务表 A0.9、A0.2(决策 D7);设计文档《架构设计》导语
## 背景
重构要把「APS 产品 + 内嵌智能体层」拆成两件事:平台从零重写,APS 搬迁适配。新代码在孤儿分支 `rewrite/platform` 上,与 `main` 的历史没有共同祖先。
两项前提决定了切换该有多重:**项目仍在开发阶段,没有客户试用数据**,因此不存在数据迁移与接口兼容问题;**旧代码仍需可查**,因为 APS 侧搬迁适配要反复对照旧实现。
## 选项
| 选项 | 做法 | 代价 | 不选的理由 |
| --- | --- | --- | --- |
| A 并行运行 | 新旧系统同时对外,逐步切流量 | 两套部署、两套运维、数据同步 | 没有生产流量,并行没有意义 |
| B 冻结期 + 待重写清单 | 冻结 main,跟踪期间新增功能并重写进新分支,再切 | 需要一套跟踪机制,周期拉长 | 旧系统不再演进,清单必然为空,机制纯属负担 |
| C 直接切换 | 旧代码冻结只作参考,新分支准备好后一次切换 | 切换瞬间不可逆(靠备份兜) | 选定 |
## 结论
选 C:**直接切换,不并行、不保留旧库、不设兼容层。**
具体动作:
1. 确认新分支通过 A 线与 B 线的验收(B 线至少要走到 `B5` 契约化接口层)
2. 备份旧代码:`git branch legacy/main main` 并推到远端,设为受保护只读
3. 切换:`git push --force-with-lease origin rewrite/platform:main`
4. 打标签 `platform-1.0.0`
5. 旧分支归档:`legacy/main` 只读,不再接收提交
6. 回退(仅切换后发现问题时):把 `main` 指回 `legacy/main`
## 影响
- **对代码**:`main` 的内容来自孤儿分支;旧实现只在 `legacy/main` 可达
- **对任务**:B2 不写迁移脚本,只做结构拆分;A0.2 的备份与强推规则照此执行;A0.10 的设计文档随首个提交入库
- **对文档**:设计文档《架构设计》导语写明不考虑兼容与迁移
- **不这么做的后果**:选 A 要先建数据同步与双跑运维;选 B 要维护一份注定为空的移植清单,把切换周期无谓拉长
## 遗留
- 切换时点取决于 A 线与 B 线进度,关键约束是 A5 依赖 B5
- 无数据迁移工作。若将来出现真实交付数据并要求延续,需另写 ADR 取代本文件

View File

@ -42,6 +42,6 @@ ADR 写完不再修改。要改结论就**新写一份**,并在两份里互相
| [0002](./0002-engine-provider-deployment.md) | 引擎与 Provider 的部署形态 | 已接受 | 任务表 A0.3(决策 D1) | | [0002](./0002-engine-provider-deployment.md) | 引擎与 Provider 的部署形态 | 已接受 | 任务表 A0.3(决策 D1) |
| [0003](./0003-data-scope-and-authority.md) | 数据作用域与权威数据源 | 已接受 | 任务表 A0.4(决策 D2) | | [0003](./0003-data-scope-and-authority.md) | 数据作用域与权威数据源 | 已接受 | 任务表 A0.4(决策 D2) |
| [0004](./0004-desktop-and-local-capabilities.md) | 桌面端与本地能力边界 | 已接受 | 任务表 A0.5(决策 D4) | | [0004](./0004-desktop-and-local-capabilities.md) | 桌面端与本地能力边界 | 已接受 | 任务表 A0.5(决策 D4) |
| 0005 | 迁移与切换策略 | 待写 | 任务表 A0.9(决策 D7) | | [0005](./0005-cutover-strategy.md) | 直接切换,不并行、不迁移 | 已接受 | 任务表 A0.9(决策 D7) |
编号在写之前先在本表登记,避免多人并行时撞号。 编号在写之前先在本表登记,避免多人并行时撞号。