EFCv4.1.0-SNAPSHOT

外观

文件记录管理 ​

文件记录保存对象的位置和元数据，便于上传后关联业务对象或在管理端查看。它不是“当前用户附件”模型：没有归属用户、工作空间、业务模块或业务对象 ID 字段，这些关系由接入应用保存并校验。

接入管理端 ​

在已导入 Business BOM、配置数据库与 Store，并补齐Mapper 扫描的应用中引入：

xml
<dependency>
    <groupId>com.own.business</groupId>
    <artifactId>springboot-business-resource-controller-admin</artifactId>
</dependency>

前缀为 /api/admin/file/record，加上应用域名、端口和实际 context path。类声明 @PermissionModule("resource-center")，但这些方法没有 @PermissionOperation 注解；不能据此声称接口已具备 SEARCH、VIEW、ADD、DELETE 分别授权。管理端认证及具体放行由应用的安全配置负责。

方法相对路径请求成功时 data
POST/pageJSON FileRecordQuery，无条件传 {}PageModel<FileRecordVo>
POST/JSON FileRecordDto新的 FileRecordVo
GET/{fileId}文件记录 IDFileRecordVo
DELETE/{fileId}文件记录 IDtrue
DELETE/batch/{fileIds}逗号分隔的 ID，如 10001,10002true

没有管理端修改接口、当前用户记录列表或文件内容下载接口。App 端提供上传与签名，范围见上传页。

查询记录 ​

调用 POST /api/admin/file/record/page，使用 Content-Type: application/json：

json
{
  "page": 1,
  "rows": 10
}

page 从 1 开始，缺省或不大于 0 时取 1；rows 缺省或不大于 0 时取 10，最大 100。分页响应包含 page、rows、total、list、isLastPage，其中 total 是总记录数，分页依赖 PageHelper。公共参数与模型见 Base Business 分页。

Query 字段不等于已实现筛选

FileRecordQuery 虽然定义了 name、oldName、path、position、type、size、md5，但当前服务没有重写对应查询条件，Mapper 也没有自定义查询 SQL。上述字段和继承的 keywords 不会产生文件筛选，分页查询也没有显式排序或用户限制。请不要使用这些参数做精确查找、租户隔离或授权。

查询确定的记录使用 GET /api/admin/file/record/{fileId}；不存在的 ID 默认抛出 business_not_found。需要 MD5 检索的应用可调用 FileRecordService.listByMd5(...) Java 列表方法，当前没有对应 HTTP 列表入口；单条 MD5 查询的限制见上传页。

响应与字段 ​

普通接口返回 ResultModel<T>，包含 code、message、data、t、success、traceId，正常业务码为 00000。客户端应依据业务码判断结果；HTTP 状态和错误转换由应用异常处理决定。

公共响应与 JSON 转换规则见 Base 使用与配置，以下字段说明只涉及文件记录。

字段语义及数据库约束
id记录主键，Java Long、数据库 bigint，使用 MyBatis-Plus ASSIGN_ID
name保存后的文件名，最长 100 字符
oldName原始文件名，最长 100 字符
path对象相对路径，最长 255 字符；经应用上传通常含起始 /
position存储访问前缀，最长 255 字符；与 path 组合定位资源
typeMIME 类型等文件类型文本，最长 200 字符；并非统一的扩展名枚举
sizeJava Long，单位字节
md5MD5 字符串，最长 32 字符；idx_md5、idx_md5_position 均非唯一索引
createTime创建时间，Java LocalDateTime，数据库 datetime 默认当前时间
createUserId、createUserName创建操作人；不等于受校验的文件所有者，可能没有填充

框架默认 MVC 将 Long 输出为字符串，id、size、createUserId 等应按该约定接收；前端用字符串保存 ID 以避免精度丢失。时间默认格式 yyyy-MM-dd HH:mm:ss，格式注解声明 GMT+8，值本身不包含时区偏移；应用和数据库应保持一致时间口径。

业务字段可为空，审计字段可依序列化配置省略。当前 PO 继承 BaseEntityPo.Create，没有 modifiedTime、version 或 isDeleted；不能套用下载中心的逻辑删除及更新时间模型。数据库生成的创建时间不保证在新增返回的内存 VO 中立即出现，重新查询后核对。

登记已有文件 ​

可信后台已上传或确认对象存在后，可调用 POST /api/admin/file/record/ 登记元数据，例如：

json
{
  "name": "resource-demo.txt",
  "oldName": "resource-demo.txt",
  "path": "/manual/resource-demo.txt",
  "position": "https://files.example.com/resource-demo",
  "type": "text/plain",
  "size": "14"
}

示例地址应替换成实际已存在对象的位置，size 改为实际字节数；可补充真实 md5。此接口只写数据库，不上传文件、不探测对象存在，也不生成私有访问地址。

FileRecordDto.check() 继承默认实现，没有文件元数据专用必填或长度校验。调用方负责完整性和可信性；若启用路径处理，path 还需非空以满足当前服务的字符串检查。

删除记录 ​

通过 DELETE /api/admin/file/record/{fileId} 或批量接口删除元数据。当前没有二次确认注解，也没有业务引用检查。

删除直接物理移除 own_system_file_record 中的行，不会删除磁盘文件或云对象，不撤销已签发 URL，也不会同步删除下载中心记录。业务需要先处理附件引用，真实文件清理由应用按存储供应商能力另行完成。

接口不根据影响行数返回不同结果：只要调用未抛异常，删除不存在的 ID 或重复删除也可能返回 data=true。模块没有恢复、回收站或定期清理流程。

记录保存与业务扩展 ​

单条保存前处理路径 ​

单条新增、上传后的 afterUpload(po) 和回调落库最终经过 FileRecordServiceImpl.addByPo。配置 own.resource.save-handler.enable=true 后，若 path 尚未包含 save-handler.params 字符串，会按 sequence() 升序调用 BaseFileRecordPathHandler。

应用可提供一个或多个该类型 Bean，在 accept(String params, FileRecord record) 中修改记录。默认 Bean 是空操作，因此仅开启配置不会自动追加 x-own、图片尺寸或其他参数。跳过判断使用字符串包含关系，不是 URL 参数解析。

继承的批量新增和 afterUpload(List<FileRecord>) 走 addBatchByPoList，不会逐条调用此重写方法，因此不会自动运行相同路径处理链。需要统一行为时由应用明确选择单条流程或补充批量编排。

回填业务附件 ​

ListFileUtil 可从业务对象中的逗号分隔文件 ID 字符串批量读取记录，并通过 setter 回填 List<FileRecordVo>。传入 getter/setter 方法引用即可，例如应用已有 attachmentIds 与 attachments 属性时，调用 listFileUtil.build(orders, OrderVo::getAttachmentIds, OrderVo::setAttachments)。

调用前先完成业务对象权限检查，文件 ID 字符串应是合法数字列表。集合重载会聚合 ID 批量查询，再按每个对象原字符串的次序回填；单对象重载先转换为 Set，不保证原顺序。找不到的记录会被略过，集合重载在完全没有匹配记录时直接返回，不保证清空原字段。

其他辅助能力 ​

FileRecordUtil.getPosition 从 HTTP(S) 地址提取 origin，非 HTTP(S) 路径返回空；getPath 从匹配的 HTTP(S) URL 去掉域名、查询串和片段，再移除开头 /。这些工具不执行下载或授权。

阿里云适配器还提供图片尺寸辅助方法 AliYunResourceUtil.getResourceDimension，但其类型判断使用扩展名列表，而普通上传记录保存 MIME 类型，不能保证对 image/png 等常见记录触发处理。DownloadFile 只是路径、名称和后缀模型，不提供 HTTP 下载接口。

需要展示“我的下载”时，可将已确认可访问的资源地址写入下载中心，由应用传递归属用户。资源记录和下载中心的 ID、删除规则、状态字段分别独立管理。

批量登记的当前限制 ​

afterUpload(List<FileRecord>) 与继承的批量新增会委托 MapperUtil，当前分组结果未遍历，Mapper 回调不会执行。因此不仅与单条路径处理器不同，还可能返回记录 VO 而没有写库；使用前需核对 MapperUtil 方法与源码。