build: add api server response envelope helpers

server-rs/apps/api-server/README.md

@@ -30,7 +30,7 @@
 1. [x] 接入统一日志与 tracing
 2. [x] 接入 `request_id`
 3. [x] 接入统一错误处理中间件
-4. [ ] 接入 response envelope
+4. [x] 接入 response envelope
 5. [ ] 接入 `/healthz`
 
 当前 tracing 约定：
@@ -51,6 +51,12 @@
 2. 已经带 `content-type` 的业务错误响应不会被覆盖，避免抢走后续 response envelope 的职责。
 3. 统一错误日志会复用当前请求的 `request_id`，便于后续和响应头、envelope 元信息串联。
 
+当前 response envelope 约定：
+
+1. `RequestContext` 已记录 `request_id`、请求开始时间、默认 `operation` 与 envelope 协商结果。
+2. `json_success_body(...)` / `json_error_body(...)` 会根据 `x-genarrative-response-envelope` 自动在“裸数据 / 标准 envelope / legacy error + meta”之间切换。
+3. `meta.apiVersion`、`meta.requestId`、`meta.routeVersion`、`meta.operation`、`meta.latencyMs`、`meta.timestamp` 已按当前前端契约生成，响应头回写仍留给后续独立任务。
+
 ## 3. 边界约束
 
 1. `api-server` 负责 HTTP、SSE、Cookie、Header、路由与协议装配。