# Admin 平台用户与权限模块指引

## 路径基准与读取顺序

- 本文件适用于 `src/modules/iam/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，权限语义见 `../../../docs/平台客户层级与权限契约.md`。
- 本模块是**平台侧**用户、角色与权限资源维护入口；客户侧成员与角色归 `backend iam/`，账号与登录标识归 `backend auth/`，前端守卫在 `../core/access/`。
- 后端只查 `iam/`（平台 RBAC、菜单资源、客户与成员）与 `auth/`（账号与会话撤销）。

## 页面与入口

| 目标 | 页面/路由 | API 与后端 |
|---|---|---|
| 平台用户列表、PDA 人员与海外仓绑定 | `pages/InternalUsersView.vue`；`system/users` | `api/platformIam.ts`；`iam/`、`auth/` |
| 角色与角色成员 | `pages/RolesView.vue`；`system/roles` | `api/platformIam.ts`；`iam/` |
| 权限资源与菜单 | `pages/PermissionsView.vue`、`utils/permissionTree.ts`；`system/permissions` | `api/platformIam.ts`；`iam/` 菜单资源 |
| 客户作用域选择器 | `components/PlatformTenantSelector.vue` | `iam/` 客户主档 |
| 权限判定与展示 | `utils/platformPermission.ts`、`../core/access/` | 服务端权限快照；前端不替代鉴权 |
| 模块密度样式 | `iamDensity.css` | 按公共密度规范接入 |

## 关键边界

- 平台用户选择 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 时必须选择唯一实际海外收货仓；其他角色不得提交 `overseasWarehouseId`；编辑时保留已绑定仓库，长整型 ID 按字符串透传。
- 国内 `CN_FIRSTLEG_PDA_OPERATOR` 与海外 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 互斥；候选来自国内 Warehouse 平台仓库 API 的公共 `OVERSEAS + ACTIVE + RECEIVING` 收货仓。
- 列表权限 `*:list` 同时授权列表与详情只读；`create`、`edit`、`delete`、`status`、`approve` 等保持独立，不保留旧 `*:view`。
- 供应商固定使用 `platform:supplier:list`；`platform:supplier:view` 不得重新启用以兼容旧调用。
- 菜单、路由与权限资源三处必须同步：改权限码时同时核对 Controller `@PreAuthorize`、OpenAPI、模块权限 SQL 与菜单资源。
- 前端守卫只改善体验，服务端必须重复校验租户、角色与数据范围。

## 验证

- 定向：`pnpm test src/modules/iam/<目标测试>`；权限码或菜单资源变更同时核对 `iam` 菜单 SQL 与权限契约测试。
- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。