IAM/iam-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
iam-service/docs/APP_API.md
shay7sev 4dc46659c9 feat(handler): add app
2026-01-31 15:44:56 +08:00

3.5 KiB
Raw Permalink Blame History

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

通用响应结构

成功：

{ "code": 0, "message": "Success|Created", "data": {}, "trace_id": null }

错误（示例）：

{ "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）

示例：

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>