SCSAI原生JavaScript使用指南

1. 概述

本文档介绍了如何在前端PLM项目中使用现有的SCSAI原生JavaScript实现，避免重复开发连接和AML操作功能。

核心文件位置：D:\n8nscsai\SCSAI\n8n\packages\nodes-base\nodes\SCSAI

2. 现有SCSAI原生JS功能

2.1 核心API连接 (GenericFunctions.ts)

GenericFunctions.ts 提供了完整的SCSAI API连接和AML操作功能：

#### 主要功能：

| 函数名 | 功能描述 | 参数 |

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

| SCSAIApiRequest | 核心API请求函数 | method: GET/POST
endpoint: API端点
aml: AML字符串 |

| executeAMLQuery | 执行AML查询 | context: 执行上下文
amlQuery: AML查询字符串 |

| batchWriteToSCSAI | 批量写入数据 | context: 执行上下文
items: 待写入的项目数组 |

| applyAML | 应用AML操作 | itemType: 对象类型
action: 操作类型(add/edit/delete)
data: 数据
id: 对象ID |

#### 连接配置：

API连接通过SCSAIApi凭证进行配置，包含以下参数：

• URL: SCSAI服务器地址
• 用户名
• 密码
• 数据库名称
• 时区

2.2 原生JS执行器 (SCSAINativeJSExecutor.ts)

SCSAINativeJSExecutor.ts 提供了在SCSAI环境中执行JavaScript代码的功能：

#### 主要功能：

| 函数名 | 功能描述 |

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

| executeSCSAIJavaScript | 执行SCSAI原生JavaScript代码 |

| executeAMLQuery | 执行AML查询并返回结果 |

| batchWriteToSCSAI | 批量写入SCSAI数据库 |

| generateJSCodeExample | 生成JavaScript代码示例 |

| validateJSCodeSafety | 验证JavaScript代码安全性 |

3. 在前端PLM项目中使用

3.1 导入现有功能

在前端PLM项目中，可以通过相对路径导入现有功能：

// 导入核心API连接功能
import { SCSAIApiRequest, applyAML, queryItems } from '../../nodes-base/nodes/SCSAI/GenericFunctions';

// 导入JavaScript执行器功能
import { executeSCSAIJavaScript, executeAMLQuery } from '../../nodes-base/nodes/SCSAI/SCSAINativeJSExecutor';

3.2 基本使用示例

#### 3.2.1 执行AML查询

// 构建AML查询
const aml = '<AML><Item type="ItemType" action="get" select="id,name,label" /></AML>';

// 执行查询
const result = await executeAMLQuery(context, aml);

// 处理结果
if (result.success) {
  console.log('查询结果:', result.result);
} else {
  console.error('查询失败:', result.error);
}

#### 3.2.2 创建新对象

// 创建对象数据
const itemData = {
  name: 'New Item',
  description: 'Test description',
  status: 'active'
};

// 应用AML创建对象
const result = await applyAML(context, 'ItemType', 'add', itemData);

if (result) {
  console.log('对象创建成功，ID:', result.id);
} else {
  console.error('对象创建失败');
}

#### 3.2.3 执行SCSAI原生JavaScript

// JavaScript代码
const jsCode = `
// 创建新的Item
var newItem = SCSAI.newItem('ItemType', 'create');
newItem.setProperty('name', 'value');
newItem.setProperty('description', 'Item Description');
newItem.save();
console.log('Item created: ' + newItem.getID());
`;

// 执行代码
const result = await executeSCSAIJavaScript(context, jsCode);

if (result.success) {
  console.log('JavaScript执行成功:', result.result);
} else {
  console.error('JavaScript执行失败:', result.error);
}

3.3 权限和安全

#### 3.3.1 凭证管理

确保在n8n配置中设置了SCSAIApi凭证，包含正确的连接信息。

#### 3.3.2 代码安全性

使用validateJSCodeSafety函数验证要执行的JavaScript代码安全性：

const { safe, warnings } = validateJSCodeSafety(jsCode);

if (!safe) {
  console.warn('代码包含安全风险:', warnings);
  // 处理不安全代码
}

4. 扩展功能

4.1 创建自定义工具函数

如果需要在前端PLM项目中添加自定义功能，可以创建新的JS文件，但要确保不重复现有功能：

// custom-SCSAI-utils.js
import { executeAMLQuery } from '../../nodes-base/nodes/SCSAI/SCSAINativeJSExecutor';

/**
 * 自定义查询函数 - 获取活跃的ItemType列表
 */
export async function getActiveItemTypes(context) {
  const aml = '<AML><Item type="ItemType" action="get" select="id,name,label"><is_current>1</is_current></Item></AML>';
  const result = await executeAMLQuery(context, aml);
  
  if (result.success) {
    return result.result;
  } else {
    throw new Error(result.error);
  }
}

4.2 错误处理

确保在使用SCSAI API时进行适当的错误处理：

try {
  const result = await executeAMLQuery(context, aml);
  return result;
} catch (error) {
  console.error('SCSAI API错误:', error);
  // 错误处理逻辑
  throw error;
}

5. 最佳实践

1. 避免重复代码：始终使用现有的SCSAI原生JS实现，不要创建新的连接或AML操作功能
2. 使用类型检查：如果使用TypeScript，确保导入正确的类型定义
3. 安全优先：始终验证用户提供的JavaScript代码
4. 适当日志：添加必要的日志记录以方便调试
5. 错误处理：实现适当的错误处理机制

6. 参考文档

• SCSAI API文档
• n8n节点开发文档
• packages/nodes-base/nodes/SCSAI目录下的源代码

7. 维护

如果现有功能需要更新或扩展，应直接在packages/nodes-base/nodes/SCSAI目录中修改，确保所有项目都能受益于更新。

8. 联系信息

如有任何问题，请联系系统管理员或开发团队。