# 租户管理 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`。