# @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` 后：

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

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

## 4. 标准调用流程

### 步骤 1：业务 Controller 标注注解

```java
@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
```

响应：

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

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

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

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

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

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

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

系统会自动读取：

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

并建立业务附件关联。

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

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

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

对应请求体示例：

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

对应响应体示例：

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

## 6. 常见注意事项

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