文件元数据
受众：开发者 / 运维 摘要：Core File 文件元数据底座，负责文件记录、当前用户文件、临时 URL、业务绑定、缩略图和内容安全扫描。
Core File 位于对象存储和业务模块之间。底层上传、签名 URL 和存储 Provider 由 文件存储 提供；Core File 保存文件元数据、生命周期和业务绑定事实。
能力范围
| 能力 | 说明 |
|---|---|
| 文件记录 | 后台分页、详情、保存、删除、临时 URL 和下载 |
| 当前用户文件 | 当前用户上传、查询、绑定和解绑业务文件 |
| 生命周期 | temporary / bound / expired、引用计数和过期清理 |
| 缩略图 | 对已保存文件生成缩略图任务 |
| 内容安全 | 触发文件内容安全扫描，并与 Content Safety 日志关联 |
| 异步导出产物 | 为 Async Task / Reporting 暴露中性文件产物 contract |
API 路径
| API | 说明 |
|---|---|
GET /api/v1/file/records | 后台文件记录分页 |
POST /api/v1/file/records | 后台保存文件元数据 |
POST /api/v1/file/records/export | 创建文件记录导出 |
GET /api/v1/file/records/download | 临时签名下载入口 |
GET /api/v1/file/records/{id}/preview-url | 获取预览 URL |
GET /api/v1/file/records/{id}/download-url | 获取下载 URL |
POST /api/v1/file/records/temporary/expire | 标记临时文件过期 |
POST /api/v1/file/records/expired/cleanup | 清理过期文件 |
POST /api/v1/file/records/thumbnails/generate | 生成缩略图 |
GET /api/v1/file/users/me/records | 当前用户文件分页 |
POST /api/v1/file/users/me/records | 当前用户上传文件 |
GET /api/v1/file/storage/config-metadata | 存储配置元数据 |
POST /api/v1/content-safety/file-scans | 触发文件安全扫描 |
数据模型
| 表 | 说明 |
|---|---|
file_record | 文件路径、磁盘、owner、业务绑定、生命周期、引用和安全扫描摘要 |
迁移归属：
| 文件 | 说明 |
|---|---|
spring-open-core/spring-open-core-file/src/main/resources/db/changelog/migrations/0000_00_00_022000_core_file_create_tables.xml | 建表 |
spring-open-core/spring-open-core-file/src/main/resources/db/changelog/migrations/0000_00_00_022100_core_file_seed_data.xml | 权限、菜单、存储配置入口和角色绑定 |
扩展点
| 扩展点 | 用途 |
|---|---|
file.bind Hook | 在业务绑定文件时做审计、校验或同步 |
FileMediaResourceBindingAdapter | 将 Media starter 的资源绑定转换为 File 记录 |
FileRecordExportService | 给 Async Task / Reporting 暴露文件产物快照 |
与其他模块的边界
- Storage starter 管底层对象存储；Core File 管业务可见文件记录。
- Content Safety 管检测策略和复核；Core File 只触发文件扫描并保存摘要。
- 用户头像等跨底座组合由真实 owning module 组合 File 能力，不回流到 application。
- 业务模块保存业务对象和文件 ID 关系，不直接操作存储路径。
验证命令
bash
./mvnw -pl spring-open-core/spring-open-core-file -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
./.ai/scripts/check modules
./.ai/scripts/check migrations
git diff --check