补齐三个成功响应缺失的 meta 信封；信封实现抽为公共（docs/05 §3.3）

"缺 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

@@ -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)

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)

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]:
+# `_envelope` / `_list_envelope` 已抽到 `app/api/views/envelope.py`，与客服链路共用同一份
-    return {
+# §3.3 实现 —— 两处各写一份的结果就是其中一处漏了 `meta`。
-        "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")),
-        },
-    }

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")),
+        },
+    }

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,
+        has_more = len(rows) > limit
-                          "created_at": row.created_at.isoformat() + "Z"} for row in rows]}
+        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

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}

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]