153 lines
3.8 KiB
Markdown
153 lines
3.8 KiB
Markdown
# @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` 建议以业务模块唯一标识命名，便于后续查询与归档。
|