49 lines
4.8 KiB
Markdown
49 lines
4.8 KiB
Markdown
# IAM 一期交付说明 / IAM Phase 1 Delivery
|
||
|
||
## 数据库归属 / Database ownership
|
||
|
||
全部表位于 `baiyue_iam`，由 `iam-service` 独占连接。`auth-service` 只访问 `baiyue_auth.auth_account` 与 `auth_refresh_token`。`iam_user.auth_user_id` 是跨库逻辑 ID，禁止建立跨库外键。商户数据通过 `tenant_id` 强制隔离；平台租户使用 `tenant_id=0`，权限通过 `app_code=PLATFORM`，商户端使用 `app_code=MERCHANT`。
|
||
|
||
All tables belong to `baiyue_iam`, accessed only by `iam-service`. `auth-service` owns credentials and tokens in `baiyue_auth`. `iam_user.auth_user_id` is a logical cross-database reference; no cross-database foreign keys are used. Every merchant query must constrain `tenant_id`. Platform scope uses `tenant_id=0` and `app_code=PLATFORM`; merchant scope uses `app_code=MERCHANT`.
|
||
|
||
## 代码落位 / Code placement
|
||
|
||
将 `src/main/java` 下的包合并到 `D:/baiyue/iam/src/main/java`；SQL 执行 `db/baiyue_iam.sql`。代码基于 Java 17、Spring Boot 3.2、MyBatis-Plus 3.5.7，并返回现有 `ApiResponse`。
|
||
|
||
Merge the packages under `src/main/java` into `D:/baiyue/iam/src/main/java`; execute `db/baiyue_iam.sql`. The skeleton targets Java 17, Spring Boot 3.2 and MyBatis-Plus 3.5.7, returning the existing `ApiResponse` envelope.
|
||
|
||
## 接口清单 / API catalogue
|
||
|
||
| Method | Path | App | Purpose / 用途 |
|
||
|---|---|---|---|
|
||
| POST | `/api/platform/v1/iam/tenants` | PLATFORM | Submit enterprise registration / 企业注册 |
|
||
| GET | `/api/platform/v1/iam/reviews` | PLATFORM | List pending reviews / 待审核列表 |
|
||
| POST | `/api/platform/v1/iam/reviews/{id}/approve` | PLATFORM | Approve registration / 审核通过 |
|
||
| POST | `/api/platform/v1/iam/reviews/{id}/reject` | PLATFORM | Reject registration / 审核驳回 |
|
||
| GET/POST | `/api/platform/v1/iam/users` | PLATFORM | Unified platform and merchant user administration / 统一用户管理 |
|
||
| GET | `/api/platform/v1/iam/users/options` | PLATFORM | Tenant and role options / 用户租户与角色选项 |
|
||
| PUT | `/api/platform/v1/iam/users/{membershipId}` | PLATFORM | Edit profile, tenant and roles / 编辑用户资料、租户和角色 |
|
||
| PUT | `/api/platform/v1/iam/users/{membershipId}/status` | PLATFORM | Enable or disable user / 启停用户 |
|
||
| PUT | `/api/platform/v1/iam/users/{membershipId}/password` | PLATFORM | Reset password / 重置密码 |
|
||
| GET/PUT | `/api/merchant/v1/iam/tenant/profile` | MERCHANT | View/update own profile / 企业资料 |
|
||
| GET/POST | `/api/merchant/v1/iam/members` | MERCHANT | List/add members / 成员 |
|
||
| GET/POST | `/api/{app}/v1/iam/roles` | PLATFORM/MERCHANT | Role management / 角色 |
|
||
| GET | `/api/{app}/v1/iam/authorization/permissions` | PLATFORM/MERCHANT | Current user's active permission codes / 当前用户有效权限编码 |
|
||
| GET/POST | `/api/{app}/v1/iam/permissions` | PLATFORM/MERCHANT | Permission tree / 权限树 |
|
||
|
||
## 审核通过初始化扩展
|
||
|
||
企业审核通过后的默认数据统一通过 `TenantApprovalInitializer` 扩展链初始化，`TenantService` 不直接依赖具体初始化事项。客户端自主注册时，注册账号已经创建 OWNER 成员并绑定 `MERCHANT_OWNER`，审核通过后继续沿用该账号；只有 Admin 平台代建且没有 OWNER 的企业，才由 `TenantAdministratorProvisioningService` 创建管理员账号。后续规则、费用方案或其他默认角色应各自新增初始化器，并通过 `@Order` 声明依赖顺序。
|
||
|
||
初始化器及其补偿必须幂等。任一初始化器失败时，协调器按完成顺序的逆序执行补偿；IAM 本地事务最终回滚时也会触发同一补偿链。初始化器名称必须非空且全局唯一，初始密码等敏感结果只能通过审核响应一次性返回，不得持久化到 IAM 或写入日志。
|
||
|
||
管理员初始化会验证既有 OWNER 成员、IAM 用户及 Auth 账号均处于可用状态且租户、成员和应用范围一致。历史数据只有 OWNER/IAM 身份而缺少 Auth 账号时，复用原身份补建认证账号；停用或范围冲突的数据会阻止审核通过，避免激活后没有可登录管理员。部署前必须执行 `phase1-onboarding.sql`；测试环境统一执行 `deploy/sql/2026-07-31一期回归测试环境增量迁移.sql`，确保全局 `MERCHANT_OWNER` 模板及权限完整。
|
||
|
||
OpenAPI is synchronized in `openapi/iam-v1.yaml`.
|
||
|
||
## 商户成员角色字段级授权
|
||
|
||
- 新增、编辑成员基础资料分别需要 `merchant:member:create`、`merchant:member:edit`。
|
||
- 新增请求的 `roleIds` 非空，或编辑请求的完整目标角色集合与当前集合不同时，还必须具有 `merchant:member:grant-role`。
|
||
- `roleIds: []` 表示清空角色，不能绕过授权；编辑时角色集合未变化则不额外拒绝。成员详情和列表均实时返回当前租户下的 `roleIds`。
|