# ADR-0001：采用原地重写 + 孤儿分支，历史从零开始

- **状态**：已接受
- **日期**：2026-09-22
- **决策人**：技术负责人
- **相关**：任务表 A0.1、A0.2；设计文档《架构设计》第 2 节

## 背景

现有仓库是「APS 产品 + 内嵌智能体层」的混合实现：网关一个文件 5232 行、数据库 18 张表混装平台与 APS 数据、APS 领域有 14 个文件反向依赖智能体层。重构的目标是把平台与 APS 拆开，平台从零重写。

同时有两项硬约束：APS 的求解依赖 Python 生态（OR-Tools CP-SAT 在 TS 侧没有等价实现），所以 APS 只能搬迁适配、不能重写；旧系统仍在生产使用，切换必须可回退。

## 选项

| 选项 | 做法 | 代价 | 不选的理由 |
| --- | --- | --- | --- |
| A 新仓库重写 | 另建仓库写新平台 | 历史干净、体积归零 | issue、CI、权限、制品发布都要重搭，两仓库协同复杂 |
| B 原地重写，继承历史 | 从 main 切分支继续写 | 切换简单 | git log 与 blame 混着旧历史，"从零"名不副实 |
| C 原地重写，孤儿分支 | 同一仓库，新分支无父提交 | 切换需强推，回退依赖备份分支 | 选定 |

## 结论

选 C。同一仓库建孤儿分支 `rewrite/platform`：工作区从 `main` 的内容出发，但提交历史从首个提交 `b878fd6` 开始，不继承旧历史。切换时以本分支强推覆盖 `main`（`--force-with-lease`），切换前把 `main` 备份为 `legacy/main` 并设为只读。

理由是两条同时满足：既保留原仓库的 issue、CI、权限与制品通道，又让新分支的历史真正从零开始。

## 影响

- **对代码**：新分支只保留工程配置（`.gitignore`、`.dockerignore`、`.env.example`），目录按 `client/`、`server/`、`providers/`、`contracts/` 重建
- **对任务**：A1.1 脚手架与 A1.6 CI 基线都依赖 A0.2 的分支与 CI 分流规则；A0.10 的设计文档随本分支首个提交入库
- **对文档**：设计文档第 2 节的项目结构以此为准
- **不这么做的后果**：选 A 会把管理成本前移且长期并行两套仓库；选 B 会让新代码的每一行 blame 都落在不该负责的旧提交上

## 遗留

- `legacy/main` 备份分支的创建与只读设置：切换前执行，见 A0.2
- 孤儿历史**不会**减小仓库体积（旧对象仍在对象库）；要体积归零只能另立仓库，本次不做
- 移植旧逻辑时在提交信息里写明 `移植自 main:<path>`，否则 `git blame` 追不到来源