Kris
f9f08221fc
本次提交包含多类代码优化： 1. 修复多处单行代码换行格式，统一代码排版 2. 为外部系统模块新增快捷菜单配置 3. 优化前端API请求参数命名一致性 4. 补充媒体下载超限错误码与领域异常类 5. 完善仓储层更新逻辑，支持显式清空字段 6. 优化部分测试用例与工具函数代码结构 7. 为微信插件白名单缓存增加过期时间
345 lines
14 KiB
Python
345 lines
14 KiB
Python
"""Alert 子域 Router。
|
||
|
||
外部系统限界上下文的告警事件管理 API，覆盖告警列表 / 详情 / 触发 /
|
||
确认 / 恢复 / 统计聚合 / 按链路查询 / 批量确认 / 批量恢复 / 告警上下文 /
|
||
通知状态。所有端点通过 ``create_use_cases_from_db`` 装配 use_cases，
|
||
经 ``alert_service`` 端口调用用例。
|
||
|
||
设计要点：
|
||
|
||
- ``list_alerts`` 支持 keyword / resource_type / resource_id / related_trace_id /
|
||
dedup_key / 时间范围 多维过滤，结果携带 ``system_name`` / ``system_slug``（LEFT JOIN 填充）。
|
||
- ``get_alert_stats`` 支持 system_id / env_key / 时间范围 过滤，聚合按 status / severity /
|
||
alert_type 分组与 Top 告警排行。
|
||
- ``list_alerts_by_trace`` 路径参数 ``trace_id`` 通过 ``Path(min_length=1, max_length=64)``
|
||
约束，避免空串与超长输入。
|
||
- ``fire_alert`` 显式字段映射构造 ``FireAlertInput``，``triggered_by`` 由当前管理员 uid 填充；
|
||
若 ``system_id`` 非空但系统不存在，Service 层抛 404；同一 ``dedup_key`` 在 firing 状态下去重更新。
|
||
- ``acknowledge_alert`` / ``resolve_alert`` 在告警不存在时返回 404，状态冲突时返回 409
|
||
（由 Service 层区分并通过 unified_error_handler 自动映射）。
|
||
- Request Schema 与 Input DTO 不共享类，Router 内显式构造 DTO，确保 API 边界与用例边界解耦。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Any, Literal
|
||
|
||
from fastapi import APIRouter, Body, Depends, Path, Query
|
||
from pydantic import BaseModel, ConfigDict, Field
|
||
from yuxi.external_systems.infrastructure.container import UseCases
|
||
from yuxi.external_systems.use_cases.dto.alert import (
|
||
AcknowledgeAlertInput,
|
||
AlertStatsInput,
|
||
BatchAcknowledgeAlertsInput,
|
||
BatchResolveAlertsInput,
|
||
FireAlertInput,
|
||
GetAlertContextInput,
|
||
GetAlertInput,
|
||
GetAlertNotificationsInput,
|
||
ListAlertsByTraceInput,
|
||
ListAlertsInput,
|
||
ResolveAlertInput,
|
||
)
|
||
from yuxi.storage.postgres.models_business import User
|
||
|
||
from server.routers.external_systems import get_use_cases, parse_and_naive, validate_time_range
|
||
from server.utils.auth_middleware import get_admin_user, get_required_user
|
||
|
||
alert_router = APIRouter(prefix="/alerts", tags=["external-systems-alert"])
|
||
|
||
|
||
# ---------------- Request Schemas ----------------
|
||
|
||
|
||
class FireAlertRequest(BaseModel):
|
||
"""触发告警请求体。字段对齐 ``FireAlertInput``。"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
system_id: int | None = Field(default=None, ge=1)
|
||
alert_type: str = Field(..., min_length=1, max_length=64)
|
||
title: str = Field(..., min_length=1, max_length=256)
|
||
triggered_at: str
|
||
env_key: str | None = Field(default=None, max_length=32)
|
||
severity: Literal["info", "warning", "critical", "fatal"] = "warning"
|
||
description: str | None = None
|
||
detail: dict[str, Any] = Field(default_factory=dict)
|
||
resource_type: str | None = Field(default=None, max_length=32)
|
||
resource_id: str | None = Field(default=None, max_length=128)
|
||
related_execution_id: str | None = Field(default=None, max_length=64)
|
||
related_trace_id: str | None = Field(default=None, max_length=64)
|
||
metric_snapshot: dict[str, Any] | None = None
|
||
dedup_key: str | None = Field(default=None, max_length=256)
|
||
|
||
|
||
class AcknowledgeAlertRequest(BaseModel):
|
||
"""确认告警请求体。``acknowledged_by`` 由当前管理员填充，仅暴露 ``note``。"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
note: str | None = None
|
||
|
||
|
||
class ResolveAlertRequest(BaseModel):
|
||
"""恢复告警请求体。字段对齐 ``ResolveAlertInput``（不含 id / user）。"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
resolution_note: str | None = None
|
||
|
||
|
||
class BatchAcknowledgeAlertsRequest(BaseModel):
|
||
"""批量确认告警请求体。字段对齐 ``BatchAcknowledgeAlertsInput``（不含 acknowledged_by）。"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
alert_ids: list[int] = Field(..., min_length=1, max_length=100)
|
||
note: str | None = None
|
||
|
||
|
||
class BatchResolveAlertsRequest(BaseModel):
|
||
"""批量恢复告警请求体。字段对齐 ``BatchResolveAlertsInput``（不含 user）。"""
|
||
|
||
model_config = ConfigDict(frozen=True)
|
||
|
||
alert_ids: list[int] = Field(..., min_length=1, max_length=100)
|
||
resolution_note: str | None = None
|
||
|
||
|
||
# ---------------- Endpoints ----------------
|
||
|
||
|
||
@alert_router.get("", response_model=dict)
|
||
async def list_alerts(
|
||
limit: int = Query(100, ge=1, le=500),
|
||
offset: int = Query(0, ge=0),
|
||
system_id: int | None = Query(None, ge=1),
|
||
env_key: str | None = Query(None, max_length=32),
|
||
alert_type: str | None = Query(None, max_length=64),
|
||
severity: Literal["info", "warning", "critical", "fatal"] | None = Query(
|
||
None, description="严重度：info/warning/critical/fatal"
|
||
),
|
||
status: Literal["firing", "acknowledged", "resolved", "suppressed"] | None = Query(
|
||
None, description="告警状态：firing/acknowledged/resolved/suppressed"
|
||
),
|
||
start_time: str | None = Query(None, description="开始时间（ISO 8601）"),
|
||
end_time: str | None = Query(None, description="结束时间（ISO 8601）"),
|
||
keyword: str | None = Query(
|
||
None, max_length=128, description="关键词搜索（title/description/alert_type/system name/slug）"
|
||
),
|
||
# 新增查询参数
|
||
resource_type: str | None = Query(None, max_length=32),
|
||
resource_id: str | None = Query(None, max_length=128),
|
||
related_trace_id: str | None = Query(None, max_length=64),
|
||
dedup_key: str | None = Query(None, max_length=256),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""分页列出告警事件（支持 keyword / resource_type / resource_id / related_trace_id / dedup_key 过滤）。
|
||
|
||
时间范围校验：若 ``start_time`` 晚于 ``end_time``，抛 ``DomainValidationError``
|
||
（由全局 ``unified_error_handler`` 统一映射为 400 + 项目统一错误格式）。
|
||
列表结果包含 ``system_name`` / ``system_slug``（由 LEFT JOIN 填充）。
|
||
"""
|
||
start_dt = parse_and_naive("start_time", start_time)
|
||
end_dt = parse_and_naive("end_time", end_time)
|
||
validate_time_range(start_dt, end_dt)
|
||
input_dto = ListAlertsInput(
|
||
limit=limit,
|
||
offset=offset,
|
||
system_id=system_id,
|
||
env_key=env_key,
|
||
alert_type=alert_type,
|
||
severity=severity,
|
||
status=status,
|
||
start_at=start_dt,
|
||
end_at=end_dt,
|
||
keyword=keyword,
|
||
resource_type=resource_type,
|
||
resource_id=resource_id,
|
||
related_trace_id=related_trace_id,
|
||
dedup_key=dedup_key,
|
||
)
|
||
output = await use_cases.alert_service.list_alerts(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.get("/stats", response_model=dict)
|
||
async def get_alert_stats(
|
||
system_id: int | None = Query(None, ge=1),
|
||
env_key: str | None = Query(None, max_length=32),
|
||
start_time: str | None = Query(None, description="开始时间（ISO 8601）"),
|
||
end_time: str | None = Query(None, description="结束时间（ISO 8601）"),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""查询告警统计聚合（支持 system_id / env_key / 时间范围过滤）。
|
||
|
||
时间范围基于 ``triggered_at`` 字段，若 ``start_time`` 晚于 ``end_time`` 抛
|
||
``DomainValidationError``（由全局 ``unified_error_handler`` 统一映射为 400）。
|
||
"""
|
||
start_dt = parse_and_naive("start_time", start_time)
|
||
end_dt = parse_and_naive("end_time", end_time)
|
||
validate_time_range(start_dt, end_dt)
|
||
input_dto = AlertStatsInput(
|
||
system_id=system_id,
|
||
env_key=env_key,
|
||
start_at=start_dt,
|
||
end_at=end_dt,
|
||
)
|
||
output = await use_cases.alert_service.get_alert_stats(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.get("/by-trace/{trace_id}", response_model=dict)
|
||
async def list_alerts_by_trace(
|
||
trace_id: str = Path(..., min_length=1, max_length=64, description="链路 ID"),
|
||
limit: int = Query(100, ge=1, le=500),
|
||
offset: int = Query(0, ge=0),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""按链路 ID 查询告警（通过 related_trace_id 关联，支持分页）。"""
|
||
input_dto = ListAlertsByTraceInput(
|
||
trace_id=trace_id,
|
||
limit=limit,
|
||
offset=offset,
|
||
)
|
||
output = await use_cases.alert_service.list_alerts_by_trace(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.post("/batch-acknowledge", response_model=dict)
|
||
async def batch_acknowledge_alerts(
|
||
payload: BatchAcknowledgeAlertsRequest,
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""批量确认告警。``acknowledged_by`` 由当前管理员填充。"""
|
||
input_dto = BatchAcknowledgeAlertsInput(
|
||
alert_ids=payload.alert_ids,
|
||
note=payload.note,
|
||
acknowledged_by=current_user.uid,
|
||
)
|
||
output = await use_cases.alert_service.batch_acknowledge_alerts(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.post("/batch-resolve", response_model=dict)
|
||
async def batch_resolve_alerts(
|
||
payload: BatchResolveAlertsRequest,
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""批量恢复告警。``user`` 由当前管理员填充，确保审计可追溯。"""
|
||
input_dto = BatchResolveAlertsInput(
|
||
alert_ids=payload.alert_ids,
|
||
user=current_user.uid,
|
||
resolution_note=payload.resolution_note,
|
||
)
|
||
output = await use_cases.alert_service.batch_resolve_alerts(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.get("/{alert_id}", response_model=dict)
|
||
async def get_alert(
|
||
alert_id: int = Path(ge=1),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""获取告警详情。"""
|
||
input_dto = GetAlertInput(id=alert_id)
|
||
output = await use_cases.alert_service.get_alert(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.post("", response_model=dict)
|
||
async def fire_alert(
|
||
payload: FireAlertRequest,
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""触发告警事件（含去重与自动通知派发）。
|
||
|
||
``triggered_by`` 由当前管理员 uid 填充，确保审计可追溯。
|
||
若 ``system_id`` 非空但对应系统不存在，Service 层抛 404。
|
||
同一 ``dedup_key`` 在 ``firing`` 状态下重复触发时更新已有记录。
|
||
"""
|
||
input_dto = FireAlertInput(
|
||
system_id=payload.system_id,
|
||
alert_type=payload.alert_type,
|
||
title=payload.title,
|
||
triggered_at=parse_and_naive("triggered_at", payload.triggered_at),
|
||
env_key=payload.env_key,
|
||
severity=payload.severity,
|
||
description=payload.description,
|
||
detail=payload.detail,
|
||
resource_type=payload.resource_type,
|
||
resource_id=payload.resource_id,
|
||
related_execution_id=payload.related_execution_id,
|
||
related_trace_id=payload.related_trace_id,
|
||
metric_snapshot=payload.metric_snapshot,
|
||
dedup_key=payload.dedup_key,
|
||
triggered_by=current_user.uid,
|
||
)
|
||
output = await use_cases.alert_service.fire_alert(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.post("/{alert_id}/acknowledge", response_model=dict)
|
||
async def acknowledge_alert(
|
||
alert_id: int = Path(ge=1),
|
||
payload: AcknowledgeAlertRequest = Body(...),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""确认告警。``acknowledged_by`` 由当前管理员 uid 填充，``note`` 可选。"""
|
||
input_dto = AcknowledgeAlertInput(
|
||
id=alert_id,
|
||
acknowledged_by=current_user.uid,
|
||
note=payload.note,
|
||
)
|
||
output = await use_cases.alert_service.acknowledge_alert(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.post("/{alert_id}/resolve", response_model=dict)
|
||
async def resolve_alert(
|
||
alert_id: int = Path(ge=1),
|
||
payload: ResolveAlertRequest = Body(...),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""恢复告警。``user`` 由当前管理员 uid 填充，确保审计可追溯。"""
|
||
input_dto = ResolveAlertInput(
|
||
id=alert_id,
|
||
user=current_user.uid,
|
||
resolution_note=payload.resolution_note,
|
||
)
|
||
output = await use_cases.alert_service.resolve_alert(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.get("/{alert_id}/context", response_model=dict)
|
||
async def get_alert_context(
|
||
alert_id: int = Path(ge=1),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""查询告警上下文（含执行记录 + 指标快照）。"""
|
||
input_dto = GetAlertContextInput(alert_id=alert_id)
|
||
output = await use_cases.alert_service.get_alert_context(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@alert_router.get("/{alert_id}/notifications", response_model=dict)
|
||
async def get_alert_notifications(
|
||
alert_id: int = Path(ge=1),
|
||
use_cases: UseCases = Depends(get_use_cases),
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""查询告警通知状态。"""
|
||
input_dto = GetAlertNotificationsInput(alert_id=alert_id)
|
||
output = await use_cases.alert_service.get_alert_notifications(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|