【表单数据】上传附件 / 图片

向指定表单上传图片或文件（如参会头像、简历材料、证件照片、附件等）。服务端上传至对象存储（OSS/本地存储）后，返回可在公网直接访问的预览/下载 URL 地址（fileUrl），该地址可直接传入表单数据的新增与修改接口作为对应题目的填报值。

---

接口基本信息

• 接口路径：/open/v2/form/data/upload （兼容 /open/v2/form/file/upload）
• 请求方法：POST
• 请求格式：multipart/form-data
• 认证方式：HTTP Basic Auth (Authorization: Basic <base64(appId:appSecret)>)

---

请求参数详细说明 (Multipart Form-Data)

参数名	类型	必填	默认值	说明	示例
formKey	String	是	-	表单全局唯一标识 Key	"ICGqvdBR"
itemId	String	否	-	关联的自定义题目 ID（如 q_avatar）	"q_avatar"
file	File	是	-	待上传的二进制文件流	-

---

请求调用示例

1. HTTP 报文请求

POST /tduck-api/open/v2/form/data/upload HTTP/1.1
Host: api.example.com
Authorization: Basic R1JzMHc5QXl6ZjVjV2dUYzpha3ZETlFSamVqVFdEZWxmOFRPTUVRTVcyMTFDM2Zqaw==
Content-Type: multipart/form-data; boundary=WebAppBoundary

--WebAppBoundary
Content-Disposition: form-data; name="formKey"

ICGqvdBR
--WebAppBoundary
Content-Disposition: form-data; name="itemId"

q_avatar
--WebAppBoundary
Content-Disposition: form-data; name="file"; filename="sample.png"
Content-Type: image/png

< ./sample.png
--WebAppBoundary--

2. cURL 命令行上传示例

curl -X POST "https://api.example.com/tduck-api/open/v2/form/data/upload" \
  -H "Authorization: Basic R1JzMHc5QXl6ZjVjV2dUYzpha3ZETlFSamVqVFdEZWxmOFRPTUVRTVcyMTFDM2Zqaw==" \
  -F "formKey=ICGqvdBR" \
  -F "itemId=q_avatar" \
  -F "file=@/path/to/sample.png"

3. JavaScript / Axios 前端示例

const formData = new FormData();
formData.append('formKey', 'ICGqvdBR');
formData.append('itemId', 'q_avatar');
formData.append('file', fileInput.files[0]);

const res = await axios.post('/tduck-api/open/v2/form/data/upload', formData, {
  headers: {
    'Authorization': 'Basic ' + btoa('appId:appSecret'),
    'Content-Type': 'multipart/form-data'
  }
});
// 填报时直接使用 fileUrl
console.log('文件访问地址:', res.data.data.fileUrl);

---

响应参数说明 (Response Body - FileUploadResultVO)

字段名	类型	说明
code	Integer	状态码（200 表示成功）
msg	String	提示信息
data	Object	文件上传结果对象（FileUploadResultVO）
├─ fileName	String	原始上传的文件名
├─ fileUrl	String	文件的公网可直接访问/预览 URL 地址（作为填报值）
├─ fileSize	Long	文件大小（单位：字节 Byte）
└─ fileType	String	文件扩展名（如 "png", "pdf", "jpg" 等）

---

响应示例 (HTTP 200)

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "fileName": "sample.png",
    "fileUrl": "http://localhost:8888/tduck-api/sys/file/20260820/sample_1a2b3c.png",
    "fileSize": 1048576,
    "fileType": "png"
  }
}