文件存储

通用文件上传/预览能力的领域语言。存储用 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: 代理下载、中转