feat: P1-P3 全栈集成 — 数据库基础 + DWS 扩展 + 小程序鉴权 + 工程化体系
## P1 数据库基础 - zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu - etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表 - 清理 assistant_abolish 残留数据 ## P2 ETL/DWS 扩展 - 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution) - 新增 assistant_order_contribution_task 任务及 RLS 视图 - member_consumption 增加充值字段、assistant_daily 增加处罚字段 - 更新 ODS/DWD/DWS 任务文档及业务规则文档 - 更新 consistency_checker、flow_runner、task_registry 等核心模块 ## P3 小程序鉴权系统 - 新增 xcx_auth 路由/schema（微信登录 + JWT） - 新增 wechat/role/matching/application 服务层 - zqyy_app 鉴权表迁移 + 角色权限种子数据 - auth/dependencies.py 支持小程序 JWT 鉴权 ## 文档与审计 - 新增 DOCUMENTATION-MAP 文档导航 - 新增 7 份 BD_Manual 数据库变更文档 - 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth） - 新增全栈集成审计记录、部署检查清单更新 - 新增 BACKLOG 路线图、FDW→Core 迁移计划 ## Kiro 工程化 - 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务） - 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan） - 新增 6 个 Hook（合规检查/会话日志/提交审计等） - 新增 doc-map steering 文件 ## 运维与测试 - 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告 - 新增属性测试：test_dws_contribution / test_auth_system - 清理过期 export 报告文件 - 更新 .gitignore 排除规则
This commit is contained in:
349
apps/backend/docs/API-REFERENCE.md
Normal file
349
apps/backend/docs/API-REFERENCE.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# 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=pending）
|
||||
- pending 用户获得受限令牌（`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": "..." }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 用于接收消息。
|
||||
|
||||
### POST `/api/member-birthday`
|
||||
助教手动补录会员生日。
|
||||
|
||||
### WebSocket `/ws/logs/{execution_id}`
|
||||
实时日志推送。连接后自动接收指定执行的日志流。
|
||||
|
||||
---
|
||||
|
||||
## 错误码约定
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
|-------------|------|
|
||||
| 200 | 成功 |
|
||||
| 201 | 创建成功 |
|
||||
| 400 | 请求参数错误 / SQL 执行错误 |
|
||||
| 401 | 未认证 / 令牌无效 / 受限令牌 |
|
||||
| 404 | 资源不存在 |
|
||||
| 408 | 查询超时 |
|
||||
| 409 | 状态冲突（如删除非 pending 任务） |
|
||||
| 422 | 请求体验证失败 |
|
||||
| 500 | 服务器内部错误 |
|
||||
Reference in New Issue
Block a user