"""统一响应信封（`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")),
        },
    }