DM-ROW 接口文档

Appearance

通用管理API ​

**本文引用的文件** - [LemesAuthApplication.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/LemesAuthApplication.java) - [SysLoginController.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/controller/SysLoginController.java) - [AuthorizationServerConfig.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/config/AuthorizationServerConfig.java) - [SysUserController.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/controller/SysUserController.java) - [SysRoleController.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/controller/SysRoleController.java) - [SysMenuController.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/controller/SysMenuController.java) - [DictController.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/controller/DictController.java) - [DepartmentApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/api/DepartmentApi.java) - [SysUserApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/api/SysUserApi.java) - [SysDictApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/api/SysDictApi.java)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件为通用管理API的完整接口文档，覆盖用户管理、角色权限、组织架构、字典管理、系统配置等基础能力，并重点说明用户认证授权、菜单权限管理、部门管理、数据字典等核心接口。文档提供统一的API规范，包括请求参数、响应格式与权限控制说明，帮助前后端协作实现一致的权限管理和基础数据标准。

项目结构 ​

本项目采用多模块微服务架构，核心模块包括：

  • 认证中心：负责OAuth2令牌发放、刷新与注销
  • 通用服务：提供用户、角色、菜单、字典等通用管理接口
  • 设备管理业务：提供部门、用户、字典等业务侧API

图表来源

章节来源

核心组件 ​

  • 认证与授权：基于OAuth2授权服务器，提供密码模式登录、令牌刷新、注销登出
  • 用户管理：提供用户查询、新增/更新/删除、重置密码、角色授权、密码校验与修改、用户列表分页等
  • 角色管理：提供角色列表、新增/更新/删除、角色与用户关联变更、自定义角色查询
  • 菜单权限：提供菜单树/列表、资源类型分类、模板应用、用户授权权限列表、访问历史维护
  • 数据字典：提供字段清单、按字段查询、分页查询、新增/更新/删除
  • 组织架构：提供部门信息查询、按名称/编号/当前用户所在部门查询
  • 业务用户：提供按用户代号/账号批量查询、按姓名查询、报表权限标识查询

章节来源

架构总览 ​

系统采用“网关+微服务”架构，认证中心提供统一鉴权入口，通用服务提供基础管理能力，业务模块通过Feign调用通用服务或直接暴露REST API。

图表来源

详细组件分析 ​

认证与授权API ​

  • 接口路径：/auth/pwdLogin

    • 方法：POST
    • 请求头：
      • TERMINAL：终端类型（如web、mobile、client）
    • 参数：
      • username：用户名
      • password：密码
    • 响应：包含access_token、refresh_token及附加声明
    • 权限：无需鉴权
    • 说明：根据终端类型选择客户端配置；若存在旧令牌则复用；否则向授权服务器申请新令牌

  • 接口路径：/auth/refreshToken

    • 方法：POST
    • 请求头：
      • TERMINAL：终端类型
    • 参数：
      • refresh_token：刷新令牌
    • 响应：新的令牌对与声明
    • 权限：无需鉴权
    • 说明：校验refresh_token有效性后，向授权服务器申请新令牌

  • 接口路径：/auth/logoff

    • 方法：DELETE
    • 请求头：
      • Authorization：Bearer token
    • 响应：登出成功提示
    • 权限：无需鉴权
    • 说明：根据传入token查找并移除授权记录

图表来源

章节来源

用户管理API ​

  • 接口路径：/sysUser/findByName

    • 方法：GET
    • 参数：userId（用户名）
    • 响应：SysUser对象
    • 权限：需具备任意自定义权限

  • 接口路径：/sysUser/getCurrentUserInfo

    • 方法：GET
    • 响应：当前登录用户信息
    • 权限：登录态

  • 接口路径：/sysUser/findPermissions

    • 方法：GET
    • 参数：userId
    • 响应：Set<String> 权限字符串集合
    • 权限：需具备任意自定义权限

  • 接口路径：/sysUser/loadUserByUsername

    • 方法：GET
    • 参数：userId
    • 响应：CustomUserDetailsDTO
    • 权限：需具备任意自定义权限

  • 接口路径：/sysUser/dataGrid

    • 方法：GET
    • 参数：分页参数PageVo与SysUser过滤条件
    • 响应：分页结果
    • 权限：sys:user

  • 接口路径：/sysUser/resetPwd

    • 方法：GET
    • 参数：userId
    • 响应：操作结果
    • 权限：sys:user

  • 接口路径：/sysUser/delUser

    • 方法：GET
    • 参数：id
    • 响应：操作结果
    • 权限：sys:user

  • 接口路径：/sysUser/updateUser

    • 方法：POST
    • 参数：SysUser（需包含userId）
    • 响应：操作结果
    • 权限：sys:user

  • 接口路径：/sysUser/addUser

    • 方法：POST
    • 参数：SysUser（userId必填）
    • 响应：操作结果
    • 权限：sys:user

  • 接口路径：/sysUser/grant

    • 方法：POST
    • 参数：SysUser（含角色信息）
    • 响应：操作结果
    • 权限：sys:user

  • 接口路径：/sysUser/checkPwd

    • 方法：GET
    • 参数：oldPsw
    • 响应：校验结果
    • 权限：登录态

  • 接口路径：/sysUser/updatePwd

    • 方法：GET
    • 参数：oldPwd、newPwd
    • 响应：修改结果
    • 权限：登录态

  • 接口路径：/sysUser/loginUpdatePwd

    • 方法：GET
    • 参数：password
    • 响应：修改结果
    • 权限：登录态

  • 接口路径：/sysUser/loadAllUsers

    • 方法：GET
    • 响应：用户列表
    • 权限：需具备任意自定义权限

  • 接口路径：/sysUser/listUsers

    • 方法：GET
    • 响应：用户列表
    • 权限：sys:user、sys:open-api、sys:role、mbg:base:stationManage

  • 接口路径：/sysUser/{role}/userList

    • 方法：GET
    • 路径参数：role
    • 响应：该角色下的用户列表
    • 权限：需具备任意自定义权限

  • 接口路径：/sysUser/uniqueId

    • 方法：GET
    • 响应：24位唯一字符串
    • 权限：sys:user

  • 接口路径：/sysUser/refreshApiCache

    • 方法：GET
    • 响应：刷新结果
    • 权限：sys:user

  • 接口路径：/sysUser/getControllerUser

    • 方法：GET
    • 响应：可管理用户列表
    • 权限：sys:role

  • 接口路径：/sysUser/updateController

    • 方法：POST
    • 参数：SysUser（controller字段）
    • 响应：更新结果
    • 权限：sys:user

  • 接口路径：/sysUser/queryUserAndGroup

    • 方法：GET
    • 参数：分页与过滤条件
    • 响应：分页结果
    • 权限：登录态

  • 接口路径：/sysUser/queryByQueryWarapper

    • 方法：GET
    • 响应：查询结果
    • 权限：需具备任意自定义权限

图表来源

章节来源

角色权限API ​

  • 接口路径：/sysRole/listRoles

    • 方法：GET
    • 参数：SysRole（可选，支持按创建人过滤）
    • 响应：角色列表（限定类型）
    • 权限：sys:user

  • 接口路径：/sysRole/listByRole

    • 方法：POST
    • 参数：SysRole
    • 响应：角色列表
    • 权限：sys:role

  • 接口路径：/sysRole/listCustomRoles

    • 方法：POST
    • 参数：SysRole（内部使用当前登录用户作为创建人）
    • 响应：自定义角色列表
    • 权限：sys:role、sys:user

  • 接口路径：/sysRole/addOrUpdate

    • 方法：POST
    • 参数：SysRole
    • 响应：操作结果
    • 权限：sys:role

  • 接口路径：/sysRole/del

    • 方法：GET
    • 参数：roleId
    • 响应：操作结果
    • 权限：sys:role

  • 接口路径：/sysRole/listUserByRole

    • 方法：GET
    • 参数：roleId
    • 响应：该角色下的用户列表
    • 权限：sys:role

  • 接口路径：/sysRole/listAllMobileRoleNameBayUserId

    • 方法：GET
    • 参数：userId
    • 响应：移动端角色名称列表
    • 权限：登录态

  • 接口路径：/sysRole/changeRoleUser

    • 方法：POST
    • 参数：UserRole
    • 响应：变更结果
    • 权限：sys:role

  • 接口路径：/sysRole/listByUserIdOrRole

    • 方法：GET
    • 参数：userId、SysRole
    • 响应：角色列表
    • 权限：需具备任意自定义权限

  • 接口路径：/sysRole/queryGroup

    • 方法：GET
    • 参数：groupName
    • 响应：分组查询结果
    • 权限：登录态

  • 接口路径：/sysRole/updateNabfRole

    • 方法：GET
    • 参数：factoryIdList、factory1、factory2
    • 响应：更新结果
    • 权限：登录态

章节来源

菜单权限API ​

  • 接口路径：/sysMenu/listMenu

    • 方法：GET
    • 响应：当前用户可访问的菜单列表
    • 权限：登录态

  • 接口路径：/sysMenu/list

    • 方法：POST
    • 参数：SysMenu（可选过滤条件）
    • 响应：按资源类型分类的菜单集合
    • 权限：sys:role、sys:resource、sys:help

  • 接口路径：/sysMenu/addOrUpdate

    • 方法：POST
    • 参数：SysMenu（客户端类型特殊处理名称与URL互换）
    • 响应：操作结果
    • 权限：sys:resource

  • 接口路径：/sysMenu/del

    • 方法：GET
    • 参数：id
    • 响应：操作结果
    • 权限：sys:resource

  • 接口路径：/sysMenu/listAssigned

    • 方法：GET
    • 参数：id（模板菜单ID）
    • 响应：已应用的菜单列表
    • 权限：sys:resource

  • 接口路径：/sysMenu/assignTemplate

    • 方法：POST
    • 参数：SysMenu（包含应用菜单ID列表）
    • 响应：操作结果
    • 权限：sys:resource

  • 接口路径：/sysMenu/listMenuHistory

    • 方法：GET
    • 响应：菜单访问历史列表
    • 权限：登录态

  • 接口路径：/sysMenu/updateMenuHistory

    • 方法：GET
    • 参数：menuId
    • 响应：更新结果
    • 权限：登录态

  • 接口路径：/sysMenu/listUserPerms

    • 方法：GET
    • 参数：type（资源类型，多个以逗号分隔）
    • 响应：已授权的perms列表
    • 权限：登录态

  • 接口路径：/sysMenu/findByMenuType

    • 方法：GET
    • 参数：menuType、menuNameList
    • 响应：匹配的菜单列表
    • 权限：需具备任意自定义权限

  • 接口路径：/sysMenu/queryMenu

    • 方法：GET
    • 参数：roleId
    • 响应：该角色拥有的资源
    • 权限：登录态

章节来源

数据字典API ​

  • 接口路径：/dict/fields

    • 方法：GET
    • 响应：所有字典键列表
    • 权限：登录态

  • 接口路径：/dict/fields/

    • 方法：GET
    • 路径参数：field
    • 响应：该键对应的字典项列表
    • 权限：登录态

  • 接口路径：/dict

    • 方法：GET
    • 参数：分页与过滤条件
    • 响应：分页结果
    • 权限：登录态

  • 接口路径：/dict/

    • 方法：GET
    • 路径参数：id
    • 响应：单条字典记录
    • 权限：登录态

  • 接口路径：/dict

    • 方法：POST
    • 参数：Dictionary（新增/更新）
    • 响应：操作结果
    • 权限：登录态

  • 接口路径：/dict

    • 方法：DELETE
    • 参数：Dictionary（JSON字符串反序列化为对象）
    • 响应：操作结果
    • 权限：登录态

章节来源

组织架构API ​

  • 接口路径：/getDept

    • 方法：GET
    • 响应：部门列表
    • 权限：登录态

  • 接口路径：/deptName

    • 方法：GET
    • 参数：deptName
    • 响应：部门信息
    • 权限：登录态

  • 接口路径：/current/user

    • 方法：GET
    • 响应：当前登录人及其下级部门
    • 权限：登录态

  • 接口路径：/by/deptNo

    • 方法：GET
    • 参数：deptNo
    • 响应：部门及其下级部门
    • 权限：登录态

  • 接口路径：/deptNo

    • 方法：GET
    • 参数：deptNo
    • 响应：部门信息
    • 权限：登录态

  • 接口路径：/deptInfo

    • 方法：GET
    • 参数：deptNo
    • 响应：部门详情
    • 权限：登录态

章节来源

业务用户API ​

  • 接口路径：/getUserByNoOrAccount

    • 方法：GET
    • 参数：userNos（用户代号数组）、accounts（账号数组）
    • 响应：用户列表
    • 权限：登录态

  • 接口路径：/queryUserInfo

    • 方法：POST
    • 参数：SysUserQueryVo
    • 响应：用户列表
    • 权限：登录态

  • 接口路径：/queryByName

    • 方法：GET
    • 参数：name
    • 响应：用户信息
    • 权限：登录态

  • 接口路径：/queryByNameList

    • 方法：GET
    • 参数：names（姓名数组）
    • 响应：用户列表
    • 权限：登录态

  • 接口路径：/queryUserReportFlag

    • 方法：GET
    • 响应：报表查询权限标识（1/0）
    • 权限：登录态

章节来源

业务字典API ​

  • 接口路径：/getDictList

    • 方法：GET
    • 参数：code（字典编码）
    • 响应：字典值列表
    • 权限：登录态

  • 接口路径：/getDictMap

    • 方法：POST
    • 参数：codes（字典编码数组）
    • 响应：字典映射
    • 权限：登录态

  • 接口路径：/checkDictIsValid

    • 方法：POST
    • 参数：校验对象列表
    • 响应：校验结果映射
    • 权限：登录态

  • 接口路径：/getDictNameByDictValue

    • 方法：POST
    • 参数：dicValue（字典值）、dicCode（字典编码）
    • 响应：字典名称
    • 权限：登录态

  • 接口路径：/getDictByDictNameAndCode

    • 方法：GET
    • 参数：name（字典名称）、dictCode（字典编码）、languageCode（语言）
    • 响应：字典信息
    • 权限：登录态

章节来源

依赖分析 ​

  • 认证中心依赖授权服务器与客户端配置，负责令牌发放与刷新
  • 通用服务控制器依赖权限注解进行细粒度授权控制
  • 业务模块通过Feign接口调用通用服务或直接暴露REST API

图表来源

章节来源

性能考虑 ​

  • 令牌复用：登录时优先复用已存在的授权，减少授权服务器压力
  • 分页查询：用户、字典等列表接口采用分页参数，避免一次性返回大量数据
  • 权限缓存：提供刷新API权限缓存接口，降低动态权限计算成本
  • 资源类型分类：菜单接口按WEB/CLIENT/MOBILE/API/PRINTER分类返回，便于前端按需渲染

故障排查指南 ​

  • 登录失败
    • 检查TERMINAL是否正确，确认客户端配置是否存在
    • 核对用户名大小写（系统统一转为小写存储）
    • 查看授权服务器返回状态与错误信息
  • 令牌无效
    • 使用/refreshToken刷新令牌
    • 确认Authorization头格式为Bearer token
    • 检查令牌是否被提前注销
  • 权限不足
    • 确认当前用户是否具备sys:user、sys:role、sys:resource等所需权限
    • 检查角色与菜单授权是否正确
  • 接口异常
    • 查看通用返回体中的success标志与message描述
    • 结合日志定位具体异常点

章节来源

结论 ​

本通用管理API提供了完善的用户、角色、菜单、字典与组织架构管理能力，并通过认证中心统一提供JWT令牌获取、刷新与注销服务。接口遵循细粒度权限控制与分页查询原则，适配多终端场景，可作为系统权限管理和基础数据的标准接口集。

附录 ​

  • 统一响应结构
    • 成功：
    • 失败：
  • 常用权限标识
    • sys:user：用户管理
    • sys:role：角色管理
    • sys:resource：资源/菜单管理
    • sys:help：帮助信息
    • sys:open-api：开放API访问
  • 终端类型
    • web、mobile、client等，由TERMINAL请求头指定