You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
|
|
|
|
# 文件存储
|
|
|
|
|
|
|
|
|
|
通用文件上传/预览能力的领域语言。存储用 MinIO，预览用 kkFileView，同时服务前端接口与后端内部调用。
|
|
|
|
|
|
|
|
|
|
## Language
|
|
|
|
|
|
|
|
|
|
**直传**:
|
|
|
|
|
单个请求把整个文件交给后端、后端写入 MinIO 的上传方式。有单请求大小上限，由后端守门校验。
|
|
|
|
|
_Avoid_: 普通上传、小文件上传
|
|
|
|
|
|
|
|
|
|
**分片上传**:
|
|
|
|
|
前端将文件切片后按三段式协议（初始化 → 传分片 → 完成合并）上传的方式。除最后一片外每片固定 5MB。
|
|
|
|
|
_Avoid_: 大文件上传、断点上传
|
|
|
|
|
|
|
|
|
|
**上传会话**:
|
|
|
|
|
一次分片上传从初始化到完成/清理之间的生命周期，由 uploadId 唯一标识。超时未完成的会话由定时任务清理。
|
|
|
|
|
_Avoid_: 上传任务、批次
|
|
|
|
|
|
|
|
|
|
**临时分片**:
|
|
|
|
|
上传会话期间以 `chunks/{uploadId}/{序号}` 为 key 落在 MinIO 的独立对象，合并后即删除。
|
|
|
|
|
_Avoid_: 分片文件、part
|
|
|
|
|
|
|
|
|
|
**合并**:
|
|
|
|
|
完成阶段用 MinIO composeObject 将临时分片拼成最终对象的动作，由后端执行。
|
|
|
|
|
_Avoid_: 秒合、multipart complete
|
|
|
|
|
|
|
|
|
|
**断点续传**:
|
|
|
|
|
前端携带 uploadId 重新初始化时，后端返回已上传分片序号、前端只补传缺失分片的能力。不依赖额外进度表。
|
|
|
|
|
_Avoid_: 续传恢复、重传
|
|
|
|
|
|
|
|
|
|
**秒传**:
|
|
|
|
|
凭整文件 hash 命中已有对象、跳过实际传输的能力。一期不实现，元数据仅保留 fileHash 字段占位。
|
|
|
|
|
_Avoid_: 极速上传、去重上传
|
|
|
|
|
|
|
|
|
|
**fileId**:
|
|
|
|
|
文件元数据记录的主键（雪花 ID），文件在全系统的唯一引用凭据。业务表只存 fileId，不存 URL。
|
|
|
|
|
_Avoid_: 文件 URL、文件路径
|
|
|
|
|
|
|
|
|
|
**objectKey**:
|
|
|
|
|
文件在 MinIO 中的对象路径，形如 `{业务域}/{yyyy}/{MM}/{fileId}.{扩展名}`。属存储内部细节，不对业务模块暴露。
|
|
|
|
|
_Avoid_: 文件名、存储路径
|
|
|
|
|
|
|
|
|
|
**业务域**:
|
|
|
|
|
上传时由调用方声明的文件归属标识（如 contract、customer），作为 objectKey 前缀隔离不同业务的文件。单 bucket，不按业务分 bucket。
|
|
|
|
|
_Avoid_: 模块名、bucket 名
|
|
|
|
|
|
|
|
|
|
**预览地址**:
|
|
|
|
|
后端拼装、返回给前端的 kkFileView 完整预览 URL。前端只负责打开，不自行拼接。
|
|
|
|
|
_Avoid_: 预览链接、kk 地址
|
|
|
|
|
|
|
|
|
|
**回源**:
|
|
|
|
|
kkFileView 服务端凭短时效凭证从 MinIO 拉取原始文件用于格式转换的动作。浏览器不直接接触 MinIO。
|
|
|
|
|
_Avoid_: 代理下载、中转
|
|
|
|
|
|
|
|
|
|
**缩略图**:
|
|
|
|
|
从原文件提取或渲染出的小尺寸静态图片（固定宽度 200px，等比缩放，上限 400px 高，JPEG 格式），用于前端文件列表优先展示以降低弱网加载延迟。点击后再请求原图或完整预览。
|
|
|
|
|
_Avoid_: 小图、预览图、封面图
|
|
|
|
|
|
|
|
|
|
**缩略图状态**:
|
|
|
|
|
一个文件缩略图的生命周期阶段：`PENDING`（已入队待生成）、`READY`（已生成可返回）、`FAILED`（重试 3 次后放弃但可由定时任务重试）、`UNSUPPORTED`（文件类型不在支持范围内，永不触发生成）。
|
|
|
|
|
_Avoid_: 缩略图进度、生成标志
|
|
|
|
|
|
|
|
|
|
**缩略图生成**:
|
|
|
|
|
将原文件转换为缩略图的动作。图片走 Java 图像缩放；PDF 走 PDFBox 渲染第一页；Office 走 LibreOffice headless 渲染第一页。支持图片（jpg/png/webp/gif/bmp）、PDF、Office（docx/xlsx/pptx），其余类型前置标记 `UNSUPPORTED` 跳过。
|
|
|
|
|
_Avoid_: 缩略、截图
|
|
|
|
|
|
|
|
|
|
**异步生成**:
|
|
|
|
|
文件上传完成后由后台任务触发的缩略图生成。与首次请求同步兜底并行，两路通过分布式锁防止重复生成。
|
|
|
|
|
_Avoid_: 后台截图、延迟生成
|
|
|
|
|
|
|
|
|
|
**同步兜底**:
|
|
|
|
|
缩略图首次被请求时若后台任务尚未完成，请求线程同步触发生成并等待返回的策略。缩略图不变，后续请求走 MinIO 缓存。
|
|
|
|
|
_Avoid_: 实时生成、即时渲染
|
|
|
|
|
|
|
|
|
|
**占位图**:
|
|
|
|
|
缩略图处于 `PENDING`、`FAILED` 或 `UNSUPPORTED` 状态时返回给前端的文件类型图标静态图。前端无感知，始终拿到一张图。
|
|
|
|
|
_Avoid_: 默认图、fallback图
|
|
|
|
|
|
|
|
|
|
**缩略图对象**:
|
|
|
|
|
缩略图在 MinIO 中的对象，objectKey 为 `thumbnails/{fileId}.jpg`，与原文件同 bucket。通过后端 API 中转返回，设置 `Cache-Control: max-age=86400` 强缓存头，浏览器不直接接触 MinIO。
|
|
|
|
|
_Avoid_: 缩略图文件、thumb对象
|
