docs(api): document response envelope and error codes

Add comprehensive documentation for the API response structure, including the standard envelope format, business code ranges, and client handling guidelines.

docs/response-codes.md

@@ -0,0 +1,116 @@
+# EZ-API Response Envelope 规范
+
+本文档定义响应信封结构及业务码表。HTTP 状态码保留用于传输层语义。
+
+## Envelope 结构
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { "user_id": 123, "name": "example" },
+  "trace_id": "req_abc123"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `code` | number | ✅ | 业务码，0=成功，非0=错误 |
+| `message` | string | ✅ | 成功时 `"success"`，错误时具体描述 |
+| `data` | object/array/null | ✅ | 成功时返回业务数据，错误时为 `null` |
+| `trace_id` | string | ✅ | 请求追踪 ID，复用 `X-Request-ID` 或自动生成 |
+| `details` | object/null | ❌ | 可选，错误时的补充信息（如字段级校验错误） |
+
+## 业务码表
+
+### 码段划分
+
+| 范围 | 类别 | 说明 |
+|------|------|------|
+| 0 | 成功 | 请求成功 |
+| 1000-1999 | 通用错误 | 参数错误、认证失败等通用场景 |
+| 4000-4999 | 客户端错误 | 业务级客户端错误 |
+| 5000-5999 | 服务端错误 | 服务端内部错误 |
+
+### 通用错误 (1xxx)
+
+| Code | 名称 | HTTP Status | 说明 |
+|------|------|-------------|------|
+| 1001 | invalid_param | 400 | 参数校验失败 |
+| 1002 | unauthorized | 401 | 未认证或认证失效 |
+| 1003 | forbidden | 403 | 无权限访问 |
+| 1004 | rate_limited | 429 | 请求频率超限 |
+
+### 客户端错误 (4xxx)
+
+| Code | 名称 | HTTP Status | 说明 |
+|------|------|-------------|------|
+| 4001 | resource_not_found | 404 | 资源不存在 |
+| 4002 | resource_conflict | 409 | 资源冲突（如重复创建） |
+| 4003 | invalid_state | 400 | 资源状态不允许此操作 |
+
+### 服务端错误 (5xxx)
+
+| Code | 名称 | HTTP Status | 说明 |
+|------|------|-------------|------|
+| 5001 | internal_error | 500 | 服务器内部错误 |
+| 5002 | service_unavailable | 503 | 服务暂不可用 |
+| 5003 | timeout | 504 | 请求超时 |
+
+## 示例
+
+### 成功响应
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "name": "example"
+  },
+  "trace_id": "req_abc123"
+}
+```
+
+### 错误响应（简单）
+
+```json
+{
+  "code": 4001,
+  "message": "master not found",
+  "data": null,
+  "trace_id": "req_abc123"
+}
+```
+
+### 错误响应（带 details）
+
+```json
+{
+  "code": 1001,
+  "message": "参数校验失败",
+  "data": null,
+  "details": {
+    "user_id": "必填",
+    "email": "格式错误"
+  },
+  "trace_id": "req_abc123"
+}
+```
+
+## 客户端处理指南
+
+1. **判断成功/失败**：检查 `code === 0`
+2. **获取业务数据**：成功时从 `data` 读取
+3. **展示错误信息**：使用 `message` 字段
+4. **排查问题**：记录/上报 `trace_id`
+5. **字段级错误**：检查 `details` 是否存在
+
+## 不包装的端点
+
+以下端点不使用 envelope 包装：
+- Swagger UI (`/swagger/*`)
+- 健康检查 (`/health`)
+- Metrics (`/debug/vars`, `/internal/metrics`)
+- CORS preflight