1. 统一对应的表字段信息

2026-01-20 09:18:46 +08:00
parent 4595cef06e
commit 6ea48a3b2f
2 changed files with 153 additions and 0 deletions
--- a/docs/附件上传注解使用说明.md
+++ b/docs/附件上传注解使用说明.md
@@ -0,0 +1,152 @@
+# @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` 建议以业务模块唯一标识命名，便于后续查询与归档。