feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

apps/backend/docs/API-REFERENCE.md

@@ -3,6 +3,26 @@
 后端 API 基于 FastAPI 构建，所有端点均以 `/api/` 为前缀。  
 在线文档：启动后访问 `http://localhost:8000/docs`（Swagger UI）或 `/redoc`（ReDoc）。
 
+## 全局响应格式（RNS1.0）
+
+所有 JSON 成功响应（HTTP 2xx）自动包装为统一格式：
+
+```json
+{ "code": 0, "data": { ... } }
+```
+
+异常响应格式：
+
+```json
+{ "code": 401, "message": "未认证" }
+```
+
+规则：
+- `code=0` 表示成功，`data` 为业务数据
+- `code≠0` 表示错误，`code` 为 HTTP 状态码，`message` 为错误描述
+- SSE 流式端点（`text/event-stream`）和非 JSON 响应不包装，直接透传
+- 所有小程序 API 响应字段名为 camelCase（如 `userId`、`storeName`）
+
 ---
 
 ## 1. 管理后台认证 `/api/auth`
@@ -382,12 +402,39 @@ MVP 全链路验证端点，从 `test."xcx-test"` 表读取数据。
 { "reason": "放弃原因" }
 ```
 
-### POST `/api/xcx/tasks/{id}/cancel-abandon`
+### POST `/api/xcx/tasks/{id}/restore`
 取消放弃，恢复为活跃状态。
 
+### GET `/api/xcx/tasks/{id}`
+获取任务详情（TASK-2）。返回单个任务的完整信息，含服务记录、备注、AI 分析、维客线索。
+
+响应包含 `customerId` 字段，供前端跳转客户详情/对话页面使用。
+
 ---
 
-## 14. 小程序备注 `/api/xcx/notes`
+## 14. 小程序绩效 `/api/xcx/performance`
+
+所有端点需 JWT（approved 状态）。
+
+### GET `/api/xcx/performance`
+绩效概览（PERF-1）。返回指定月份的收入档位、DateGroup 分组记录、新客/常客列表。
+
+查询参数：
+- `month`：月份（格式 `YYYY-MM`，默认当月）
+
+响应包含：`currentTier`/`nextTier`/`upgradeHoursNeeded`/`upgradeBonus`（收入档位）、`thisMonthRecords`（DateGroup 分组）、`lastMonthIncome`、`incomeItems`（含 desc）、`newCustomers`/`regularCustomers`。
+
+### GET `/api/xcx/performance/records`
+绩效明细（PERF-2）。返回指定月份的服务记录明细，按日期分组，支持分页。
+
+查询参数：
+- `month`：月份（格式 `YYYY-MM`，默认当月）
+- `page`：页码（默认 1）
+- `page_size`：每页条数（默认 20）
+
+---
+
+## 15. 小程序备注 `/api/xcx/notes`
 
 所有端点需 JWT（approved 状态）。