系统管理接口（sys 域）¶

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/api-standards/biz-api/sys.md

bams-apex 系统管理的 15 个 Controller。含登录认证、用户/角色/菜单/应用管理。4 个完全自定义 Controller（应用角色/角色按钮/角色菜单/用户角色关联）+ 11 个继承 EnergyBaseController。

📖 标准 CRUD 接口格式见 标准CRUD接口规范。

⚠️ 前端必读的易错点¶

1. 登录接口参数是 @RequestParam（query/form），不是 JSON body
2. sessionId 从响应体 data.sessionId 获取，后续放请求头 sessionid 回传（不走 Cookie）
3. 没有 logout / updatePassword 的 REST 端点（service 层已实现但未暴露，登出=前端丢弃 sessionId 即可）
4. assign 类接口是"全量覆盖"语义（先删该角色全部关联再插入新集合）
5. /sys/sysResource/exist 返回 true=已存在

一、用户与登录 /dac/sysUser（前端最常用）¶

@Tag：9000-系统用户接口。继承 EnergyBaseController（标准 CRUD 全套，重写了 saveOrUpdate）。

POST /dac/sysUser/auth/loginByPassword — 登录¶

根据用户名、密码、验证码登录，创建 session 并返回用户信息。

• 参数：@RequestParam（query 或 form-urlencoded，非 JSON）

• 响应：JsonResult<Object>，data = SysUser：

{
  "code": "200",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "id": "123",
    "user_name": "张三",
    "login_name": "zhangsan",
    "role_list": [...],
    "role_name": "管理员",
    "role_id_list": [...],
    "corp": { "公司信息 BdCorp" },
    "super_admin": 0,
    "password": null
  }
}

• 登录失败：用户不存在/已停用（AUTH_REQUEST_ERROR）、密码错误

GET /dac/sysUser/transferToLocalUser?sessionId=xxx — 会话换换¶

跨系统/底座跳转场景：校验传入 sessionId 有效，读取用户信息，创建全新 sessionId 返回。@IgnoreSession。

POST /dac/sysUser/auth/accessToken?appId=&appKey= — 获取底座 token¶

必须精确匹配 appId=cnbmBamsDataId、appKey=ZW5lcmd5UmVnaW9u。响应 data = JWT token 字符串。

GET /dac/sysUser/getResourceByUserTree?appId=&token=&accountId=&menuType= — 获取用户菜单树¶

@CommonData。按 appId 对应应用的认证模式分两支： - 本地认证（authenticationMode=0）：按 accountId+appId 查权限资源，组树返回 - 底座认证：代理转发底座网关菜单接口（header 携带 Sys {token}）

• 响应：JsonResult<Object>（树形 SysResource 数组）

POST /dac/sysUser/saveOrUpdate — 新增/修改用户（重写）¶

• 请求：SysUser JSON。关键字段：pid（父账号）、account_type（1主/2子）、super_admin（0/1）、dept_code、login_name（唯一）、user_name、user_type、email、phone_number、sex、password、status（0正常/1停用）、corp_code、org_id、role_id_list
• 响应：JsonResult<SysUser>

二、应用角色关联 /dac/sysAppRole（完全自定义）¶

@Tag：应用角色关联接口。关联表 sys_app_role。

三、角色按钮权限 /sys/roleButton（完全自定义）¶

@Tag：1202-系统角色按钮权限接口。

GET /sys/roleButton/getButtonsBySessionId?sysCode=xxx — 获取角色按钮权限（前端鉴权主接口）¶

• 认证：请求头 sessionid（从 session 解析当前用户）
• 逻辑：用户→角色列表→按 sysCode+roleIds 查菜单按钮；无角色返回空列表
• 响应：JsonResult<List<SysMenuButton>>

SysMenuButton 关键字段：

其他接口¶

四、角色菜单关联 /sys/roleResource（完全自定义）¶

@Tag：角色菜单关联接口。

五、用户角色关联 /sys/userRole（完全自定义）¶

@Tag：用户角色关联接口。

六、应用管理 /dac/sysApp（继承 + 10 个自定义）¶

@Tag：应用管理接口。继承标准 CRUD。主要字段：app_name、app_code、type、sort、app_icon、open_type、is_enable、auth_mode、mobile_url、support_terminal、corp_code 等。

七、角色管理 /sys/role（继承 + 4 个自定义）¶

@Tag：1202-角色管理接口。SysRole 关键字段：role_code（唯一）、role_name（唯一）、role_sort、data_scope（1全部/2本公司及以下/3本公司/4本部门/5本部门及以下/6仅本人）、status、corp_code。

八、资源/菜单管理 /sys/sysResource（继承 + 2 个自定义）¶

@Tag：1201-系统资源接口。SysResource 实现 ITreeAble（支持 /tree 树形接口）。关键字段：pid、menu_type（dir目录/menu菜单）、menu_code、menu_name、menu_icon、path、sort、is_hide、is_enable、open_type、app_id、checked（非表）、children（非表）。

九、业务状态配置 /sys/businessStatus（继承 + 1 个自定义）¶

SysBusinessStatus 字段：app_code、corp_code、business_code、business_status（状态列表 JSON 串）、overdue。

十、其余标准 CRUD 模块¶

十一、典型调用流程（前端登录到鉴权全流程）¶

// 1. 登录（form 参数，非 JSON！）
const res = await axios.post('/apex-api/dac/sysUser/auth/loginByPassword',
  `username=zhangsan&password=${rsaEncryptedPwd}`);
const sessionId = res.data.data.sessionId;

// 2. 存 sessionId，后续请求带头
axios.defaults.headers.common['sessionid'] = sessionId;

// 3. 拉菜单树
const menus = await axios.get('/apex-api/dac/sysUser/getResourceByUserTree', {
  params: { appId: 'myApp', token: '', accountId: userId }
});

// 4. 拉按钮权限（按钮显隐控制）
const buttons = await axios.get('/apex-api/sys/roleButton/getButtonsBySessionId', {
  params: { sysCode: 'myApp' }
});
// buttons.data.data → [{ auth_code: 'sys:user:delete', ... }]

相关文档¶

• 标准CRUD接口规范
• 业务中台接口首页
• SDK开发包-数据权限 — dataScope 数据范围机制