Kris
b8ac375e8e
本次提交包含多项核心功能迭代与优化： 1. 新增KF客服会话类型，完善聊天类型枚举 2. 新增消息撤回操作类型与身份置信度排序方法 3. 新增控制面结果DTO与敏感字段注册表端口 4. 新增身份合并回滚、重试失败投递目标等业务能力 5. 优化Outbox投递逻辑与熔断器状态判断 6. 修复部分代码冗余与类型不匹配问题 7. 新增数据库索引并发创建与路由绑定清理逻辑 8. 优化会话关闭服务与插件重载并发控制
90 lines
3.4 KiB
Python
90 lines
3.4 KiB
Python
"""控制面 DTO。
|
||
|
||
定义控制面端口的命令与结果值对象，包括控制命令与控制结果。所有 DTO 均为
|
||
``dataclass(frozen=True)``，仅依赖标准库与契约层内部类型，用于向导、诊断、
|
||
白名单、目录、配对、配置、会话、插件、健康、审计等控制面操作的命令传递
|
||
与结果返回。集合字段使用 tuple 以保证 frozen dataclass 的不可变语义。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from typing import Any, Literal
|
||
|
||
from yuxi.channels.contract.dtos.channel import ChannelType
|
||
from yuxi.channels.contract.dtos.common import FailureDetail, Operator
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ControlCmd:
|
||
"""控制命令（CON-001）。
|
||
|
||
由控制面端口方法引用，描述一次控制面操作请求，携带操作类型、目标渠道、
|
||
参数与操作人。``operation`` 为带子域前缀的自由字符串（如
|
||
``dashboard/overview`` / ``config/update`` / ``session/merge``），
|
||
具体合法值由 ``operation_audit_meta`` 与各 handler 的 ``operations()``
|
||
共同约束，DTO 仅校验非空。
|
||
|
||
字段：
|
||
operation: 操作类型（带子域前缀的自由字符串，非空）。
|
||
operator: 操作人（审计用）。
|
||
target_channel: 目标渠道类型（可选）。
|
||
params: 操作参数（可选）。
|
||
"""
|
||
|
||
operation: str
|
||
operator: Operator
|
||
target_channel: ChannelType | None = None
|
||
params: dict[str, Any] | None = None
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验必填字段非空。
|
||
|
||
``operation`` 必须非空，在构造时即抛出 ``ValidationError``，
|
||
adapter 不再做该校验（INV-8）。
|
||
"""
|
||
if not self.operation:
|
||
raise ValidationError("operation", "must not be empty")
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ControlResult:
|
||
"""控制结果（CON-001）。
|
||
|
||
描述控制面操作的执行结果，携带状态、数据与错误详情，用于结果汇报与
|
||
错误聚合。集合字段使用 tuple 以保证不可变。
|
||
|
||
字段：
|
||
status: 执行状态（success | failed | partial）。
|
||
data: 返回数据（可选）。
|
||
errors: 错误详情列表（默认空 tuple）。
|
||
"""
|
||
|
||
status: Literal["success", "failed", "partial"]
|
||
data: dict[str, Any] | None = None
|
||
errors: tuple[FailureDetail, ...] = ()
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ControlPlaneResult:
|
||
"""控制面 handler 返回值（H-7）。
|
||
|
||
控制面域 handler 的操作方法返回此类型化 DTO，替代裸 ``dict[str, Any]``。
|
||
``data`` 仍为 JSON 可序列化 dict（由 ``dataclass_to_dict`` 等序列化器
|
||
生成），保证外部 API 响应不变；``status`` / ``meta`` 携带 HTTP 语义
|
||
与分页等元数据，供 ``ChannelControlService`` 与序列化层消费。
|
||
|
||
当前版本 ``status`` / ``meta`` 为预留字段，handler 暂只填充 ``data``。
|
||
未来可用于分页 cursor/total 或创建类操作的 201 状态码。
|
||
|
||
字段：
|
||
data: handler 返回的业务数据 dict（必填，无数据场景 handler 返回 ``None``）。
|
||
status: HTTP 状态码语义（默认 200，创建类操作可设 201）。
|
||
meta: 元数据（可选，如分页 cursor / total）。
|
||
"""
|
||
|
||
data: dict[str, Any]
|
||
status: int = 200
|
||
meta: dict[str, Any] | None = None
|