# IAM Service 集成基线（接口清单 & 鉴权流程）

本文用于后续其他服务（如 CMS）集成时对齐以下能力基线：

- 租户隔离（Tenant Context / X-Tenant-ID / Token tenant_id 一致性校验）
- 用户注册/登录/刷新
- 基础租户管理
- 基于 JWT 的认证中间件
- RBAC 权限校验（服务端校验接口）

## 核心 Header/Token 约定

- `Authorization: Bearer <access_token>`
- `X-Tenant-ID: <tenant_uuid>`
  - 当请求携带 `Authorization` 时，若同时提供 `X-Tenant-ID`，必须与 JWT claims 内的 `tenant_id` 一致，否则返回 403（`tenant:mismatch`）。

## 接口清单（REST）

### 文档

- `GET /scalar`：Scalar UI

### Auth（公开）

- `POST /tenants/register`：创建租户（初始租户管理员账号由后续 `/auth/register` + 首用户 bootstrap 完成）
- `POST /auth/register`：用户注册（需要 `X-Tenant-ID`）
- `POST /auth/login`：用户登录（需要 `X-Tenant-ID`）
- `POST /auth/refresh`：刷新 access token（refresh token 一次性轮换）

### Tenant（需认证 + 权限）

- `GET /tenants/me`（`tenant:read`）
- `PATCH /tenants/me`（`tenant:write`）
- `DELETE /tenants/me`（`tenant:write`）
- `POST /tenants/me/status`（`tenant:write`）

### Me（需认证）

- `GET /me/permissions`：查询当前用户在当前租户下的权限码列表

### RBAC（供其他服务复用）

- `POST /authorize/check`：服务端校验“当前用户”是否具备指定权限码（用于各业务微服务鉴权复用）

### User（需认证 + 权限）

- `GET /users`
- `GET /users/{id}`
- `PATCH /users/{id}`
- `DELETE /users/{id}`
- `POST /users/me/password/reset`
- `POST /users/{id}/password/reset`
- `GET /users/{id}/roles`
- `PUT /users/{id}/roles`

### Role（需认证 + 权限）

- `GET /roles`
- `POST /roles`
- `GET /roles/{id}`
- `PATCH /roles/{id}`
- `DELETE /roles/{id}`
- `POST /roles/{id}/permissions/grant`
- `POST /roles/{id}/permissions/revoke`
- `POST /roles/{id}/users/grant`
- `POST /roles/{id}/users/revoke`

### Permission（需认证 + 权限）

- `GET /permissions`

### Platform（需认证；平台权限）

- `GET /platform/tenants/{tenant_id}/enabled-apps`
- `PUT /platform/tenants/{tenant_id}/enabled-apps`
- `GET /platform/apps`
- `POST /platform/apps`
- `GET /platform/apps/{app_id}`
- `PATCH /platform/apps/{app_id}`
- `DELETE /platform/apps/{app_id}`
- `POST /platform/apps/{app_id}/status-change-requests`
- `GET /platform/app-status-change-requests`
- `POST /platform/app-status-change-requests/{request_id}/approve`
- `POST /platform/app-status-change-requests/{request_id}/reject`

## 鉴权流程图（请求 → 认证 → 租户隔离 → 权限校验）

```mermaid
flowchart TD
  A[HTTP 请求进入] --> B[trace_http_request: 创建 http.request span]
  B --> C{是否公开路径?}
  C -- 是 --> H[进入 Handler]
  C -- 否 --> D[JWT 认证中间件: Authorization Bearer]
  D -->|验签/解析失败| E[返回 401]
  D -->|成功| F[注入 AuthContext<br/>tenant_id/user_id/roles/permissions<br/>并 record span 字段]
  F --> G[租户解析中间件: resolve_tenant]
  G -->|缺少 X-Tenant-ID 且 Token 无 tenant| I[返回 400]
  G -->|X-Tenant-ID 与 Token tenant 不一致| J[返回 403 tenant:mismatch]
  G -->|成功| K[注入 TenantId 到 extensions 并 record span tenant_id]
  K --> H
  H --> L{是否需要 RBAC 权限?}
  L -- 否 --> M[返回业务响应]
  L -- 是 --> N[调用 AuthorizationService::require_permission]
  N -->|无权限| O[返回 403 PermissionDenied]
  N -->|通过| M
```

## 集成建议（面向业务微服务）

- 业务服务应直接复用 iam-service 的 JWT 认证中间件与 Tenant 解析中间件，并在业务路由层按以下顺序挂载：
  - `trace_http_request`（生成请求 span）
  - `authenticate`（解析 token 并注入 user/tenant 字段到 span）
  - `resolve_tenant`（统一 TenantId 注入，并校验 X-Tenant-ID 与 token tenant 一致性）
- 权限校验禁止在业务侧实现一套 RBAC 聚合逻辑；应通过 `POST /authorize/check` 由 IAM 统一裁决。