baiyue-firstleg/iam/README-IAM.md

# 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 > 0` 按客户强制隔离；平台账号、平台 RBAC 和平台公共资源使用技术作用域 `tenant_id=0`，平台身份使用 `app_code=PLATFORM`，商户端使用 `app_code=MERCHANT`。`tenant` 相关表、类、路径和字段为历史兼容命名，不表示已经存在真实租户层。

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. The current product has only platform and customer levels. Every merchant query must constrain the compatibility field `tenant_id`, which currently stores the customer ID. Platform identities, RBAC, and public warehouse master data use technical scope `tenant_id=0`; platform identity also uses `app_code=PLATFORM`, while merchant scope uses `app_code=MERCHANT`. Historical tenant-named tables, types, paths, and fields do not establish a real tenant layer.

## 代码落位 / 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 | Paginated platform-internal user administration (`tenant_id=0`) / 平台内部用户分页管理 |
| GET | `/api/platform/v1/iam/users/options` | PLATFORM | Platform technical scope and PLATFORM role options / 平台技术作用域与平台角色选项 |
| PUT | `/api/platform/v1/iam/users/{membershipId}` | PLATFORM | Edit internal-user profile 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`。