张胜宇
e239eb778b
1) 客服 Agent 四份交付文档 + 构建脚手架：品牌由包装占位 XX科技 / 旧名 南方财富 统一为南方基金（热线 400-889-8899 / 官网 nffund.com），系统名改为「智能服务系统」； 同步追加 §0.4 修订记录行，工程记录行保留原占位字面以支撑硬编码扫描验收。 2) 开发文档：清理 28 份已作废/残留文档（14 份移出归档 + 14 份仓库副本）， 新增《文档规整方案与开发前待决事项-2026-09-17》。 3) 客服agent 四份交付文档首次纳入本分支。
41 lines
1.5 KiB
Python
41 lines
1.5 KiB
Python
"""统一响应信封（`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")),
|
|
},
|
|
}
|