From dd3bd909cedda2acc4db3b878e460541be22b6a5 Mon Sep 17 00:00:00 2001 From: jxxghp Date: Fri, 16 Oct 2026 12:32:39 +0800 Subject: [PATCH] refactor(types): align database backup process runner contract --- app/adapters/system/backup/database.py | 17 +++++++++++++---- docs/code-quality.md | 2 +- docs/refactor/optimization-checklist.md | 4 ++-- mypy.ini | 1 + tests/fixtures/architecture/mypy-baseline.json | 3 --- 5 files changed, 17 insertions(+), 10 deletions(-) diff --git a/app/adapters/system/backup/database.py b/app/adapters/system/backup/database.py index 55201a1e3..87e77f067 100644 --- a/app/adapters/system/backup/database.py +++ b/app/adapters/system/backup/database.py @@ -9,7 +9,7 @@ import subprocess from contextlib import closing from dataclasses import dataclass from pathlib import Path -from typing import Callable, Mapping, Protocol, Sequence +from typing import Callable, Literal, Mapping, Protocol, Sequence from sqlalchemy.engine import Engine @@ -37,13 +37,14 @@ class ProcessRunner(Protocol): def __call__( self, command: Sequence[str], + /, *, env: Mapping[str, str], - capture_output: bool, - text: bool, + capture_output: Literal[True], + text: Literal[True], check: bool, ) -> ProcessResult: - """执行命令并返回结果。""" + """按位置传入命令，并以文本模式捕获标准输出和错误输出。""" def verify_database_backup( @@ -89,6 +90,7 @@ def _require_tool( executable: str, tool_resolver: Callable[[str], str | None], ) -> str: + """解析客户端工具路径，缺失时在执行数据库操作前明确报错。""" resolved = tool_resolver(executable) if resolved is None: raise RuntimeError( @@ -103,6 +105,7 @@ def _postgres_environment( password: str | None = None, sslmode: str | None = None, ) -> dict[str, str]: + """隔离继承的 PostgreSQL 凭证，仅传入本次操作所需的连接设置。""" environment = dict(os.environ) environment.pop("PGPASSWORD", None) environment.pop("PGSSLMODE", None) @@ -120,6 +123,7 @@ class SQLiteBackupBackend: suffix = ".db" def __init__(self, engine: Engine) -> None: + """绑定活动 SQLite 文件路径，拒绝无法生成文件快照的内存数据库。""" self._engine = engine database = engine.url.database if not database or database == ":memory:": @@ -169,6 +173,7 @@ class PostgreSQLBackupBackend: pg_dump: str = "pg_dump", pg_restore: str = "pg_restore", ) -> None: + """绑定活动引擎和可替换的客户端执行边界。""" self._engine = engine self._runner = runner self._tool_resolver = tool_resolver @@ -220,6 +225,7 @@ class PostgreSQLBackupBackend: raise RuntimeError(f"pg_restore 执行失败，退出码 {result.returncode}") def _connection_arguments(self) -> list[str]: + """构建不含密码的客户端连接参数，优先使用 URL 查询项中的主机和端口。""" url = self._engine.url host = str(url.query.get("host") or url.host or "") port = str(url.query.get("port") or url.port or "") @@ -236,6 +242,7 @@ class PostgreSQLBackupBackend: return arguments def _run(self, command: Sequence[str], *, include_password: bool) -> ProcessResult: + """捕获文本输出，并按操作需要向子进程环境注入凭证。""" return self._runner( command, env=self._environment(include_password=include_password), @@ -245,9 +252,11 @@ class PostgreSQLBackupBackend: ) def _require_tool(self, executable: str) -> str: + """通过当前解析器确认 PostgreSQL 客户端可用。""" return _require_tool(executable, self._tool_resolver) def _environment(self, *, include_password: bool) -> dict[str, str]: + """从活动引擎提取当前命令需要的密码与 SSL 设置。""" password = ( str(self._engine.url.password) if include_password and self._engine.url.password diff --git a/docs/code-quality.md b/docs/code-quality.md index a04a510ff..53b96ee84 100644 --- a/docs/code-quality.md +++ b/docs/code-quality.md @@ -75,7 +75,7 @@ uv run --locked --no-sync python scripts/architecture/complexity.py 回调和返回值类型；全仓错误计数为零并不保证单独纳入 strict frontier 后也为零。 2026-10-16 开始逐文件清理类型债务，`app/domain/title.py` 通过局部可空类型声明保留 -既有搜索解析行为，并纳入严格清单；当前清单共 63 个文件（62 个生产文件和 1 个脚本）。 +既有搜索解析行为，并纳入严格清单；当前清单共 64 个文件（63 个生产文件和 1 个脚本）。 每个治理提交聚焦一个生产文件及其必要测试、门禁配置、真实下降基线和指标文档。 验收同时检查完整严格清单与全宿主 Linux 分析，避免 `follow_imports = skip` 隐藏依赖 签名冲突；不通过忽略诊断或放宽类型合同接受回退。最新文件清单以 `mypy.ini` 为准， diff --git a/docs/refactor/optimization-checklist.md b/docs/refactor/optimization-checklist.md index 5d2c3e24d..18e2346ef 100644 --- a/docs/refactor/optimization-checklist.md +++ b/docs/refactor/optimization-checklist.md @@ -106,9 +106,9 @@ ARCH-201 至 ARCH-204 均达到实现、验证、提交、推送和远端门禁 | Model/Oper 事务债务 | 0 | 自建 Session、自动事务装饰器、直接 commit/rollback 等基线均为零 | | Module Contract | 215 specs / 211 methods / 263 calls | 动态方法名为 0；分类事实富化通过显式合同进入插件调度，旧 YAML 分类方法已移除；download 新增 custom_words 可选参数，旧 provider 签名通过显式合同兼容 | | Event Contract | 53 | 均已有 payload model，但当前全部是 diagnostic enforcement | -| Python 源码量 | 372,023 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 | +| Python 源码量 | 372,032 行 | 本次重新扫描物理行数，排除 `app/plugins/**`；74 个文件超过 1,000 行，12 个超过 2,000 行；源码尺寸仅作观察 | | 长方法 | 309 个超过 80 行 | 本次 AST 扫描排除 `app/plugins/**`；61 个超过 150 行，17 个超过 250 行；新增函数仍受 C901/嵌套深度门禁约束 | -| 全量 mypy 历史债务 | 9,039 / 489 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项；Transmission 进度回退值归一化再减少 2 项，逐文件逐错误码无增长 | +| 全量 mypy 历史债务 | 9,037 / 488 文件 | 通知排版补齐 Slack 消息块类型，历史债务减少 2 项；工作流资源过滤改用领域对象调用过滤链，恢复的节点输出在消费前归一化，并收紧可空资源列表的类型低水位；消息媒体交互类型债务已清零，canonical Facade 与 endpoint 类型边界已补齐，低水位只允许继续下降；微信 ClawBot 入站 item_list 媒体解析改为按子项键名分派后，类型错误减少 4 项；站点解析器分享率改用浮点初值，类型错误减少 20 项；本次下载与文件安全修复再减少 3 项；Transmission 进度回退值归一化再减少 2 项，逐文件逐错误码无增长 | | Ruff 历史诊断 | 100 | 低水位门禁通过，但规则集只覆盖 `E4/E7/E9/F/I` | | 覆盖率固定基线 | Application 80.00%，Domain 80.00% | Chain、Runtime、Agent、Adapter、Startup 未进入包级覆盖率门禁 | diff --git a/mypy.ini b/mypy.ini index 5a7ce535b..175f6d6a3 100644 --- a/mypy.ini +++ b/mypy.ini @@ -21,6 +21,7 @@ files = app/adapters/network/cloudflare.py, app/adapters/network/ip.py, app/adapters/web/correlation.py, + app/adapters/system/backup/database.py, app/agent/contracts.py, app/runtime/correlation.py, app/runtime/coalesce.py, diff --git a/tests/fixtures/architecture/mypy-baseline.json b/tests/fixtures/architecture/mypy-baseline.json index 47e310348..00cfb0f07 100644 --- a/tests/fixtures/architecture/mypy-baseline.json +++ b/tests/fixtures/architecture/mypy-baseline.json @@ -61,9 +61,6 @@ "no-untyped-def": 33, "type-arg": 26 }, - "app/adapters/system/backup/database.py": { - "assignment": 2 - }, "app/adapters/system/fsproxy.py": { "arg-type": 1, "assignment": 1,