系统使用指南

欢迎使用系统指南。本文档全面概述了现代无头数据转换 (Modern Headless Data Transformation) SaaS，该平台在设计时提供类似 Altova MapForce 的“Schema优先”可视化体验，在运行时提供 Serverless API 执行能力。

1. 核心架构与工作流

本平台连接了低代码的易用性和专业代码的灵活性。您无需编写自定义脚本，而是可以直观地对数据结构进行可视化映射。

• 前端 (设计器): 基于 React Flow 的可视化画布，在此您可以连接源和目标 Schema。
• 引擎 (JSONata): 每一次可视化映射操作都会实时编译为 .jsonata 表达式文件。JSONata 是一种为 JSON 数据设计的轻量级、声明式查询与转换语言。
• 后端 (运行时): 转换任务通过 Serverless API (如 AWS Lambda) 瞬间执行。

XML/XSD 支持 (适配器模式)

虽然引擎底层基于 JSON 运行，但它通过 适配器模式 原生支持 XML 和 XSD 格式：

1. 设计时: 您可以选择“XML”格式并上传 .xsd 文件。系统会将 XSD 转换为内部的 JSON Schema，并将其渲染为可视化树结构。XML 属性会被自动添加 @_ 前缀以便识别。
2. 运行时: 系统拦截 application/xml 请求，利用 fast-xml-parser 将 XML 解析为 JSON，执行 JSONata 转换逻辑，并在需要时将输出重新序列化为 XML 字符串。

2. 使用可视化映射器

平台的核心是可视化映射器，由双向 Schema 可视化树和拖拽画布组成。

导入 Schema

• 导入您的 源 (Source) 和 目标 (Target) Schema。支持 JSON 示例、JSON Schema 或 XSD 文件。
• 界面提供交互式树状拓扑图。对于深层嵌套的 Object 和 Array，支持自由折叠与展开。
• 字段类型 (String, Number, Boolean, Array, Object) 都配有专属的图标与颜色标识。

声明式映射

• 拖拽连线: 直接将源字段拖拽到目标字段上，即可建立映射关系。
• 类型检查: 连线时系统会进行实时的类型兼容性检查。例如，将 String 映射到 Number 可能会触发类型强转提示，或自动添加转换函数。

3. 高级逻辑与函数管道

您不仅能进行简单的 1 对 1 字段映射，还可以将复杂逻辑直接注入到映射连线中。

函数节点

从左侧函数面板拖拽任何内置函数到连线上，即可对数据进行转换。

• 字符串函数: Uppercase, Lowercase, Trim, Substring, Replace 等。
• 数学函数: Round, Multiply, Add 等。
• 条件逻辑: If/Else, 默认值, Lookup 查找表等。

函数节点支持 链式调用（如：Source -> Uppercase -> Substring -> Target）。部分函数（如 Concatenate）支持多输入句柄，允许将多个源字段合并到一个目标字段。

虚拟节点 (中间变量)

对于中间计算或固定常量，您可以创建虚拟节点。它们充当自定义变量，在将数据传递给最终目标之前对数据进行处理或聚合。

数组上下文处理

数组转换是数据映射中的常见难点。当连接两个数组时，系统将弹出 数组上下文对话框：

1. 遍历 (Iterate): 逐元素映射（如：源列表的商品映射到目标列表的产品）。
2. 聚合 (Aggregate): 将多个元素汇总为单个值（如：对一组价格求和计算 totalAmount）。
3. 索引匹配 (Index Match): 精确提取指定索引的元素。
4. 过滤 (Filter): 附带条件表达式，筛选后进行处理。

4. 实时预览与调试

在画布下方，平台提供 零延迟 的实时预览与调试面板。

• 即时反馈: 每次画线或插入函数时，底层的 JSONata 表达式都会被即时编译，并在浏览器中基于示例数据运行，瞬间展示转换结果。
• 反向溯源: 点击转换后输出面板中的某个值，系统会在画布上高亮显示生成该值所对应的特定连线和函数节点，让调试变得轻而易举。

5. 部署与 API 调用

当转换规则设计满意后：

1. 保存并发布: 平台会安全存储编译后的 JSONata 规范。
2. API 执行: 系统为您的转换项目分配一个专用的 API 端点 (POST /api/v1/transform)。
   • 使用 API Key 进行调用鉴权。
   • 将原始数据（JSON 或 XML）及项目 ID 作为请求体发送。
   • Serverless 后端将瞬间执行您的转换规则，并自动应对高并发请求。

AI 智能助手 (即将推出)

后续更新将引入 AI Copilot 助手。它能通过语义分析自动建议字段匹配（如 fname -> firstName），并支持“将所有价格乘以 1.2”等自然语言命令，AI 将为您自动生成并插入对应的函数节点。