130 lines
3.5 KiB
Markdown
130 lines
3.5 KiB
Markdown
# 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>`
|
||
|