@FileUploadController 注解使用说明

本文档说明 @FileUploadController 的使用方式、调用流程、以及报文结构示例。适用范围为业务创建接口在请求体中携带附件列表的场景，并在业务创建成功后自动建立“业务-附件”的关联关系。

1. 适用前提

附件列表在业务创建请求体中传入。
业务创建返回结构统一为：{ code, data: { id, code } }。
不涉及二次请求与补充请求头流程（文档不包含相关内容）。

2. 注解字段说明

位置：com.zt.plat.framework.business.annotation.FileUploadController

字段	说明	默认值	备注
`filesKey`	请求体中附件数组的路径	`files`	支持多层级路径，如 `data.files`
`fileNameKey`	附件名称字段	`name`	解析附件名称使用
`fileIdKey`	附件ID字段	`id`	解析附件ID使用
`source`	业务来源标识	`default`	例如 `bpm` / `oa` / `hr` 等
`primaryKey`	响应中业务主键路径	`data.id`	支持多层级路径
`codeKey`	响应中业务编码路径	`data.code`	支持多层级路径

3. 关联处理机制（简述）

当 Controller 标注 @FileUploadController 后：

请求进入时会读取注解配置并写入 request attribute。
请求处理完成后，过滤器会读取：
- 请求体中的附件数组
- 响应体中的业务主键与业务编码
当响应 code == 0 时，自动调用 BusinessFileApi.batchCreateBusinessFile(...) 建立附件关联。

注意：如果请求体中未包含附件数组，或响应中未返回业务主键，则不会产生关联。

4. 标准调用流程

步骤 1：业务 Controller 标注注解

@FileUploadController(source = "template.contract")
public class DemoContractController extends AbstractFileUploadController implements BusinessControllerMarker {
    static {
        FileUploadController annotation = DemoContractController.class.getAnnotation(FileUploadController.class);
        if (annotation != null) {
            setFileUploadInfo(annotation);
        }
    }
}

步骤 2：可选获取 source 信息

请求：

GET /template/demo-contract/upload-info

响应：

{
  "code": 0,
  "data": { "source": "template.contract" },
  "msg": "成功"
}

步骤 3：业务创建请求携带附件列表

请求体示例（默认字段）：

{
  "name": "测试合同",
  "amount": 2000,
  "files": [
    { "id": 10125, "name": "合同附件.pdf" },
    { "id": 10126, "name": "补充材料.docx" }
  ]
}

步骤 4：业务创建成功返回

响应体示例（统一结构）：

{
  "code": 0,
  "data": {
    "id": 90001,
    "code": "HT-2026-0001"
  },
  "msg": "成功"
}

系统会自动读取：

files 中的 id/name
data.id 和 data.code

并建立业务附件关联。

5. 多层级字段示例（可选配置）

如果业务请求体与响应体存在嵌套结构，可通过注解自定义路径：

@FileUploadController(
  source = "template.contract",
  filesKey = "data.files",
  fileIdKey = "fileId",
  fileNameKey = "fileName",
  primaryKey = "data.businessId",
  codeKey = "data.businessCode"
)

对应请求体示例：

{
  "data": {
    "files": [
      { "fileId": 1001, "fileName": "合同.pdf" }
    ]
  }
}

对应响应体示例：

{
  "code": 0,
  "data": {
    "businessId": 90001,
    "businessCode": "HT-2026-0001"
  },
  "msg": "成功"
}

6. 常见注意事项

响应 code != 0 时不会执行附件关联。
files 必须是数组，否则会被忽略。
若业务返回未包含 primaryKey 对应的字段，附件不会关联。
source 建议以业务模块唯一标识命名，便于后续查询与归档。

3.8 KiB Raw Blame History Unescape Escape