组织、用户与权限体系
这套正式管理能力是新系统的账户基础。默认后台提供首页、部门、用户、角色、字典、本人资料和真实界面偏好；任务、资源和表单等学习示例通过 VITE_ADMIN_EXAMPLES=true 显式开启。模块开关不替代账户授权，关闭模块的菜单、搜索结果、路由和旧页签都不能继续进入。字典选项按实际业务授权读取，具体合同见 字典管理与业务消费。
管理列表优先占用工作区。当前位置只在顶栏展示一套语义面包屑；手机保留当前页名称。部门树、筛选、工具栏和表格使用统一的 UG UI 公开组件，长名称不挤走其他有效列，完整名称通过提示和详情查看。
稳定主体与关系
| 合同 | 含义 | 后续业务如何使用 |
|---|---|---|
AdminUserId |
字符串用户 ID；AdminIdentity.id 与 ManagementUser.id 对应同一主体 |
业务记录使用 createdBy、ownerId 等字段引用该 ID，不以账号或姓名作主键 |
ManagementUser.departmentId |
用户当前所属部门，可为空 | 组织归属、成员列表；不能直接解释为服务端数据范围 |
ManagementUser.roleIds |
分配给用户的角色实体 ID，可有多个 | 编辑账户关联，角色成员筛选 |
ManagementRole.code |
稳定角色编码 | 认证快照 AdminIdentity.roles 中的可信角色编码；与角色 ID、展示名称区别使用 |
ManagementRole.permissions |
角色包含的功能权限码 | 服务端计算有效权限，登录/刷新返回身份的权限快照 |
ManagementDepartment.parentId |
部门父级 ID，可为空 | 保持组织树；禁止循环及有关联成员或子部门时删除；停用保留既有关联，阻止新增归属 |
管理列表、成员入口与关联详情使用同一套 Provider 查询。用户筛选的 department、role 等 URL 状态转换为 Provider 筛选，服务端必须先筛选、再排序分页和计算总数，不能只过滤当前页。精简关联选项使用 users/options，不为了展示名称读取用户无权查看的完整资源。
页面与后端的边界
flowchart LR
Pages[管理页面与业务页面] --> UI[UG UI 公开组件]
Pages --> Access[Access Control Provider]
Pages --> Data[Data Provider]
Session[认证状态] --> Auth[Auth Provider]
Access --> Snapshot[可信身份与权限快照]
Auth --> Adapter[接入方 Adapter]
Data --> Adapter
Adapter --> Backend[Go / Java / TypeScript / Python 后端]
Auth Provider 负责登录、退出、会话恢复与刷新；Data Provider 负责资源查询和写入；Access Control Provider 统一判断功能与记录操作。业务页面消费这些合同，不直接请求接口或根据后端语言分支。路径、字段命名、分页封装、认证头和错误映射在 Adapter 收敛，见 后端 Adapter。数字后端 ID 应在接入边界无损转换为字符串，不能经 JavaScript 不安全整数损失精度。
具备对应 read 权限时，编辑先读取最新记录；仅有列表和更新权限时只编辑已授权的列表字段，不额外读取无权访问的详情。提交只包含实际发生变化的字段，未改的权限、关系和服务端字段不随旧列表快照覆盖。详情失败提供重试；写入保护和字段错误按共享合同处理。演示 Provider 验证页面行为，不能证明真实后端授权和持久化已接通。
权限登记与扩展
auth/permissions.ts 保存统一的前端权限目录。system 模块提供用户、部门、角色、字典与设置权限；业务权限放在自己的模块入口，由应用在生成导航之前统一登记：
// src/modules/orders/index.ts 的模块声明中：
permissions: [
{ code: "orders:list", label: "查询订单", group: "订单" },
{ code: "orders:approve", label: "审批订单", group: "订单" },
],
数组项结构为 { code, label, group, description? }。模块入口同时登记自己的 pages，不修改核心 app/modules.ts 或 system 模块。学习权限由 examples 模块按开关登记。不能在运行中的页面修改目录；重复权限码和无效定义会直接报错。
目录登记仅提供含义与操作选项，不授予当前用户权限。角色编辑不能分配超出当前账户授权的权限。既有记录中的未登记权限只读显示并保留，批量全选或保存其他字段不得删除它们，也不得从输入或服务端目录自动加入可授予集合。内置角色、自删/自停用、最后启用超管以及部门关系保护在所有适配器下保持一致，真实服务端必须再次执行。
权限选择复用 UGSelectionList 的公开分组、搜索和全选/半选能力；领域规则留在 Admin。新系统的用户、角色、组织与接口 DTO 不进入 UG UI。
接入新业务
- 复用稳定用户 ID，定义业务资源、字段和权限目录，不再创建第二套账户或角色体系。
- 在业务模块的 pages 登记页面、菜单、访问声明与原生 loader；消费业务只写所选端，模板 system 功能同步双端。
- 页面使用现有列表、编辑与详情模式，组合 UG UI 公开组件；公共缺口在 UG UI 扩充。
- 在 Provider/Adapter 映射真实后端，统一筛选、总数、部分更新与错误，不在页面解析后端 DTO。
- 验证无权限、空数据、失败重试、关联跳转、刷新恢复和响应式，再验证实际后端会话及 CRUD 持久化。
开户、邀请、密码重置、数据范围、多租户与具体后端实现需要相应服务端合同；当前用户模型不存密码。它们可继续扩展这套稳定主体，但不能用演示创建用户或前端按钮代替后端能力。