补齐三个成功响应缺失的 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。
This commit is contained in:
2026-09-11 15:21:36 +08:00
parent 575b4c2baa
commit 8d79bd9767
7 changed files with 212 additions and 36 deletions
@@ -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]