任务文件表结构

引用文件

本文引用的文件

简介

本文档围绕任务系统中的文件管理子系统展开，重点阐述任务文件表（infra_file_content）的设计与实现，涵盖字段定义、文件存储策略、命名与路径组织、版本管理机制，以及与任务表、UOTA详情表的关联关系。同时提供文件上传、下载、删除等典型操作流程与数据示例，帮助读者全面理解任务文件在整个系统中的作用与最佳实践。

项目结构

任务文件管理由基础设施模块（infra）提供通用文件能力，任务模块（task）消费这些能力并将其与具体业务（如 UOTA 升级包）结合。关键文件分布如下：

数据库层：infra_file_config（文件配置）、infra_file_content（文件内容）
基础设施模块：文件上传、下载、删除接口与服务实现
任务模块：UOTA 明细与文件的关联、任务模块对文件使用的检查

Mermaid Diagram Code:

graph TB
subgraph "基础设施模块(infra)"
FC["文件控制器<br/>FileController"]
FS["文件服务实现<br/>FileServiceImpl"]
FSE["文件存储器枚举<br/>FileStorageEnum"]
FCF["文件客户端工厂<br/>FileClientFactoryImpl"]
end
subgraph "任务模块(task)"
TFA["任务文件接口<br/>TaskFileApi"]
UDDO["UOTA明细实体<br/>UotaDetailDO"]
UDM["UOTA明细Mapper<br/>UotaDetailMapper"]
UDS["UOTA明细Service<br/>UotaDetailServiceImpl"]
UDVO["UOTA明细响应VO<br/>UotaDetailRespVO"]
FUM["UOTA MAC关联Mapper<br/>FlowUotaMacMapper"]
FUMVO["UOTA MAC响应VO<br/>FlowUotaMacRespVO"]
end
subgraph "数据库"
IFC["infra_file_content<br/>文件内容表"]
IFCFG["infra_file_config<br/>文件配置表"]
end
FC --> FS
FS --> FSE
FS --> FCF
TFA --> UDS
UDS --> UDDO
UDS --> UDM
UDS --> FUM
UDS --> IFC
FS --> IFC
FS --> IFCFG

图表来源

章节来源

核心组件

任务文件表（infra_file_content）
- 字段：id、config_id、path、content、creator、create_time、updater、update_time、deleted
- 用途：存储文件的物理内容与元数据，支持多配置（config_id）隔离
文件配置表（infra_file_config）
- 字段：id、name、storage、remark、master、config、creator、create_time、updater、update_time、deleted
- 用途：定义文件存储器类型与配置，支持主配置切换
文件服务（FileServiceImpl）
- 功能：上传（后端模式）、删除、创建记录、生成预签名下载链接
任务模块文件使用检查（TaskFileApi）
- 功能：校验某文件是否在任务模块中被使用，避免误删

章节来源

架构总览

文件管理采用“配置驱动 + 多存储器”的架构：

通过 infra_file_config 管理存储器配置（本地、FTP、SFTP、S3 等）
通过 FileStorageEnum 与 FileClientFactoryImpl 解耦不同存储器
通过 infra_file_content 存储文件内容，记录文件元数据
任务模块通过 TaskFileApi 检查文件使用状态，确保安全删除

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant InfraCtrl as "基础设施控制器<br/>FileController"
participant InfraSvc as "基础设施服务<br/>FileServiceImpl"
participant Store as "文件存储器<br/>FileClientFactoryImpl"
participant DB as "数据库<br/>infra_file_content"
Client->>InfraCtrl : "POST /infra/file/upload/m3"
InfraCtrl->>InfraSvc : "上传文件(后端模式)"
InfraSvc->>Store : "获取主配置客户端"
Store-->>InfraSvc : "返回存储器实例"
InfraSvc->>Store : "上传文件(路径/内容/类型)"
Store-->>InfraSvc : "返回访问URL"
InfraSvc->>DB : "插入文件记录(配置ID/路径/URL/大小)"
DB-->>InfraSvc : "插入成功"
InfraSvc-->>InfraCtrl : "返回URL"
InfraCtrl-->>Client : "上传完成"

图表来源

详细组件分析

任务文件表（infra_file_content）设计

字段说明
- id：文件记录编号（主键）
- config_id：文件配置编号（外键，关联 infra_file_config）
- path：文件在存储器中的相对路径
- content：文件二进制内容（大对象）
- creator/updater：创建/更新人
- create_time/update_time：创建/更新时间
- deleted：逻辑删除标志
设计要点
- 将“内容”与“元数据”分离：便于扩展其他存储介质（如对象存储）
- 通过 config_id 支持多配置隔离与切换
- 使用逻辑删除，保障历史任务引用的完整性

章节来源

infra_file_content 表结构定义

文件配置表（infra_file_config）设计

字段说明
- id：配置编号
- name：配置名称
- storage：存储器类型（枚举值）
- remark：备注
- master：是否主配置（同一时刻仅允许一个）
- config：存储配置（JSON）
- 其余为通用审计字段
设计要点
- 主配置用于系统默认上传场景
- config 字段承载不同存储器的动态参数
- 通过枚举 FileStorageEnum 统一管理存储器类型

章节来源

文件存储策略

存储器类型
- DB：将文件直接存入数据库（适合小文件）
- LOCAL：本地磁盘
- FTP/SFTP：网络文件传输协议
- S3：兼容 S3 的对象存储
命名与路径组织
- 建议采用“年/月/日/随机前缀_原始文件名”的层级结构，便于检索与清理
- 路径统一由服务端生成，避免客户端污染
版本管理
- 通过“同名文件覆盖即产生新记录”的方式实现版本化
- 删除时遵循任务模块使用检查，避免误删正在使用的文件

章节来源

任务文件与任务系统的关系

与 UOTA 明细的关联
- UotaDetailDO 通过 infraFileId 关联到 infra_file_content 的 id
- UotaDetailMapper 提供按 infraFileId 的查询能力
- UotaDetailServiceImpl 在创建 UOTA 明细时，会通过 InfraFileUtil 获取文件信息，确保文件存在且可用
与任务模块的交互
- TaskFileApi 提供 checkFileUseOnTask 接口，用于判断某文件是否在任务模块中被使用
- 删除文件前，任务模块可调用该接口进行安全检查

Mermaid Diagram Code:

erDiagram
INFRA_FILE_CONFIG {
bigint id PK
string name
integer storage
string remark
bit master
json config
string creator
datetime create_time
string updater
datetime update_time
bit deleted
}
INFRA_FILE_CONTENT {
bigint id PK
bigint config_id FK
string path
mediumblob content
string creator
datetime create_time
string updater
datetime update_time
bit deleted
}
TASK_UOTA_DETAIL {
bigint id PK
string name
bigint infra_file_id FK
integer company
string package_name
string version_code
string version_name
datetime create_time
datetime update_time
}
INFRA_FILE_CONFIG ||--o{ INFRA_FILE_CONTENT : "配置-内容"
TASK_UOTA_DETAIL }o--|| INFRA_FILE_CONTENT : "引用文件"

图表来源

章节来源

文件上传、下载、删除流程

上传流程（后端模式）

接口：POST /infra/file/upload/m3
步骤：
1. 服务端获取主配置客户端
2. 调用存储器上传（传入内容、路径、类型）
3. 写入 infra_file_content 记录（config_id/path/url/type/size）
4. 返回访问 URL

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant Ctrl as "FileController"
participant Svc as "FileServiceImpl"
participant Fac as "FileClientFactoryImpl"
participant DB as "infra_file_content"
C->>Ctrl : "POST /infra/file/upload/m3"
Ctrl->>Svc : "createFile(后端模式)"
Svc->>Fac : "获取主配置客户端"
Fac-->>Svc : "返回客户端"
Svc->>Svc : "上传文件(内容/路径/类型)"
Svc->>DB : "insert(配置ID/路径/URL/大小)"
DB-->>Svc : "成功"
Svc-->>Ctrl : "返回URL"
Ctrl-->>C : "上传完成"

图表来源

下载流程

接口：GET /infra/file/{configId}/get/**（带路径）
步骤：
1. 根据 configId 选择对应存储器
2. 读取存储器中的文件内容
3. 返回给客户端

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant Ctrl as "FileController"
participant Svc as "FileServiceImpl"
participant Fac as "FileClientFactoryImpl"
participant Store as "存储器"
C->>Ctrl : "GET /infra/file/{configId}/get/**"
Ctrl->>Svc : "getFileContent(路径)"
Svc->>Fac : "获取配置客户端(configId)"
Fac-->>Svc : "返回客户端"
Svc->>Store : "读取文件内容"
Store-->>Svc : "返回内容"
Svc-->>Ctrl : "输出到响应"
Ctrl-->>C : "下载完成"

图表来源

删除流程

接口：DELETE /infra/file/delete?id={id}
步骤：
1. 任务模块调用 TaskFileApi.checkFileUseOnTask 检查文件是否被使用
2. 若未使用，删除 infra_file_content 记录
3. 若存在多条记录指向同一 URL，则仅删除记录而不删除物理文件

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> CheckUse["调用 TaskFileApi.checkFileUseOnTask"]
CheckUse --> Used{"是否被使用？"}
Used --> |是| Abort["终止删除，提示不可删除"]
Used --> |否| LoadFiles["按URL查询所有文件记录"]
LoadFiles --> Multi{"是否存在多条记录？"}
Multi --> |是| DeleteRecord["仅删除记录"]
Multi --> |否| DeletePhysical["删除物理文件与记录"]
DeleteRecord --> End(["结束"])
DeletePhysical --> End
Abort --> End

图表来源

不同类型文件的管理机制

固件文件（UOTA 升级包）
- 通过 UOTA 明细表 task_uota_detail 的 infra_file_id 关联到 infra_file_content
- 支持按包名、版本号、平台等条件筛选与下发
配置文件
- 作为普通文件上传，记录在 infra_file_content，供任务或设备侧按需拉取
日志文件
- 可通过相同流程上传，便于集中存储与检索

章节来源

依赖关系分析

存储器解耦
- FileStorageEnum 定义存储器类型与客户端类映射
- FileClientFactoryImpl 负责创建/刷新存储器客户端实例
任务模块依赖
- UotaDetailServiceImpl 依赖 InfraFileUtil 获取文件信息
- TaskFileApi 为任务模块提供文件使用检查能力
数据一致性
- 通过 config_id 与 infra_file_content 的 id 建立强关联
- 通过逻辑删除与 URL 去重，避免误删与重复存储

Mermaid Diagram Code:

classDiagram
class FileStorageEnum {
+getByStorage(storage)
+storage
+configClass
+clientClass
}
class FileClientFactoryImpl {
+getFileClient(configId)
+createOrUpdateFileClient(configId, storage, config)
}
class FileServiceImpl {
+upload(content, path, type)
+createFile(req)
+deleteFile(id)
}
class UotaDetailServiceImpl {
+createUotaDetail(req)
}
FileStorageEnum --> FileClientFactoryImpl : "提供客户端类映射"
FileClientFactoryImpl --> FileServiceImpl : "提供存储器实例"
UotaDetailServiceImpl --> FileServiceImpl : "获取文件信息"

图表来源

章节来源

性能考虑

大文件上传
- 建议优先使用对象存储（S3）以提升并发与稳定性
- 控制单次上传大小，必要时采用分片上传策略
查询优化
- 为 path、url、config_id 建立索引，加速检索
- 对高频查询（如按包名/版本）建立复合索引
删除策略
- 仅删除记录而不删除物理文件，减少 IO 压力
- 定期清理逻辑删除的文件与无引用的文件

故障排除指南

无法上传文件
- 检查主配置是否正确，存储器是否可用
- 核对存储配置（endpoint、bucket、key 等）是否正确
下载失败
- 确认路径是否正确，存储器是否允许公开访问
- 检查预签名 URL 是否过期
删除报错
- 先调用 TaskFileApi.checkFileUseOnTask 确认未被使用
- 若存在多条记录指向同一 URL，系统不会删除物理文件

章节来源

结论

任务文件表（infra_file_content）通过清晰的字段设计与配置驱动的存储器体系，实现了对固件、配置、日志等各类文件的统一管理。结合任务模块的使用检查与 UOTA 明细的关联，系统在保证安全性的同时，具备良好的扩展性与可维护性。建议在生产环境中优先采用对象存储，完善索引与清理策略，确保高并发下的稳定运行。

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

任务文件表（infra_file_content）设计​

文件配置表（infra_file_config）设计​

文件存储策略​

任务文件与任务系统的关系​

文件上传、下载、删除流程​

上传流程（后端模式）​

下载流程​

删除流程​

不同类型文件的管理机制​

依赖关系分析​

性能考虑​

故障排除指南​

结论​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

任务文件表（infra_file_content）设计

文件配置表（infra_file_config）设计

文件存储策略

任务文件与任务系统的关系

文件上传、下载、删除流程

上传流程（后端模式）

下载流程

删除流程

不同类型文件的管理机制

依赖关系分析

性能考虑

故障排除指南

结论