Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
83 lines
2.8 KiB
Python
83 lines
2.8 KiB
Python
"""能力声明与证明协议。
|
||
|
||
定义能力声明、能力证明值对象与能力证明 Protocol。能力校验分为两层：
|
||
静态声明（``CapabilityDeclaration``）与运行时证明（``CapabilityProof``）。
|
||
出站中间件判断是否调用富消息渲染时，必须同时检查静态声明与运行时证明，
|
||
两者均为真才调用（FR-08 增强）。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from datetime import datetime
|
||
from typing import Protocol, runtime_checkable
|
||
|
||
from yuxi.channels.contract.dtos.capability import ChannelCapabilities
|
||
from yuxi.channels.contract.errors import NotImplementedError
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class CapabilityDeclaration:
|
||
"""能力声明。
|
||
|
||
描述插件的静态能力声明，封装 ``ChannelCapabilities``，用于清单注册
|
||
与能力校验的声明层。
|
||
|
||
字段：
|
||
capabilities: 渠道能力集合（静态声明）。
|
||
"""
|
||
|
||
capabilities: ChannelCapabilities
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class CapabilityProof:
|
||
"""能力证明。
|
||
|
||
描述单项能力的运行时证明结果，包括能力名称、是否证明通过、证明时间戳
|
||
与缓存 TTL，用于能力校验的证明层。
|
||
|
||
字段：
|
||
capability_name: 能力名称。
|
||
proven: 是否证明通过。
|
||
proof_timestamp: 证明时间戳。
|
||
cache_ttl: 缓存 TTL（秒，默认 300s）。
|
||
"""
|
||
|
||
capability_name: str
|
||
proven: bool
|
||
proof_timestamp: datetime
|
||
cache_ttl: int = 300
|
||
|
||
|
||
@runtime_checkable
|
||
class CapabilityProver(Protocol):
|
||
"""能力证明 Protocol。
|
||
|
||
由插件实现，对单项能力进行运行时证明。证明为异步方法，以支持需要远程
|
||
调用的能力验证场景。
|
||
|
||
缓存约束（FR-08 增强）：
|
||
- 能力证明结果 **可以** 缓存，默认 TTL 300s（见 ``CapabilityProof.cache_ttl``）。
|
||
- 缓存失效时重新证明。
|
||
|
||
降级约束（FR-08 增强 / FR-21）：
|
||
- 静态声明支持但运行时证明不支持时，**必须** 记录告警日志并走降级路径。
|
||
- 契约测试 **必须** 强制清单声明的能力与运行时投递能力一致，不一致时
|
||
阻止合入主干。
|
||
"""
|
||
|
||
async def proveCapability(self, capability_name: str) -> CapabilityProof:
|
||
"""证明单项能力。
|
||
|
||
参数：
|
||
capability_name: 能力名称。
|
||
|
||
返回：
|
||
能力证明结果，包含是否通过、时间戳与缓存 TTL。
|
||
|
||
@consistency: 最终一致（eventual），证明结果可缓存（默认 TTL 300s），缓存失效后重新证明。
|
||
@idempotent: True — 相同能力名称的证明应产生等价结果，重复证明无累积副作用。
|
||
"""
|
||
raise NotImplementedError(operation="proveCapability")
|