134 lines
2.6 KiB
Markdown
134 lines
2.6 KiB
Markdown
# 租户管理 API 使用说明
|
||
|
||
## 通用约定
|
||
|
||
### 成功响应
|
||
|
||
所有成功响应使用 `common-telemetry` 的统一包装：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "Success|Created|Accepted",
|
||
"data": {},
|
||
"trace_id": null
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
错误响应由 `AppError` 统一转换为 JSON：
|
||
|
||
```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`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"name": "New Tenant Name",
|
||
"config": { "theme": { "primary": "#0ea5e9" } }
|
||
}
|
||
```
|
||
|
||
### 4) 变更当前租户状态（需要 tenant:write）
|
||
|
||
`POST /tenants/me/status`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{ "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`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"enabled_apps": ["cms", "tms"],
|
||
"expected_version": 0
|
||
}
|
||
```
|
||
|
||
说明：
|
||
- `expected_version` 用于并发控制；不传则按“最后写入覆盖”处理。
|
||
- 写入成功后会更新 `tenant_entitlements.version`，并将结果同步写入 `tenants.config.enabled_apps` 与 `tenants.config.enabled_apps_version`。
|