XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1197363ac6ea5d7f1554360bbc89eceecb4fabbb
aiot-platform-cloud/.qoder/repowiki/zh/content/API接口文档/系统管理API.md

25 KiB
Raw Blame History

系统管理API

**本文引用的文件** - [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/user/AdminUserApi.java) - [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/PermissionApi.java) - [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/permission/RoleApi.java) - [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/dept/DeptApi.java) - [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/LoginLogApi.java) - [viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java](file://viewsh-module-system-api/src/main/java/com/viewsh/module/system/api/logger/OperateLogApi.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/user/UserController.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/permission/PermissionController.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/controller/admin/dept/DeptController.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/user/AdminUserService.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/permission/PermissionService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/permission/PermissionService.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/dept/DeptService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/service/dept/DeptService.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/user/AdminUserDO.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/user/AdminUserDO.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/dept/DeptDO.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/dal/dataobject/dept/DeptDO.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/enums/common/SexEnum.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/enums/common/SexEnum.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/config/SystemSecurityConfig.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/config/SystemSecurityConfig.java) - [viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/core/SecurityFrameworkService.java](file://viewsh-module-system-server/src/main/java/com/viewsh/module/system/framework/security/core/SecurityFrameworkService.java)

目录

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

简介

本文件为“系统管理API”提供全面的RESTful接口文档，覆盖用户管理、权限管理、角色管理、部门管理、日志管理等核心能力。内容包括：

  • 接口的HTTP方法、URL路径、请求参数与响应格式
  • 请求示例与响应示例
  • 参数校验规则与错误处理机制
  • 访问权限控制与安全注意事项

项目结构

系统管理模块采用“API接口层 + 控制器层 + 服务层 + 数据访问层”的分层架构，遵循微服务间通过Feign进行RPC调用的约定。

graph TB
subgraph "系统管理API层"
A1["AdminUserApi<br/>用户RPC接口"]
A2["PermissionApi<br/>权限RPC接口"]
A3["RoleApi<br/>角色RPC接口"]
A4["DeptApi<br/>部门RPC接口"]
A5["LoginLogApi<br/>登录日志RPC接口"]
A6["OperateLogApi<br/>操作日志RPC接口"]
end
subgraph "系统管理服务层"
S1["UserController<br/>用户REST控制器"]
S2["PermissionController<br/>权限REST控制器"]
S3["DeptController<br/>部门REST控制器"]
SV1["AdminUserService<br/>用户服务"]
SV2["PermissionService<br/>权限服务"]
SV3["DeptService<br/>部门服务"]
end
A1 --> S1
A2 --> S2
A3 --> S2
A4 --> S3
A5 --> S1
A6 --> S1
S1 --> SV1
S2 --> SV2
S3 --> SV3

图表来源

章节来源

核心组件

  • 用户管理：提供用户增删改查、状态变更、密码重置、分页查询、导出导入、下属查询、按部门/岗位查询等能力。
  • 权限管理：提供角色菜单授权、角色数据范围授权、用户角色授权、角色有效性校验等能力。
  • 角色管理：提供角色有效性校验RPC接口。
  • 部门管理：提供部门增删改查、列表查询、树形子部门查询、部门有效性校验等能力。
  • 日志管理：提供登录日志创建RPC接口与操作日志分页查询RPC接口。

章节来源

架构总览

系统管理API采用“控制器 + 服务 + RPC接口”的分层设计。控制器负责对外暴露REST接口并进行权限校验；服务层封装业务逻辑；RPC接口用于跨模块调用。

sequenceDiagram
participant C as "客户端"
participant UC as "UserController"
participant US as "AdminUserService"
participant UA as "AdminUserApi(RPC)"
participant DB as "数据库"
C->>UC : "POST /system/user/create"
UC->>US : "createUser(reqVO)"
US->>DB : "插入用户记录"
DB-->>US : "返回主键"
US-->>UC : "用户ID"
UC-->>C : "200 成功 + 用户ID"
C->>UA : "GET /system/user/get?id=1"
UA->>US : "getUser(id)"
US->>DB : "查询用户"
DB-->>US : "用户对象"
US-->>UA : "用户对象"
UA-->>C : "200 成功 + 用户信息"

图表来源

详细组件分析

用户管理API

  • 接口概览

    • 新增用户：POST /system/user/create
    • 修改用户：PUT /system/user/update
    • 删除用户：DELETE /system/user/delete
    • 批量删除用户：DELETE /system/user/delete-list
    • 重置用户密码：PUT /system/user/update-password
    • 修改用户状态：PUT /system/user/update-status
    • 分页查询用户：GET /system/user/page
    • 获取精简用户列表：GET /system/user/list-all-simple 或 /system/user/simple-list
    • 获取用户详情：GET /system/user/get
    • 导出用户Excel：GET /system/user/export-excel
    • 下载用户导入模板：GET /system/user/get-import-template
    • 导入用户：POST /system/user/import

  • 请求与响应要点

    • 权限注解：@PreAuthorize 指定具体权限标识，如 system:user:create、system:user:query 等
    • 参数校验：使用 @Valid、@Validated 对请求体或分页参数进行校验
    • 响应统一：返回 CommonResult，成功时携带数据，失败时携带错误码与消息
    • 数据拼装：在控制器中结合部门服务获取部门信息，统一转换为视图对象返回

  • 关键流程示意

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "UserController"
participant Svc as "AdminUserService"
participant DeptSvc as "DeptService"
participant DO as "AdminUserDO"
Client->>Ctrl : "GET /system/user/page?pageNo=1&pageSize=10"
Ctrl->>Svc : "getUserPage(pageReqVO)"
Svc-->>Ctrl : "PageResult<AdminUserDO>"
Ctrl->>DeptSvc : "根据用户所属部门ID获取部门映射"
DeptSvc-->>Ctrl : "Map<Long, DeptDO>"
Ctrl-->>Client : "PageResult<UserRespVO>"

图表来源

章节来源

权限管理API

  • 接口概览

    • 获得角色菜单列表：GET /system/permission/list-role-menus
    • 赋予角色菜单：POST /system/permission/assign-role-menu
    • 赋予角色数据范围：POST /system/permission/assign-role-data-scope
    • 获得用户角色列表：GET /system/permission/list-user-roles
    • 赋予用户角色：POST /system/permission/assign-user-role

  • 关键流程示意

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "PermissionController"
participant Svc as "PermissionService"
participant Tenant as "TenantService"
Client->>Ctrl : "POST /system/permission/assign-role-menu"
Ctrl->>Tenant : "handleTenantMenu(filter未开通菜单)"
Tenant-->>Ctrl : "过滤后的菜单ID集合"
Ctrl->>Svc : "assignRoleMenu(roleId, menuIds)"
Svc-->>Ctrl : "授权完成"
Ctrl-->>Client : "200 成功"

图表来源

章节来源

角色管理API

  • 接口概览

    • 校验角色是否合法：GET /system/role/valid
    • RPC接口：RoleApi.validRoleList(ids)

  • 参数与权限对照

    • 校验角色是否合法：GET /system/role/valid
      • 方法：GET
      • 路径：/system/role/valid
      • 参数：ids（角色编号数组）
      • 响应：CommonResult

  • 错误处理

    • 参数校验失败：返回400
    • 业务异常：返回500

章节来源

部门管理API

  • 接口概览

    • 创建部门：POST /system/dept/create
    • 更新部门：PUT /system/dept/update
    • 删除部门：DELETE /system/dept/delete
    • 批量删除部门：DELETE /system/dept/delete-list
    • 获取部门列表：GET /system/dept/list
    • 获取精简部门列表：GET /system/dept/list-all-simple 或 /system/dept/simple-list
    • 获取部门详情：GET /system/dept/get

  • 参数与权限对照

    • 创建/更新/删除/查询：分别需要 system:dept:create、system:dept:update、system:dept:delete、system:dept:query
    • 示例：创建部门
      • 方法：POST
      • 路径：/system/dept/create
      • 权限：@PreAuthorize("@ss.hasPermission('system:dept:create')")
      • 请求体：DeptSaveReqVO（字段由VO定义）
      • 响应：CommonResult

  • 错误处理

    • 参数校验失败：返回400
    • 权限不足：返回403

章节来源

日志管理API

  • 登录日志API

    • 创建登录日志：POST /system/login-log/create
    • 参数：LoginLogCreateReqDTO（由DTO定义）
    • 响应：CommonResult

  • 操作日志API

    • 获取操作日志分页：GET /system/operate-log/page
    • 参数：OperateLogPageReqDTO（由DTO定义）
    • 响应：CommonResult<PageResult>

  • 错误处理

    • 参数校验失败：返回400
    • 业务异常：返回500

章节来源

RPC接口（跨模块调用）

  • 用户RPC接口：AdminUserApi

    • 查询单个用户：GET /infra/user/get
    • 查询用户列表：GET /infra/user/list
    • 校验用户是否有效：GET /infra/user/valid
    • 下属用户查询：GET /infra/user/list-by-subordinate
    • 按部门/岗位查询用户：GET /infra/user/list-by-dept-id、GET /infra/user/list-by-post-id

  • 权限RPC接口：PermissionApi

    • 获得拥有多个角色的用户编号集合：GET /infra/permission/user-role-id-list-by-role-id

  • 角色RPC接口：RoleApi

    • 校验角色是否合法：GET /infra/role/valid

  • 部门RPC接口：DeptApi

    • 获得部门信息：GET /infra/dept/get
    • 获得部门信息数组：GET /infra/dept/list
    • 校验部门是否合法：GET /infra/dept/valid
    • 获得指定部门的所有子部门：GET /infra/dept/list-child

章节来源

依赖关系分析

  • 控制器到服务：控制器通过资源注入调用服务层，服务层封装业务逻辑并访问数据访问层
  • 服务到RPC：服务层可调用系统管理API中的RPC接口以跨模块查询用户、部门、角色等信息
  • 安全配置：系统安全配置类提供统一的安全策略与权限校验入口
classDiagram
class UserController {
+createUser(reqVO)
+updateUser(reqVO)
+deleteUser(id)
+getUserPage(pageReqVO)
+getUser(id)
}
class PermissionController {
+getRoleMenuList(roleId)
+assignRoleMenu(reqVO)
+assignRoleDataScope(reqVO)
+listAdminRoles(userId)
+assignUserRole(reqVO)
}
class DeptController {
+createDept(saveReqVO)
+updateDept(saveReqVO)
+deleteDept(id)
+getDeptList(reqVO)
+getDept(id)
}
class AdminUserService
class PermissionService
class DeptService
UserController --> AdminUserService : "依赖"
PermissionController --> PermissionService : "依赖"
DeptController --> DeptService : "依赖"

图表来源

章节来源

性能考量

  • 分页查询：建议使用分页参数避免一次性加载大量数据
  • 批量操作：优先使用批量接口减少网络往返
  • 缓存与转换：在控制器层对关联数据（如部门信息）进行Map化缓存，降低重复查询成本
  • 导出与导入：导出时设置无分页参数，导入时注意文件大小限制与幂等处理

故障排查指南

  • 权限不足
    • 现象：返回403
    • 排查：确认当前用户是否具备所需权限标识（如 system:user:create）
  • 参数校验失败
    • 现象：返回400，提示字段缺失或格式错误
    • 排查：检查请求体字段类型、必填项与取值范围
  • 业务异常
    • 现象：返回500，携带错误码与消息
    • 排查：查看服务层日志，定位具体异常原因
  • RPC调用失败
    • 现象：跨模块查询用户/部门/角色报错
    • 排查：确认RPC接口是否正确暴露、服务名与前缀是否一致

章节来源

结论

系统管理API提供了完善的用户、权限、角色、部门与日志管理能力，采用清晰的分层架构与统一的权限控制策略，满足企业级系统的管理需求。建议在生产环境中结合安全配置与监控体系，持续优化性能与稳定性。

附录

  • 统一响应结构
    • 成功：{ "code": 0, "msg": "成功", "data": T }
    • 失败：{ "code": 非0, "msg": "错误描述", "data": null }
  • 常用枚举
    • 性别枚举：参考 SexEnum
  • 数据模型
    • 用户DO：参考 AdminUserDO
    • 部门DO：参考 DeptDO