feat(database): add managed backup and offline restore (#6359)

app/application/database.py

@@ -1,19 +1,25 @@
-"""数据库连通性应用服务。"""
+"""数据库健康、清理、备份与离线还原的统一应用门面。"""
 
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import Optional
+from typing import Any, Optional
+
+from app.application.backup import (
+    BackupArtifact,
+    BackupVerification,
+    DatabaseBackupService,
+)
+from app.application.maintenance import DataCleanupService
 
 
 DatabaseProbe = Callable[[], Optional[str]]
 
 
 class DatabaseHealthService:
-    """为模块和诊断入口提供不暴露会话实现的数据库探测能力。"""
+    """提供不暴露会话实现的数据库探测能力。"""
 
     def __init__(self, probe: DatabaseProbe) -> None:
-        """保存由组合根提供的数据库探测端口。"""
         self._probe = probe
 
     def test(self) -> Optional[str]:
@@ -21,17 +27,64 @@ class DatabaseHealthService:
         return self._probe()
 
 
-_configured_database_health: DatabaseHealthService | None = None
+class DatabaseGovernance:
+    """向宿主入口提供唯一的数据库治理能力入口。"""
+
+    def __init__(
+        self,
+        *,
+        health: DatabaseHealthService,
+        cleanup: DataCleanupService,
+        backup: DatabaseBackupService,
+    ) -> None:
+        self._health = health
+        self._cleanup = cleanup
+        self._backup = backup
+
+    def test(self) -> Optional[str]:
+        """探测当前活动数据库。"""
+        return self._health.test()
+
+    def cleanup(
+        self,
+        *,
+        batch_size: int | None = None,
+        progress_callback: Callable[..., None] | None = None,
+    ) -> dict[str, Any]:
+        """按当前配置执行数据表清理。"""
+        return self._cleanup.execute(
+            batch_size=batch_size,
+            progress_callback=progress_callback,
+        )
+
+    def create_backup(self) -> BackupArtifact:
+        """创建一个当前活动数据库的一致备份。"""
+        return self._backup.create()
+
+    def list_backups(self) -> tuple[BackupArtifact, ...]:
+        """列出受管数据库备份文件。"""
+        return self._backup.list()
+
+    def verify_backup(self, name: str) -> BackupVerification:
+        """校验一个受管数据库备份文件。"""
+        return self._backup.verify(name)
+
+    def restore_backup(self, name: str) -> BackupArtifact:
+        """在离线 CLI 进程中还原一个受管数据库备份。"""
+        return self._backup.restore(name)
 
 
-def configure_database_health(service: DatabaseHealthService) -> None:
-    """由启动组合根登记数据库探测服务。"""
-    global _configured_database_health
-    _configured_database_health = service
+_DATABASE_GOVERNANCE: list[DatabaseGovernance] = []
 
 
-def get_configured_database_health() -> DatabaseHealthService:
-    """返回启动阶段登记的数据库探测服务。"""
-    if _configured_database_health is None:
-        raise RuntimeError("数据库探测服务尚未配置")
-    return _configured_database_health
+def configure_database_governance(governance: DatabaseGovernance) -> None:
+    """由启动组合根登记宿主唯一的数据库治理门面。"""
+    _DATABASE_GOVERNANCE.clear()
+    _DATABASE_GOVERNANCE.append(governance)
+
+
+def get_database_governance() -> DatabaseGovernance:
+    """返回启动阶段登记的数据库治理门面。"""
+    if not _DATABASE_GOVERNANCE:
+        raise RuntimeError("数据库治理服务尚未配置")
+    return _DATABASE_GOVERNANCE[0]