# IAM Service 模块指引

## 职责与边界

- 负责客户主档、成员、企业资料/审核、平台用户、角色权限、数据范围和授权快照。
- 账号凭据/Token 属于 `auth/`，文件内容属于 `file/`；资质登记只接收 File 的内部元数据调用。
- 修改用户可见层级、菜单权限、列表/详情只读语义或权限资源前，先读 `../../docs/平台客户层级与权限契约.md`。
- 当前仅“平台—客户”两级：`iam_tenant.id=0` 为平台作用域，`id>0` 为客户主档；不得新增真实租户层。

## 模块入口

| 目标 | 入口 |
|---|---|
| 客户资料/审核 | `controller/PlatformTenantController.java`、`service/TenantService.java` |
| 客户默认尺寸初始化、重试与补偿 | `service/CustomerDimensionRuleInitializationService.java`、`CustomerDimensionInitializationRelay.java`、`repository/CustomerDimensionInitializationRepository.java`、`client/CustomerDimensionRuleClient.java`、`model/CustomerDimensionInitializationTask.java`；持久任务异步调用 Firstleg `/internal/firstleg/v1/customer-dimension-configs/defaults` |
| 商户成员与个人资料 | `controller/MerchantTenantController.java`、`service/MemberService.java`、`service/PersonalProfileService.java` |
| 平台用户与海外 PDA 仓绑定 | `controller/PlatformUserManagementController.java`、`service/PlatformUserManagementService.java`、`dto/PlatformUserManagementDtos.java`、`entity/IamMembership.java`；`WAREHOUSE_PICKER` 必须且只能绑定一个 `overseasWarehouseId` |
| 角色/权限/RBAC | `controller/RbacController.java`、`service/RbacService.java` |
| 授权快照/内部资格 | `controller/AuthorizationController.java`、`InternalAuthorizationController.java`、`service/AuthorizationSnapshotService.java` |
| 海外安全状态事件 Outbox | `service/SecurityEventOutboxService.java`、`SecurityEventOutboxRelay.java`、`client/SecurityEventBridgeClient.java`；账号、授权或客户状态变更经版本化事件投影到 `../lastleg-service/security/` |
| 消息中心/站内通知 | `notification/controller/NotificationInboxController.java`、`notification/controller/PlatformNotificationController.java`、`notification/service/NotificationService.java`；模板、任务、收件箱及事件消费均在 `notification/` |
| File 资质元数据协作 | `controller/InternalTenantController.java`、`service/ProfileResourceService.java`、`client/AuthAccountClient.java` |
| DTO/持久化 | `dto/`、`entity/`、`mapper/`、`repository/` |
| SQL/OpenAPI | IAM 主契约 `src/main/resources/openapi/iam-v1.yaml`；消息契约 `src/main/resources/openapi/notification-v1.yaml`；消息脚本 `src/main/resources/db/notification-center.sql`，其余数据库脚本在同目录 |
| 测试/验证 | `src/test/java/com/baiyue/iam/`；`mvn -pl iam -am test` |

## 修改约束

- 所有客户查询按 `tenant_id` 过滤；平台用户只能 `tenant_id=0`。必填资质审核通过才具备下单资格。
- 成员/账号跨 IAM/Auth 保持幂等补偿；资质跨 IAM/File 不保存文件内容。
- 客户建档只在 IAM 事务内落持久初始化意图，远端投递由带租约、退避和最大次数的 Relay 完成；只有状态为 `READY` 才能审核通过。注册补偿必须投递 `COMPENSATE`，不得在建档事务中同步依赖 Firstleg。
- 权限资源 code/type 不可变；按钮隐藏不能替代后端权限校验。
- 只有平台 `WAREHOUSE_PICKER` 可保存 `overseasWarehouseId`，且必须为单个有效海外仓；非拣货员必须为空。仓绑定、账号状态、角色权限或客户状态变化要在同一业务事务内推进安全事件 Outbox，不得依赖海外服务回查国内 IAM。
- `IamTenantStatusChanged` 是安全可用性快照，不暴露客户建档/审核流程状态：仅 IAM 业务状态 `ACTIVE` 发布 `ACTIVE`，`PROFILE_REQUIRED`、`PENDING`、`REJECTED`、`DISABLED`、`ARCHIVED` 及其他不可用状态统一发布 `DISABLED`。

## 全量验收导航

本模块承载客户建档审核、平台用户/RBAC、企业资料、消息中心及三期作业角色权限；按本次验收链路读取对应阶段/专题文档和权限契约，核对授权快照、客户隔离、权限码和消息收件箱，不因历史阶段划分排除协作场景。