init

docs/07-api.md

@@ -51,7 +51,25 @@ POST /api/v1/outbounds/{outbound_no}/ship
 }
 ```
 
-分页数据使用统一格式（具体字段在 Phase 2 确定并固化到统一响应工具类中），所有列表接口保持一致。
+分页列表的 `data` 是当前页记录，分页信息放在同级 `meta`。所有列表接口都走 `ApiResponse::paginated()`。
+
+```json
+{
+    "success": true,
+    "message": "OK",
+    "data": [],
+    "meta": {
+        "current_page": 1,
+        "per_page": 20,
+        "total": 0,
+        "last_page": 1
+    }
+}
+```
+
+默认每页 20 条，最大 100 条。失败响应的 `errors` 没有内容时是 JSON 对象 `{}`，不是数组。
+
+`/api/*` 的异常由统一异常处理转成失败格式，不返回框架堆栈。响应头 `X-Request-Id` 贯穿本次请求；客户端传入的值仅在字母、数字、下划线、连字符且不超过 64 位时沿用。
 
 ## 内部 API（Python Service）