From d814c241699f6479676dec6493042660cf40876f Mon Sep 17 00:00:00 2001 From: jxxghp Date: Sun, 23 Aug 2026 14:50:19 +0800 Subject: [PATCH] docs: refresh architecture debt status --- docs/refactor/backend-architecture-next-stage.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/refactor/backend-architecture-next-stage.md b/docs/refactor/backend-architecture-next-stage.md index 48fcec7ac..c45ca161f 100644 --- a/docs/refactor/backend-architecture-next-stage.md +++ b/docs/refactor/backend-architecture-next-stage.md @@ -61,8 +61,8 @@ 1. **先做后台任务审计与统一登记**：建立 TaskOwner/生命周期协议，区分请求后非关键通知、可重试 Outbox 副作用和必须在请求内完成的业务写入；为断线、崩溃、重复执行和 shutdown 补测试。 2. **再做模块契约 V2 增量收口**：优先识别调用量最高、影响下载/整理/识别的能力族，补真实参数对象、结果验证、超时预算和 provider 行为快照；legacy fallback 只保留给第三方未知方法。 -3. **随后迁移查询 ABI**：从订阅、历史、消息、用户和站点等高频查询开始，逐步让 Query/Repository 接收显式 Session，并验证 detached 对象、懒加载和事务组合。 -4. **最后扩展类型和复杂度预算**：每次触碰大型职责域时拆一个可回滚垂直切片，同时扩大 mypy strict 清单和 Pylint 新增问题 ratchet；不要为追求行数指标进行无行为收益的拆分。 +3. **随后收敛组合根和全局状态**：为新代码禁止新增 Service Locator/Singleton 依赖，逐步让关键服务只通过 typed HostRuntime 获取；旧 Facade 继续保留命中观测和插件 ABI。 +4. **最后扩展类型和复杂度预算**：每次触碰大型职责域时拆一个可回滚垂直切片，同时扩大 mypy strict 清单和 Pylint 新增问题 ratchet；不要为追求行数指标进行无行为收益的拆分。查询 ABI 已完成正式装饰器清零，后续只做零回退和 ORM 跨层收口。 5. **跨仓发布以契约为中心**：保持插件索引、前端远程组件、资源版本、Rust wheel 和主仓依赖的 provenance；将插件测试环境固定为主仓 `uv.lock` 可复现安装，避免本地和 CI 依赖漂移。 本轮复核结论：**当前架构不需要推倒重来，真正未完成的是运行时可靠性和协议收口。** 下一轮治理完成上述 P1 后，再评估是否值得继续拆分大型文件或扩大严格类型范围。 @@ -81,7 +81,7 @@ MoviePilot V3 当前不是“目录混乱、必须推倒重来”的状态。第 1. **架构基线工具把语义、源码位置和跨仓版本混在一起。**普通行号变化或独立插件仓更新都会触发全量基线漂移，AI 容易用 `--write` 掩盖真正变化。 2. **部署拓扑与实际进程职责不一致。**`API_WORKERS` 可配置多进程，但每个 Uvicorn worker 都会独立运行插件、调度器、监控器和工作流；当前 `app.main` 又把 app 实例传给 Uvicorn，与 reload/workers 的官方约束不一致。 -3. **事务所有权只在少数新用例中收口。**ORM Model 仍大量自带查询和自动提交装饰器，Oper 多为薄转发；调用方无法一眼判断一次业务动作何时提交、回滚和触发提交后副作用。 +3. **事务所有权已完成装饰器层收口，但 ORM 对象跨层流转仍需治理。**正式 Model 查询/写装饰器均已清零，宿主 Oper 查询统一接收显式 Session；调用方仍需继续明确 ORM 对象生命周期、懒加载和业务提交后副作用边界。 4. **组合根之后仍存在大量全局服务定位。**宿主有 180 个文件直接读取 `settings`，21 个文件出现 45 次 `SystemConfigOper()` 构造；API 数据端口仍是全局字符串注册表。 5. **模块与事件契约主要是“快照化的动态协议”。**211 个模块方法名中有 96 个落在 legacy 默认契约；53 个事件只有 20 个专用 `EventData` model，payload、可见范围和可靠性等级没有统一登记。 6. **后台副作用缺少统一可靠性定义。**事件队列、APScheduler、FastAPI BackgroundTasks 和线程池任务的丢失、重试、幂等、关停语义各不相同；数据库提交与事件/上报之间仍有进程崩溃窗口。 @@ -131,7 +131,7 @@ MoviePilot V3 当前不是“目录混乱、必须推倒重来”的状态。第 | 专用 EventData model | 53 | Event Contract Registry 已为全部事件登记 typed payload/fallback 原因 | | 直接读取 `settings` 的文件 | 105 | 仍按模块族迁移，动态协议和安全端口暂保留 | | `SystemConfigOper()` | 1 个 | 仅组合根创建 `SystemConfigService` 时保留 | -| Model 上的 DB 查询装饰器 | 117 | `db_update`/`async_db_update` 为 0；查询 ABI 继续按 canonical 用例迁移 | +| Model 上的正式 DB 查询装饰器 | 0 | 查询/写装饰器均保持为 0；旧插件只读 ABI 由 `legacy_*` 外壳承接 | | 路由端点 | 335 | 11 个已装饰端点超过 80 行，最大 400 行 | | Chain 方法超过 150 行 | 18 | 最大 `TransferChain.do_transfer()` 885 行 | | Application 方法超过 150 行 | 8 | 最大 296 行 |