# API 参考手册

后端 API 基于 FastAPI 构建，所有端点均以 `/api/` 为前缀。  
在线文档：启动后访问 `http://localhost:8000/docs`（Swagger UI）或 `/redoc`（ReDoc）。

---

## 1. 管理后台认证 `/api/auth`

### POST `/api/auth/login`
管理后台用户名密码登录。

请求体：
```json
{ "username": "admin", "password": "..." }
```
响应：
```json
{ "access_token": "...", "refresh_token": "...", "token_type": "bearer" }
```

### POST `/api/auth/refresh`
刷新访问令牌。

请求体：
```json
{ "refresh_token": "..." }
```

---

## 2. 小程序认证 `/api/xcx-auth`

小程序用户的完整生命周期：微信登录 → 提交申请 → 管理员审批 → 正式使用。

### POST `/api/xcx-auth/login`
微信登录。用 `wx.login()` 获取的 code 换取 JWT。

请求体：
```json
{ "code": "微信临时登录凭证" }
```
响应：
```json
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "bearer",
  "user_status": "pending | approved | rejected | disabled",
  "user_id": 1
}
```
说明：
- 首次登录自动创建 `auth.users` 记录（status=new），前端引导至申请页
- new/pending/rejected 用户获得受限令牌（`limited=True`），仅可访问申请相关端点
- approved 用户获得完整令牌，包含 `site_id` 和 `roles`

### POST `/api/xcx-auth/apply`
提交入驻申请。需受限令牌或完整令牌。

请求体：
```json
{
  "site_code": "AB123",
  "applied_role_text": "助教",
  "phone": "13800138000",
  "employee_number": "E001",
  "nickname": "张三"
}
```
说明：
- `site_code` 格式：2 字母 + 3 数字（如 `AB123`），映射到 `auth.site_code_mapping`
- 后端自动进行人员匹配（`matching.py`），在 ETL 库中查找助教/员工记录

### GET `/api/xcx-auth/status`
查询当前用户状态和申请记录。需受限令牌或完整令牌。

响应：
```json
{
  "user_id": 1,
  "status": "approved",
  "nickname": "张三",
  "applications": [
    {
      "id": 1,
      "site_code": "AB123",
      "applied_role_text": "助教",
      "status": "approved",
      "review_note": null,
      "created_at": "2026-02-25T10:00:00",
      "reviewed_at": "2026-02-25T11:00:00"
    }
  ]
}
```

### GET `/api/xcx-auth/sites`
获取当前用户关联的门店列表。需完整令牌。

### POST `/api/xcx-auth/switch-site`
切换当前门店，返回新的令牌对。需完整令牌。

请求体：
```json
{ "site_id": 2 }
```

### POST `/api/xcx-auth/refresh`
刷新令牌。

请求体：
```json
{ "refresh_token": "..." }
```

### POST `/api/xcx-auth/dev-login`
开发模式 mock 登录（仅 `WX_DEV_MODE=true` 时注册）。

请求体：
```json
{ "openid": "模拟openid", "status": "approved" }
```
说明：
- `status` 可选，为空时保留已有用户当前状态，新用户默认 `new`
- 仅开发/测试环境可用

---

## 3. 任务配置 `/api/tasks`

所有端点需 JWT 认证。

### GET `/api/tasks/registry`
按业务域分组的 ETL 任务列表。

响应示例：
```json
{
  "groups": {
    "会员": [
      {
        "code": "DWD_LOAD_FROM_ODS",
        "name": "ODS → DWD 加载",
        "domain": "会员",
        "layer": "DWD",
        "requires_window": true,
        "is_ods": false,
        "is_dimension": false,
        "default_enabled": true,
        "is_common": true
      }
    ]
  }
}
```

### GET `/api/tasks/dwd-tables`
按业务域分组的 DWD 表定义。

### GET `/api/tasks/flows`
返回 7 种 Flow 定义和 4 种处理模式。

Flow 列表：
| ID | 名称 | 层级 |
|----|------|------|
| `api_ods` | API → ODS | ODS |
| `api_ods_dwd` | API → ODS → DWD | ODS, DWD |
| `api_full` | API → ODS → DWD → DWS → INDEX | ODS, DWD, DWS, INDEX |
| `ods_dwd` | ODS → DWD | DWD |
| `dwd_dws` | DWD → DWS汇总 | DWS |
| `dwd_dws_index` | DWD → DWS → INDEX | DWS, INDEX |
| `dwd_index` | DWD → DWS指数 | INDEX |

处理模式：
| ID | 名称 | 说明 |
|----|------|------|
| `increment_only` | 仅增量处理 | 只处理新增和变更的数据 |
| `verify_only` | 仅校验修复 | 校验现有数据并修复不一致 |
| `increment_verify` | 增量 + 校验修复 | 先增量处理，再校验并修复 |
| `full_window` | 全窗口处理 | 用 API 返回数据的实际时间范围处理全部层 |

### POST `/api/tasks/validate`
验证任务配置并返回 CLI 命令预览。`store_id` 从 JWT 自动注入。

### GET `/api/tasks/sync-check`
对比后端硬编码任务列表与 ETL 真实注册表，返回差异。

---

## 4. 任务执行 `/api/execution`

所有端点需 JWT 认证，`site_id` 从 JWT 提取。

### POST `/api/execution/run`
直接执行任务（不经过队列）。异步启动 ETL CLI 子进程。

请求体：`TaskConfigSchema`（flow、tasks、window 等）

响应：
```json
{ "execution_id": "uuid", "message": "任务已提交执行" }
```

### GET `/api/execution/queue`
获取当前门店的待执行队列。

### POST `/api/execution/queue`
将任务配置添加到执行队列。

### PUT `/api/execution/queue/reorder`
调整队列中任务的执行顺序。

### DELETE `/api/execution/queue/{task_id}`
从队列中删除待执行任务（仅 pending 状态）。

### POST `/api/execution/{execution_id}/cancel`
取消正在执行的任务。

### GET `/api/execution/history`
执行历史记录（按 `started_at` 降序，默认 50 条，最多 200 条）。

### GET `/api/execution/{execution_id}/logs`
获取指定执行的完整日志。优先从内存缓冲区读取（执行中），否则从数据库读取（已完成）。

---

## 5. 调度管理 `/api/schedules`

所有端点需 JWT 认证。

### GET `/api/schedules`
列出当前门店的所有调度任务。

### POST `/api/schedules`
创建调度任务，自动计算 `next_run_at`。

### PUT `/api/schedules/{schedule_id}`
更新调度任务（部分更新，仅更新请求中提供的字段）。

### DELETE `/api/schedules/{schedule_id}`
删除调度任务。

### PATCH `/api/schedules/{schedule_id}/toggle`
切换启用/禁用状态。禁用时 `next_run_at` 置 NULL；启用时重新计算。

---

## 6. 数据库查看器 `/api/db`

所有端点需 JWT 认证。使用 ETL 只读连接 + RLS 门店隔离。

### GET `/api/db/schemas`
返回 ETL 数据库中的 Schema 列表。

### GET `/api/db/schemas/{name}/tables`
返回指定 Schema 下所有表的名称和行数统计。

### GET `/api/db/tables/{schema}/{table}/columns`
返回指定表的列定义（列名、数据类型、是否可空、默认值）。

### POST `/api/db/query`
只读 SQL 执行。

安全措施：
- 拦截写操作关键词（INSERT / UPDATE / DELETE / DROP / TRUNCATE）
- 返回行数上限 1000 行
- 查询超时 30 秒
- 连接级 `read_only` 保护

请求体：
```json
{ "sql": "SELECT * FROM dwd.member_info LIMIT 10" }
```

---

## 7. ETL 状态 `/api/etl-status`

### GET `/api/etl-status/cursors`
返回各 ODS 表的最新数据游标（查询 `meta.etl_cursor`）。

### GET `/api/etl-status/recent-runs`
返回最近 50 条任务执行记录。

---

## 8. 环境配置 `/api/env-config`

### GET `/api/env-config`
读取根 `.env` 文件内容（敏感值脱敏显示）。

### PUT `/api/env-config`
更新 `.env` 文件中的配置项。

---

## 9. 运维面板 `/api/ops`

### GET `/api/ops/system`
服务器系统资源概况（CPU、内存、磁盘、启动时间）。

### GET `/api/ops/services`
所有环境（test/prod）的服务运行状态（PID、端口、内存、CPU、运行时长）。

### POST `/api/ops/services/{env}/start`
启动指定环境的后端服务。

### POST `/api/ops/services/{env}/stop`
停止指定环境的后端服务。

### POST `/api/ops/services/{env}/restart`
重启指定环境的后端服务。

### GET `/api/ops/git`
所有环境的 Git 状态（分支、最新提交、是否有本地修改）。

### POST `/api/ops/git/{env}/pull`
对指定环境执行 `git pull --ff-only`。

### POST `/api/ops/git/{env}/sync-deps`
对指定环境执行 `uv sync --all-packages`。

### GET `/api/ops/env-file/{env}`
读取指定环境的 `.env` 文件（敏感值脱敏）。

---

## 10. 其他端点

### GET `/health`
健康检查。返回 `{"status": "ok"}`。

### GET `/api/xcx-test`
MVP 全链路验证端点，从 `test."xcx-test"` 表读取数据。

### GET/POST `/api/wx-callback`
微信消息推送回调。GET 用于签名验证，POST 用于接收消息。

---

## 11. 管理端申请审核 `/api/admin/applications`

### GET `/api/admin/applications`
获取待审核申请列表。需管理后台 JWT。

### POST `/api/admin/applications/{id}/approve`
批准申请。

### POST `/api/admin/applications/{id}/reject`
拒绝申请。

---

## 12. 营业日配置 `/api/business-day`

### GET `/api/business-day/config`
获取营业日分割点配置（`BUSINESS_DAY_START_HOUR`）。

---

## 13. 小程序任务 `/api/xcx/tasks`

所有端点需 JWT（approved 状态）。

### GET `/api/xcx/tasks`
获取当前助教的活跃任务列表。

响应：`TaskListItem[]`

### POST `/api/xcx/tasks/{id}/pin`
置顶任务。

### POST `/api/xcx/tasks/{id}/unpin`
取消置顶。

### POST `/api/xcx/tasks/{id}/abandon`
放弃任务（需填写原因）。

请求体：
```json
{ "reason": "放弃原因" }
```

### POST `/api/xcx/tasks/{id}/cancel-abandon`
取消放弃，恢复为活跃状态。

---

## 14. 小程序备注 `/api/xcx/notes`

所有端点需 JWT（approved 状态）。

### POST `/api/xcx/notes`
创建备注（含星星评分，可选关联任务）。

请求体：
```json
{
  "target_type": "member",
  "target_id": 1,
  "content": "备注内容",
  "task_id": null,
  "rating_service_willingness": 4,
  "rating_revisit_likelihood": 3
}
```

### GET `/api/xcx/notes`
查询某目标的备注列表（按创建时间倒序）。

查询参数：
- `target_type`：目标类型（默认 `member`）
- `target_id`：目标 ID（必填）

### DELETE `/api/xcx/notes/{id}`
删除备注（验证归属后硬删除）。

---

## 15. 维客线索 `/api/member-retention-clue`

替代原 `member-birthday` 端点，提供维客线索管理能力。

### WebSocket `/ws/logs/{execution_id}`
实时日志推送。连接后自动接收指定执行的日志流。

---

## 错误码约定

| HTTP 状态码 | 含义 |
|-------------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 / SQL 执行错误 |
| 401 | 未认证 / 令牌无效 / 受限令牌 |
| 404 | 资源不存在 |
| 408 | 查询超时 |
| 409 | 状态冲突（如删除非 pending 任务） |
| 422 | 请求体验证失败 |
| 500 | 服务器内部错误 |