merge: 并入同事的场外申购/推广/行情/NL2SQL 线（11 提交、334 文件）

冲突仅 3 个文件，全部取并集（双方都没有需要丢弃的改动）：
- app/main.py：import 双方路由（我方 knowledge_management + 同事的 offsite_fund/
  promotion_material）；include_router 段本已自动合并
- app/service/agent/bootstrap.py：import 与工具注册均取并集
  （query_customer_profile + query_financial_data 都注册）
- tests/integration/test_config_release_mysql.py：outbox 清理同时保留
  架构师的 event_type 限定（防误删其它域 outbox 行）与同事新增的 peer_release_id

同事这轮带入：11 个 alembic 迁移（建 offsite_* / promotion_* 等表）、
场外申购与推广素材 Agent、financial NL2SQL 工具。
注意：本库尚无 offsite_*/promotion_* 表，跑相关测试前需要执行 alembic upgrade。

边界核对：同事的场外代码未写入场内交易表（fin_sim_order/fin_capital_flow/fin_cash_ledger），
符合 AGENTS.md 规则 8。

tests/unit/api/test_promotion_material_routes.py

@@ -0,0 +1,13 @@
+from app.main import app
+
+
+def test_promotion_material_routes_are_registered() -> None:
+    paths = set(app.openapi()["paths"])
+
+    assert "/api/v1/fund-promotion-materials" in paths
+    assert "/api/v1/fund-promotion-materials/{task_no}/inputs" in paths
+    assert "/api/v1/fund-promotion-materials/{task_no}/attachments" in paths
+    assert "/api/v1/fund-promotion-materials/{task_no}/generations" in paths
+    assert "/api/v1/fund-promotion-materials/{task_no}/compliance-checks" in paths
+    assert "/api/v1/fund-promotion-materials/{task_no}/reviews" in paths
+    assert "/api/v1/fund-promotion-materials/{task_no}/deliveries" in paths

tests/unit/api/test_request_validation_envelope.py

@@ -0,0 +1,53 @@
+"""请求校验错误信封契约测试（文档 §3.4 / §3.5 / §3.6 `AGENT_INPUT_INVALID`）。
+
+修复前 FastAPI 返回自己的 `{"detail": [...]}` 结构，与业务异常的 `{error, meta}` 信封
+不一致，客户端必须为"参数错误"单独兼容一套解析逻辑。本测试锁定修复后的形状：
+状态码 422、顶层只有 `error`/`meta`、字段级原因进 `error.field_errors`、
+`meta.trace_id` 沿用 `X-Trace-ID` 回显规则，同时保证鉴权仍先于参数校验失败。
+"""
+
+from fastapi.testclient import TestClient
+
+from app.api.dependencies.auth import build_request_context
+from app.core.contracts import RequestContext
+from app.main import create_app
+
+AGENT_RUNS = "/api/v1/agent-runs"
+
+
+def _authenticated_client() -> TestClient:
+    application = create_app()
+
+    async def context() -> RequestContext:
+        return RequestContext(
+            user_id="1", trace_id="validation-trace", permissions=("agent:run",)
+        )
+
+    application.dependency_overrides[build_request_context] = context
+    return TestClient(application)
+
+
+def test_missing_body_fields_use_unified_envelope() -> None:
+    with _authenticated_client() as client:
+        response = client.post(AGENT_RUNS, json={}, headers={"X-Trace-ID": "val-trace"})
+
+    assert response.status_code == 422
+    body = response.json()
+    assert set(body) == {"error", "meta"}, "校验错误只允许 error/meta 两个顶层字段"
+    error = body["error"]
+    assert error["code"] == "AGENT_INPUT_INVALID"
+    assert error["retryable"] is False
+    assert error["message"] == "请求参数不满足接口约束"
+    fields = {item["field"] for item in error["field_errors"]}
+    assert {"body.agent_type", "body.message", "body.session_id"} <= fields
+    assert all(item["message"] for item in error["field_errors"])
+    assert body["meta"] == {"trace_id": "val-trace"}
+
+
+def test_validation_handler_does_not_hijack_authentication() -> None:
+    """未带令牌 + 参数也不合法：必须仍是 401，参数校验不得掩盖鉴权失败。"""
+    with TestClient(create_app()) as client:
+        response = client.post(AGENT_RUNS, json={})
+
+    assert response.status_code == 401
+    assert response.json()["error"]["code"] == "AUTHENTICATION_REQUIRED"

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}