ForcePilot/backend/server/routers/external_systems/notification_channel_router.py

"""NotificationChannel 子域 Router。

外部系统限界上下文的通知渠道管理 API，覆盖通知渠道列表 / 详情 / 创建 /
更新 / 删除 / 统计 / 测试。所有端点通过 ``create_use_cases_from_db`` 装配 use_cases，
经 ``notification_channel_service`` 端口调用用例。

路径顺序约束：静态路径（``/stats``）必须在 ``/{channel_id}`` 前声明，
避免被路径参数捕获。``POST /{channel_id}/test`` 与 ``POST ""`` 路径模式不重叠，
无需额外排序。

认证策略：查询类端点使用 ``get_required_user``，写操作端点（含测试）使用 ``get_admin_user``。

校验层次：
- **边界校验（Pydantic）**：``channel_type`` 使用 ``ChannelTypeLiteral`` 类型，
  Pydantic 在请求反序列化时即拒绝非法类型，并在 OpenAPI schema 中生成枚举。
- **领域校验（framework）**：``validate_channel_config`` 按 ``channel_type``
  校验 ``config`` 必填字段与 URL 协议，抛 ``DomainValidationError``（映射 400）。
  创建时直接校验；更新时先读取现有渠道的 ``channel_type`` 再校验 ``config``。

Request Schema 与 Input DTO 不共享类，Router 内显式构造 DTO，创建 / 更新 / 删除
操作的 ``created_by`` / ``updated_by`` 字段由 ``current_user.uid`` 填充。
"""

from __future__ import annotations

from typing import Any

from fastapi import APIRouter, Depends, Path, Query
from pydantic import BaseModel, ConfigDict, Field
from sqlalchemy.ext.asyncio import AsyncSession
from yuxi.external_systems.framework.adapters.notifications import (
    ChannelTypeLiteral,
    validate_channel_config,
)
from yuxi.external_systems.infrastructure.container import create_use_cases_from_db
from yuxi.external_systems.use_cases.dto.notification_channel import (
    CreateNotificationChannelInput,
    DeleteChannelInput,
    GetChannelInput,
    ListNotificationChannelsInput,
    NotificationChannelStatsInput,
    TestChannelInput,
    UpdateChannelInput,
)
from yuxi.storage.postgres.models_business import User

from server.utils.auth_middleware import get_admin_user, get_db, get_required_user

notification_channel_router = APIRouter(
    prefix="/notification-channels",
    tags=["external-systems-notification-channel"],
)


# ---------------- Request Schemas ----------------


class CreateNotificationChannelRequest(BaseModel):
    """创建通知渠道请求体。字段对齐 ``CreateNotificationChannelInput``（不含 created_by）。

    字段长度约束对齐 ``ExternalNotificationChannel`` ORM 列定义，在边界层拦截非法输入：
    ``channel_type`` 对齐 String(64) 且必须是支持的类型枚举，
    ``name`` 对齐 String(128)，``description`` 对齐 Text。
    """

    model_config = ConfigDict(frozen=True)

    channel_type: ChannelTypeLiteral
    name: str = Field(..., min_length=1, max_length=128)
    config: dict[str, Any] = Field(default_factory=dict)
    enabled: bool = True
    description: str | None = Field(default=None, max_length=2000)


class UpdateNotificationChannelRequest(BaseModel):
    """更新通知渠道请求体。字段对齐 ``UpdateChannelInput``（不含 id / updated_by）。

    字段长度约束对齐 ``ExternalNotificationChannel`` ORM 列定义，仅透传客户端显式设置的字段。
    ``channel_type`` 不可更新（渠道类型一经确定不可变更），如需变更应删除重建。
    """

    model_config = ConfigDict(frozen=True)

    name: str | None = Field(default=None, min_length=1, max_length=128)
    config: dict[str, Any] | None = None
    enabled: bool | None = None
    description: str | None = Field(default=None, max_length=2000)


class TestNotificationChannelRequest(BaseModel):
    """测试通知渠道请求体。``message`` 可选，未传时由 service 使用默认测试消息。"""

    model_config = ConfigDict(frozen=True)

    message: str | None = Field(default=None, max_length=2000)


# ---------------- Endpoints ----------------


@notification_channel_router.get("", response_model=dict)
async def list_notification_channels(
    limit: int = Query(100, ge=1, le=500),
    offset: int = Query(0, ge=0),
    channel_type: ChannelTypeLiteral | None = Query(None),
    enabled: bool | None = Query(None),
    keyword: str | None = Query(None, max_length=128),
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """分页查询通知渠道列表（支持 channel_type / enabled / keyword 过滤）。"""
    use_cases = create_use_cases_from_db(db)
    input_dto = ListNotificationChannelsInput(
        limit=limit,
        offset=offset,
        channel_type=channel_type,
        enabled=enabled,
        keyword=keyword,
    )
    output = await use_cases.notification_channel_service.list_channels(input_dto)
    return {"success": True, "data": output.model_dump()}


@notification_channel_router.get("/stats", response_model=dict)
async def get_notification_channel_stats(
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询通知渠道统计（按 channel_type 分组 + 按启用状态分组）。"""
    use_cases = create_use_cases_from_db(db)
    input_dto = NotificationChannelStatsInput()
    output = await use_cases.notification_channel_service.get_channel_stats(input_dto)
    return {"success": True, "data": output.model_dump()}


@notification_channel_router.get("/{channel_id}", response_model=dict)
async def get_notification_channel(
    channel_id: int = Path(ge=1),
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_required_user),
) -> dict[str, Any]:
    """查询通知渠道详情。"""
    use_cases = create_use_cases_from_db(db)
    input_dto = GetChannelInput(id=channel_id)
    output = await use_cases.notification_channel_service.get_channel(input_dto)
    return {"success": True, "data": output.model_dump()}


@notification_channel_router.post("", response_model=dict)
async def create_notification_channel(
    payload: CreateNotificationChannelRequest,
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """创建通知渠道。

    ``created_by`` 由当前管理员填充。
    ``channel_type`` 通过 ``ChannelTypeLiteral`` 在 Pydantic 层完成枚举校验，
    ``config`` 通过 ``validate_channel_config`` 按 ``channel_type`` 校验必填字段与 URL 协议。
    """
    validate_channel_config(payload.channel_type, payload.config)
    use_cases = create_use_cases_from_db(db)
    input_dto = CreateNotificationChannelInput(
        channel_type=payload.channel_type,
        name=payload.name,
        config=payload.config,
        enabled=payload.enabled,
        description=payload.description,
        created_by=current_user.uid,
    )
    output = await use_cases.notification_channel_service.create_channel(input_dto)
    return {"success": True, "data": output.model_dump()}


@notification_channel_router.put("/{channel_id}", response_model=dict)
async def update_notification_channel(
    payload: UpdateNotificationChannelRequest,
    channel_id: int = Path(ge=1),
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """更新通知渠道。

    仅透传客户端显式设置的字段。``updated_by`` 由当前管理员填充。
    若更新包含 ``config``，先读取现有渠道的 ``channel_type``，再按该类型校验
    ``config`` 结构（``channel_type`` 不可变更，校验基于已持久化的类型）。
    """
    use_cases = create_use_cases_from_db(db)
    if payload.config is not None:
        existing = await use_cases.notification_channel_service.get_channel(
            GetChannelInput(id=channel_id),
        )
        validate_channel_config(existing.channel_type, payload.config)
    input_dto = UpdateChannelInput(
        id=channel_id,
        updated_by=current_user.uid,
        **payload.model_dump(exclude_unset=True),
    )
    output = await use_cases.notification_channel_service.update_channel(input_dto)
    return {"success": True, "data": output.model_dump()}


@notification_channel_router.delete("/{channel_id}", response_model=dict)
async def delete_notification_channel(
    channel_id: int = Path(ge=1),
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """删除通知渠道（软删除）。

    ``updated_by`` 由当前管理员填充，写入 ORM 记录确保软删除可追溯操作人。
    若渠道被活跃告警引用，service 抛 ``ReferencedError``（映射 409）。
    """
    use_cases = create_use_cases_from_db(db)
    input_dto = DeleteChannelInput(
        id=channel_id,
        updated_by=current_user.uid,
    )
    output = await use_cases.notification_channel_service.delete_channel(input_dto)
    return {"success": True, "data": output.model_dump()}


@notification_channel_router.post("/{channel_id}/test", response_model=dict)
async def test_notification_channel(
    payload: TestNotificationChannelRequest,
    channel_id: int = Path(ge=1),
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """测试通知渠道连通性。

    构造测试 ``NotificationMessage``，通过 ``NotificationDispatcher`` 派发到渠道，
    返回派发结果（成功/失败 + 错误信息 + HTTP 状态码 + 耗时）。
    不持久化任何状态，仅用于验证渠道配置是否正确。
    """
    use_cases = create_use_cases_from_db(db)
    input_dto = TestChannelInput(
        id=channel_id,
        message=payload.message,
    )
    output = await use_cases.notification_channel_service.test_channel(input_dto)
    return {"success": True, "data": output.model_dump()}