风控 SSE 内容协商与鉴权时序；docs/05 补齐 413 与风控入口（docs/25 P3 #23 #24 #25）

#23：413 是上传超限的标准语义，前端文档（风控业务演示文档 17）也已按 413 做提示
映射，所以不把代码降成 422，而是在 docs/05 §3.5 状态码表补登 413 —— 契约以"补齐"
而不是"改动"的方式对齐。

#24：/api/v1/risk/daily-report/stream 此前既不校验 Accept，又把鉴权留在 async
generator 内部。后者更隐蔽：StreamingResponse 已经返回、响应头已经发出，403 只能
变成"200 + 半截流"。现在 controller 先 await service.authorize(context) 再判定
Accept，顺序与 §6.4 一致（鉴权先行，不用状态码差异做探测）。SSE 协商逻辑抽到
app/api/dependencies/negotiation.py，与 /agent-runs/{run_id}/events 共用同一口径，
避免同一种客户端在一个端点上 200、另一个端点上 406。

#25：复核后确认前半段不成立 —— §19 末尾写明业务域接口由各自业务文档登记，风控 15 条
端点已在 06-模块接口与字段映射.md 逐条登记。真问题是 §12 表里写的
/api/v1/risk-scans/**、/api/v1/risk-alerts/** 与实际实现 /api/v1/risk/** 不符，
按实际实现更新 §12 并加说明；顺带把风控文档里 /daily-report/mail 的权限从
"按主项目邮件策略执行"改为实际的 risk:report:mail。

新增 tests/unit/api/test_risk_stream_negotiation.py（7 例）。

tests/unit/api/test_risk_controller.py

@@ -94,6 +94,9 @@ class StubRiskDailyReportService:
     def __init__(self, _session: Any) -> None:
         pass
 
+    async def authorize(self, _context: RequestContext) -> None:
+        """SSE 端点要求构造 `StreamingResponse` 之前先完成鉴权（docs/25 P3 #24）。"""
+
     async def generate(self, _context: RequestContext, _report_time: Any) -> dict[str, Any]:
         return {"report_date": "2026-09-10", "content": "日报正文"}
 

tests/unit/api/test_risk_stream_negotiation.py

@@ -0,0 +1,103 @@
+"""风控 SSE 端点的内容协商与鉴权时序（`docs/25` P3 #24）。
+
+`POST /api/v1/risk/daily-report/stream` 此前既不校验 `Accept`，又把鉴权留在
+async generator 内部 —— 后者更隐蔽：`StreamingResponse` 已经返回、响应头已经发出，
+`403` 只能变成"200 + 半截流"。所以这里同时断言两件事：
+
+1. 显式只接受 `application/json` → `406 SSE_NOT_ACCEPTABLE`，且响应体是统一 JSON 错误；
+2. 无权限时即使 `Accept` 也非法，仍先得到 `403 AGENT_PERMISSION_DENIED`（顺序与
+   `docs/05` §6.4 一致：鉴权先行，防止用状态码差异做探测）。
+"""
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.api.dependencies.auth import build_request_context
+from app.api.dependencies.database import get_session
+from app.core.contracts import RequestContext
+from app.core.errors import AgentPermissionDeniedError
+from app.main import create_app
+
+STREAM_PATH = "/api/v1/risk/daily-report/stream"
+
+
+async def resolve_context() -> RequestContext:
+    return RequestContext(
+        user_id="1",
+        trace_id="trace-1",
+        permissions=("risk:alert:read",),
+        data_scope="all",
+    )
+
+
+class StubReportService:
+    """替身：`authorize` 通过、流立即收尾，避免测试连接挂住。"""
+
+    def __init__(self, session: Any) -> None:
+        self.session = session
+
+    async def authorize(self, _context: RequestContext) -> None:
+        return None
+
+    async def stream(
+        self,
+        _context: RequestContext,
+        _now: Any,
+    ) -> AsyncIterator[dict[str, Any]]:
+        yield {"type": "done", "report": {}}
+
+
+class DenyingReportService(StubReportService):
+    async def authorize(self, _context: RequestContext) -> None:
+        raise AgentPermissionDeniedError("缺少 risk:alert:read 权限")
+
+
+def client_with(
+    monkeypatch: pytest.MonkeyPatch,
+    service_class: type[StubReportService],
+) -> TestClient:
+    application = create_app()
+    application.dependency_overrides[build_request_context] = resolve_context
+    application.dependency_overrides[get_session] = lambda: None
+    monkeypatch.setattr("app.api.controllers.risk.RiskDailyReportService", service_class)
+    return TestClient(application)
+
+
+@pytest.mark.parametrize("accept", [None, "", "*/*", "text/*", "text/event-stream"])
+def test_absent_or_wildcard_accept_is_allowed(
+    monkeypatch: pytest.MonkeyPatch, accept: str | None
+) -> None:
+    headers = {} if accept is None else {"Accept": accept}
+    with client_with(monkeypatch, StubReportService) as client:
+        response = client.post(STREAM_PATH, json={}, headers=headers)
+
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("text/event-stream")
+
+
+def test_json_only_accept_is_rejected_before_streaming(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    with client_with(monkeypatch, StubReportService) as client:
+        response = client.post(
+            STREAM_PATH, json={}, headers={"Accept": "application/json"}
+        )
+
+    assert response.status_code == 406
+    assert response.json()["error"]["code"] == "SSE_NOT_ACCEPTABLE"
+    assert response.headers["content-type"].startswith("application/json")
+
+
+def test_authorization_precedes_accept_negotiation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    with client_with(monkeypatch, DenyingReportService) as client:
+        response = client.post(
+            STREAM_PATH, json={}, headers={"Accept": "application/json"}
+        )
+
+    assert response.status_code == 403
+    assert response.json()["error"]["code"] == "AGENT_PERMISSION_DENIED"