@@ -0,0 +1,179 @@
---
title : "系统整改与重构方案 · 实施承接计划（框架+映射回填）"
status : planned
created : 2026-09-23
updated : 2026-09-23
owner : Cursor
task_id : modular-refactor-impl-plan-2026-09-23
base_dev_sha : "2ce8688db4f49fdd116799b9d36ef7ea802afc33"
---
# 系统整改与重构方案 · 实施承接计划（框架+映射回填）
## 1. 目的、输入依赖与非目标
### 1.1 目的
为产物机器上的《系统整改与重构方案》（22 条规范 → 17 工作包 → 6 阶段）提供**可在本机规范下执行的承接框架**：阶段门禁、工作包登记模板、防重复施工前置检查、回填与开工准入、集成与收口分项。产物机器把工作包明细填入本模板后即可按包开工。
### 1.2 输入依赖（本机不可见须回填）
| 输入 | 路径 / 说明 | 本机状态 |
|---|---|---|
| 重构方案正文 | `.doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md` （ `modular-contract-standard-2026-09-22` ） **不可见 ** ；
| 审核检查清单 | [../audit/2026-09-23-modular-refactor-plan-review-checklist.md ](../audit/2026-09-23-modular-refactor-plan-review-checklist.md ) | 已合入本机 `dev` ； –
| 模块开发规范 | [../system-design/2026-09-20-module-development-standards.md ](../system-design/2026-09-20-module-development-standards.md ) | 生效 |
| 验证契约 | [../ops/2026-09-21-validation-contract.md ](../ops/2026-09-21-validation-contract.md ) | 生效 |
| 操作规范 | [../ops/2026-09-21-agent-worktree-workflow.md ](../ops/2026-09-21-agent-worktree-workflow.md ) | 生效 |
| A– ./2026-09-20-module-decoupling-batch-plan.md ](./2026-09-20-module-decoupling-batch-plan.md ) | FEATURE-MATRIX 行 `done` ；本文件保持 planned 为历史批次记录 |
### 1.3 非目标
- 本文件**不实施**业务代码、不代填 17 工作包明细、不虚构方案正文内容。
- 不改 `production_ready` ；不整支 merge FAV；不升 `MULTI_INTENT_PLAN_TIER` ；不接线 `SEMANTIC_SUMMARY_REPLACE` ；不放开 PI 叙事 flag；
- 不 push、不操作 test/main（除非另获授权）。
## 2. 已落地基线盘点（本机实测）
编制日：**2026-09-23**。基线 tip： `2ce8688db4f49fdd116799b9d36ef7ea802afc33` （本任务 `base_dev_sha` ；合入后以当时 `dev` tip 为准重测）。
| 检查项 | 命令 / 依据 | 结果 |
|---|---|---|
| 架构门禁 | `./scripts/arch-check.sh --mode block` | **PASS ** （ ）
| 边界例外 | `.doc/system-design/module-boundaries.yaml` `exceptions:` | * * `[]` **（曾记 21 条已清零） |
| A– – * * `done` **（ – ； ）
| 发布缺口 | [gap-matrix.md ](./gap-matrix.md ) 现行区段 | 已列行均为 **PASS ** （新缺陷须新开 audit/gap 行，不得静默覆盖） |
| 审核清单 | audit 2026-09-23 checklist | 已入库；自查列多为「待回填」 |
**含义 ** ：方案阶段中与 A–G / 通知事务 / SSE / 鉴权相关的大量「从零整改」在本机已有落地。后续工作包默认按 **增量修复 ** 或 **回归门禁 ** 登记，禁止重复施工覆盖既有证据。
## 3. 阶段 → 门禁表
方案六阶段与本机验证契约对齐。每阶段须满足「准入」方可开工下属工作包；「完成」须证据可核验。
| 阶段 | 主题（方案口径） | 准入 | 完成判据 | 验证契约适用行 |
|---|---|---|---|---|
| 1 | 契约、模块职责、验证基线 | 审核清单 §3 P1 无「阻断」；N 映射至少覆盖本阶段涉及规范 | 契约/registry/table_owners 变更有 before/after； `arch-check` + 范围测试绿 | 纯文档 **或 ** Go/接口（改契约时） |
| 2 | 通知事务、事件领取、授权、业务入口一致性 | 清单 §4 P2 无阻断；§5 前置检查声明与已 PASS gap 关系 | 同事务通知/lease/鉴权/入口一致性有精确用例 PASS | Go/接口；涉 SSE 追加既有 stream 测试 |
| 3 | 任务受理、执行租约、Runner 取消与未知结果、SSE 恢复 | 清单 §5 CX 无阻断；取消状态契约已冻结 | CX 状态机/未知结果/SSE 恢复场景 PASS | Go/接口；产品链路按范围追加 |
| 4 | DB 写权、文件访问、后端接口、工作流依赖收敛 | 阶段 1–3 相关包 done 或显式 deferred；
| 5 | 前端状态职责拆分、架构门禁完善 | 后端契约稳定（wire DTO 不变或已同步） | `web/` `npm test` + `npm run build` ；受影响浏览器场景 | 前端 |
| 6 | 分批迁移、真实验收、上线 | 阶段 1–5 完成判据满足；红线未触碰 | 获授权环境 `/health` `/ready` + 范围真实业务；制品身份可对账 | 迁移/运行配置 **并 ** 产品 Agent（按变更并集） |
阶段之间：**编码与隔离测试可并行**（mutex 不重叠）；**dev 集成与共享环境验收串行**（`git:dev` / `env:dev` ）。
## 4. 工作包登记模板
产物机器将方案每个工作包复制为下表一行（或独立 short-term，回链本计划）。缺任一项 → 不得标 `in_progress` 编码。
### 4.1 必填字段
| 字段 | 要求 |
|---|---|
| `wp_id` | 方案工作包 ID（例 WP-01）；唯一 |
| `phase` | 1–
| `title` | ≤40 字 |
| `norm_refs` | Nxx + 审核清单行（P1-*/P2-*/CX-*）
| `relation_to_baseline` | **必须**三选一：`incremental` （增量修复）/ `regression_gate` （仅加固测试与门禁）/ `net_new` （本机确认无对等落地；须写明检索范围） |
| `code_anchors` | 文件路径 + 符号（函数/类型）；禁止只写包名 |
| `deps` | 依赖的 `wp_id` / 已合入 tip / 外部 ADR |
| `mutex` | 模块/路径资源名；与 CURRENT 认领一致 |
| `write_scope` | 允许写路径列表 |
| `test_scenarios` | Given/When/Then + **精确 ** `-run` 用例名或 npm 测试文件；stub/SKIP 不得作交付 PASS |
| `rollback` | 可操作回退：单批 `revert` 边界；数据/迁移是否兼容；例外条目是否需成对恢复 |
| `evidence` | `.doc/test-reports/…` 或 short-term 验证节路径 |
| `owner` / `branch` / `worktree` / `base_dev_sha` | 开工时填写；必须从当时 `dev` tip 创建 |
### 4.2 登记表示例（空行供回填）
| wp_id | phase | title | relation_to_baseline | code_anchors | mutex | test_scenarios | rollback | 判定 |
|---|---|---|---|---|---|---|---|---|
| * WP-?? * | * ? * | * 待回填 * | * 待声明 * | * 待回填 * | * 待回填 * | * 待回填 * | * 待回填 * | 待回填 |
### 4.3 推荐代码锚点（本机已知落点，供对照，非代填）
| 主题 | 本机锚点（符号级） |
|---|---|
| 事件契约 | `internal/events/registry.go` `StaticContracts` |
| 事件领取 | `internal/events/dispatcher.go` `ClaimLeases` ； `worker.go` |
| 可见通知同事务 | `internal/notification/document_events.go` `EmitVisibleDocumentEvent` ； `service.go` `EmitVisibleStageReady` |
| 授权 | `internal/authz/authorizer.go` `RequireProjectAccess*` |
| 任务取消 | `internal/taskrun/finalize.go` `Commands.Cancel` ； `manager.go` `Manager.Cancel` |
| SSE / 续订 | `internal/server/sse.go` `extendSSEWriteDeadline` ； `task_run_handlers.go` `after_seq` |
| 边界门禁 | `.doc/system-design/module-boundaries.yaml` ； `./scripts/arch-check.sh` |
## 5. 防重复施工前置检查
每个工作包开工前，owner 在 short-term 勾选并留证据链接：
1. [ ] 检索 [gap-matrix ](./gap-matrix.md )：若已有 PASS 行覆盖同一缺陷，默认 `regression_gate` ；声称重开须新 audit 证据。
2. [ ] 检索 FEATURE-MATRIX：相关模块行状态与「剩余条件」；不得把已 `done` 伞行改回 `planned` 以「再做一遍」。
3. [ ] 确认 `module-boundaries.yaml` `exceptions` 仍为 `[]` （或仅含本包显式新增且带到期日的例外）；禁止无到期例外。
4. [ ] 对照审核清单：关联 P1/P2/CX 行不是「阻断」。
5. [ ] 声明 `relation_to_baseline` ； `net_new` 须列出已检索路径（至少含 §4.3 相关锚点与 A–G short-term）。
6. [ ] mutex / write_scope 与 CURRENT / agentctl 登记一致；热点（lockfile、迁移号、顶层路由）单独认领。
7. [ ] 红线未触碰（§1.3）；若工作包接近红线能力，单独授权记录。
任一项未勾 → 状态保持 `planned` 或 `blocked` ，不得编码。
## 6. 产物机器回填与开工准入
### 6.1 回填顺序
1. 同步本机已合入的本计划 + [审核清单 ](../audit/2026-09-23-modular-refactor-plan-review-checklist.md )。
2. 完成清单 §2 N01–N22 映射与 §3–§5 自查（优先 CX → P1 → P2）。
3. 将方案 17 工作包填入 §4.2 表（或每包一个 short-term，回链 `wp_id` ）。
4. 每包做完 §5 前置检查。
### 6.2 开工准入（硬条件）
同时满足才可 `agentctl task register` 并编码：
- 审核清单相关行无「阻断」；
- 该包 §4 必填字段齐全；
- §5 前置检查全部勾选；
- 从**产物机器（或本机）当时 `dev` 完整 SHA** 创建 feature/fix worktree，不从他人 feature 派生。
### 6.3 本机 vs 产物机器协调
- CURRENT / `.locks` **不是跨机分布式锁 ** ；两机并行须靠人工 mutex 约定或只在一机实施。
- 文档合入本机 `dev` 后，产物机器需 push/同步才能看见；未授权 push 时用手动拷贝，并在任务文记录同步方式。
## 7. 集成、部署与收口
### 7.1 集成
遵循操作规范：冻结 head → 候选 worktree `merge --no-ff` （第一父 = expected_dev）→ `agentctl validate` → `agentctl integrate --expected-dev <SHA>` （ `git:dev` 租约内 `--ff-only` ）。主目录禁止直接开发提交。
共享文档（CURRENT / FEATURE-MATRIX）变更走 `docs apply` ；任务仅改自己的 CURRENT 行。
### 7.2 部署判定
| 变更 | deployment |
|---|---|
| 仅 `.doc` 普通文档 / 本承接计划 | `not_required` |
| Go/API/事件/迁移/模板提示词 | 获授权环境 rebuild + `/health` `/ready` + 范围业务；`restart` 不足证明 |
| 前端交互 | `npm test` /`build` + 受影响真实浏览器 |
### 7.3 收口分项（每个工作包与本框架任务均须报告）
| 字段 | 含义 |
|---|---|
| `review_state` | 审查结论 |
| `integration_state` | 是否已合入目标 `dev` |
| `deployment` | 见上 |
| `cleanup` | worktree/分支清理；拒绝时 `pending` + owner/触发条件，不 `--force` |
| `remote_sync` | 默认 `not_requested` |
### 7.4 与本框架任务的关系
- 本文件 status=`planned` ：追踪「17 包回填后的实施队列」，**不是**业务已开工。
- 编制本框架的 short-term： ../ops/short-term/2026-09-23-modular-refactor-impl-plan.md ](../ops/short-term/2026-09-23-modular-refactor-impl-plan.md )（文档任务，合入后 done）。
## 8. 相关链接
- 审核清单：[../audit/2026-09-23-modular-refactor-plan-review-checklist.md ](../audit/2026-09-23-modular-refactor-plan-review-checklist.md )
- 模块开发规范 · 验证契约 · 操作规范（见 §1.2）
- A– ： ./2026-09-20-module-decoupling-batch-plan.md ](./2026-09-20-module-decoupling-batch-plan.md )
- gap-matrix： ./gap-matrix.md ](./gap-matrix.md )
- 目标方案（产物机器）：`.doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md`
WeiCHEN