crm-backend-matt/.qoder/repowiki/zh/content/项目概览/模块说明/文件服务模块(crm-file).md

# 文件服务模块(crm-file)

<cite>
**本文引用的文件**   
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)
- [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java)
- [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java)
- [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java)
- [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java)
- [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java)
- [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java)
- [ThumbnailDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/ThumbnailDTO.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [ThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailRenderer.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [ThumbnailImageUtils.java](file://crm-file/src/main/java/com/crm/file/service/impl/ThumbnailImageUtils.java)
- [ThumbnailPlaceholderService.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailPlaceholderService.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
</cite>

## 更新摘要
**变更内容**   
- 新增完整的缩略图预览系统，支持异步生成、分布式锁和重试机制
- 添加多种渲染器实现：图片渲染器、PDF渲染器、Office文档渲染器
- 新增缩略图API端点 /api/file/thumbnail
- 集成缩略图生成任务和失败重试任务
- 增强配置支持，包括缩略图尺寸、超时、重试限制等
- 添加占位图服务，为不支持的文件类型提供默认图标

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

## 简介
本文件为 crm-file 文件服务模块的详细技术文档。该模块提供统一的文件上传下载、分片上传与断点续传、在线预览、缩略图生成、存储管理与元数据管理等功能，并通过 MinIO 作为对象存储后端，结合定时任务清理孤立的分片文件和失败的缩略图生成任务，保障系统稳定性与可维护性。文档面向开发者与运维人员，既包含接口设计、配置项说明，也涵盖并发处理、性能优化与扩展方案。

**更新** 新增了完整的缩略图预览系统，支持图片、PDF和Office文档的自动缩略图生成，具备异步处理、分布式锁保护、失败重试和占位图回退等高级特性。

## 项目结构
crm-file 模块采用分层组织：
- API 层：对外暴露统一接口定义（FileApi）
- Controller 层：HTTP 控制器（FileController）
- Service 层：业务逻辑实现（FileApiImpl、FileInfoServiceImpl、缩略图渲染器）
- Client 层：第三方能力集成（KkFileViewClient）
- Config 层：配置与初始化（MinioConfig、FileProperties、SchedulingConfig）
- Domain 层：实体与 DTO（FileInfo、UploadSession、各类 DTO、ThumbnailDTO）
- Mapper 层：持久化访问（FileInfoMapper）
- Task 层：定时任务（OrphanChunkCleanupTask、ThumbnailGenerationTask、ThumbnailRetryTask）
- Constant 层：常量定义（FileConstants）

```mermaid
graph TB
subgraph "API 层"
A["FileApi"]
end
subgraph "控制器层"
C["FileController"]
end
subgraph "服务层"
S1["FileApiImpl"]
S2["FileInfoServiceImpl"]
S3["ThumbnailRenderer"]
S4["ImageThumbnailRenderer"]
S5["PdfThumbnailRenderer"]
S6["OfficeThumbnailRenderer"]
S7["ThumbnailPlaceholderService"]
end
subgraph "客户端层"
K["KkFileViewClient"]
end
subgraph "配置层"
M["MinioConfig"]
F["FileProperties"]
SC["SchedulingConfig"]
end
subgraph "领域层"
E["FileInfo"]
D1["UploadSession"]
D2["MultipartInitDTO"]
D3["FileDownloadDTO"]
D4["FileInfoDTO"]
D5["ThumbnailDTO"]
end
subgraph "持久化层"
MAP["FileInfoMapper"]
end
subgraph "任务层"
T1["OrphanChunkCleanupTask"]
T2["ThumbnailGenerationTask"]
T3["ThumbnailRetryTask"]
end
subgraph "常量层"
CON["FileConstants"]
end
A --> C
C --> S1
C --> S2
S1 --> MAP
S1 --> K
S1 --> M
S1 --> F
S2 --> MAP
T1 --> MAP
T1 --> F
T2 --> MAP
T2 --> F
T3 --> MAP
S1 --> E
S1 --> D1
S1 --> D2
S1 --> D3
S1 --> D4
S1 --> D5
S2 --> E
S1 --> CON
S2 --> CON
S3 --> S4
S3 --> S5
S3 --> S6
```

**图表来源**
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [ThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailRenderer.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)

## 核心组件
- FileController：HTTP 接口入口，封装上传、分片上传、下载、预览、缩略图等请求到服务层。
- FileApi 与 FileApiImpl：文件操作的核心服务接口与实现，协调 MinIO、分片会话、元数据持久化、预览服务和缩略图生成。
- FileInfoServiceImpl：文件信息管理服务，负责文件元数据的增删改查与状态维护。
- KkFileViewClient：对接 kkFileView 进行在线预览，返回预览链接或流式内容。
- **缩略图渲染器体系**：ThumbnailRenderer 接口及具体实现（ImageThumbnailRenderer、PdfThumbnailRenderer、OfficeThumbnailRenderer），支持多种文件类型的缩略图生成。
- **缩略图任务系统**：ThumbnailGenerationTask 负责异步生成缩略图，ThumbnailRetryTask 处理失败重试。
- **缩略图占位图服务**：ThumbnailPlaceholderService 为不支持的文件类型生成默认图标。
- MinioConfig 与 FileProperties：MinIO 客户端与文件相关配置（端点、桶名、密钥、分片大小、超时、缩略图配置等）。
- FileInfoMapper：文件元数据持久化访问。
- OrphanChunkCleanupTask：定时清理未完成的分片上传残留，释放存储空间。
- 领域模型：FileInfo（文件元数据）、UploadSession（分片会话）、ThumbnailDTO（缩略图传输对象）、各 DTO（上传初始化、下载参数、文件信息等）。

**更新** 新增了完整的缩略图功能组件，包括渲染器接口、多种渲染器实现、异步生成任务和失败重试机制。

## 架构总览
文件服务模块以 HTTP 接口为入口，通过服务层编排 MinIO 对象存储、kkFileView 预览服务、缩略图生成系统和数据库元数据持久化。分片上传流程由 UploadSession 驱动，支持断点续传；下载流程支持范围请求与流式输出；预览通过 kkFileView 生成预览地址或直接返回内容；缩略图生成采用异步处理，支持分布式锁避免重复生成，具备失败重试和占位图回退机制。定时任务定期扫描并清理孤立分片和失败的缩略图生成任务，避免存储膨胀和服务异常。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "FileController"
participant Service as "FileApiImpl"
participant ThumbnailTask as "ThumbnailGenerationTask"
participant Renderer as "ThumbnailRenderer"
participant MinIO as "MinIO 客户端"
participant DB as "FileInfoMapper"
participant Preview as "KkFileViewClient"
Client->>Controller : "发起上传/分片上传/下载/预览/缩略图请求"
Controller->>Service : "调用文件服务方法"
alt 普通上传
Service->>MinIO : "上传完整文件"
Service->>DB : "写入文件元数据"
Service->>ThumbnailTask : "触发异步缩略图生成"
Service-->>Controller : "返回文件信息"
else 缩略图获取
Service->>DB : "查询文件缩略图状态"
alt 已就绪
Service->>MinIO : "读取缩略图"
Service-->>Controller : "返回缩略图"
else 生成中
Service->>ThumbnailTask : "尝试同步生成(分布式锁)"
ThumbnailTask->>Renderer : "执行渲染"
Renderer->>MinIO : "生成缩略图"
ThumbnailTask->>DB : "更新缩略图状态"
Service-->>Controller : "返回缩略图或占位图"
end
else 分片上传
Service->>Service : "初始化分片会话(UploadSession)"
loop 每个分片
Client->>Service : "上传分片(chunk)"
Service->>MinIO : "上传分片"
Service->>Service : "更新分片进度"
end
Service->>MinIO : "合并分片"
Service->>DB : "写入文件元数据"
Service->>ThumbnailTask : "触发异步缩略图生成"
Service-->>Controller : "返回文件信息"
else 下载
Service->>MinIO : "读取文件流"
Service-->>Controller : "返回文件流"
else 预览
Service->>Preview : "生成预览链接/获取预览内容"
Preview-->>Service : "预览结果"
Service-->>Controller : "返回预览结果"
end
Controller-->>Client : "响应结果"
```

**图表来源**
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailRenderer.java)
- [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)

## 详细组件分析

### 控制器层：FileController
- 职责：接收 HTTP 请求，校验参数，路由到对应服务方法，处理响应格式与异常。
- 关键能力：
  - 文件上传：支持单文件与多文件上传。
  - 分片上传：初始化会话、上传分片、合并分片。
  - 文件下载：按文件标识或路径下载，支持范围请求。
  - 文件预览：调用预览服务返回预览链接或内容。
  - **缩略图获取**：新增 `/api/file/thumbnail` 端点，支持缩略图获取、缓存控制和状态码处理。
- 错误处理：对非法参数、权限不足、存储异常等进行统一包装与提示。

**更新** 新增了缩略图获取端点，支持动态缓存策略和HTTP状态码控制。

章节来源
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)

### 服务层：FileApi 与 FileApiImpl
- 职责：实现文件上传、分片上传、断点续传、下载、预览、缩略图生成等核心业务逻辑。
- 关键能力：
  - 分片会话管理：基于 UploadSession 跟踪分片上传状态，支持断点续传。
  - MinIO 集成：上传、分片上传、合并分片、下载流式读取。
  - 元数据管理：创建、更新、查询文件元数据（FileInfo）。
  - 预览集成：通过 KkFileViewClient 获取预览链接或内容。
  - **缩略图管理**：完整的缩略图生命周期管理，包括状态判断、异步生成、同步兜底、占位图回退。
- 并发处理：对分片上传进行并发控制，确保分片顺序与完整性；缩略图生成使用分布式锁避免重复处理。
- 事务与一致性：在分片合并成功后再持久化元数据，保证最终一致性；缩略图状态机确保一致性。

**更新** 新增了完整的缩略图处理逻辑，包括状态判断、异步生成触发、同步兜底机制和占位图回退。

```mermaid
classDiagram
class FileApi {
+ "上传文件(file)"
+ "分片初始化(params)"
+ "上传分片(sessionId, chunkIndex, data)"
+ "合并分片(sessionId)"
+ "下载文件(downloadDTO)"
+ "预览文件(fileInfo)"
+ "获取缩略图(fileId)"
}
class FileApiImpl {
- "minioClient"
- "fileInfoService"
- "kkFileViewClient"
- "fileProperties"
- "thumbnailGenerationTask"
- "thumbnailPlaceholderService"
+ "上传文件(file)"
+ "分片初始化(params)"
+ "上传分片(sessionId, chunkIndex, data)"
+ "合并分片(sessionId)"
+ "下载文件(downloadDTO)"
+ "预览文件(fileInfo)"
+ "获取缩略图(fileId)"
}
class ThumbnailRenderer {
+ "supports(contentType, ext)"
+ "render(original, ext, width, maxHeight)"
}
class ImageThumbnailRenderer {
+ "supports(contentType, ext)"
+ "render(original, ext, width, maxHeight)"
}
class PdfThumbnailRenderer {
+ "supports(contentType, ext)"
+ "render(original, ext, width, maxHeight)"
}
class OfficeThumbnailRenderer {
+ "supports(contentType, ext)"
+ "render(original, ext, width, maxHeight)"
}
class ThumbnailGenerationTask {
+ "isSupported(contentType, ext)"
+ "assignInitialStatus(info)"
+ "generate(fileId)"
+ "tryGenerateSync(fileId)"
}
class ThumbnailPlaceholderService {
+ "getPlaceholder(ext)"
}
class FileInfoService {
+ "保存文件元数据(info)"
+ "更新文件状态(id, status)"
+ "查询文件信息(id)"
}
class KkFileViewClient {
+ "获取预览链接(url)"
+ "获取预览内容(url)"
}
class MinioConfig {
+ "endpoint"
+ "bucketName"
+ "accessKey"
+ "secretKey"
}
class FileProperties {
+ "chunkSize"
+ "maxFileSize"
+ "timeout"
+ "thumbnail.width"
+ "thumbnail.maxHeight"
+ "thumbnail.retryLimit"
}
FileApi <|.. FileApiImpl : "实现"
FileApiImpl --> FileInfoService : "依赖"
FileApiImpl --> KkFileViewClient : "依赖"
FileApiImpl --> MinioConfig : "依赖"
FileApiImpl --> FileProperties : "依赖"
FileApiImpl --> ThumbnailGenerationTask : "依赖"
FileApiImpl --> ThumbnailPlaceholderService : "依赖"
ThumbnailRenderer <|-- ImageThumbnailRenderer
ThumbnailRenderer <|-- PdfThumbnailRenderer
ThumbnailRenderer <|-- OfficeThumbnailRenderer
```

**图表来源**
- [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [ThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailRenderer.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailPlaceholderService.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailPlaceholderService.java)
- [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)

章节来源
- [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [IFileInfoService.java](file://crm-file/src/main/java/com/crm/file/service/IFileInfoService.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)

### 缩略图渲染器体系
- **ThumbnailRenderer 接口**：定义缩略图渲染的统一接口，支持根据文件类型判断和处理。
- **ImageThumbnailRenderer**：基于 Java ImageIO 的图片渲染器，支持 jpg/jpeg/png/gif/bmp 格式，webp 需要额外插件。
- **PdfThumbnailRenderer**：基于 Apache PDFBox 的 PDF 渲染器，将第一页渲染为图片，DPI 设置为 150 平衡清晰度与性能。
- **OfficeThumbnailRenderer**：基于 LibreOffice headless 模式的 Office 文档渲染器，支持 docx/xlsx/pptx/doc/xls/ppt 格式。
- **ThumbnailImageUtils**：通用的图像处理工具类，提供等比缩放和 JPEG 编码功能。

**更新** 新增了完整的缩略图渲染器体系，支持多种文件类型的自动缩略图生成。

章节来源
- [ThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailRenderer.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [ThumbnailImageUtils.java](file://crm-file/src/main/java/com/crm/file/service/impl/ThumbnailImageUtils.java)

### 缩略图任务系统
- **ThumbnailGenerationTask**：缩略图异步生成任务，支持分布式锁保护、失败重试和状态管理。
  - `assignInitialStatus()`：设置初始缩略图状态（PENDING 或 UNSUPPORTED）
  - `generate()`：异步生成缩略图，不阻塞上传链路
  - `tryGenerateSync()`：同步兜底机制，用于首次请求时的快速响应
  - 分布式锁：使用 Redis 防止重复生成，锁 TTL 大于最慢渲染时间
  - 失败重试：支持配置的重试次数，耗尽后标记 FAILED 状态
- **ThumbnailRetryTask**：缩略图失败重试定时任务，周期性扫描 FAILED 状态的记录并重新提交生成。

**更新** 新增了完整的缩略图任务系统，具备异步处理、分布式锁、失败重试等高级特性。

章节来源
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)

### 缩略图占位图服务
- **ThumbnailPlaceholderService**：为不支持的文件类型或生成失败的缩略图提供默认占位图。
- 功能特点：
  - 根据文件扩展名动态生成带标签的占位图
  - 200x200 像素灰底 PNG 格式
  - 居中显示文件扩展名文字
  - 异常时返回空字节数组

**更新** 新增了占位图服务，提升用户体验，为不支持的文件类型提供视觉反馈。

章节来源
- [ThumbnailPlaceholderService.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailPlaceholderService.java)

### 元数据服务：FileInfoServiceImpl
- 职责：文件元数据的持久化与查询，包括创建、更新、删除、分页查询等。
- 关键能力：
  - 文件记录创建：上传完成后写入 FileInfo。
  - 状态更新：分片上传过程中更新进度与状态，缩略图生成过程中更新缩略图状态。
  - 查询与过滤：按文件名、类型、时间范围等条件查询。
- 与 Mapper 的交互：通过 FileInfoMapper 执行 SQL 操作。

章节来源
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java)
- [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java)

### 预览服务：KkFileViewClient
- 职责：对接 kkFileView 服务，生成预览链接或获取预览内容。
- 关键能力：
  - 根据文件 URL 或路径生成预览链接。
  - 直接获取预览内容（如 PDF、图片等）。
- 错误处理：网络异常、预览服务不可用时的降级策略。

章节来源
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)

### 配置与初始化：MinioConfig、FileProperties、SchedulingConfig
- MinioConfig：MinIO 客户端配置（端点、桶名、密钥、连接池等）。
- FileProperties：文件相关配置（分片大小、最大文件大小、超时、临时目录、**缩略图配置**等）。
- SchedulingConfig：定时任务开关与调度策略（如分片清理任务的执行周期、**缩略图重试任务的 cron 表达式**）。

**更新** FileProperties 新增了缩略图相关配置项，SchedulingConfig 支持缩略图重试任务的调度。

章节来源
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)

### 领域模型：FileInfo、UploadSession、DTOs
- FileInfo：文件元数据实体（名称、路径、大小、类型、状态、创建时间、**缩略图状态、重试次数**等）。
- UploadSession：分片上传会话（sessionId、总大小、已上传分片集合、状态等）。
- **ThumbnailDTO**：缩略图传输对象（二进制内容、内容类型、缓存策略、HTTP状态码）。
- DTOs：
  - MultipartInitDTO：分片初始化参数。
  - FileDownloadDTO：下载参数（文件标识、路径、范围等）。
  - FileInfoDTO：文件信息传输对象。

**更新** FileInfo 实体新增了缩略图状态和重试次数字段，新增 ThumbnailDTO 用于缩略图数据传输。

章节来源
- [FileInfo.java](file://crm-file/src/main/java/com/crm/file/domain/entity/FileInfo.java)
- [UploadSession.java](file://crm-file/src/main/java/com/crm/file/domain/dto/UploadSession.java)
- [ThumbnailDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/ThumbnailDTO.java)
- [MultipartInitDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/MultipartInitDTO.java)
- [FileDownloadDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileDownloadDTO.java)
- [FileInfoDTO.java](file://crm-file/src/main/java/com/crm/file/domain/dto/FileInfoDTO.java)

### 定时任务：OrphanChunkCleanupTask、ThumbnailRetryTask
- **OrphanChunkCleanupTask**：周期性扫描未完成的分片上传会话，清理孤立分片文件，释放存储空间。
- **ThumbnailRetryTask**：周期性扫描 thumbnail_status = FAILED 的记录，重置为 PENDING 并重新提交异步生成。

**更新** 新增了缩略图失败重试任务，提升系统的自愈能力。

章节来源
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)

### 常量：FileConstants
- 职责：集中定义文件相关常量（如 MIME 类型、错误码、默认值、**缩略图状态常量、锁前缀等**）。

**更新** 新增了缩略图相关的常量定义，包括状态枚举、锁前缀、存储前缀等。

章节来源
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)

## 依赖关系分析
- 控制器依赖服务层，服务层依赖 MinIO 客户端、预览客户端、缩略图任务和数据库 Mapper。
- 缩略图渲染器通过接口抽象，支持多种实现方式。
- 定时任务依赖配置与 Mapper，用于清理孤立分片和重试失败的缩略图生成。
- 领域模型在各层之间传递，保证数据结构一致。

```mermaid
graph LR
FC["FileController"] --> FA["FileApiImpl"]
FA --> FMS["FileInfoServiceImpl"]
FA --> MINIO["MinioConfig"]
FA --> KK["KkFileViewClient"]
FA --> TGT["ThumbnailGenerationTask"]
FA --> TPS["ThumbnailPlaceholderService"]
FMS --> MAP["FileInfoMapper"]
TASK1["OrphanChunkCleanupTask"] --> MAP
TASK1 --> FP["FileProperties"]
TASK2["ThumbnailRetryTask"] --> MAP
TASK2 --> TGT
TGT --> TR["ThumbnailRenderer"]
TR --> ITR["ImageThumbnailRenderer"]
TR --> PTR["PdfThumbnailRenderer"]
TR --> ORR["OfficeThumbnailRenderer"]
```

**图表来源**
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailRenderer.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)

章节来源
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [FileInfoMapper.java](file://crm-file/src/main/java/com/crm/file/mapper/FileInfoMapper.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/ThumbnailRenderer.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)

## 性能考量
- 分片上传：合理设置分片大小与并发数，平衡内存占用与上传速度。
- 流式处理：下载时采用流式读取，避免大文件内存溢出。
- 缓存策略：对频繁访问的文件元数据进行缓存，减少数据库压力；缩略图支持强缓存（READY 状态 max-age=86400）。
- 连接池：优化 MinIO 客户端连接池大小与超时配置。
- 异步处理：将非关键路径（如预览生成、缩略图生成）异步化，提升响应速度。
- 资源清理：定时任务及时清理孤立分片和失败的缩略图生成任务，防止存储膨胀。
- **分布式锁**：缩略图生成使用 Redis 分布式锁，避免重复处理和资源浪费。
- **渲染器优化**：不同渲染器针对特定文件格式优化，如 PDF 使用 150 DPI 平衡质量与性能。

**更新** 新增了缩略图相关的性能优化策略，包括分布式锁、异步处理、缓存策略和渲染器优化。

## 故障排查指南
- 上传失败：检查 MinIO 配置、网络连通性与权限；查看分片会话状态与日志。
- 分片丢失：确认客户端分片顺序与重试机制；检查定时任务是否误删。
- 预览失败：验证 kkFileView 服务可用性；检查文件路径与 MIME 类型。
- 下载缓慢：调整流式缓冲大小与网络带宽；检查 MinIO 性能。
- 存储膨胀：检查孤立分片清理任务是否正常运行；手动清理残留分片。
- **缩略图生成失败**：检查渲染器依赖（LibreOffice、PDFBox、ImageIO）；查看缩略图状态和重试次数；验证文件类型支持情况。
- **缩略图生成超时**：调整 LibreOffice 转换超时配置；检查系统资源使用情况。
- **缩略图缓存问题**：检查浏览器缓存策略；确认 Cache-Control 头设置正确。

**更新** 新增了缩略图相关的故障排查指南，涵盖生成失败、超时、缓存等问题。

章节来源
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)

## 结论
crm-file 模块提供了完整的文件处理能力，涵盖上传下载、分片上传、断点续传、预览、缩略图生成与存储管理。通过清晰的架构设计与合理的配置，能够满足企业级应用对文件服务的稳定、高效与可扩展需求。**新增的缩略图系统**进一步增强了用户体验，支持多种文件类型的自动缩略图生成，具备异步处理、分布式锁、失败重试和占位图回退等高级特性。建议在生产环境中充分测试并发与异常场景，并根据实际负载优化配置参数。

**更新** 模块现在具备了完整的缩略图功能，能够显著提升用户界面的加载速度和用户体验。

## 附录
- 接口设计建议：统一返回格式、明确错误码、提供幂等性支持。
- 存储策略配置：按业务划分桶与目录，设置生命周期规则。
- 扩展方案：抽象存储后端接口，支持多存储切换；插件化预览服务；扩展新的缩略图渲染器。
- 监控与告警：记录上传下载成功率、延迟与错误率，设置阈值告警；监控缩略图生成成功率和失败率。
- **缩略图配置建议**：根据文件类型选择合适的渲染器；合理设置缩略图尺寸和 DPI；配置适当的重试次数和超时时间。
- **性能调优建议**：根据服务器资源配置 LibreOffice 进程数；优化 MinIO 连接池大小；合理设置缩略图缓存策略。

**更新** 新增了缩略图相关的配置建议和性能调优指导。