Files

T

weichenandCursor 22cac8dcbe docs(remediation): plan module decoupling batches A through G

Keep each hotspot on its own branch and mutex so a later code fix cannot spread across modules.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-20 13:22:59 +00:00

8.1 KiB

Raw Blame History

title, status, created, updated

title	status	created	updated
模块解耦分批整改（A–G）	planned	2026-09-20	2026-09-20

模块解耦分批整改（A–G）

背景

耦合审计确认：模块化单体、窄端口和 PG 事件总线已经在运行。本计划只清除仍会让故障跨模块扩散的残留，不推翻 ADR，不引入 RPC，不合入 FAV，不改 production_ready。

通信规则以模块开发规范为准。每一批开工前另建 short-term，并在 CURRENT 认领；本文件把批次保持 planned。

目标

每一批合并后，该批声明的依赖边消失，且 ./scripts/arch-check.sh --mode block、go vet ./...、go test -short ./... 通过。不要求七批同一周做完。

分波次计划

波次	内容	验收
A	server 只依赖用例端口，不再持有领域具体服务与 pool 写路径	见批次 A
B	拆掉 chat → app 子包的反向 import	见批次 B
C	docgov 状态/角色/错误不再被当跨包协议	见批次 C
D	workflow 定义、目录、实例、运行时的依赖改成单向	见批次 D
E	先拆 `coordinator/engine.go`，再按审计清单处理其余超 1000 行文件	见批次 E；依赖 B
F	前端 api 共用一个 fetch 封装	见批次 F
G	清零 YAML 里 21 条例外，U3/U4 优先	见批次 G

A、B、C、D、F 互不阻塞，可并行，但 mutex 不得重叠，合入 dev 必须串行占集成槽位。E 等 B 合并后再动 coordinator。G 按例外自己的里程碑走，其中到期日为 2026-09-28 的条目优先于其余 path 例外。

批次 A — server 装配收口

问题: Server 持有 *bizdev.Service、*docgov.GovernanceEngine、*pgxpool.Pool 等具体类型（internal/server/server.go）。
做法: handler 改为调用已有 internal/app 用例。领域错误到 HTTP code 的映射收进一个适配函数。新增路由不得再给 Server 加具体服务字段，也不得在 handler 里写非本适配层的 SQL。
分支 / mutex: refactor/server-port-assembly / server-assembly（与进行中的 web、authz 冲突时等待）。
验收: 生产 internal/server 不再出现 *pgxpool.Pool 字段；handlers.go 不再直接引用 docgov.Err*（映射函数除外，且该函数不 import 领域 SQL）。既有 HTTP 特征测试保持状态码。
回滚: 单批 revert。不改表。

批次 B — chat / app / coordinator 解环

问题: internal/chat/session.go 与 action_executor.go import app/chatflow、app/intentflow、app/stageflow；chatflow/ports.go 又嵌入 coordinator 类型。
做法: 动作执行所需能力改成 chat 或 chatflow 拥有的窄端口，具体 docgov / taskrun / coordinator 指针留在组合根。AssembleRequest 不再使用 coordinator.UserInfo 这类对方具体结构。
分支 / mutex: refactor/chatflow-dependency-inversion / chat + coordinator。开工前确认这两把 mutex 没有别的 in_progress。
验收: go list -f '{{.ImportPath}} {{.Imports}}' 下 internal/chat 生产文件不再 import internal/app/...。一轮对话的现有短测试仍通过。
回滚: 单批 revert。不改事件名。

批次 C — docgov 词汇收敛

问题: StateDrafting、RoleAuthor、ErrDocumentBusy 以及字符串 "docgov.review_approve" 出现在 coordinator、bizdev、server、chat。
做法: 跨包需要的无行为枚举进稳定词汇或调用方自己的端口错误。领域包保留不变量实现。server 只映射 typed error。禁止把 canonical 哈希或路径函数放进词汇包。
分支 / mutex: refactor/docgov-vocabulary-boundary / docgov。
验收: 审计热点 3 列出的生产引用点改为端口或词汇；docgov 测试仍覆盖原状态机。不改变 HTTP 错误 code。
回滚: 单批 revert。

批次 D — 工作流定义与实例单向化

问题: workflowdef/catalog.go import projectworkflow，validator_v2.go import workflow，projectinstance import workflowdef，workflow/runtime/orchestrator.go import projectinstance。
做法: 共享的无行为定义类型留在 workflowdef 或词汇；catalog 与 runtime 通过端口读定义，不反向 import 实例包。先画允许的依赖方向再改 import，避免为解环再套一层子包。
分支 / mutex: refactor/workflow-definition-direction / workflow-def。若 rdev 模板任务占用同一 mutex，本批等待。
验收: 依赖方向写成 YAML allowlist 的收紧（只删边，不放开新边）。工作流校验与门禁短测试通过。
回滚: 单批 revert。不改已发布工作流 JSON 的键。

批次 E — 巨型文件拆分

依赖: 批次 B 已合并。否则拆 engine.go 会把逻辑环复制到新文件。
顺序: internal/coordinator/engine.go（1844 行）→ internal/bizdev/service.go → internal/server/handlers.go。其余超过 1000 行的文件各一批，不在同一次提交里“全部拆完”。
做法: 按用例搬文件，不改行为。新文件 ≤ 800 行。不借拆分改 SQL 或事件。
分支 / mutex: refactor/split-coordinator-engine 起，mutex 与被拆包一致。
验收: 搬迁前后该包 go test -short 同绿；无新的跨模块 import。
回滚: 按文件批次 revert。

批次 F — 前端统一 API client

问题: web/src/api/ 各文件自行 fetch，错误处理与鉴权头重复。
做法: 一个小封装负责 base URL、鉴权头、typed error envelope 解析和有限重试。各域文件改为调用它，不改路径与请求体。预览器里的 fetch 若只取静态资源，可以后迁，但要在本批 short-term 里点名留下的文件。
分支 / mutex: refactor/web-api-client / web。
验收: web 下 npm test 与 npm run build 通过。抽一条 chat 与一条 docgov 请求，失败时仍走到现有错误卡，而不是未捕获 rejection。
回滚: 单批 revert。无后端变更。

批次 G — 例外清零

不在本计划里改 module-boundaries.yaml。开工时按到期日处理，禁止只改 expires 而不迁代码。

组	到期	内容	mutex
G1	2026-09-28	4 条 U3 `sql_write`（`docduty`/`docrevision` 写 `document_records` 与 `freeform_documents`）+ 2 条 U4 `path`（server / docrevision 的 `output.md`）	`docgov`
G2	2026-10-12	14 条 U5 `path`（agent、bizdev、coordinator、docgov、storage）	按文件所属包，一次一个包
G3	2026-10-26	`projectinstance` 写 `task_runs`	`taskrun` + `projectinstance`

G1 若在到期日前无法合并，必须另写 audit：要么延长并给出新的移除里程碑，要么让 arch-check 在到期后失败并停写。两种选择都要留在 ops，不能沉默。

验收: 对应 exception 从 YAML 删除，baseline_counts 下降，arch-check --mode block 通过，行为测试覆盖原来那条写入或读路径。
回滚: 恢复 exception 条目的提交必须与代码回滚成对，避免门禁与代码错位。

验收标准

每一批有独立 short-term、CURRENT 认领、测试记录；本文件不代替那些记录。
未开始的批次在 FEATURE-MATRIX 保持 planned。
任一批不得把 FAV live、production_ready 或 RPC 拆分写进自己的完成定义。
合入 dev 时集成槽位为该批 holder，冒烟包含 arch-check、go vet、go test -short。

8.1 KiB Raw Blame History Unescape Escape