权限模型与系统管理
平台采用通用的「用户 - 角色 - 菜单」权限模型，并在其之上叠加数据权限与项目隔离。
权限层级
| 层级 | 决定什么 |
|---|---|
| 菜单权限 | 能看到哪些导航、页面与按钮，能访问哪些后端接口 |
| 数据权限 | 能看到哪些接口、数据源、分组与日志 |
| 项目隔离 | 进入项目后只能操作当前项目的数据 |
| 超级管理员 | 默认拥有全部菜单，不受角色菜单限制 |
数据权限范围
- 用户自己创建的接口、数据源、分组。
- 被协作授权的分组，以及分组下的所有接口。
- 被授权的数据源（仅可使用，不能查看连接信息）。
- 接口日志：本人创建的接口、本人凭证访问的接口、被授权分组下的接口，以及无认证接口的调用日志。
用户管理
入口：【系统管理 → 用户列表】。
| 操作 | 说明 |
|---|---|
| 新增 | 填写账号、昵称、部门、岗位、角色、备注等；岗位与备注可为空 |
| 编辑 | 修改基础信息与角色 |
| 删除 | 删除用户；请先确认没有未完成的审批或订阅 |
| 重置密码 | 密码默认重置为用户名；敏感操作仅超级管理员可执行 |
规则：
- 用户必须分配角色才能登录，否则返回
41003。 - 新增用户的初始密码默认为用户名，首次登录后应修改。
- 用户来源可能是本地、企业微信、钉钉等，SSO 用户通过绑定关系关联本地账号。
部门管理
入口：【系统管理 → 部门列表】。
部门也称组织，用于对用户做业务划分：
- 以树形结构展示，默认有一个根节点。
- 根节点可以设置为任意部门或组织。
- 支持新增、编辑、删除子部门。
角色管理
入口：【系统管理 → 角色列表】。
| 字段/操作 | 说明 |
|---|---|
| 角色名称 | 展示名称 |
| 类型 | 用于业务区分角色，便于分类管理 |
| 关联菜单 | 勾选角色可访问的菜单与按钮 |
| 新增/编辑/删除 | 维护角色信息与授权范围 |
角色未关联任何菜单时，该角色下的用户无法登录（41004）。修改角色菜单后，相关用户需要重新登录或刷新页面才能看到新的菜单。
菜单管理
入口：【系统管理 → 菜单列表】。
菜单以树形展示，可添加一级菜单或子菜单。
| 字段 | 说明 |
|---|---|
| 菜单 Path | 前端页面跳转的路由地址 |
| 菜单 Code | 菜单唯一标识 |
| 是否隐藏 | 控制前端是否展示该菜单入口 |
| 菜单类型 | 目录（导航）或按钮（页面操作） |
| 权限标识 | 菜单下可访问的接口地址规则，使用 /** 适配统一前缀，多条用分号 ; 分隔 |
| 排序 | 控制菜单展示顺序 |
| 图标 | 菜单图标 |
菜单与后端接口的对应关系通过「权限标识」维护。例如 /api/box/sys/api/info/** 表示允许访问该前缀下的管理端接口。新增页面或按钮时，需要同步配置权限标识，否则即使用户能看到菜单，也可能因接口无权限而失败。
系统日志
入口：【系统管理 → 操作日志】。
记录新增、编辑、删除、授权、发布等关键操作，包含：
- 操作人
- 操作人 IP
- 操作模块
- 操作内容
- 操作时间
支持按操作人与时间范围筛选，用于审计与问题回溯。系统日志与接口调用日志是两套数据：前者记录管理端操作，后者记录开放接口调用。
系统参数
入口：【系统管理 → 系统参数】。
系统参数以键值对维护平台级配置，字段包括参数名称、参数键、参数值、参数类型与备注。
- 参数值修改后立即生效，并覆盖部署文件中的同类默认值。
- 新增自定义参数不会影响既有功能。
- 修改
api_prefix会影响接口地址拼接，变更前请确认现有调用方与网关路由。
常见错误码
| code | 含义 | 处理 |
|---|---|---|
41003 | 用户无角色 | 在用户管理中分配角色 |
41004 | 角色无菜单权限 | 在角色管理中关联菜单 |
41014 | 用户不存在 | 检查账号是否已创建或已删除 |
41005 | Token 无效 | 重新登录 |
43003 | 没有操作权限 | 检查数据归属、项目角色与菜单权限 |
最佳实践
- 按岗位拆分角色，避免直接给所有用户管理员角色。
- 菜单权限与接口权限标识同时配置，不要只配置页面入口。
- 定期检查操作日志与长期未登录账号。
- 生产环境修改系统参数前先在测试环境验证。
- 对外协作用户优先使用项目成员 + 分组授权，而不是直接提升为超级管理员。