iam-service/docs/TENANT_API.md

租户管理 API 使用说明

通用约定

成功响应

所有成功响应使用 common-telemetry 的统一包装：

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

错误响应

错误响应由 AppError 统一转换为 JSON：

{
  "code": 30000,
  "message": "Invalid request parameters: ...",
  "details": "...",
  "trace_id": null
}

常见错误码（节选，来自 common-telemetry）：

• 20006：缺少认证 Header（Authorization）
• 20003：无权限（403）
• 30000：请求参数错误（400）
• 30002：资源不存在（404）
• 10001：数据库错误（500）

认证与租户上下文

• 受保护接口需要：
  • Authorization: Bearer <access_token>
• 租户上下文优先来自 Token 的 tenant_id claim
• 兼容 X-Tenant-ID：
  • 如果同时传 X-Tenant-ID 与 Token，则必须一致，否则返回 403

接口列表

1) 租户注册（公共）

POST /tenants/register

请求体：

{
  "name": "Tenant A",
  "config": {
    "theme": { "primary": "#1d4ed8" },
    "password_policy": { "min_len": 12 }
  }
}

响应：TenantResponse

2) 获取当前租户信息（需要 tenant:read）

GET /tenants/me

请求头：

• Authorization: Bearer <access_token>
• X-Tenant-ID: <uuid>（可选）

3) 更新当前租户信息（需要 tenant:write）

PATCH /tenants/me

请求体：

{
  "name": "New Tenant Name",
  "config": { "theme": { "primary": "#0ea5e9" } }
}

4) 变更当前租户状态（需要 tenant:write）

POST /tenants/me/status

请求体：

{ "status": "active|disabled|suspended" }

5) 删除当前租户（需要 tenant:write）

DELETE /tenants/me

说明：当前实现为物理删除。生产建议改为软删除并触发异步数据清理流程。

平台级接口（超级管理员）

以下接口用于管理“租户已开通应用（enabled_apps）”，仅允许拥有平台级权限的用户调用：

• iam:tenant:enabled_apps:read
• iam:tenant:enabled_apps:write

6) 获取租户已开通应用

GET /platform/tenants/{tenant_id}/enabled-apps

响应：TenantEnabledAppsResponse

7) 更新租户已开通应用（全量覆盖，幂等）

PUT /platform/tenants/{tenant_id}/enabled-apps

请求体：

{
  "enabled_apps": ["cms", "tms"],
  "expected_version": 0
}

说明：

• expected_version 用于并发控制；不传则按“最后写入覆盖”处理。
• 写入成功后会更新 tenant_entitlements.version，并将结果同步写入 tenants.config.enabled_apps 与 tenants.config.enabled_apps_version。