用途
Taruvi Storage 是一个参考模块，用于指导 Taruvi 存储相关的工作流实现，包括存储桶管理、对象上传与下载、可见性控制、批量操作以及配额感知的界面设计。它面向需要在前端应用中集成文件管理能力的开发者，例如构建文件管理器、附件列表或媒体画廊。
该技能不适用于数据库表 CRUD（应使用 taruvi-database 技能）、用户数据（应使用 taruvi-refine-providers 技能）或多资源存储与数据库组合操作（应使用 taruvi-functions 技能）。
主要能力
- 创建或配置存储桶，包括 app_category、visibility 和 allowed_mime_types。
- 通过 storageDataProvider 与 useCreate 从前端上传文件。
- 通过基于路径的 GET API 下载或提供文件。
- 使用 useDeleteMany 单独或批量删除文件。
- 构建文件管理器、附件列表或媒体画廊。
- 对对象列表应用前缀、MIME 类型、大小、日期等过滤器。
- 在界面中展示存储桶配额使用情况。
使用方式
技能提供了分步说明：首先阅读 ../taruvi-refine-providers/references/storage-provider.md 获取完整存储 API 参考；然后识别所需操作，例如单文件上传使用 PUT|POST /api/apps/{app_slug}/storage/buckets/{bucket}/objects/{key}，批量上传使用 batch-upload 端点（每次最多 10 个文件 / 100MB），批量删除使用 batch-delete 端点（每次最多 100 个路径），带过滤的列表使用 GET 加查询参数（prefix、mimetype、size__gte 等）。存储桶可见性在桶级别设置，仅在需要时按对象覆盖。对于配额感知的界面，调用 usage 端点并显示警告，而不是依赖上传阻断。
对于文档或附件流程，默认采用多文件上传界面：允许每次操作选择/上传多个文件；独立处理每个文件并捕获逐文件成功/失败；保持存储对象与元数据记录创建/删除的一致性（在元数据失败时尽可能清理存储）；上传/删除后使文件列表失效或重新获取，以反映当前后端状态。
技能还提供了验证清单，包括：存储桶是否设置了 app_category（assets 或 attachments）；是否配置了 allowed_mime_types；批量上传是否拆分为 ≤10 个文件 / ≤100MB 的块；批量删除是否拆分为 ≤100 个路径的块；上传界面是否在覆盖现有路径时警告用户（upsert 行为）；配额使用是否作为警告而非上传阻断；多文件上传是否报告逐文件状态而非单一聚合成功；当某一步失败时元数据与存储对象状态是否保持一致。
示例代码包括通过 Refine provider hook 上传、批量删除以及带前缀过滤的列表查询。
适用场景
- 需要在前端应用中实现文件上传、下载、列举和管理的场景。
- 构建文件管理器、附件列表或媒体画廊。
- 需要对存储对象应用过滤条件（前缀、MIME 类型、大小、日期）。
- 需要在界面中展示存储桶配额使用情况。
- 需要处理多文件上传并报告逐文件状态的文档或附件流程。
限制与注意事项
- 上传到现有路径会静默替换对象（upsert），API 不发出警告，界面应提示用户。
- 按对象设置的可见性会覆盖存储桶默认值，私有文件在公共桶中仍保持私有，这是常见的访问问题来源。
- 批量上传每次最多 10 个文件且不超过 100MB，超出任一限制返回 400 且无部分成功。
- 批量删除每次最多 100 个路径，与上传不同，批量删除支持部分成功。
- 配额仅为监控/告警用途，不是硬性上传阻断，API 在超出配额时仍接受上传。
- allowed_mime_types 拒绝时静默返回通用 400，错误信息不提及 MIME 类型。
- 创建存储桶必须提供 app_category（assets 或 attachments），否则返回验证错误。
- 在 useCreate/useList/useDeleteMany 中必须指定 dataProviderName: "storage"，否则调用会路由到默认（数据库）provider 并返回令人困惑的“资源未找到”错误。
- 文档工作流不应仅支持单文件上传，附件流程默认应支持多文件选择。
- 批量上传不应采用全有或全无的状态报告，应显示逐文件结果并暴露具体失败。