### 聚水潭数据集成到金蝶云星辰V2：实现调拨单至其他入库单的高效对接
在现代企业的数据处理过程中，系统集成扮演着不可或缺的角色。如何高效、准确地完成多个业务系统间的数据同步，是每个技术团队都需要面对的重要挑战。本文将分享一个成功案例：使用轻易云数据集成平台，将聚水潭中的调拨单顺利对接到金蝶云星辰V2，实现其他入库单（调拨入库）的自动化。
本次案例中，我们主要利用了聚水潭API接口`/open/allocate/query`来抓取源数据，并通过轻易云的平台进行相关转换，再写入至金蝶云星辰V2的API接口`/jdy/v2/scm/inv_other_in`。以下是整个方案实施的一些核心技术点：
1. **确保不漏单**：为了保证所有待处理的调拨单都能准确无遗漏地被抓取和处理，我们设计了一套定时任务机制，可靠定时从聚水潭按分页方式获取最新数据，同时处理限流问题，以应对大规模数据量。
2. **快速批量写入**：由于业务需求是在较短时间内完成大量数据信息的传输与记录，因此我们特别优化了批量写入金蝶云星辰V2 API 的算法，提高整体操作效率。
3. **实时监控及日志记录**：为全面掌握整个数据流动过程，系统实施了实时监控功能并保留详细的日志记录。这不仅有助于随时发现可能出现的问题，也为后续变更提供宝贵参考。
4. **异常处理与重试机制**：在实际运行过程中，不可避免会遇到网络抖动等导致的数据发送失败。因此，为保障最终一致性，我们针对各种常见异常设计了智能错误重试机制，有效降低因意外情况造成的数据丢失。
5. **格式差异解决方案**：不同系统间的数据格式差异常是跨系统对接中的难题之一。在此次项目中，通过自定义映射规则，将聚水潭输出内容精准匹配至金蝶云所需格式，大大简化双方向通信复杂度。
这些步骤综合起来，为我们的调拨单至其他入库单（调拨入库）整合方案奠定了坚实基础。在下文中，我们将进一步深入探讨各个环节具体实现细节，以期为类似场景下的开发者提供可借鉴经验和思路。
### 调用聚水潭接口/open/allocate/query获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将详细探讨如何通过轻易云数据集成平台调用聚水潭的接口 `/open/allocate/query` 来获取调拨单数据，并进行初步加工处理。
#### 接口配置与请求参数
首先，我们需要了解 `/open/allocate/query` 接口的基本配置和请求参数。该接口采用 POST 方法进行调用，主要用于查询调拨单信息。以下是具体的请求参数配置：
- `modified_begin`：修改起始时间，类型为字符串，用于指定查询的起始时间点。
- `modified_end`：修改结束时间，类型为字符串，用于指定查询的结束时间点。
- `page_index`：第几页，类型为字符串，用于分页查询。
- `page_size`：每页多少条，类型为字符串，默认值为30，最大值为50。
- `type`：调拨类型，类型为字符串，此处固定为“调拨入”。
这些参数可以通过元数据配置文件进行自动填充，例如：
```json
{
"field": "modified_begin",
"label": "修改起始时间",
"type": "string",
"describe": "修改起始时间",
"value": "{{DAYS_AGO_1|datetime}}"
}
```
这里使用了模板变量 `{{DAYS_AGO_1|datetime}}` 来动态生成前一天的日期时间。
#### 数据过滤条件
为了确保获取的数据符合业务需求，我们还需要设置一些过滤条件。在本例中，我们设置了以下条件：
- `link_warehouse`：仓库链接，逻辑操作符为 `in`，值包括多个仓库名称，如“恩比仓主仓”、“恩比仓销退仓”等。
- `status`：状态，逻辑操作符为 `eqv2`（等于），值为“Confirmed”。
这些条件可以通过元数据配置文件中的 `condition` 字段进行定义：
```json
{
"field": "link_warehouse",
"logic": "in",
"value": "恩比仓主仓,恩比仓销退仓,恩比仓次品仓,恩比仓报废仓,恩比仓返修仓,恩比仓进货仓"
},
{
"field": "status",
"logic": "eqv2",
"value": "Confirmed"
}
```
#### 数据请求与清洗
在完成接口配置和过滤条件设置后，我们可以发起数据请求。轻易云平台提供了全异步的数据处理机制，可以有效提升数据请求和处理效率。
发起请求后，我们会得到一个包含调拨单信息的响应。此时，需要对响应数据进行初步清洗和加工，以便后续的数据转换和写入步骤。例如，可以对调拨单中的日期格式进行标准化处理，对数值字段进行单位转换等。
#### 实际案例分析
假设我们需要获取过去一天内所有已确认的“调拨入”类型调拨单，并将其导入到星辰系统作为其他入库单。以下是具体的实现步骤：
1. **定义请求参数**：
```json
{
"modified_begin": "{{DAYS_AGO_1|datetime}}",
"modified_end": "{{CURRENT_TIME|datetime}}",
"page_index": "1",
"page_size": "30",
"type": "调拨入"
}
```
2. **设置过滤条件**：
```json
[
{
"field": "link_warehouse",
"logic": "in",
"value": ["恩比仓主仓", "恩比仓销退仓", ...]
},
{
"field": "status",
"logic": "eqv2",
"value": ["Confirmed"]
}
]
```
3. **发起请求并处理响应**：
- 使用轻易云平台提供的API调用功能发起POST请求。
- 对返回的数据进行清洗，如去除无效字段、标准化日期格式等。
4. **准备下一步的数据转换与写入**：
- 将清洗后的数据准备好，以便后续写入星辰系统。
通过以上步骤，我们可以高效地从聚水潭系统获取所需的调拨单信息，并为后续的数据处理做好准备。这不仅提高了数据集成的效率，也确保了数据的一致性和准确性。
### 使用轻易云数据集成平台实现金蝶云星辰V2API接口的数据转换与写入
在数据集成生命周期的第二步中，我们需要将已经从源平台（如聚水潭）获取并清洗后的数据进行ETL（Extract, Transform, Load）转换，最终写入目标平台（如金蝶云星辰V2）。本文将详细探讨如何利用轻易云数据集成平台的元数据配置，将调拨单数据转换为金蝶云星辰V2API接口所能接收的格式，并成功写入目标平台。
#### API接口元数据配置解析
首先，我们来看一下元数据配置的具体内容：
```json
{
"api": "/jdy/v2/scm/inv_other_in",
"effect": "EXECUTE",
"method": "POST",
"number": "id",
"id": "id",
"name": "id",
"idCheck": true,
"request": [
{"field": "bill_date", "label": "单据日期", "type": "string", "describe": "单据日期", "value": "{io_date}"},
{"field": "bill_no", "label": "单据编码", "type": "string", "describe": "单据编码", "value": "{io_id}"},
{"field": "custom_field",
"label": "自定义字段",
"type": "object",
"children":[
{"field":"custom_field__1__3urq5p9yivjiam","label":"其他入库类型","type":"string","value":"调拨入库"}
]
},
{"field": "trans_type_id",
"label": "业务类型id",
"type": "string",
"describe":"业务类型id",
"value":"12"
},
{"field":"operation_key","label":"操作类型","type":"string","describe":"操作类型，审核audit、提交submit","value":"audit"},
{"field":"remark","label":"备注","type":"string","value":"{remark}"},
{"field":"material_entity",
"label":"商品分录",
"type":"array",
"describe":"商品分录",
"value":"items",
...
}
]
}
```
#### 数据字段映射与转换
1. **单据日期与单据编码**：
- `bill_date` 和 `bill_no` 分别对应 `{io_date}` 和 `{io_id}`。这些字段直接从源数据中提取，不需要复杂的转换。
2. **自定义字段**：
- `custom_field` 中包含了一个子字段 `custom_field__1__3urq5p9yivjiam`，其值固定为 `"调拨入库"`。这个字段用于标识特定的入库类型。
3. **业务类型ID与操作类型**：
- `trans_type_id` 固定为 `"12"`，表示特定的业务类型。
- `operation_key` 固定为 `"audit"`，表示审核操作。
4. **备注**：
- `remark` 对应 `{remark}`，从源数据中提取备注信息。
5. **商品分录**：
- `material_entity` 是一个数组，每个元素代表一个商品分录。它包含多个子字段，如商品ID、数量、单位、仓库和出库成本等。
- 商品ID (`material_id`) 使用 `_findCollection find id from a481458e-26be-330f-a8ab-69c01d1837e1 where number={{items.sku_id}}` 从预定义集合中查找。
- 数量 (`qty`) 直接映射为 `{{items.qty}}`。
- 单位 (`unit_id`) 固定为 `"4"`。
- 仓库 (`stock_id`) 使用 `_findCollection find id from 6346526e-1f90-33cf-8c77-05d1fc7d9134 where name={link_warehouse}` 查找。
- 出库成本 (`cost`) 使用 `_findCollection find skus_cost_price from 152f8a9b-100c-34b4-8dd4-3eab4deba9b3 where skus_sku_id={{items.sku_id}}` 查找。
#### 实现步骤
1. **提取源数据**：
从聚水潭系统提取调拨单的数据，包括单据日期、单据编码、备注和商品分录等信息。
2. **映射与转换**：
根据上述元数据配置，将提取的数据进行映射和转换。例如，将 `{io_date}` 映射到 `bill_date` 字段，将 `{io_id}` 映射到 `bill_no` 字段等。
3. **构建请求体**：
根据转换后的数据构建符合金蝶云星辰V2API接口规范的请求体。例如：
```json
{
...
{
bill_date: '2023-10-01',
bill_no: 'DB202310010001',
custom_field: {
custom_field__1__3urq5p9yivjiam: '调拨入库'
},
trans_type_id: '12',
operation_key: 'audit',
remark: '这是一个测试备注',
material_entity: [
{
material_id: '1234567890',
qty: '100',
unit_id: '4',
stock_id: '9876543210',
cost: '50'
}
...
]
}
}
```
4. **发送请求并处理响应**：
使用 POST 方法将构建好的请求体发送到 `/jdy/v2/scm/inv_other_in` 接口，并处理响应结果。如果成功，则记录日志或更新状态；如果失败，则进行错误处理和重试机制。
通过以上步骤，我们可以高效地将源平台的数据转换并写入到目标平台，实现不同系统间的数据无缝对接。这不仅提升了业务效率，还确保了数据的一致性和准确性。
