baiyue-firstleg/iam/AGENTS.md

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；OVERSEAS_WAREHOUSE_PDA_OPERATOR 必须且只能绑定一个 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 不可变；按钮隐藏不能替代后端权限校验。
• 国内头程 PDA 使用 CN_FIRSTLEG_PDA_OPERATOR，海外仓 PDA 使用 OVERSEAS_WAREHOUSE_PDA_OPERATOR；两个角色互斥且权限不得交叉。只有海外角色可保存 overseasWarehouseId，且必须为单个有效海外仓；国内角色及其他角色必须为空。仓绑定、账号状态、角色权限或客户状态变化要在同一业务事务内推进安全事件 Outbox，不得依赖海外服务回查国内 IAM。
• IamTenantStatusChanged 是安全可用性快照，不暴露客户建档/审核流程状态：仅 IAM 业务状态 ACTIVE 发布 ACTIVE，PROFILE_REQUIRED、PENDING、REJECTED、DISABLED、ARCHIVED 及其他不可用状态统一发布 DISABLED。

全量验收导航

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