diff --git a/docs/architecture/optimization-checklist.md b/docs/architecture/optimization-checklist.md index 946975513..574373da0 100644 --- a/docs/architecture/optimization-checklist.md +++ b/docs/architecture/optimization-checklist.md @@ -7,6 +7,20 @@ > > 文档性质:原始差距、治理结果和剩余交付边界的持续校准账本 +## 0.1 当前残余收口目标(G-ARCH-RESIDUAL) + +2026-08-30 已针对本账本识别的残余问题建立独立追踪目标。历史 S4 仍为 +`CANCELLED`,本目标不将全量 mypy、Ruff、覆盖率或并发质量债务重新扩大为本轮完成依赖; +只处理下表所列、已由审计确认且会影响真实运行语义或治理可信度的缺口。 + +| ID | 状态 | 问题 | 收口要求 | +|---|---|---|---| +| RES-001 | `ACTIVE`(R0) | System API 仍混有日志、Wiki、配置、事件和更新编排 | Application service/Port 拥有业务与 I/O 决策,endpoint 只做传输适配;canonical 旧实现删除 | +| RES-002 | `PLANNED`(R2) | 复杂度门禁漏扫私有方法、类/文件和 Scheduler;原生并发清单不完整 | 事实扫描覆盖全部宿主调用点(排除 `app/plugins/**`),每项有 owner/精确豁免且零增长 | +| RES-003 | `PLANNED`(R3) | Outbox after_commit 失败只有内存 pending 标记,重启不可恢复 | 持久 intent、唯一 handler、claim/fencing、重启回放、幂等和失败观测完整闭环 | +| RES-004 | `PLANNED`(R4) | Startup initializer 与插件市场存在多套 Transport/Adapter/Manager 构造 | 所有构造回收到 composition root,插件兼容只经 SDK/Compat,canonical 不保留重复正式入口 | +| RES-005 | `PLANNED`(R5) | 审计声明、机器门禁、CI 与远端交付状态需要重新校准 | 文档与事实源一致;专项、锁定全量、Pylint、架构/兼容门禁和 GitHub CI 闭环,远端 `0/0` | + ## 1. 结论摘要 MoviePilot V3 已经形成较清晰的模块化单体:`foundation`、`domain`、`runtime`、 diff --git a/docs/architecture/refactor-roadmap.md b/docs/architecture/refactor-roadmap.md index 0b57b2892..017c21eae 100644 --- a/docs/architecture/refactor-roadmap.md +++ b/docs/architecture/refactor-roadmap.md @@ -9,6 +9,24 @@ > > 兼容原则:新插件只使用 `app.sdk`;旧插件导入、符号和行为只由统一 Compat/Legacy 层承接。 +## 0.1 当前追踪目标:G-ARCH-RESIDUAL(ACTIVE) + +原 G-ARCH 的 S0-S3、S5 交付记录和 S4 `CANCELLED` 决定保持不变。基于 2026-08-30 +对 exact-head 的复核,另行建立本次追踪目标 `G-ARCH-RESIDUAL`,只收口审计已经明确的残余 +语义和治理缺口,不把 S4 的全量质量债务重新作为隐性依赖。 + +| Leaf | 状态 | 依赖 | 退出条件 | +|---|---|---|---| +| R0 事实基线刷新 | `ACTIVE` | 无 | exact-head、远端、工作树、CI 和五类残余问题证据冻结;不修改 `app/plugins/**` | +| R1 System API 边界收口 | `PLANNED` | R0 | `system.py` 仅保留 HTTP/SSE/ZIP/响应映射;日志、Wiki、配置、事件、更新编排由 Application service/Port 拥有并由 startup 注入;旧 canonical 实现和重复导出删除 | +| R2 复杂度与原生并发门禁 | `PLANNED` | R0 | 扫描私有方法、类/文件热点及 `app/scheduler`;枚举全部 Thread/Timer/Executor/asyncio 原语;每条事实有 owner 或精确豁免,门禁不可绕过且本范围新增债务为零 | +| R3 Outbox after_commit 恢复语义 | `PLANNED` | R0 | after_commit 失败写入持久 intent;有唯一恢复 handler、claim/fencing、重启回放、幂等和失败可观测性;不得以内存 `pending_effects` 代替恢复 | +| R4 Startup/插件市场单一装配 | `PLANNED` | R0 | Transport、Adapter、Package、Dependency、Domain service 由 composition root 单一构造;initializer 和 market facade 不得隐式 new 第二套实例;SDK/Compat ABI 保持不变 | +| R5 验收与交付收口 | `PLANNED` | R1,R2,R3,R4 | 路线图、优化清单、规则和机器门禁一致;专项与锁定全量测试、Pylint、架构/兼容门禁、GitHub CI 通过;`HEAD == origin/v3` 且 ahead/behind 为 `0/0` | + +执行合同:任一时刻只允许一个 `ACTIVE` 叶子;每个叶子必须独立验证、显式提交和推送, +并在交付前复核插件 ABI、canonical 旧实现/重复导出和 `app/plugins/**` 排除边界。 + ## 1. 治理合同 ### 1.1 Goal 层级