62 lines
9.5 KiB
Markdown
62 lines
9.5 KiB
Markdown
# IAM Service 模块指引
|
||
|
||
## 职责边界
|
||
|
||
- 商户侧资质公开接口在 IAM 中只提供查询；真实文件上传统一由 File 服务的 multipart 接口完成，IAM 仅接受 File 服务携带内部令牌提交的资质元数据。
|
||
|
||
- 负责客户主档、用户、企业成员关系、企业资料与审核、角色、权限、数据范围、个人资料和授权快照；`iam_tenant`、`Tenant*` 及 `/tenants` 是历史兼容命名。
|
||
- 账号凭据与 Token 属于 `auth/`；资质文件内容属于 `file/`。IAM 只维护业务元数据和跨服务协作。
|
||
- 当前只实现“平台—客户”两级：`iam_tenant.id > 0` 的 `MERCHANT` 记录直接作为客户主档，相关 `tenant_id` 是客户隔离兼容字段；`iam_tenant.id = 0` 是平台账号、平台 RBAC 和平台公共资源技术作用域。不得由本模块提前引入真实租户、租户选择或租户级 RBAC。
|
||
|
||
## 功能快速索引
|
||
|
||
| 功能 | 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/` | 客户主档、成员、角色、权限、地址、资质与审核模型；表字段保留 `tenant` 兼容命名 |
|
||
| 数据库 | `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 > 0` 是当前客户数据隔离核心；平台端与商户端访问域、角色和权限不可混用，`tenant_id=0` 只表示平台技术作用域。
|
||
- 按钮隐藏不能代替后端 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 回归。
|
||
|
||
## 分期快速索引
|
||
|
||
- 一期入口：`PlatformTenantController`（客户建档/审核）、`PlatformUserManagementController`/`RbacController`（平台用户与 RBAC）、`ProfileResourceController`（企业资料）；先读 `../../docs/一期/README.md` → `../../docs/一期/一期开发进度表.md` → `../../docs/一期/一期头程订单闭环设计.md`。状态边界为客户审核与两类必填资质均 `APPROVED` 后才允许下单。
|
||
- 二期协作：IAM 不承载入库或计费状态，仅为 `firstleg/` 提供客户资格/授权快照；先读 `../../docs/二期/README.md` 与 `../../docs/二期/二期V2需求确认清单.md`，确认 `tenant_id>0` 客户隔离和 `tenant_id=0` 平台公共资源边界不变。
|
||
- 三期：当前 NO-GO；不提前新增出仓角色、租户层或 PDA 权限。待 `../../docs/三期/三期需求确认表.md` 的 P3 阻断项解除后，再同步权限资源、角色种子与 Auth Claim 消费者。
|