From 6fb5310ecea2ebf78a007b47bc5e5e09e639ad4b Mon Sep 17 00:00:00 2001 From: zh Date: Wed, 23 Sep 2026 11:03:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(adr):=20=E8=A1=A5=E9=BD=90=20ADR-0005?= =?UTF-8?q?=EF=BC=88=E7=9B=B4=E6=8E=A5=E5=88=87=E6=8D=A2=EF=BC=8C=E4=B8=8D?= =?UTF-8?q?=E5=B9=B6=E8=A1=8C=E3=80=81=E4=B8=8D=E8=BF=81=E7=A7=BB=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/0005-cutover-strategy.md | 45 +++++++++++++++++++++++++++++++ docs/adr/README.md | 2 +- 2 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0005-cutover-strategy.md diff --git a/docs/adr/0005-cutover-strategy.md b/docs/adr/0005-cutover-strategy.md new file mode 100644 index 0000000..4db7029 --- /dev/null +++ b/docs/adr/0005-cutover-strategy.md @@ -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 取代本文件 diff --git a/docs/adr/README.md b/docs/adr/README.md index b452f2c..bf0fb3c 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -42,6 +42,6 @@ ADR 写完不再修改。要改结论就**新写一份**，并在两份里互相 | [0002](./0002-engine-provider-deployment.md) | 引擎与 Provider 的部署形态 | 已接受 | 任务表 A0.3（决策 D1） | | [0003](./0003-data-scope-and-authority.md) | 数据作用域与权威数据源 | 已接受 | 任务表 A0.4（决策 D2） | | [0004](./0004-desktop-and-local-capabilities.md) | 桌面端与本地能力边界 | 已接受 | 任务表 A0.5（决策 D4） | -| 0005 | 迁移与切换策略 | 待写 | 任务表 A0.9（决策 D7） | +| [0005](./0005-cutover-strategy.md) | 直接切换，不并行、不迁移 | 已接受 | 任务表 A0.9（决策 D7） | 编号在写之前先在本表登记，避免多人并行时撞号。