Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
160 lines
4.5 KiB
Python
160 lines
4.5 KiB
Python
"""配置诊断 DTO。
|
||
|
||
定义渠道配置诊断与修复的不可变值对象，包括诊断严重级别、诊断检查项、诊断
|
||
结果、修复结果、连通性结果与权限结果。所有 DTO 均为
|
||
``dataclass(frozen=True)``，仅依赖标准库，用于配置诊断流程的结果回传与
|
||
修复策略决策。集合字段使用 tuple 以保证 frozen dataclass 的不可变语义。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from enum import StrEnum
|
||
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
|
||
|
||
class DiagnosticSeverity(StrEnum):
|
||
"""诊断严重级别。
|
||
|
||
标识诊断检查项的严重程度，用于结果聚合与修复优先级决策。继承
|
||
``str, Enum`` 以支持 JSON 序列化与字符串比较。
|
||
|
||
取值：
|
||
INFO: 提示信息。
|
||
WARNING: 警告。
|
||
ERROR: 错误。
|
||
CRITICAL: 严重错误。
|
||
"""
|
||
|
||
INFO = "info"
|
||
WARNING = "warning"
|
||
ERROR = "error"
|
||
CRITICAL = "critical"
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class DiagnosticCheck:
|
||
"""诊断检查项。
|
||
|
||
描述一项配置诊断检查的元信息，包括检查 ID、名称、严重级别、描述与是否
|
||
支持自动修复。
|
||
|
||
字段：
|
||
check_id: 检查 ID。
|
||
name: 检查名称。
|
||
severity: 严重级别。
|
||
description: 检查描述。
|
||
auto_repairable: 是否支持自动修复（默认 False）。
|
||
"""
|
||
|
||
check_id: str
|
||
name: str
|
||
severity: DiagnosticSeverity
|
||
description: str
|
||
auto_repairable: bool = False
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验 check_id 与 name 非空。
|
||
|
||
``check_id`` 与 ``name`` 必须非空，在构造时即抛出 ``ValidationError``，
|
||
避免空检查 ID 或空名称导致诊断项无法定位与展示（INV-8）。
|
||
"""
|
||
if not self.check_id:
|
||
raise ValidationError("check_id", "must not be empty")
|
||
if not self.name:
|
||
raise ValidationError("name", "must not be empty")
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class DiagnosticResult:
|
||
"""诊断结果。
|
||
|
||
描述一项诊断检查的执行结果，携带是否通过、消息与可选的修复计划。
|
||
|
||
字段：
|
||
check_id: 检查 ID。
|
||
passed: 是否通过。
|
||
severity: 严重级别。
|
||
message: 结果消息。
|
||
auto_repairable: 是否支持自动修复（默认 False）。
|
||
repair_plan: 修复计划（未失败或不可修复时为 None）。
|
||
"""
|
||
|
||
check_id: str
|
||
passed: bool
|
||
severity: DiagnosticSeverity
|
||
message: str
|
||
auto_repairable: bool = False
|
||
repair_plan: str | None = None
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验 check_id 非空。
|
||
|
||
``check_id`` 必须非空，在构造时即抛出 ``ValidationError``，避免空
|
||
检查 ID 导致诊断结果无法关联到对应检查项（INV-8）。
|
||
"""
|
||
if not self.check_id:
|
||
raise ValidationError("check_id", "must not be empty")
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class RepairResult:
|
||
"""修复结果。
|
||
|
||
描述一项自动修复操作的执行结果。
|
||
|
||
字段：
|
||
check_id: 检查 ID。
|
||
passed: 是否修复成功。
|
||
message: 修复结果消息。
|
||
"""
|
||
|
||
check_id: str
|
||
passed: bool
|
||
message: str
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验 check_id 非空。
|
||
|
||
``check_id`` 必须非空，在构造时即抛出 ``ValidationError``，避免空
|
||
检查 ID 导致修复结果无法关联到对应检查项（INV-8）。
|
||
"""
|
||
if not self.check_id:
|
||
raise ValidationError("check_id", "must not be empty")
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ConnectivityResult:
|
||
"""连通性结果。
|
||
|
||
描述渠道账户的连通性检测结果，包括是否可达、延迟与错误信息。
|
||
|
||
字段：
|
||
reachable: 是否可达。
|
||
latency_ms: 延迟（毫秒，不可达时为 None）。
|
||
error: 错误信息（可达时为 None）。
|
||
"""
|
||
|
||
reachable: bool
|
||
latency_ms: int | None = None
|
||
error: str | None = None
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class PermissionResult:
|
||
"""权限结果。
|
||
|
||
描述渠道账户权限校验的结果，包括是否授权、缺失权限列表与错误信息。
|
||
集合字段使用 tuple 以保证不可变。
|
||
|
||
字段：
|
||
granted: 是否授权。
|
||
missing_permissions: 缺失权限列表（默认空 tuple）。
|
||
error: 错误信息（无错误时为 None）。
|
||
"""
|
||
|
||
granted: bool
|
||
missing_permissions: tuple[str, ...] = ()
|
||
error: str | None = None
|