# 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>`