From 8d79bd9767af4e6bb85f34ce95ca4a2aa19f51c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com> Date: Fri, 11 Sep 2026 15:21:36 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E9=BD=90=E4=B8=89=E4=B8=AA=E6=88=90?= =?UTF-8?q?=E5=8A=9F=E5=93=8D=E5=BA=94=E7=BC=BA=E5=A4=B1=E7=9A=84=20meta?= =?UTF-8?q?=20=E4=BF=A1=E5=B0=81=EF=BC=9B=E4=BF=A1=E5=B0=81=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0=E6=8A=BD=E4=B8=BA=E5=85=AC=E5=85=B1=EF=BC=88docs/05?= =?UTF-8?q?=20=C2=A73.3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "缺 meta"很容易被误判成"有"：X-Trace-ID 是**响应头**（中间件加），和 body 里的 meta.trace_id 是两件事；错误响应一直有 meta（异常处理器统一加），漏的只有成功路径。 核到三个端点在把 service 的内部结构直接当响应体返回： - GET /conversations/{session_id}/messages → 裸 {"data": [...]}，meta 整个缺失， 游标也没地方放（§3.3 要求列表的 data 为纯数组、next_cursor/has_more 进 meta） - POST /conversation-messages/{id}/feedback → 同样没有 meta - GET /knowledge-references/{token} → 直接返回资源对象 改动： - 新增 app/api/views/envelope.py，把 envelope / list_envelope 抽成一份公共实现， 风控链路改为复用它 —— 同一份契约写两遍的结果就是其中一处漏了 meta。 - ConversationService.messages 改为返回内部结构 {items, next_cursor, has_more}， 用 limit + 1 判断 has_more：只看"取满没取满"会把恰好等于 limit 的最后一页说成 还有下一页。next_cursor 取本页最后一条的 message_id —— 游标语义是"取更旧的一页"， 天然可续，集成测试本来就是这么翻页的。 - Controller 统一套信封，data 仍是数组、字段名不变，前端不需要改。 测试：新增 tests/unit/api/test_response_envelope.py，断言 set(body) == {"data","meta"} （多或少一个顶层字段都会红），并覆盖 has_more / next_cursor / trace_id； 另更新两处既有断言（limit 20→21、feedback 返回裸对象）。 门禁：ruff 干净 / mypy 138 文件 / 696 unit+contract / 33 integration。 --- app/api/controllers/conversations.py | 8 +- app/api/controllers/knowledge.py | 6 +- app/api/controllers/risk.py | 29 +---- app/api/views/envelope.py | 40 ++++++ app/service/conversation_service.py | 34 ++++- tests/unit/api/test_response_envelope.py | 119 ++++++++++++++++++ .../unit/service/test_conversation_service.py | 12 +- 7 files changed, 212 insertions(+), 36 deletions(-) create mode 100644 app/api/views/envelope.py create mode 100644 tests/unit/api/test_response_envelope.py diff --git a/app/api/controllers/conversations.py b/app/api/controllers/conversations.py index f5375db..e123144 100644 --- a/app/api/controllers/conversations.py +++ b/app/api/controllers/conversations.py @@ -5,6 +5,7 @@ from app.api.dependencies.auth import build_request_context from app.api.dependencies.database import get_session from app.api.dependencies.rate_limit import enforce_rate_limit from app.api.schemas.conversations import FeedbackRequest +from app.api.views.envelope import envelope, list_envelope from app.core.contracts import RequestContext from app.core.cursor import parse_cursor from app.service.conversation_service import ConversationService @@ -28,9 +29,10 @@ async def list_messages( `400 INVALID_CURSOR`，而不是被静默忽略后返回第一页。 """ before = parse_cursor(cursor) - return await ConversationService(session).messages( + page = await ConversationService(session).messages( session_id, context, limit, before=before ) + return list_envelope(page, context) @router.post("/conversation-messages/{message_id}/feedback", status_code=status.HTTP_201_CREATED) @@ -40,5 +42,7 @@ async def create_feedback( context: RequestContext = Depends(build_request_context), # noqa: B008 session: AsyncSession = Depends(get_session), # noqa: B008 ) -> dict[str, object]: - return await ConversationService(session).feedback( + # 与消息列表同理：§3.3 的信封由 Controller 统一套，service 只负责业务数据。 + data = await ConversationService(session).feedback( message_id, context, payload.rating, payload.feedback_type, payload.feedback_content) + return envelope(data, context) diff --git a/app/api/controllers/knowledge.py b/app/api/controllers/knowledge.py index af6fa49..7375b0e 100644 --- a/app/api/controllers/knowledge.py +++ b/app/api/controllers/knowledge.py @@ -2,6 +2,7 @@ from fastapi import APIRouter, Depends, Path from app.api.dependencies.auth import build_request_context from app.api.dependencies.rate_limit import enforce_rate_limit +from app.api.views.envelope import envelope from app.core.contracts import RequestContext from app.service.knowledge_service import KnowledgeReferenceService @@ -14,4 +15,7 @@ async def resolve_reference( reference_token: str = Path(min_length=20, max_length=300), context: RequestContext = Depends(build_request_context), # noqa: B008 ) -> dict[str, object]: - return await KnowledgeReferenceService().resolve(context, reference_token) + # §3.3：成功响应也要有 `meta.trace_id`。此前这里直接返回资源对象，客户端拿不到 + # 本次请求的追踪标识，出问题时无法与服务端日志对上。 + data = await KnowledgeReferenceService().resolve(context, reference_token) + return envelope(data, context) diff --git a/app/api/controllers/risk.py b/app/api/controllers/risk.py index 878debe..d9f380e 100644 --- a/app/api/controllers/risk.py +++ b/app/api/controllers/risk.py @@ -24,6 +24,8 @@ from app.api.schemas.risk import ( 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 @@ -304,28 +306,5 @@ async def send_risk_daily_report_mail( return _envelope(data, context) -def _envelope(data: object, context: RequestContext) -> dict[str, object]: - return { - "data": data, - "meta": {"trace_id": context.trace_id}, - } - - -def _list_envelope(page: dict[str, Any], context: RequestContext) -> dict[str, object]: - """列表资源的信封（docs/05 §3.3）。 - - §3.3 的列表样例是 `data` 为**纯数组**、游标与 `has_more` 放在 `meta` 里，并且明确 - 「业务接口不得增加其他顶层字段」。而 `RiskQueryService._page` 返回的是 - `{items, next_cursor, has_more}` —— 整体塞进 `data` 后，游标跑进了**业务数据**里、 - `meta` 只剩 trace_id，两处都不符合契约。 - - 这里统一拆包；service 侧不必改（它继续返回那个内部结构，只是不再直接当 `data` 用）。 - """ - return { - "data": page.get("items") or [], - "meta": { - "trace_id": context.trace_id, - "next_cursor": page.get("next_cursor"), - "has_more": bool(page.get("has_more")), - }, - } +# `_envelope` / `_list_envelope` 已抽到 `app/api/views/envelope.py`，与客服链路共用同一份 +# §3.3 实现 —— 两处各写一份的结果就是其中一处漏了 `meta`。 diff --git a/app/api/views/envelope.py b/app/api/views/envelope.py new file mode 100644 index 0000000..8df42e9 --- /dev/null +++ b/app/api/views/envelope.py @@ -0,0 +1,40 @@ +"""统一响应信封（`docs/05` §3.3）。 + +§3.3 规定成功响应是 `{data, meta}`，列表的 `data` 为**纯数组**、游标与 `has_more` 放在 +`meta` 里，并且明确「业务接口不得增加其他顶层字段」。 + +放在这里而不是各 Controller 各写一份：同一个偏差已经出现过两次 —— service 返回 +`{items, next_cursor, has_more}`（或干脆只有 `data`）之后被直接当响应体返回，于是 +`meta` 要么只剩 trace_id、要么整个缺失。同一份契约不该有多份实现。 +""" + +from __future__ import annotations + +from typing import Any + +from app.core.contracts import RequestContext + + +def envelope(data: object, context: RequestContext) -> dict[str, object]: + """单资源 / 单对象的信封。""" + return { + "data": data, + "meta": {"trace_id": context.trace_id}, + } + + +def list_envelope(page: dict[str, Any], context: RequestContext) -> dict[str, object]: + """列表资源的信封：`data` 只放数组，分页元数据进 `meta`。 + + `page` 是 service 的内部结构 `{items, next_cursor, has_more}` —— service 不必改， + 只是不再把它整体当 `data` 用。缺失的键按空值处理，因此只返回 `{"data": [...]}` + 的旧 service 也不会炸。 + """ + return { + "data": page.get("items") or [], + "meta": { + "trace_id": context.trace_id, + "next_cursor": page.get("next_cursor"), + "has_more": bool(page.get("has_more")), + }, + } diff --git a/app/service/conversation_service.py b/app/service/conversation_service.py index d1ecaff..03aafe0 100644 --- a/app/service/conversation_service.py +++ b/app/service/conversation_service.py @@ -22,12 +22,34 @@ class ConversationService: async def messages( self, session_id: str, context: RequestContext, limit: int, before: int | None = None ) -> dict[str, object]: - """消息列表投影；`before` 是文档 §3.8 的游标（记录 ID 边界），已由入口校验。""" + """消息列表投影；`before` 是文档 §3.8 的游标（记录 ID 边界），已由入口校验。 + + 取 `limit + 1` 行来判断"还有没有更旧的"：只看"取满没取满"会把恰好等于 limit 的 + 最后一页说成还有下一页。`next_cursor` 就是本页最后一条的 `message_id` —— + 游标语义是"取更旧的一页"，所以它天然可续（集成测试正是这么翻页的）。 + + 返回的是内部结构 `{items, next_cursor, has_more}`，由 Controller 用 + `list_envelope` 拆成 `docs/05` §3.3 要求的 `{data, meta}`；此前这里直接返回 + `{"data": [...]}`，成功响应因此**完全没有 `meta.trace_id`**。 + """ rows = await self.repository.messages( - session_id, int(context.user_id), limit, before=before + session_id, int(context.user_id), limit + 1, before=before ) - return {"data": [{"message_id": str(row.id), "role": row.role, "content": row.content, - "created_at": row.created_at.isoformat() + "Z"} for row in rows]} + has_more = len(rows) > limit + page_rows = rows[:limit] + return { + "items": [ + { + "message_id": str(row.id), + "role": row.role, + "content": row.content, + "created_at": row.created_at.isoformat() + "Z", + } + for row in page_rows + ], + "next_cursor": str(page_rows[-1].id) if has_more and page_rows else None, + "has_more": has_more, + } async def feedback( self, message_id: int, context: RequestContext, rating: int, @@ -50,7 +72,9 @@ class ConversationService: self.session.add(feedback) self._audit(context, message.session_id, "conversation.feedback_created", {"feedback_no": feedback.feedback_no}) - return {"data": {"feedback_no": feedback.feedback_no, "status": feedback.status}} + # 只返回业务数据；§3.3 的信封由 Controller 套（此前这里自带 {"data": ...}， + # 于是成功响应没有 meta.trace_id）。 + return {"feedback_no": feedback.feedback_no, "status": feedback.status} # 转人工申请（POST /api/v1/conversations/{id}/handover-requests）的唯一实现 # 在 PublicPlatformService.write("handover", ...)：它同一事务写工单 + Outbox diff --git a/tests/unit/api/test_response_envelope.py b/tests/unit/api/test_response_envelope.py new file mode 100644 index 0000000..9d9456b --- /dev/null +++ b/tests/unit/api/test_response_envelope.py @@ -0,0 +1,119 @@ +"""成功响应的统一信封（`docs/05` §3.3）。 + +§3.3 规定成功响应是 `{data, meta}`，列表的 `data` 为**纯数组**、`next_cursor` 与 +`has_more` 放在 `meta` 里，并且明确「业务接口不得增加其他顶层字段」。 + +此前有三个端点漏了这件事，它们都是"service 直接把内部结构当响应体返回"： + +- `GET /conversations/{session_id}/messages` → 裸 `{"data": [...]}`，`meta` 整个缺失， + 游标也没有地方放； +- `POST /conversation-messages/{id}/feedback` → 同样没有 `meta`； +- `GET /knowledge-references/{token}` → 直接返回资源对象。 + +注意"缺 meta"很容易被误判成"有"：`X-Trace-ID` 是**响应头**（由中间件加），和 body 里的 +`meta.trace_id` 是两件事；错误响应一直有 `meta`（异常处理器统一加），只有成功路径漏了。 +所以这里断言的是 `set(body)`，多一个或少一个顶层字段都会红。 +""" + +from typing import Any + +import pytest +from fastapi.testclient import TestClient + +from app.api.controllers import conversations as conversations_controller +from app.api.controllers import knowledge as knowledge_controller +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.main import create_app + +TRACE = "trace-envelope" + + +async def resolve_context() -> RequestContext: + return RequestContext( + user_id="9001", + trace_id=TRACE, + permissions=("conversation:create", "conversation:feedback", "knowledge:reference:read"), + ) + + +class StubConversationService: + def __init__(self, _session: Any) -> None: + pass + + async def messages( + self, _session_id: str, _context: RequestContext, _limit: int, before: int | None = None + ) -> dict[str, Any]: + del before + return { + "items": [ + { + "message_id": "11", + "role": "user", + "content": "稳健型", + "created_at": "2026-09-10T00:00:00Z", + } + ], + "next_cursor": "11", + "has_more": True, + } + + async def feedback( + self, + _message_id: int, + _context: RequestContext, + _rating: int, + _feedback_type: str | None, + _feedback_content: str | None, + ) -> dict[str, Any]: + return {"feedback_no": "fb-1", "status": "open"} + + +class StubKnowledgeService: + async def resolve(self, _context: RequestContext, _token: str) -> dict[str, Any]: + return {"knowledge_id": 7, "title": "个人投资者适当性管理指南"} + + +def envelope_client(monkeypatch: pytest.MonkeyPatch) -> TestClient: + monkeypatch.setattr( + conversations_controller, "ConversationService", StubConversationService + ) + monkeypatch.setattr(knowledge_controller, "KnowledgeReferenceService", StubKnowledgeService) + application = create_app() + application.dependency_overrides[build_request_context] = resolve_context + application.dependency_overrides[get_session] = lambda: None + return TestClient(application) + + +def test_message_list_puts_cursor_in_meta(monkeypatch: pytest.MonkeyPatch) -> None: + with envelope_client(monkeypatch) as http: + response = http.get("/api/v1/conversations/session-1/messages", params={"limit": 20}) + + assert response.status_code == 200 + body = response.json() + assert set(body) == {"data", "meta"} + assert isinstance(body["data"], list) + assert body["data"][0]["message_id"] == "11" + assert body["meta"] == {"trace_id": TRACE, "next_cursor": "11", "has_more": True} + + +def test_feedback_success_response_has_meta(monkeypatch: pytest.MonkeyPatch) -> None: + with envelope_client(monkeypatch) as http: + response = http.post("/api/v1/conversation-messages/11/feedback", json={"rating": 1}) + + assert response.status_code == 201 + body = response.json() + assert set(body) == {"data", "meta"} + assert body["data"] == {"feedback_no": "fb-1", "status": "open"} + assert body["meta"] == {"trace_id": TRACE} + + +def test_knowledge_reference_success_response_has_meta(monkeypatch: pytest.MonkeyPatch) -> None: + with envelope_client(monkeypatch) as http: + response = http.get(f"/api/v1/knowledge-references/{'a' * 20}") + + assert response.status_code == 200 + body = response.json() + assert set(body) == {"data", "meta"} + assert body["meta"] == {"trace_id": TRACE} diff --git a/tests/unit/service/test_conversation_service.py b/tests/unit/service/test_conversation_service.py index c74988f..da8fb10 100644 --- a/tests/unit/service/test_conversation_service.py +++ b/tests/unit/service/test_conversation_service.py @@ -108,14 +108,20 @@ async def test_messages_are_scoped_to_current_user(monkeypatch: pytest.MonkeyPat # user_id 必须透传：Repository 靠它做归属过滤，漏传就等于不限范围。 assert captured["user_id"] == 9001 - assert captured["limit"] == 20 + # 21 = limit + 1：service 多取一行判断"还有没有更旧的"，用来填 §3.3 的 has_more。 + # 只看"取满没取满"会把恰好等于 limit 的最后一页说成还有下一页。 + assert captured["limit"] == 21 assert captured["session_id"] == "session-1" # 不带游标时必须传 None，行为与加游标前一致（取最新一页）。 assert captured["before"] is None - assert result["data"] == [ + # service 返回内部结构，Controller 用 list_envelope 拆成 {data, meta}（§3.3）。 + # 一行数据小于 limit，所以没有下一页。 + assert result["items"] == [ {"message_id": "11", "role": "user", "content": "稳健型", "created_at": NOW.isoformat() + "Z"} ] + assert result["has_more"] is False + assert result["next_cursor"] is None async def test_messages_forward_cursor_to_repository(monkeypatch: pytest.MonkeyPatch) -> None: @@ -156,7 +162,7 @@ async def test_feedback_writes_feedback_and_audit_with_trace_id( result = await ConversationService(session).feedback(11, CONTEXT, 1, "rating", "很有帮助") - assert result["data"]["status"] == "open" + assert result["status"] == "open" kinds = [type(item).__name__ for item in session.added] assert kinds == ["ConversationFeedback", "InteractionAudit"] audit = session.added[1]