321 lines
13 KiB
Python
321 lines
13 KiB
Python
"""风控只读查询接口。"""
|
||
|
||
import json
|
||
from collections.abc import AsyncIterator, Awaitable, Callable
|
||
from datetime import datetime, time
|
||
from typing import Any
|
||
|
||
from fastapi import APIRouter, Depends, File, Header, Path, Request, UploadFile
|
||
from sqlalchemy.ext.asyncio import AsyncSession
|
||
from starlette.responses import StreamingResponse
|
||
|
||
from app.api.dependencies.auth import build_request_context
|
||
from app.api.dependencies.database import get_session
|
||
from app.api.dependencies.negotiation import accepts_event_stream
|
||
from app.api.dependencies.rate_limit import enforce_rate_limit
|
||
from app.api.schemas.risk import (
|
||
RiskAlertEscalationRequest,
|
||
RiskAlertExclusionRequest,
|
||
RiskAlertPageQuery,
|
||
RiskAlertResolutionRequest,
|
||
RiskDailyReportGenerateRequest,
|
||
RiskDailyReportMailRequest,
|
||
RiskEvidencePageQuery,
|
||
RiskEvidenceSource,
|
||
RiskNotificationPageQuery,
|
||
)
|
||
from app.api.views.envelope import envelope as _envelope
|
||
from app.api.views.envelope import list_envelope as _list_envelope
|
||
from app.core.contracts import RequestContext
|
||
from app.core.errors import SseNotAcceptableError
|
||
from app.infrastructure.db import mysql_scan_lock
|
||
from app.service.api_transaction_service import ApiTransactionService
|
||
from app.service.risk_action_service import RiskActionService
|
||
from app.service.risk_daily_report_mail_service import RiskDailyReportMailService
|
||
from app.service.risk_daily_report_service import RiskDailyReportService
|
||
from app.service.risk_evidence_archive_service import RiskEvidenceArchiveService
|
||
from app.service.risk_notification_service import RiskNotificationService
|
||
from app.service.risk_query_service import RiskQueryService
|
||
from app.service.risk_scan_service import RiskScanBusyError, RiskScanService
|
||
|
||
router = APIRouter(
|
||
prefix="/api/v1/risk",
|
||
tags=["risk"],
|
||
dependencies=[Depends(enforce_rate_limit)],
|
||
)
|
||
|
||
|
||
async def _idempotent_write(
|
||
session: AsyncSession,
|
||
context: RequestContext,
|
||
key: str | None,
|
||
scope: str,
|
||
body: Any,
|
||
action: Callable[[AsyncSession], Awaitable[dict[str, Any]]],
|
||
) -> dict[str, Any]:
|
||
"""风控写接口的统一幂等入口（`docs/05` §5.1、§5.2、§13.2）。
|
||
|
||
`scope` 用**实际**路径（含 `alert_no`）：§5.1 的幂等范围是
|
||
`user_id + method + normalized_path + idempotency_key`，把路径参数折成模板会让
|
||
同一个键在不同预警之间互相回放 —— 那是把两次不同资源的操作当成一次。
|
||
|
||
幂等记录与业务写入同事务（见 `ApiTransactionService.execute_in`），重复请求直接
|
||
回放 `response_json`，不会二次驱动状态机。
|
||
"""
|
||
return await ApiTransactionService().execute_in(session, context, scope, key, body, action)
|
||
|
||
|
||
def _risk_list_envelope(page: dict[str, Any], context: RequestContext) -> dict[str, object]:
|
||
"""在统一列表信封上补充风控列表总数和页大小。"""
|
||
response = _list_envelope(page, context)
|
||
meta = response["meta"]
|
||
if isinstance(meta, dict):
|
||
meta["total"] = int(page.get("total") or 0)
|
||
meta["page_size"] = int(page.get("page_size") or 0)
|
||
return response
|
||
|
||
|
||
@router.get("/overview")
|
||
async def risk_overview(
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> dict[str, object]:
|
||
data = await RiskQueryService(session).overview(context)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.get("/alerts")
|
||
async def list_risk_alerts(
|
||
query: RiskAlertPageQuery = Depends(), # noqa: B008
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> dict[str, object]:
|
||
data = await RiskQueryService(session).list_alerts(context, query)
|
||
return _risk_list_envelope(data, context)
|
||
|
||
|
||
@router.post("/alerts/scan")
|
||
async def scan_risk_alerts(
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
key: str | None = Header(default=None, alias="Idempotency-Key"),
|
||
) -> dict[str, object]:
|
||
async def run(inner: AsyncSession) -> dict[str, Any]:
|
||
# 手工触发的扫描必须与定时扫描互斥，否则两条路径会同时查不到重复、同时插入。
|
||
# 锁加在**入口层**而不是 `RiskScanService.scan()` 内部：`GET_LOCK` 是连接级的，
|
||
# 而调度器已在它自己的 session 上持锁 —— 被两个入口共用的服务方法若再取同一把锁，
|
||
# 取锁的连接不是持锁的那一个、必然失败，会**把定时扫描自己挡死**。
|
||
async with mysql_scan_lock() as acquired:
|
||
if not acquired:
|
||
raise RiskScanBusyError("规则扫描正在执行，请稍后重试")
|
||
return await RiskScanService.from_settings(inner).scan(context)
|
||
|
||
data = await _idempotent_write(
|
||
session, context, key, "POST /api/v1/risk/alerts/scan", {}, run
|
||
)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.post("/alerts/{alert_no}/acknowledgements")
|
||
async def acknowledge_risk_alert(
|
||
alert_no: str = Path(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$"),
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
key: str | None = Header(default=None, alias="Idempotency-Key"),
|
||
) -> dict[str, object]:
|
||
data = await _idempotent_write(
|
||
session,
|
||
context,
|
||
key,
|
||
f"POST /api/v1/risk/alerts/{alert_no}/acknowledgements",
|
||
{},
|
||
lambda inner: RiskActionService(inner).acknowledge(alert_no, context),
|
||
)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.post("/alerts/{alert_no}/investigations")
|
||
async def investigate_risk_alert(
|
||
alert_no: str = Path(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$"),
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
key: str | None = Header(default=None, alias="Idempotency-Key"),
|
||
) -> dict[str, object]:
|
||
data = await _idempotent_write(
|
||
session,
|
||
context,
|
||
key,
|
||
f"POST /api/v1/risk/alerts/{alert_no}/investigations",
|
||
{},
|
||
lambda inner: RiskActionService(inner).investigate(alert_no, context),
|
||
)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.post("/alerts/{alert_no}/exclusions")
|
||
async def exclude_risk_alert(
|
||
payload: RiskAlertExclusionRequest,
|
||
alert_no: str = Path(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$"),
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
key: str | None = Header(default=None, alias="Idempotency-Key"),
|
||
) -> dict[str, object]:
|
||
data = await _idempotent_write(
|
||
session,
|
||
context,
|
||
key,
|
||
f"POST /api/v1/risk/alerts/{alert_no}/exclusions",
|
||
{"reason": payload.reason},
|
||
lambda inner: RiskActionService(inner).exclude(alert_no, payload.reason, context),
|
||
)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.post("/alerts/{alert_no}/resolutions")
|
||
async def resolve_risk_alert(
|
||
payload: RiskAlertResolutionRequest,
|
||
alert_no: str = Path(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$"),
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
key: str | None = Header(default=None, alias="Idempotency-Key"),
|
||
) -> dict[str, object]:
|
||
data = await _idempotent_write(
|
||
session,
|
||
context,
|
||
key,
|
||
f"POST /api/v1/risk/alerts/{alert_no}/resolutions",
|
||
{"resolution": payload.resolution},
|
||
lambda inner: RiskActionService(inner).resolve(alert_no, payload.resolution, context),
|
||
)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.post("/alerts/{alert_no}/escalations")
|
||
async def escalate_risk_alert(
|
||
payload: RiskAlertEscalationRequest,
|
||
alert_no: str = Path(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$"),
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
key: str | None = Header(default=None, alias="Idempotency-Key"),
|
||
) -> dict[str, object]:
|
||
data = await _idempotent_write(
|
||
session,
|
||
context,
|
||
key,
|
||
f"POST /api/v1/risk/alerts/{alert_no}/escalations",
|
||
{"reason": payload.reason},
|
||
lambda inner: RiskActionService(inner).escalate(alert_no, payload.reason, context),
|
||
)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.post("/alerts/{alert_no}/evidence")
|
||
async def archive_risk_evidence(
|
||
evidence_file: UploadFile = File(...), # noqa: B008
|
||
alert_no: str = Path(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$"),
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> dict[str, object]:
|
||
try:
|
||
data = await RiskEvidenceArchiveService(session).archive(alert_no, evidence_file, context)
|
||
return _envelope(data, context)
|
||
finally:
|
||
await evidence_file.close()
|
||
|
||
|
||
@router.get("/alerts/{alert_no}")
|
||
async def get_risk_alert(
|
||
alert_no: str = Path(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$"),
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> dict[str, object]:
|
||
data = await RiskQueryService(session).get_alert_detail(context, alert_no.strip())
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.get("/evidence/{source}")
|
||
async def list_risk_evidence(
|
||
source: RiskEvidenceSource = Path(), # noqa: B008
|
||
query: RiskEvidencePageQuery = Depends(), # noqa: B008
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> dict[str, object]:
|
||
data = await RiskQueryService(session).list_evidence(context, source, query)
|
||
return _risk_list_envelope(data, context)
|
||
|
||
|
||
@router.get("/notifications")
|
||
async def list_risk_notifications(
|
||
query: RiskNotificationPageQuery = Depends(), # noqa: B008
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> dict[str, object]:
|
||
data = await RiskNotificationService(session).list_notifications(context, query)
|
||
return _risk_list_envelope(data, context)
|
||
|
||
|
||
@router.post("/daily-report")
|
||
async def generate_risk_daily_report(
|
||
payload: RiskDailyReportGenerateRequest,
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> dict[str, object]:
|
||
report_time = (
|
||
datetime.combine(payload.report_date, time.min)
|
||
if payload.report_date is not None
|
||
else None
|
||
)
|
||
data = await RiskDailyReportService(session).generate(context, report_time)
|
||
return _envelope(data, context)
|
||
|
||
|
||
@router.post("/daily-report/stream")
|
||
async def stream_risk_daily_report(
|
||
payload: RiskDailyReportGenerateRequest,
|
||
request: Request,
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
session: AsyncSession = Depends(get_session), # noqa: B008
|
||
) -> StreamingResponse:
|
||
report_time = (
|
||
datetime.combine(payload.report_date, time.min)
|
||
if payload.report_date is not None
|
||
else None
|
||
)
|
||
service = RiskDailyReportService(session)
|
||
# 鉴权与内容协商都必须在返回 StreamingResponse **之前**完成：`stream()` 是 async
|
||
# generator，函数体到第一次迭代才执行，而那时响应头已经发出去了 —— 403/406 只能
|
||
# 变成"200 + 半截流"（docs/25 P3 #24）。顺序与 §6.4 一致：先鉴权，后 Accept。
|
||
await service.authorize(context)
|
||
if not accepts_event_stream(request.headers.get("Accept")):
|
||
raise SseNotAcceptableError("Accept 必须接受 text/event-stream")
|
||
|
||
async def events() -> AsyncIterator[str]:
|
||
async for event in service.stream(context, report_time):
|
||
event_type = str(event.get("type", "message"))
|
||
payload = json.dumps(event, ensure_ascii=False, default=str)
|
||
yield f"event: {event_type}\ndata: {payload}\n\n"
|
||
|
||
return StreamingResponse(
|
||
events(),
|
||
media_type="text/event-stream",
|
||
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
|
||
)
|
||
|
||
|
||
@router.post("/daily-report/mail")
|
||
async def send_risk_daily_report_mail(
|
||
payload: RiskDailyReportMailRequest,
|
||
context: RequestContext = Depends(build_request_context), # noqa: B008
|
||
) -> dict[str, object]:
|
||
data = await RiskDailyReportMailService().send(
|
||
payload.recipients,
|
||
payload.subject,
|
||
payload.content,
|
||
context=context,
|
||
)
|
||
return _envelope(data, context)
|
||
|
||
|
||
# `_envelope` / `_list_envelope` 已抽到 `app/api/views/envelope.py`，与客服链路共用同一份
|
||
# §3.3 实现 —— 两处各写一份的结果就是其中一处漏了 `meta`。
|