完成表单直传

1. 接口定位

• 接口名称: 完成表单直传
• 所属域: object
• 业务目标: 在客户端表单上传完成后，校验上传对象并写入对象元数据，返回业务访问 URL

2. 请求定义

• Method: POST
• Path: /object/complete_form_data
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 非幂等（同一 id 重复提交可能导致重复写入或校验失败）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
id	是	string	initiate_form_data 返回的上传会话标识，需原样回传
urlPrefix	否	string	返回 URL 的前缀（scheme+host），不传则使用服务端默认配置

字段约束

• id 不能为空，且必须是有效会话串。
• id 对应对象需已实际上传到对象存储。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

字段	类型	说明
url	string	文件访问 URL

5. 业务规则

• 调用方持有合法 token 即可调用，无角色硬限制。
• 服务端会解析 id 中的上下文（名称、大小、类型、分组、key），并校验对象是否存在。
• 若对象实际大小与会话记录的 size 不一致，返回数据错误。
• 校验通过后写入对象元数据，并返回可访问 URL。

6. 错误码与失败场景

错误码	场景	典型报错
1001	id 为空或格式非法	ArgsError
1004	上传文件大小与会话记录不一致	DataError
500	服务内部错误（对象不存在、存储异常、入库失败）	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/object/complete_form_data", {
  method: "POST",
  headers: {
    operationID: "f8a2e174-9a9b-4d6c-9b43-d7b4f3d9e1a6",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "eyJuYW1lIjoidXNlci9maWxlLzIwMjYwNjIwL2V4YW1wbGUucG5nIiwic2l6ZSI6MjA0ODAwfQ",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "id": "eyJuYW1lIjoidXNlci9maWxlLzIwMjYwNjIwL2V4YW1wbGUucG5nIiwic2l6ZSI6MjA0ODAwfQ"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "url": "https://minio.example.com/openim/user/file/20260620/example.png"
  }
}

8. 时序流程

1. 客户端完成对象存储表单上传。
2. 调用 complete_form_data 提交 id。
3. 服务端校验对象存在与大小一致性，写入对象元数据并返回 url。

9. 变更记录

• 2026-06-20: 首版补充文档发布。