ForcePilot/backend/package/yuxi/channels/contract/dtos/dashboard.py

"""Dashboard 聚合视图域 DTO。

定义跨子域 KPI 聚合视图的不可变值对象，供 dashboard_router 端点返回。
所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库与契约层内部类型。
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime

from yuxi.channels.contract.dtos.channel import ChannelType
from yuxi.channels.contract.dtos.outbox import OutboxStats


@dataclass(frozen=True)
class AccountStats:
    """账户统计快照（DSB-02）。

    字段：
        total: 账户总数（仅含 is_deleted=0）。
        by_channel: 按渠道类型分组的计数 dict（key 为 ChannelType.value）。
        by_status: 按账户状态分组的计数 dict（key ∈ {active, disabled, degraded}）。
    """

    total: int
    by_channel: dict[str, int]
    by_status: dict[str, int]


@dataclass(frozen=True)
class MessageStats:
    """消息统计快照（DSB-03）。

    字段：
        total: 消息总数（满足时间过滤条件）。
        by_channel: 按渠道类型分组的计数 dict（channel_type 通过 conversation 关联填充）。
        by_role: 按发送角色分组的计数 dict（key ∈ {user, assistant, system, tool}）。
        by_delivery_status: 按渠道侧投递状态分组的计数 dict
            （key ∈ {sent, delivered, read, recalled, edited}）。
    """

    total: int
    by_channel: dict[str, int]
    by_role: dict[str, int]
    by_delivery_status: dict[str, int]


@dataclass(frozen=True)
class SessionStats:
    """会话统计快照（DSB-04）。

    字段：
        total: 未软删除会话总数。
        by_channel: 按渠道类型分组的计数 dict。
        by_is_temporary: 按是否临时会话分组的计数 dict（key 为 "true" / "false"）。
    """

    total: int
    by_channel: dict[str, int]
    by_is_temporary: dict[str, int]


@dataclass(frozen=True)
class DashboardOverview:
    """全局总览快照（DSB-01）。

    聚合四类子域计数，供管理后台首页看板渲染。

    字段：
        accounts: 账户总览。
        messages: 消息总览。
        sessions: 会话总览。
        outbox: 投递总览（复用 OutboxStats）。
    """

    accounts: AccountStats
    messages: MessageStats
    sessions: SessionStats
    outbox: OutboxStats


@dataclass(frozen=True)
class DashboardDeliveryQuery:
    """投递总览查询（DSB-DELIVERY）。

    描述投递总览查询条件，按渠道类型与时间范围过滤；所有字段可选，
    缺省时返回全局聚合。

    字段：
        channel_type: 渠道类型过滤（可选）。
        start_time: 起始时间（可选）。
        end_time: 截止时间（可选）。
    """

    channel_type: ChannelType | None = None
    start_time: datetime | None = None
    end_time: datetime | None = None


@dataclass(frozen=True)
class ChannelDeliveryStat:
    """渠道投递统计（DSB-DELIVERY by_channel 条目）。

    描述单渠道投递计数与成功率，用于投递总览的按渠道切片展示。

    字段：
        channel_type: 渠道类型字符串值。
        sent: 该渠道投递总数。
        success_rate: 成功率（0-100）。
    """

    channel_type: str
    sent: int
    success_rate: float


@dataclass(frozen=True)
class DashboardDeliveryResult:
    """投递总览结果（DSB-DELIVERY）。

    描述投递总览聚合结果，包含总计数、成功率、延迟分位数、队列深度、
    死信数与按渠道切片。

    字段：
        total_sent: 投递总数。
        success_count: 成功数。
        failed_count: 失败数。
        success_rate: 成功率（0-100）。
        avg_latency_ms: 平均延迟（毫秒）。
        p95_latency_ms: P95 延迟（毫秒）。
        p99_latency_ms: P99 延迟（毫秒）。
        current_queue_depth: 当前队列深度。
        dead_letter_count: 死信总数。
        by_channel: 按渠道切片的统计元组。
    """

    total_sent: int
    success_count: int
    failed_count: int
    success_rate: float
    avg_latency_ms: float
    p95_latency_ms: float
    p99_latency_ms: float
    current_queue_depth: int
    dead_letter_count: int
    by_channel: tuple[ChannelDeliveryStat, ...]


@dataclass(frozen=True)
class RealtimeQuery:
    """实时监控查询（DSB-REALTIME）。

    描述实时监控查询条件，按渠道类型与滑动窗口过滤；``window_seconds``
    范围 10-300，默认 60。

    字段：
        channel_type: 渠道类型过滤（可选）。
        window_seconds: 滑动窗口秒数（默认 60）。
    """

    channel_type: ChannelType | None = None
    window_seconds: int = 60


@dataclass(frozen=True)
class ChannelRealtimeStat:
    """渠道实时统计（DSB-REALTIME by_channel 条目）。

    描述单渠道实时消息速率与活跃会话数，用于实时监控的按渠道切片展示。

    字段：
        channel_type: 渠道类型字符串值。
        mps: 每秒消息数（messages per second）。
        active_sessions: 活跃会话数。
    """

    channel_type: str
    mps: float
    active_sessions: int


@dataclass(frozen=True)
class RealtimeMetricsResult:
    """实时监控结果（DSB-REALTIME）。

    描述实时监控纯内存态聚合结果，包含全局消息速率、活跃会话/会话数、
    队列深度、worker 利用率与按渠道切片。高频查询场景使用，避免 DB 连接占用。

    字段：
        window_seconds: 滑动窗口秒数。
        messages_per_second: 全局每秒消息数。
        active_sessions: 活跃会话总数。
        active_conversations: 活跃会话总数（与 active_sessions 同义，由
            不同来源聚合：sessions 来自 QueuePort，conversations 来自会话仓库）。
        queue_depth: 当前队列深度。
        worker_utilization: worker 利用率（0-100）。
        by_channel: 按渠道切片的实时统计元组。
    """

    window_seconds: int
    messages_per_second: float
    active_sessions: int
    active_conversations: int
    queue_depth: int
    worker_utilization: float
    by_channel: tuple[ChannelRealtimeStat, ...]


__all__ = [
    "AccountStats",
    "ChannelDeliveryStat",
    "ChannelRealtimeStat",
    "DashboardDeliveryQuery",
    "DashboardDeliveryResult",
    "DashboardOverview",
    "MessageStats",
    "RealtimeMetricsResult",
    "RealtimeQuery",
    "SessionStats",
]