DM-ROW 接口文档

Appearance

文件与配置管理 ​

**本文引用的文件** - [FileServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/service/impl/FileServiceImpl.java) - [AttachmentEntity.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/entity/AttachmentEntity.java) - [AttachmentMapper.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/dao/AttachmentMapper.java) - [SystemOpenApiController.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/controller/SystemOpenApiController.java) - [OpenApiService.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/service/OpenApiService.java) - [OssController.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/controller/OssController.java) - [document.vue（设备）](file://app/devicemate-app/modules/equipment/document.vue) - [document.vue（维修）](file://app/devicemate-app/modules/repair/components/document.vue) - [document.vue（保养）](file://app/devicemate-app/modules/maintain/components/document.vue) - [seaweedfs-ingress.yaml](file://lemes-cloud/src/devops/k8s/service/base/seaweedfs-ingress.yaml) - [application.properties](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/resources/application.properties) - [CaptchaCacheServiceRedisHandler](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/resources/META-INF/services/com.anji.captcha.service.CaptchaCacheService)

目录 ​

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

简介 ​

本技术文档围绕“文件与配置管理系统”展开，系统由三层组成：前端移动端应用（uni-app）、后端微服务网关与业务服务（Spring Boot 微服务），以及对象存储（SeaweedFS）。文档重点覆盖以下方面：

  • 文件管理：上传、下载、存储、删除、批量操作、按业务键与目标ID检索等核心能力
  • 配置管理：系统开放API配置项的增删改查、启用禁用、导入校验等
  • 存储策略：基于 SeaweedFS 的对象存储接入、网关层路由与超时配置
  • 安全与合规：下载路径拼接、文件存在性检查、访问鉴权与权限控制
  • API 接口：文件上传下载、配置项查询与更新的完整说明
  • 实战示例：设备管理、工单处理等业务场景中的文件与配置使用方式
  • 最佳实践：文件安全、存储优化与性能提升建议

项目结构 ​

系统采用前后端分离架构，前端通过 uni-app 提供多端一致的交互体验；后端通过 Spring Cloud Gateway 聚合各微服务，文件与配置相关能力分别由业务服务与通用服务模块提供。

图表来源

章节来源

核心组件 ​

  • 文件服务实现：负责文件上传、下载、删除、更新、批量保存、按业务键与目标ID检索等
  • 附件实体与映射：定义附件表字段及 MyBatis Mapper 接口
  • OSS 控制器：提供对象存储的下载、存在性检查、重命名、目录创建等接口
  • OpenAPI 控制器：提供系统开放API配置的分页查询、新增/修改、删除、启用禁用、导入校验等
  • 前端页面组件：设备、维修、保养模块的文档列表与下载逻辑

章节来源

架构总览 ​

系统通过网关统一对外暴露文件与配置相关接口，文件下载链路经由 OSS 控制器转发至对象存储，前端通过 baseUrl 与 filePath 组合访问具体资源。

图表来源

详细组件分析 ​

文件服务组件（FileServiceImpl） ​

  • 职责
    • 单文件/多文件上传：生成文件元信息并写入数据库，同时上传至对象存储
    • 文件下载：根据文件路径与桶名从对象存储读取并返回字节流
    • 文件删除：支持单个或批量删除，同时更新数据库标记
    • 文件更新：支持更新文件元信息与替换文件内容
    • 文件查询：支持按业务键+目标ID、按业务键+ID集合、按文件名等条件查询
    • 语言维度去重：同一业务键+语言维度下同名文件仅保留一条
  • 关键点
    • 上传路径规则：businessKey/原文件名
    • 默认桶名：通过配置注入，默认值指向 SeaweedFS Web 服务器地址
    • 多语言支持：langName 字段用于区分不同语言环境下的同名文件
    • 权限范围：scope 字段用于标识附件所属权限范围（如全局或部门）

图表来源

章节来源

OSS 控制器（OssController） ​

  • 职责
    • 流式下载：支持浏览器下载进度条显示
    • 存在性检查：判断指定桶与路径是否存在
    • 重命名：支持桶、目录、文件重命名
    • 目录创建：通过上传空文件占位实现空目录创建
  • 关键点
    • 路径解析：自动剥离 /oss/download/ 或 /oss/exist/ 前缀
    • 默认桶参数：支持 useDefaultBucket 参数切换是否使用默认桶
    • 访问控制：部分接口需要特定权限注解

图表来源

章节来源

OpenAPI 配置管理（SystemOpenApiController） ​

  • 职责
    • 分页查询：支持按模块与请求路径过滤
    • 新增/修改：校验请求路径与模块组合唯一性
    • 删除：按ID删除
    • 启用/禁用：动态开关
    • 导入校验：批量导入前先校验是否存在
    • 批量导入：去除ID后批量保存
  • 关键点
    • 权限控制：基于自定义权限注解
    • 国际化提示：通过工具类获取多语言提示文本

图表来源

章节来源

前端文档下载组件 ​

  • 设备文档页：拉取设备号对应的文件列表，点击后通过 baseUrl 与 filePath 拼接下载地址，使用 plus.downloader 进行下载并尝试打开
  • 维修/保养文档组件：复用相同下载逻辑，props 传入数据列表

图表来源

章节来源

依赖分析 ​

  • 文件服务依赖对象存储工具与附件实体/映射，通过 MyBatis Plus 持久化
  • OSS 控制器依赖对象存储属性与工具类，提供下载与管理能力
  • OpenAPI 控制器依赖服务层进行数据网格与业务操作
  • 前端组件依赖后端提供的文件列表与下载接口

图表来源

章节来源

性能考虑 ​

  • 流式下载：OSS 控制器采用流式输出，避免一次性加载大文件到内存，降低内存峰值
  • 超时与缓冲：Ingress 对代理连接、发送、读取超时进行了配置，适合大文件传输
  • 批量操作：文件服务支持批量保存与批量删除，减少网络往返次数
  • 缓存与验证码：通用服务启用了 Redis 缓存验证码，有助于提升登录与验证场景的响应速度

章节来源

故障排查指南 ​

  • 下载失败
    • 检查 baseUrl 与 filePath 拼接是否正确
    • 确认对象存储中文件是否存在，可通过 /oss/exist/** 接口校验
    • 查看网关 Ingress 的超时与代理配置是否合理
  • 文件上传后无法查询
    • 核对业务键 businesskey 与目标ID targetId 是否匹配
    • 检查语言维度 langName 是否与当前语言一致
  • OpenAPI 配置冲突
    • 新增/修改时若提示请求路径与模块组合已存在，请调整模块或路径
  • 验证码缓存问题
    • 若验证码相关功能异常，检查 Redis 配置与 CaptchaCacheService 实现

章节来源

结论 ​

本系统以“文件服务 + OSS 控制器 + OpenAPI 配置管理”为核心，结合 uni-app 前端组件，实现了设备、维修、保养等业务场景下的文件上传、下载、存储与配置管理能力。通过对象存储与网关层的配合，系统具备良好的扩展性与性能表现。建议在生产环境中进一步完善鉴权策略、监控告警与备份恢复机制，确保数据安全与高可用。

附录 ​

API 接口清单（文件与配置） ​

  • 文件上传
    • 方法：POST
    • 路径：/dm-common/file/save
    • 参数：multipartFile、businessKey、scope、targetId、fileId
    • 返回：文件元信息（含 baseUrl、filePath 等）
  • 文件下载
    • 方法：GET
    • 路径：/oss/download/**?bucket=...&path=...
    • 返回：文件字节流（带 Content-Disposition）
  • 文件删除
    • 方法：DELETE
    • 路径：/dm-common/file/delete
    • 参数：fileId 或 fileIds
  • 文件查询
    • 方法：GET
    • 路径：/dm-common/file/list
    • 参数：businessKey、targetId 或 ids
  • OpenAPI 配置
    • 列表：GET /system/open-api/dataGrid
    • 新增/修改：POST /system/open-api/addOrUpdate
    • 删除：GET /system/open-api/delete?id=...
    • 启用/禁用：GET /system/open-api/changeEnabled?id=...&enabled=...
    • 导入校验：POST /system/open-api/checkData
    • 批量导入：POST /system/open-api/importData

章节来源