Kris
b88c0ae29e
新增完整的 channels 限界上下文模块，包含契约层、领域核心层、应用服务、管道编排、插件体系、基础设施组合根等全层级代码，新增飞书与微信 iLink 渠道插件基础结构，补充各类 DTO、端口协议与领域服务实现。
166 lines
4.9 KiB
Python
166 lines
4.9 KiB
Python
"""路由 DTO。
|
||
|
||
定义路由匹配相关的不可变值对象，包括匹配来源枚举、配置匹配来源枚举、
|
||
路由绑定、匹配层级、绑定上下文、配置回退链与嵌套白名单决策。所有
|
||
DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库与契约层内部类型，
|
||
用于路由匹配、绑定解析与白名单决策。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from enum import StrEnum
|
||
|
||
from yuxi.channels.contract.dtos.channel import ChannelType
|
||
|
||
|
||
class MatchSource(StrEnum):
|
||
"""匹配来源。
|
||
|
||
标识路由绑定的匹配来源，用于路由决策追溯与审计。继承
|
||
``str, Enum`` 以支持 JSON 序列化与字符串比较。
|
||
|
||
取值：
|
||
EXPLICIT: 显式绑定。
|
||
SESSION: 会话级匹配。
|
||
IDENTITY: 身份级匹配。
|
||
DEFAULT: 默认回退。
|
||
"""
|
||
|
||
EXPLICIT = "explicit"
|
||
SESSION = "session"
|
||
IDENTITY = "identity"
|
||
DEFAULT = "default"
|
||
|
||
|
||
class ConfigMatchSource(StrEnum):
|
||
"""配置匹配来源。
|
||
|
||
标识配置层路由匹配的来源类型，用于配置回退链决策追溯。继承
|
||
``str, Enum`` 以支持 JSON 序列化与字符串比较。
|
||
|
||
取值：
|
||
DIRECT: 直接匹配。
|
||
NORMALIZED_DIRECT: 归一化直接匹配。
|
||
PARENT: 父级匹配。
|
||
NORMALIZED_PARENT: 归一化父级匹配。
|
||
WILDCARD: 通配符匹配。
|
||
CHANNEL_BINDING: 渠道绑定。
|
||
"""
|
||
|
||
DIRECT = "direct"
|
||
NORMALIZED_DIRECT = "normalized_direct"
|
||
PARENT = "parent"
|
||
NORMALIZED_PARENT = "normalized_parent"
|
||
WILDCARD = "wildcard"
|
||
CHANNEL_BINDING = "channel_binding"
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class RouteBinding:
|
||
"""路由绑定。
|
||
|
||
描述路由匹配产出的绑定关系，关联渠道账户、可选渠道会话与 Agent
|
||
绑定（agent slug），并记录匹配来源用于审计。
|
||
|
||
字段：
|
||
channel_account_id: 渠道账户 ID。
|
||
channel_session_id: 渠道会话 ID（可选）。
|
||
agent_binding: Agent 绑定（agent slug，即配置匹配值）。
|
||
match_source: 匹配来源。
|
||
matched_layer: 命中的匹配层级名称（FR-04 诊断元数据，AC-05）。
|
||
config_match_source: 配置匹配来源（FR-30 诊断元数据，AC-59）。
|
||
config_match_key: 配置匹配键（FR-30 诊断元数据，AC-58，配置回退
|
||
命中时记录匹配到的键；未经过配置回退时为 None）。
|
||
"""
|
||
|
||
channel_account_id: str
|
||
agent_binding: str
|
||
match_source: MatchSource
|
||
channel_session_id: str | None = None
|
||
matched_layer: str | None = None
|
||
config_match_source: ConfigMatchSource | None = None
|
||
config_match_key: str | None = None
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class MatchTier:
|
||
"""匹配层级。
|
||
|
||
描述路由匹配层级的配置，包括名称、优先级、启用状态与匹配方法，
|
||
用于 FR-04 匹配层级注册与执行顺序控制。
|
||
|
||
字段：
|
||
name: 层级名称。
|
||
priority: 优先级（越小越先执行）。
|
||
enabled: 是否启用（默认 True）。
|
||
match_method: 匹配方法标识（exact / prefix / regex）。
|
||
"""
|
||
|
||
name: str
|
||
priority: int
|
||
match_method: str
|
||
enabled: bool = True
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class BindingContext:
|
||
"""绑定上下文。
|
||
|
||
描述路由匹配的上下文信息，包括会话键、渠道类型、账户 ID、会话
|
||
类型、对端 ID 与可选的会话 / 身份关联，用于匹配层级执行。
|
||
|
||
字段：
|
||
session_key: 会话键。
|
||
channel_type: 渠道类型。
|
||
account_id: 渠道账户 ID。
|
||
chat_type: 会话类型（p2p | group）。
|
||
peer_id: 对端 ID。
|
||
conversation_id: 关联的内部会话 ID（可选）。
|
||
unified_identity_id: 统一身份 ID（可选）。
|
||
"""
|
||
|
||
session_key: str
|
||
channel_type: ChannelType
|
||
account_id: str
|
||
chat_type: str
|
||
peer_id: str
|
||
conversation_id: str | None = None
|
||
unified_identity_id: str | None = None
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ConfigFallbackChain:
|
||
"""配置回退链。
|
||
|
||
描述配置层路由匹配的回退链节点，包括匹配键、匹配来源与匹配值，
|
||
用于配置回退决策追溯。
|
||
|
||
字段：
|
||
match_key: 匹配的键。
|
||
match_source: 匹配来源。
|
||
match_value: 匹配值（可选）。
|
||
"""
|
||
|
||
match_key: str
|
||
match_source: ConfigMatchSource
|
||
match_value: str | None = None
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class NestedWhitelistDecision:
|
||
"""嵌套白名单决策。
|
||
|
||
描述嵌套白名单的决策结果，包括外层配置与匹配状态以及内层决策，
|
||
用于 FR-30 嵌套白名单场景的决策追溯。
|
||
|
||
字段：
|
||
outer_configured: 外层是否配置。
|
||
outer_matched: 外层是否匹配。
|
||
inner_decision: 内层决策（allow / deny，可选）。
|
||
"""
|
||
|
||
outer_configured: bool
|
||
outer_matched: bool
|
||
inner_decision: str | None = None
|