baiyue-firstleg/iam/AGENTS.md

IAM Service 模块指引

职责与边界

• Mapper 只由 BaiyueIamApplication.java 对 com.baiyue.iam 根包按 @Mapper 过滤扫描；新增或移动 Mapper 后从后端根运行 node scripts/mapper-scan-contract.mjs，不得增加子域扫描配置。
• 负责客户主档、成员、企业资料/审核、平台用户、角色权限、数据范围和授权快照。
• 账号凭据/Token 属于 auth/，文件内容属于 file/；资质登记只接收 File 的内部元数据调用。
• 修改用户可见层级、菜单权限、列表/详情只读语义或权限资源前，先读 ../../docs/平台客户层级与权限契约.md。
• 当前仅“平台—客户”两级：iam_tenant.id=0 为平台作用域，id>0 为客户主档；不得新增真实租户层。

模块入口

目标	入口
客户资料/审核与企业联系信息	controller/PlatformTenantController.java、service/TenantService.java；企业客户编号由 CustomerCodeRepository 在创建事务内从 00001 起分配固定五位数字，平台技术主体仍为 PLATFORM；公司联系电话/邮箱属于企业资料，不作为登录标识且不要求跨企业唯一；审核必填资质仅营业执照与统一社会信用代码，法人身份证选填
客户默认箱规与权重系数初始化、重试及补偿	service/CustomerDimensionRuleInitializationService.java、CustomerDimensionInitializationRelay.java、repository/CustomerDimensionInitializationRepository.java、client/CustomerDimensionRuleClient.java、model/CustomerDimensionInitializationTask.java；持久任务异步调用 Firstleg /internal/firstleg/v1/customer-dimension-configs/defaults，尺寸配置和默认权重系数规则均返回成功后才标记 READY
商户成员、登录手机号与个人资料	controller/MerchantTenantController.java、service/MemberService.java、service/PersonalProfileService.java、client/AuthAccountClient.java；成员手机号是可选登录标识，变更时同步 Auth、撤销该账号全部会话并审计，不与公司联系电话联动
平台用户与海外 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
持久化安全版本	service/SecurityVersionService.java、src/main/resources/db/security-version.sql；安全变更与 subject/customer 版本同事务提交，Auth 在线核对单 SQL 授权快照，无专用安全事件投影
消息中心/站内通知	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 不保存文件内容。
• 注册创建时可用同一手机号初始化公司联系电话与首位管理员登录手机号，但此后两者独立：企业资料更新不得探测 Auth 唯一性或修改任何成员账号；成员登录手机号修改必须检查 Auth 唯一性、同步账号并撤销该账号会话。企业审核不得把法人身份证恢复为必填资质。
• 客户建档只在 IAM 事务内落持久初始化意图，远端投递由带租约、退避和最大次数的 Relay 完成；只有状态为 READY 才能审核通过。注册补偿必须投递 COMPENSATE，不得在建档事务中同步依赖 Firstleg。
• 权限资源 code/type 不可变；按钮隐藏不能替代后端权限校验。
• 国内头程 PDA 使用 CN_FIRSTLEG_PDA_OPERATOR，海外仓 PDA 使用 OVERSEAS_WAREHOUSE_PDA_OPERATOR；两个角色互斥且权限不得交叉。只有海外角色可保存 overseasWarehouseId，且必须为单个有效海外仓；国内角色及其他角色必须为空。仓绑定、账号状态、成员角色与角色/权限状态变化必须在同一业务事务内推进持久化 subject 版本，客户状态推进 tenant 版本。SecurityVersionService 强制 MANDATORY 事务；不能用提交前 Redis 删除或 afterCommit 回调代替持久化版本。
• AuthorizationQueryMapper.findSnapshot 单条 SELECT 同时读取有效身份、角色权限、两类仓绑定、subject/tenant 版本，避免跨语句混合快照。客户 DISABLED/ARCHIVED、成员或用户停用/删除拒绝授权；建档审核状态继续允许登录完善资料，业务资格仍由对应服务校验。无角色/权限的有效主体保留空集合，不能因 LEFT JOIN 丢失身份。共享角色变更须枚举全部关联客户成员。

全量验收导航

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