java-project/baiyue-firstleg
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4d8b31429ccf800ce364b5b047eb71e8e8a6e18b
baiyue-firstleg/iam/AGENTS.md
T
ouyangxq cd540f9b3e 优化
2026-08-04 14:15:55 +08:00

8.0 KiB
Raw Blame History

IAM Service 模块指引

职责边界

  • 商户侧资质公开接口在 IAM 中只提供查询；真实文件上传统一由 File 服务的 multipart 接口完成，IAM 仅接受 File 服务携带内部令牌提交的资质元数据。

  • 负责租户、用户、成员关系、企业资料与审核、角色、权限、数据范围、个人资料和授权快照。

  • 账号凭据与 Token 属于 auth/；资质文件内容属于 file/。IAM 只维护业务元数据和跨服务协作。

功能快速索引

功能 Controller Service / 数据入口
商户个人与企业资料 controller/MerchantTenantController.java PersonalProfileService.java、TenantService.java
商户成员增改、启停、重置密码 MerchantTenantController.java MemberService.java，账号协作看 client/AuthAccountClient.java
平台创建企业与入驻审核 controller/PlatformTenantController.java MerchantOnboardingService.java、TenantService.java
平台企业客户分页 controller/PlatformTenantController.java TenantService.pageMerchants、TenantRepository.pageMerchants；仅返回 tenant_type=MERCHANT
平台企业客户档案 controller/PlatformTenantController.java 一期维护销售负责人、账期、企业登记资料、联系微信、注册地址和内部备注；响应返回入驻与审批时间，不承载运单、财务或套餐统计
平台内部用户管理 controller/PlatformUserManagementController.java（/api/platform/v1/iam/users） PlatformUserManagementService.java、PlatformUserManagementDtos.java；服务端分页且强制 tenant_id=0，选项仅返回平台租户和 PLATFORM 角色
平台内部用户 controller/ProfileResourceController.java PlatformInternalUserService.java；账号创建、显示名、启停和重置密码经 AuthAccountClient 编排
企业地址与资质元数据 controller/ProfileResourceController.java ProfileResourceService.java、ProfileResourceRepository.java；平台上传登记由 InternalTenantController /platform-qualifications 接收 File 内部调用
角色、权限、成员角色、角色授权 controller/RbacController.java RbacService.java、RbacRepository.java
Auth/Order 内部授权与资格查询 InternalAuthorizationController.java、InternalTenantController.java AuthorizationSnapshotService.java、TenantGuard.java
当前登录成员有效权限 controller/AuthorizationController.java AuthorizationSnapshotService.currentPermissions；实时按有效成员、角色和权限资源计算，不依赖角色管理权限
DTO src/main/java/com/baiyue/iam/dto/ 按 Authorization、Member、Onboarding、Profile、Rbac、Tenant 分类
持久化 entity/、mapper/、repository/ 租户、成员、角色、权限、地址、资质与审核模型
数据库 src/main/resources/db/ 主结构 iam.sql，一期与 RBAC 增量脚本同目录
OpenAPI 与说明 src/main/resources/openapi/iam-v1.yaml、README-IAM.md 修改接口契约时同步更新
测试 src/test/java/com/baiyue/iam/ Controller 路由、授权快照、成员、资料、内部用户、平台资质和 RBAC 测试

修改与验证

  • /api/platform/v1/iam/users 是 Admin 后台内部用户入口，列表、创建、编辑、启停和重置密码都只能作用于 tenant_id=0 的平台账号；企业租户成员必须走商户成员边界。

  • 内部用户列表使用后端分页，分页查询必须在仓储层显式携带 tenant_id=0；创建要求 platform:user:create 与 platform:user:grant-role，角色只能属于平台租户且 appCode=PLATFORM。受保护的平台管理员不得被降权、停用或自停用。

  • /users 不提供跨租户移动能力；企业成员的维护由商户成员接口负责，不得通过内部用户接口修改 Auth scope。

  • 平台客户档案维护使用 PlatformTenantController 的列表、详情、新建、编辑、启停接口；详情和维护仅接受 tenant_type=MERCHANT。PENDING/REJECTED 只能由审核流程变更，不得由启停接口绕过。

  • 平台代客户上传资质的公开 multipart 入口在 File 服务；IAM 的 /internal/iam/platform-qualifications 只登记元数据。当前仅 PROFILE_REQUIRED/REJECTED 可上传，同类型重复需显式 replace=true；替换时旧记录标记 REJECTED 并把旧 documentUrl 返回 File 清理。

  • 平台资质登记在事务内通过 ProfileResourceRepository.findQualificationsForUpdate 锁定目标租户现有资质，避免并发上传或替换产生多个有效同类型记录；该查询不得改回普通无锁列表。

  • 企业送审和审核通过只要求 BUSINESS_LICENSE、LEGAL_PERSON_ID 两类必填资质均为 PENDING；FREIGHT_FORWARDER_CERTIFICATE 与 BANK_ACCOUNT_LICENSE 为选填，已上传时仍随审核统一处理。审核由 TenantService.review() 同事务更新审核单、租户和所有 PENDING 资质，行锁负责并发防重。

  • 平台客户列表使用 platform:customer:list 并脱敏电话、邮箱；完整详情、平台地址和平台资质只读查询统一使用独立的 platform:customer:view，不得复用 platform:customer:review。

  • 权限资源的 code/type 不可变；只有 built_in=0 的自定义资源可编辑、启停或删除，删除前必须无子节点且无角色绑定。

  • tenant_id 是商户数据隔离核心；平台端与商户端访问域、角色和权限不可混用。

  • 按钮隐藏不能代替后端 permission code / permissionIds 校验；权限快照变化需同步检查 Auth 与 Gateway Claim 消费。

  • /api/{app}/v1/iam/authorization/permissions 是登录初始化接口，只校验已认证应用域和有效成员身份；禁止增加 role:list 等业务权限前置条件。

  • 平台企业客户分页仅查询商户租户；分页参数类型错误使用 body code A0400，Bean Validation 范围或状态约束错误使用 A0422，两者普通业务响应均为 HTTP 200。

  • 成员账号操作跨 IAM/Auth，保持幂等与补偿；资质上传跨 IAM/File，IAM 不保存文件内容。

  • 平台内部用户的公开主键是 membershipId；列表必须回显 roleIds，密码只允许通过 DTO 转交 Auth，禁止进入 IAM 实体、日志或审计快照。

  • 平台内部用户角色分配使用 PUT /api/platform/v1/iam/internal-users/{membershipId}/roles，仅允许平台租户下已启用的平台角色；空 roleIds 表示清空。

  • 商户成员新增、编辑采用字段级授权：基础资料分别校验 merchant:member:create、merchant:member:edit；创建时非空角色、编辑时角色集合发生任何变化（含空数组清空）还必须校验 merchant:member:grant-role。详情和列表实时回显当前 roleIds，比较和写入均限定当前租户。

  • 企业 ACTIVE 只表示平台审核已通过；下单资格还必须营业执照和法人身份证两类必填资质均为 APPROVED。任一必填资质缺失、驳回、已替换或过期都必须由服务端阻止提交订单；选填资质不影响下单资格。

  • SQL 增量保持可重复部署顺序，修改 Entity 时同步检查 Mapper、Repository、DTO 与种子数据。phase1-platform-master-data-and-permission-management.sql 必须在 phase1-admin-rbac.sql 和 rbac-role-management-v2.sql 之后执行；它标记既有系统资源并补齐平台客户、快递公司、往来单位与权限资源管理权限。

  • 存量库新增一期客户档案字段时执行 phase1-customer-profile.sql；该脚本只扩展 iam_tenant，可重复执行，不得把运单数、财务金额、套餐计费、代客登录或物理删除能力并入 IAM。

  • deploy/scripts/initialize-test-databases.sh 的 IAM 客户档案和 Warehouse 主数据脚本顺序必须与当前文件保持一致；测试环境正式增量仍以 ../deploy/sql/README.md 指定的统一迁移为准。

  • 从父目录运行 mvn -pl iam -am test，再按影响执行一期认证/IAM API 回归。

Reference in New Issue View Git Blame Copy Permalink