MinIO 数据迁移实战：导出压缩包、下载到本地并绑定目标服务器

氚云对接第三方平台：以 `ding-oa` 为例的 HTTP 请求集成指南

目标：氚云表单或流程审批完成后，把业务数据安全地推送到第三方平台；本文以本机 D:\ChuanYun\ding-oa 暴露的请假接口作为示例。当前 ding-oa 项目中没有氚云表单 SchemaCode、字段编码或氚云 OpenApi 工程，因此本文对这些值使用占位符，不能直接猜测替换。

一、推荐架构

rust 复制代码

氚云表单/流程
   -> 自动化 HTTP 请求或自定义接口
   -> HTTPS 业务中间层（ding-oa）
   -> 校验、鉴权、幂等、字段转换
   -> 第三方平台 API（例如钉钉 OA）
   -> 返回业务结果并记录关联 ID

把鉴权、重试、幂等和字段转换放在 ding-oa 这类中间层，氚云只负责触发和传递必要字段，后续更换第三方平台时改动更小。

二、开始前必须确认的资料

按照氚云开发规范，以下值必须从当前应用资料或 analysis 结果确认：

项目	示例占位符	来源
表单编码	`<SchemaCode>`	氚云表单设计/结构分析
业务字段编码	`<F_...>`	字段属性或字段目录
流程节点/触发事件	`<通过节点>`	流程设计
第三方 URL	`https://api.example.com/...`	第三方接口文档
鉴权方式	`Authorization` 或签名	第三方接口文档
幂等键	`<审批实例ID>`	业务规则

不要把历史项目中的字段名、人员或部门编码直接复制到当前应用。缺少这些资料时，只能先完成接口契约和测试桩配置。

三、准备 `ding-oa` 服务

项目已提供以下本地接口：

bash 复制代码

POST /api/dingtalk/oa/leave
Content-Type: application/json

请求体示例：

json 复制代码

{
  "processCode": "PROC-XXXXXXXX",
  "originatorUserId": "发起人userId",
  "deptId": 1,
  "approverUserIds": ["审批人userId"],
  "leaveType": "年假",
  "startDate": "2026-08-01",
  "endDate": "2026-08-01",
  "leaveDays": 1,
  "reason": "家庭事务"
}

本地联调启动：

ini 复制代码

Set-Location D:\ChuanYun\ding-oa
$env:DINGTALK_APP_KEY="你的 Client ID"
$env:DINGTALK_APP_SECRET="你的 Client Secret"
$env:DINGTALK_AGENT_ID="你的 AgentId"
$env:DINGTALK_OA_PROCESS_CODE="请假模板 ProcessCode"
.\mvnw.cmd spring-boot:run

氚云自动化服务通常不能访问开发机 localhost。正式接入需要部署到可从氚云访问的 HTTPS 地址，并通过防火墙、网关或 IP 白名单限制来源。

四、氚云侧配置思路

不同氚云版本的菜单名称可能略有差异，原则是一致的：

在目标表单确认触发事件，例如"审批通过"或"保存后"。
新增自动化动作/HTTP 请求，方法选择 POST。
URL 填写部署后的 ding-oa 地址，例如 https://oa.example.com/api/dingtalk/oa/leave。
Header 设置 Content-Type: application/json，鉴权 Header 使用短期令牌或签名，不把长期密钥放在表单字段中。
Body 按 JSON 契约映射字段；数值、日期、人员 ID 的类型必须与接口要求一致。
保存并启用后，先用测试表单发起一条数据，核对自动化执行记录和 ding-oa 日志。

示例 Body（字段编码必须替换为当前氚云真实编码）：

json 复制代码

{
  "processCode": "<钉钉模板ProcessCode>",
  "originatorUserId": "<发起人userId字段>",
  "deptId": "<发起人deptId字段>",
  "approverUserIds": ["<审批人userId字段>"],
  "leaveType": "<请假类型字段>",
  "startDate": "<开始日期字段>",
  "endDate": "<结束日期字段>",
  "leaveDays": "<请假天数字段>",
  "reason": "<请假事由字段>"
}

五、服务端必须做的四类保护

1. 鉴权

为入口增加独立的服务间密钥、HMAC 签名或网关认证；密钥只从环境变量读取。不要仅依赖"URL 不公开"。

2. 幂等

以氚云流程实例 ID 或业务单号作为唯一键。重复请求时返回第一次处理结果，不要重复创建钉钉审批。若当前请求体没有实例 ID，应先扩展接口契约。

3. 重试与超时

只对连接超时、网关错误等可恢复错误进行有限次数重试；4xx 参数错误不应盲目重试。设置连接和读取超时，并记录请求 ID。

4. 日志脱敏

记录业务单号、流程实例 ID、HTTP 状态码、第三方错误码和耗时；禁止记录 Client Secret、accessToken、完整 Authorization 和人员隐私。

六、失败处理与补偿

推荐把"已接收、处理中、成功、待重试、失败"作为本地状态。氚云自动化显示成功只代表 HTTP 请求被接受，不能等同于钉钉审批最终通过。业务系统应保存氚云实例 ID与钉钉 instanceId 的关联，并提供人工重试或补偿入口。

如果氚云支持失败分支，可在 HTTP 非 2xx 时通知管理员；如果不支持，需在 ding-oa 增加告警和重试队列。写入第三方后再撤销氚云流程时，必须调用作废/撤销接口，不能期待 HTTP 自动回滚。

七、联调检查表

已确认当前应用的 SchemaCode、字段编码、流程节点和人员 ID。
ding-oa 已部署为氚云可访问的 HTTPS 地址。
氚云请求 Header、Body 与接口契约一致。
使用测试模板和测试人员，不使用生产审批。
重复提交同一流程实例不会重复创建。
钉钉返回的 instanceId 已保存并可查询。
超时、4xx、5xx 和第三方限流均有可定位日志。
失败数据有重试、人工补偿和告警方案。

八、什么时候改用氚云 OpenApi

如果需求是"从第三方拉取数据写回氚云表单"，则不是单向 HTTP 推送，应使用氚云 OpenApi 或自定义接口完成读取/写入。按照氚云操作安全规则：查询、结构扫描和导出默认只读；CreateBizObjects、UpdateBizObject、apply=true、applyUpdate=true、updateH3=true 或 dryRun=false 等写操作必须先做预览并获得明确确认。

涉及真实字段、附件、批量同步或回填时，应先读取当前应用的结构分析资料和 OpenApi 封装，确认目标环境、数据范围、回滚方式和验证结果；本文不执行任何线上写入。

本方案适合"氚云触发 → Java 中间层 → 钉钉/其他平台"的单向集成。发布前请把占位符替换为当前环境已核对的编码，并在测试环境完成一条成功、一条重复、一条失败和一条超时场景验证。