跳到主要内容

设备信息修改

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与并发特性
  8. 安全与合规
  9. 故障排查
  10. 结论
  11. 附录：API 接口文档

简介​

本技术文档围绕“设备信息修改”能力进行系统化梳理，重点覆盖以下方面：

  • 安全控制机制：权限验证、操作审计、数据校验
  • 支持修改的信息范围：设备 MAC、CPU、MAC 分配状态与时间、创建/更新信息等
  • 审核与变更管理：修改申请、审批流程、变更记录
  • 日志与审计：操作时间、操作人、修改内容、审批状态等
  • API 接口规范：请求格式、参数校验、响应处理
  • 安全最佳实践与合规要求

说明：当前仓库实现聚焦于“设备信息修改记录”的管理与 MAC 分配池的导入/统计，以及基于 Redis 的 MAC 分配逻辑；“设备信息修改”的完整业务（如品牌、系统版本、构建号、内存配置等）在现有代码中未体现，本文按现有实现进行说明，并在“概念性概述”部分给出扩展建议。

项目结构​

设备信息修改相关模块位于 yudao-module-device 子模块中，采用典型的分层架构：

  • 控制层：对外暴露 REST 接口，负责鉴权、参数校验、调用服务层
  • 服务层：封装业务逻辑，协调 Mapper/DAO、Redis 缓存与导入处理
  • 数据访问层：MyBatis Mapper 负责数据库 CRUD；XML 提供批量插入等 SQL
  • 数据对象：DO 映射 base_device_info_modify 表
  • VO/DTO：请求/响应参数结构，用于接口契约

Mermaid Diagram Code:

graph TB
subgraph "设备模块"
C["DeviceInfoModifyController<br/>REST 控制器"]
S["DeviceInfoModifyServiceImpl<br/>服务实现"]
M["DeviceInfoModifyMapper<br/>MyBatis Mapper"]
XML["DeviceInfoModifyMapper.xml<br/>SQL 映射"]
DO["DeviceInfoModifyDO<br/>数据对象"]
VOS["VO/DTO<br/>请求/响应结构"]
end
C --> S
S --> M
M --> XML
M --> DO
C --> VOS
S --> VOS

图表来源

章节来源

核心组件​

  • 控制器 DeviceInfoModifyController：提供创建、更新、删除、查询、分页、导出 Excel、导入 MAC 池、统计未分配 MAC 等接口，并通过注解进行权限控制与操作日志记录
  • 服务 DeviceInfoModifyService/Impl：实现创建/更新/删除/查询/分页、导入 MAC 池、统计未分配数量、系统自动分配 MAC 的核心逻辑
  • 数据访问 DeviceInfoModifyMapper：提供分页查询、批量插入 MAC 池、查询未分配 MAC、更新分配设备信息、按状态计数等方法
  • 数据对象 DeviceInfoModifyDO：映射 base_device_info_modify 表，包含分配 MAC、设备原 MAC、CPU、状态、分配时间、创建/更新时间及创建者/更新者等字段
  • VO/DTO：DeviceInfoModifySaveReqVO、DeviceInfoModifyPageReqVO、AppDeviceInfoModifyReqVO、DeviceModifyRespDTO，分别用于管理后台新增/修改、分页查询、APP 修改请求、RPC 响应

章节来源

架构总览​

下图展示“设备信息修改”从接口到持久化的整体交互：

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "DeviceInfoModifyController"
participant Svc as "DeviceInfoModifyServiceImpl"
participant Mapper as "DeviceInfoModifyMapper"
participant DB as "数据库"
participant Redis as "Redis"
Client->>Ctrl : "POST /create 或 PUT /update"
Ctrl->>Svc : "createInfoModify/updateInfoModify"
Svc->>Mapper : "insert/updateById/selectPage"
Mapper->>DB : "执行 SQL"
DB-->>Mapper : "结果集"
Mapper-->>Svc : "返回结果"
Svc-->>Ctrl : "返回结果"
Ctrl-->>Client : "CommonResult"
Client->>Ctrl : "GET /import/mac-pool"
Ctrl->>Svc : "saveMacPool(files)"
Svc->>Mapper : "insertMacPool(list)"
Mapper->>DB : "批量插入"
DB-->>Mapper : "影响行数"
Mapper-->>Svc : "返回计数"
Svc-->>Ctrl : "返回计数"
Ctrl-->>Client : "CommonResult"
Client->>Ctrl : "GET /count/mac-pool"
Ctrl->>Svc : "countMacPool()"
Svc->>Mapper : "selectCountByStatus(0)"
Mapper->>DB : "查询未分配数量"
DB-->>Mapper : "计数"
Mapper-->>Svc : "返回计数"
Svc-->>Ctrl : "返回计数"
Ctrl-->>Client : "CommonResult"

图表来源

详细组件分析​

控制器层：DeviceInfoModifyController​

  • 权限控制：使用注解对各接口进行权限校验，如创建/更新/删除/查询/导出/导入等
  • 操作审计：通过注解开启 API 访问日志，导出/导入操作记录操作类型
  • 接口职责：
    • 创建/更新/删除/查询/分页
    • 导出 Excel
    • 导入 MAC 池（Excel）
    • 统计未分配 MAC 数量

章节来源

服务层：DeviceInfoModifyServiceImpl​

  • 核心逻辑：
    • 创建/更新/删除/查询/分页：委托 Mapper 执行
    • 导入 MAC 池：解析 Excel，批量写入数据库
    • 统计未分配 MAC：按状态计数
    • 系统自动分配 MAC：从 Redis 弹出可用 MAC，更新分配设备信息
    • 缓存加载：首次加载未分配 MAC 到 Redis，带重入锁避免重复加载

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> Pop["Redis 弹出可用 MAC"]
Pop --> Has{"是否为空？"}
Has --> |是| Load["加载未分配 MAC 到 Redis"]
Load --> Pop2["再次弹出"]
Has --> |否| Use["使用该 MAC"]
Pop2 --> Has2{"仍为空？"}
Has2 --> |是| ReturnNull["返回空无可分配 MAC"]
Has2 --> |否| Use2["使用该 MAC"]
Use & Use2 --> Update["更新分配设备信息<br/>status=1, allocated_time, deviceMac, cpu"]
Update --> Done(["结束"])
ReturnNull --> Done

图表来源

章节来源

数据访问层：DeviceInfoModifyMapper 与 XML​

  • Mapper 方法：
    • selectPage：按条件分页查询
    • insertMacPool：批量插入 MAC 池
    • selectUnallocatedMac：查询未分配 MAC（限制数量）
    • updateAllocationDeviceByAllocatedMac：更新分配设备信息
    • selectCountByStatus：按状态计数
  • XML 提供 insertMacPool 的批量插入 SQL

章节来源

数据对象：DeviceInfoModifyDO​

  • 字段说明：
    • id：主键
    • allocatedMac：分配的 MAC
    • deviceMac：设备原 MAC
    • cpu：CPU 信息
    • status：MAC 分配状态（0 未分配，1 已分配）
    • allocatedTime：分配时间
    • createTime/updateTime：创建/更新时间
    • creator/updater：创建者/更新者标识

章节来源

请求/响应结构：VO/DTO​

  • 管理后台：
    • DeviceInfoModifySaveReqVO：新增/修改请求，包含 id、allocatedMac、deviceMac、cpu、status、allocatedTime 等
    • DeviceInfoModifyPageReqVO：分页查询请求，支持按 allocatedMac、deviceMac、cpu、status、时间区间过滤
  • APP/RPC：
    • AppDeviceInfoModifyReqVO：APP 修改请求，包含 mac、cpu、可选 macs 数组
    • DeviceModifyRespDTO：RPC 响应，包含 mac、cpu、可选 macs 数组

章节来源

依赖关系分析​

  • 控制器依赖服务接口 DeviceInfoModifyService
  • 服务实现依赖 Mapper 接口与 Redis DAO（通过类名可见）
  • Mapper 依赖 XML SQL 与数据库
  • VO/DTO 作为接口契约，贯穿控制器与服务层

Mermaid Diagram Code:

classDiagram
class DeviceInfoModifyController
class DeviceInfoModifyService
class DeviceInfoModifyServiceImpl
class DeviceInfoModifyMapper
class DeviceInfoModifyDO
class DeviceInfoModifySaveReqVO
class DeviceInfoModifyPageReqVO
class AppDeviceInfoModifyReqVO
class DeviceModifyRespDTO
DeviceInfoModifyController --> DeviceInfoModifyService : "依赖"
DeviceInfoModifyServiceImpl ..|> DeviceInfoModifyService : "实现"
DeviceInfoModifyServiceImpl --> DeviceInfoModifyMapper : "调用"
DeviceInfoModifyMapper --> DeviceInfoModifyDO : "映射"
DeviceInfoModifyController --> DeviceInfoModifySaveReqVO : "请求"
DeviceInfoModifyController --> DeviceInfoModifyPageReqVO : "请求"
DeviceInfoModifyServiceImpl --> AppDeviceInfoModifyReqVO : "系统分配返回"
DeviceInfoModifyServiceImpl --> DeviceModifyRespDTO : "RPC 响应"

图表来源

性能与并发特性​

  • 批量导入：使用 EasyExcel 分页监听器逐批处理，减少内存占用
  • Redis 缓存：未分配 MAC 预热到 Redis，降低数据库压力；带过期策略
  • 双重检查加锁：避免重复加载缓存，保证并发安全
  • 分页查询：支持按多个维度过滤，提升检索效率

章节来源

安全与合规​

  • 权限控制：所有接口均标注权限注解，仅授权用户可访问
  • 参数校验：请求 VO 使用注解进行必填/格式校验
  • 操作审计：启用 API 访问日志，记录导出/导入等关键操作
  • 数据隔离：服务层统一校验记录存在性，防止越权删除/更新
  • 合规建议（概念性）：
    • 审批流程：对敏感字段修改增加审批流（如品牌、系统版本、构建号、内存配置），结合审批状态字段记录审批人与时间
    • 变更记录：建立变更历史表，记录每次修改前后的值、操作人、审批状态、操作时间
    • 数据脱敏：导出/展示时对敏感字段进行脱敏处理
    • 审计日志：完善字段级审计，支持回溯与合规检查

章节来源

故障排查​

  • 导入失败：检查 Excel 格式与字段映射，查看日志异常堆栈
  • 无可用 MAC：确认 MAC 池是否已加载或是否存在未分配记录
  • 权限不足：确认用户角色是否具备相应权限
  • 查询无结果：检查分页参数与过滤条件

章节来源

结论​

当前实现提供了完善的“设备信息修改记录”管理能力与 MAC 分配池的导入/统计功能，并通过权限控制、参数校验与操作日志保障基本安全与可追溯性。若需覆盖品牌、系统版本、构建号、内存配置等更广泛的设备信息修改场景，可在现有基础上扩展审批流、变更历史与字段级审计，以满足更高合规要求。

附录：API 接口文档​

  • 创建设备信息修改记录

    • 方法与路径：POST /device/info-modify/create
    • 权限：device:info-modify:create
    • 请求体：DeviceInfoModifySaveReqVO
    • 响应：Long（记录编号）

  • 更新设备信息修改记录

    • 方法与路径：PUT /device/info-modify/update
    • 权限：device:info-modify:update
    • 请求体：DeviceInfoModifySaveReqVO
    • 响应：Boolean（true）

  • 删除设备信息修改记录

    • 方法与路径：DELETE /device/info-modify/delete?id={id}
    • 权限：device:info-modify:delete
    • 参数：id（Long）
    • 响应：Boolean（true）

  • 获取设备信息修改记录

    • 方法与路径：GET /device/info-modify/get?id={id}
    • 权限：device:info-modify:query
    • 参数：id（Long）
    • 响应：DeviceInfoModifyRespVO

  • 分页查询设备信息修改记录

    • 方法与路径：GET /device/info-modify/page
    • 权限：device:info-modify:query
    • 查询参数：DeviceInfoModifyPageReqVO（支持按 allocatedMac、deviceMac、cpu、status、allocatedTime、createTime 过滤）
    • 响应：PageResult<DeviceInfoModifyRespVO>

  • 导出设备信息修改记录 Excel

    • 方法与路径：GET /device/info-modify/export-excel
    • 权限：device:info-modify:export
    • 查询参数：DeviceInfoModifyPageReqVO（不分页，一次性导出全部）
    • 响应：Excel 文件

  • 导入分配 MAC Excel

    • 方法与路径：POST /device/info-modify/import/mac-pool
    • 权限：device:info-modify:import
    • 请求：multipart/form-data（文件列表）
    • 响应：Integer（导入成功数量）

  • 统计未分配 MAC 数量

    • 方法与路径：GET /device/info-modify/count/mac-pool
    • 权限：无需
    • 响应：Long（未分配数量）

  • APP 设备信息修改（系统分配 MAC）

    • 方法与路径：RPC/内部调用（系统自动分配）
    • 请求：AppDeviceInfoModifyReqVO（包含 mac、cpu、可选 macs）
    • 响应：AppDeviceInfoModifyReqVO（返回分配的 mac）

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答