feat(handler): add app

2026-01-31 15:44:56 +08:00
parent 6b68a368f1
commit 4dc46659c9
25 changed files with 2516 additions and 14 deletions
--- a/docs/APP_API.md
+++ b/docs/APP_API.md
@@ -0,0 +1,129 @@
+# App 生命周期管理接口（平台级）
+
+本模块用于维护“允许的 App 注册表（apps）”，并提供应用上下线审批（含生效时间）与审计记录能力。
+
+## 权限与访问级别
+
+本模块所有接口均为平台级接口：
+- URL 前缀：`/platform`
+- 认证：`Authorization: Bearer <access_token>`
+- 权限：平台权限（系统角色 `SuperAdmin`）校验
+
+权限码：
+- `iam:app:read`：查询 apps 与审批单
+- `iam:app:write`：创建/更新 apps、提交上下线申请
+- `iam:app:approve`：审批上下线申请
+- `iam:app:delete`：删除（软删除）app
+
+## 通用响应结构
+
+成功：
+
+```json
+{ "code": 0, "message": "Success|Created", "data": {}, "trace_id": null }
+```
+
+错误（示例）：
+
+```json
+{ "code": 20003, "message": "Permission denied: iam:app:read", "details": null, "trace_id": null }
+```
+
+常见错误码：
+- 20000/20006：未认证（缺少 Authorization）
+- 20003：无权限（缺少平台权限码）
+- 30000：参数错误（格式/长度/取值非法）
+- 30002：资源不存在（app / request_id 不存在）
+- 30003：资源冲突（app_id 重复）
+
+## 1) 新增 App
+
+**POST** `/platform/apps`
+
+Body：
+- `id`：应用标识符（2~32，`[a-z0-9_-]`，建议小写，如 `cms`/`tms`）
+- `name`：名称（必填，<=100）
+- `description`：描述（可选）
+- `app_type`：类型（可选，默认 `generic`，建议小写短标识）
+- `owner`：负责人/团队（可选，<=100）
+
+示例：
+
+```bash
+curl -X POST "http://127.0.0.1:3000/platform/apps" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{ "id":"dms","name":"DMS","description":"Document","app_type":"product","owner":"team-a" }'
+```
+
+## 2) 查询 App 列表（分页/筛选/排序）
+
+**GET** `/platform/apps`
+
+Query：
+- `page`：默认 1
+- `page_size`：默认 20，范围 1..=200
+- `status`：可选（`active|disabled|deleted`）
+- `app_type`：可选
+- `created_from` / `created_to`：可选（RFC3339）
+- `sort_by`：`id|name|status|app_type|created_at|updated_at`（默认 `created_at`）
+- `sort_order`：`asc|desc`（默认 `desc`）
+
+## 3) 查询 App 详情
+
+**GET** `/platform/apps/{app_id}`
+
+## 4) 更新 App 基础信息
+
+**PATCH** `/platform/apps/{app_id}`
+
+Body（全部可选）：
+- `name`
+- `description`
+- `app_type`
+- `owner`
+
+## 5) 申请 App 上下线（审批 + 生效时间）
+
+**POST** `/platform/apps/{app_id}/status-change-requests`
+
+Body：
+- `to_status`：`active|disabled`
+- `effective_at`：可选（RFC3339；不填表示审批后立即生效）
+- `reason`：可选
+
+说明：
+- 新建审批单初始 `status=pending`
+- 审批通过后：
+  - 若 `effective_at` 为空或已到达，则自动应用并把审批单状态置为 `applied`
+  - 若 `effective_at` 在未来，则审批单状态为 `approved`，在后续列表/查询时会尝试自动应用到期变更
+
+## 6) 查询审批单列表
+
+**GET** `/platform/app-status-change-requests`
+
+Query：
+- `status`：可选（`pending|approved|applied|rejected`）
+- `page` / `page_size`
+
+## 7) 审批通过 / 驳回
+
+通过：
+
+**POST** `/platform/app-status-change-requests/{request_id}/approve`
+
+Body：
+- `effective_at`：可选（用于覆盖/补充生效时间）
+
+驳回：
+
+**POST** `/platform/app-status-change-requests/{request_id}/reject?reason=...`
+
+## 8) 删除 App（软删除）
+
+**DELETE** `/platform/apps/{app_id}`
+
+说明：
+- 软删除会将 `apps.status` 标记为 `deleted`
+- 若设置环境变量 `IAM_SENSITIVE_ACTION_TOKEN`，必须同时提供 Header：`X-Sensitive-Token: <token>`
+