"""成功响应的统一信封（`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}