SCSAI 调用流程指南：从初始化到降级策略，一篇就够

在日常开发中，与 SCSAI 系统交互是不少前端同学头疼的事——AML 语法、异步初始化、结果解析……稍有不慎就会踩坑。今天我们就来梳理一套完整、可靠的 SCSAI 调用流程，包含前端初始化、AML 执行、结果解析以及降级策略，帮你一键打通 SCSAI 数据通道。

一、初始化：确保 SCSAI 就绪

核心思路：先加载 JS 库，再创建 agent 实例，最后暴露全局对象。

// 加载 SCSAI 核心脚本
loadSCSAIJs() {
  // 通过动态创建 script 标签加载 /Scripts/SCSAI.agent.js
  // 加载完成后 new agent() 并赋值给 window.sciot
}

• 防重复加载：已存在 window.sciot 则直接返回。
• 错误处理：加载失败或初始化异常会 reject，并打印友好日志。
• 登录检查：初始化后调用 sciot.isLoggedIn() 确认用户已登录。

关键文件：/app/lib/SCSAI/client.ts 中的 initSCSAI() 方法，它串联了上述步骤，是调用 SCSAI 的“总开关”。

二、执行 AML：数据查询的标准姿势

SCSAI 的查询语言是 AML（类似 XML），前端通过 sciot.applyAML() 发送请求，返回 XML 字符串。

2.1 原生调用

const result = await sciot.applyAML('<AML><Item type="ECR" action="get"></Item></AML>');

返回的是 XML 字符串，我们需要进一步解析。

2.2 解析 XML → JSON

推荐封装一个 parseAmlResult() 函数：

• 先检查 XML 解析错误（）和 AML 业务错误（）。
• 再遍历 元素，提取 type、id 属性及所有子元素文本。
• 最终返回结构清晰的数组对象。

export function parseAmlResult(xmlString) {
  // 使用 DOMParser 解析
  // 检查错误节点
  // 提取 Item 数组
}

2.3 一次封装：执行 + 解析

为了减少重复代码，我们把两步合并为 executeAndParseAml(aml)，直接返回解析后的 JSON，异常时返回错误信息。

export async function executeAndParseAml(aml) {
  const result = await executeAml(aml);
  if (!result.success) return result;
  try {
    const items = parseAmlResult(result.data);
    return { success: true, data: items };
  } catch (e) {
    return { success: false, error: e.message };
  }
}

文件位置：/app/lib/SCSAI/aml.ts

三、降级策略：当 SCSAI 不可靠时，我们还有本地数据

场景：网络波动、服务异常、用户未登录……任���可能导致 SCSAI 调用失败的情况。为了保证用户体验，我们需要一个“兜底方案”。

3.1 设计思路

优先级：SCSAI 数据 > 本地缓存数据。

如果 SCSAI 调用成功且返回非空数据，则直接使用；否则从本地数据库（如 IndexedDB、localStorage）中获取对应类型的数据。

async function executeAmlWithFallback(aml, itemType, localKey?) {
  // 1. 尝试 SCSAI 调用
  const result = await executeAndParseAml(aml);
  if (result.success && result.data?.length > 0) {
    return { ...result, source: 'SCSAI' };
  }
  // 2. 降级到本地数据
  const localData = getLocalData(itemType, localKey);
  return { success: true, data: localData, source: 'local' };
}

好处：

• 系统更健壮，SCSAI 挂掉也不影响基本功能。
• 开发调试时可强制走本地数据，避免依赖真实环境。

文件位置：/app/lib/SCSAI/fallback.ts

四、完整调用流程速览

1. loadSCSAIJs()      → 加载 SCSAI.agent.js
2. new agent()   → 创建 agent 实例
3. window.sciot      → 设置全局对象
4. sciot.applyAML()  → 执行 AML 查询
5. parseAmlResult()  → 解析 XML 为 JSON
6. 降级策略          → SCSAI 失败时使用本地数据

五、快速验证（浏览器控制台）

开发阶段，你可以直接在控制台测试：

// 1. 加载 SCSAI
fetch('/Scripts/SCSAI.agent.js').then(r => r.text()).then(eval);

// 2. 创建实例
const agent = new agent();

// 3. 设置全局对象
window.sciot = agent;

// 4. 测试查询 ECR 类型
window.sciot.applyAML('<AML><Item type="ECR" action="get"></Item></AML>')
  .then(r => console.log(r))
  .catch(e => console.error(e));

六、关键文件索引

| 文件 | 位置 | 用途 |

|------|------|------|

| client.ts | /app/lib/SCSAI/client.ts | SCSAI 初始化与连接管理 |

| aml.ts | /app/lib/SCSAI/aml.ts | AML 执行与结果解析 |

| fallback.ts | /app/lib/SCSAI/fallback.ts | 降级策略（SCSAI→本地） |

| connection.ts | /app/lib/SCSAI/connection.ts | SCSAI 连接配置（如有） |

写在最后

SCSAI 的前端调用并不复杂，关键在于规范化流程和异常处理。把初始化、AML 执行、结果解析、降级策略封装成独立模块，既能提高可维护性，也能让团队协作更顺畅。

如果你正在开发与 SCSAI 交互的功能，不妨参考本文的架构，直接复用或微调代码。遇到问题欢迎留言交流～