文件与存储

YeahBoot 将“业务文件”和“底层存储记录”分成两层管理。

模块	表	作用
文件管理	sys_file	面向业务和管理员的文件记录
存储管理	sys_storage	保存 Provider、桶、路径、文件键和使用状态

文件上传

文件管理上传使用业务配置中的桶和路径，并在底层创建存储记录。上传结果返回 fileKey，后续下载和预览通过该键定位文件。

未传 storageType 时，由存储管理器根据已启用 Provider 的优先级选择最终存储类型。

下载与预览

• 下载接口：以附件方式返回，浏览器通常触发保存。
• 预览接口：以内联方式返回，适合图片等浏览器可展示内容。
• 公开下载和公开预览位于 /public/storage，只应服务明确允许公开的文件。

预览和下载语义不同，不应为了复用前端逻辑统一成同一种响应方式。

使用标记

上传后的临时文件可以处于未使用状态，业务保存成功后调用 markUse，替换或移除引用时调用 unmarkUse。

上传 → 未使用 → 业务保存 → 已使用
                         ↓
              解除引用 → 可清理

markUse 对新引用保持严格：找不到目标存储记录时应报告异常。unmarkUse 允许容错：旧记录已清理时忽略即可。

批量删除

文件和存储删除接口都使用 JSON Body，同时兼容：

{
  "ids": [1, 2, 3],
  "fileKeys": ["example-key"]
}

优先使用 ids；没有 ids 时使用 fileKeys；两者都为空属于参数异常。目标记录不存在时按幂等删除处理，不必报错。

存储管理额外支持：

{
  "ids": [1],
  "force": true
}

正在使用的存储记录默认不能删除。管理员二次确认后可以强制删除；公开 Demo 不建议给体验角色开放此权限。

引用安全边界

isUsed 是轻量使用标记，不是跨所有业务表的引用计数。如果两个业务对象意外引用同一 fileKey，一方解除标记可能影响另一方。因此业务层应做到：

• 新业务只引用自己上传或明确授权的文件。
• 更新时比较新旧文件键，先完成业务事务再处理标记。
• 强制删除必须显示影响提示。
• 对高安全业务增加独立文件关联表或引用计数。