ECS-WEB-SDK

ECS 云底座前端相关仓库

• node >= 16

开发及编译

# nvm use 16 # important!

npm i # 安装依赖

npm run dev # 启动开发模式，可在“页面控制台”中查看输出

npm run build --lib # 打包sdk，更多配置参考 vite.config

ECS 类

• 构造参数

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | -------------------------------------- | -------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | | authorization | String | 是 | - | 用户中心权限标识，如（accessToken） | | consume | Array<String> | 是 | - | 消费的组件 | | produce | Object<{ComponentCode : ComponentVersion}> | 是 | - | 生产的组件及对应版本 | | consumeProductCodes | Array<String> | 否 | - | 消费的组件中数据提供方的产品编码，针对多个产品写入数据到同一个组件中时，精准筛选对应数据 | | getInitialData | Function | 否 | - | 对接 EcsHubPanel 时必须，需返回 Panel 所需初始数据，更多参考 EcsHubPanel | | getCurrentAllProduceComponentsFullData | Function | 否 | - | 对接 EcsHubPanel 时必须，需返回当前生产的所有数据，参数格式如方法commitAndPush参数一致 | | onEventCallback | Function | 否 | - | 对接 EcsHubPanel 时必须，Panel 对应操作的事件回调通知 | | enableLog | Boolean | 否 | true | 是否启用运行日志 | | env | String | 否 | production | 可选环境 production、test |

• ECSHubPanel 所需方法

getInitialData: ()=> Object

Panel 需要用户提供的初始信息，需要用户实现该方法

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | ------------- | -------------------------------------------- | -------- | ------ | ---------------------------------------------------------------- | | repoName | String | 是 | - | 仓库名 | | branchCode | String | 否 | master | 分支名称 | | consume | Array<{Code, Version, Products}> | 是 | - | 消费的组件，指定合约组件编码，版本，产品编码(Products 是个数组) | | produce | Object<{ComponentCode : ComponentVersion}> | 是 | - | 生产的组件及对应版本 ，与 ECS 构造参数一致 | | productCode | String | 是 | '' | 产品编码 | | author | String | 否 | - | 可读的用户唯一标识，如（zhangsan） | | commitId | String | 否 | "" | 当前仓库最新的 commitId，新仓库默认为空字符串 | | authorization | String | 否 | - | 用户中心权限标识，如（accessToken），如未登录，则 Panel 会先登录 |

getCurrentAllProduceComponentsFullData: ()=> Object

Panel 获取当前所有产品及组件的全量数据，即调用 commitAndPush 时需要传递的数据，需要用户实现该方法

onEventCallback: ({ operation, status, payload })=> {}

Panel 操作流程中的回调通知方法，如用户登录、提交、更新等操作，需要用户实现该方法；

• 操作(operation)事件列表如下：

| 事件字段 | 描述 | 返回参数（payload） | | ------------------------- | ------------ | --------------------------- | | APP_MOUNTED | 应用挂载 | - | | PANEL_VISIBILITY_CHANGE | 可见性变更 | { visible } | | REPO_CHANGE | 仓库变更 | { repoName, branchCode } | | SIGNIN | 登录 | { username, authorization } | | COMMIT_PUSH | 提交数据 | { commit } | | UPDATE_CONSUME_COMPONENTS | 更新消费组件 | { commit } |

• 状态(status)列表如下：

| 字段 | 描述 | | ------- | ---- | | SUCCESS | 成功 | | FAILED | 失败 |

APIs

init: Promise

必须“最先”调用，返回一个 Promise 对象

fetchCommits<repoName, branchCode, resolveAll>: Promise<Array<{id, author, commit_time, desc, seq_num,...}>>

获取所有提交记录

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | ---------- | ------- | -------- | ------ | ----------------------------------------------- | | repoName | String | 是 | - | 仓库名 | | branchCode | String | 否 | master | 分支名称 | | resolveAll | Boolean | 否 | true | 默认返回所有记录，如果 false 则只返回最新记录 |

fetchComponentSnapshots<repoName, commitId, branchCode>: Promise

获取仓库指定 commitId 的快照数据，如不传递则表示获取最新的快照，返回一个 Promise 对象

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | ---------- | ------ | -------- | ------ | ----------- | | repoName | String | 是 | - | 仓库名 | | commitId | String | 否 | - | 提交记录 ID | | branchCode | String | 否 | master | 分支名称 |

getComponentData<componentCode, productCodes>: Promise<Array<Object>>

获取组件数据，返回一个 Promise 对象，成功并返回数据对象数组

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | ------------- | --------------- | -------- | ---- | -------------------------- | | componentCode | String | 是 | - | 组件编码 | | productCodes | Array<String> | 否 | [] | 产品编码，查询对应产品数据 |

commitAndPush<produceData, returnSuccessWithoutChanges>: Promise<{id, author, commit_time, desc, seq_num,...}>

提交数据到云端，返回一个 Promise 对象，返回值为最新的 commit 记录

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | --------------------------- | ------- | -------- | ----- | --------------------------------------------------------- | | produceData | Object | 是 | - | 当前生成的所有组件数据 | | returnSuccessWithoutChanges | Boolean | 否 | false | 默认返回错误，如果数据没有变化；true 时，无变化则无返回值 |

• produceData 中字段如下

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | ----------------- | -------------------------- | -------- | ------ | ---------------------------------- | | repoName | String | 是 | - | 仓库名称 | | author | String | 是 | - | 可读的用户唯一标识，如（zhangsan） | | produceComponents | Array<ComponentDataItem> | 是 | - | 组件数据数组 | | productCode | String | 是 | '' | 产品编码 | | desc | String | 否 | '' | 提交信息描述 | | branchCode | String | 否 | master | 分支名称 |

ComponentDataItem

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | ------------- | ---------------------------------------------------------------------------------------------------- | -------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | componentCode | String | 是 | - | 组件编码，如（FC_MESH） | | fullData | Array<{ entityId: String, eeid: String, entityName: String, entityType: String, content: Object }> | 是 | - | 组件数据，entityId为产品范围内实体 ID 也叫 peid(project entity id) ，eeid为 ECS 实体唯一 ID，entityName为实体名称，entityType 聚合类型，如（ET_LOT） ，content 为组件内容，且必填 |

注意： content 内部的字段顺序需与特性组件定义保持一致，否则会影响 MD5 校验

query<sql>: Promise<Array<Object>

通过 SQL 查询数据，表名称为组件编码(componentCode)，如 FC_MESH，SQL 规范参考duckDB

| 参数 | 类型 | 是否必须 | 默认 | 描述 | | ---- | ------ | -------- | ---- | -------- | | sql | String | 是 | - | 查询语句 |

示例

安装依赖

import ECS from "@glodon-ecs/web-sdk";

const ecsClient = new ECS({
    authorization: 'cn-ab11f319-5469-40fd-aae9-01be5791cfa4',
    consume: [
      "FC_MESH",
    ],
    produce: { FC_GEOMETRY: "1" },
    ...
    // 参考如下 Panel示例中方法实现
    onEventCallback,
    getInitialData,
    getCurrentAllProduceComponentsFullData,
});
await ecsClient.init();

const author = "zhangsan";
const repoName = "test-0711-01";
const productCode = 'gnc';
...

const commits = await ecsClient.fetchCommits(repoName);
await ecsClient.fetchComponentSnapshots(repoName);
const FC_MESH = await ecsClient.getComponentData("FC_MESH");

...

const GEOMETRY_DATA = [...];
const componentDataItem = {
    componentCode: "FC_GEOMETRY",
    fullData: GEOMETRY_DATA.map((data) => {
        const {
        ident: { id, eeid, entity_name: entityName, entityType },
        content,
        } = data;

        return { entityId: id, eeid, entityName, content, entityType };
    }),
};

const produceComponents = [componentDataItem];
const newCommitData = await ecsClient.commitAndPush({ repoName, author, produceComponents, productCode });

...

// 通过 SQL 查询数据
const data = await ecsClient.query( "select ident from FC_MESH" );

Panel 相关示例

import ECSHubPanel from "@glodon-ecs/web-panel-sdk";

const author = "zhangsan";
const repoName = "test-0711-01";
const branchCode = "master";
const commitId = "ab11f319-5469-40fd-aae9-01be5791cf";
const authorization = "cn-ab11f319-5469-40fd-aae9-01be5791cfa4";
const productCode = "gnc";

new ECSHubPanel({
  el: "#ecs-hub-panel",
  ecsClient: ecsClient,
});

const getInitialData = () => {
  return {
    repoName,
    author,
    branchCode,
    commitId,
    authorization,
    consume: [
      {
        Code: "FC_LOT_PROPERTY",
        Version: 1,
        Products:['gns']
      }
    ],
    produce: { FC_LOT_PROPERTY: "1" },
    productCode,
  };
};

// 同 commitAndPush 方法数据组织方式
const getCurrentAllProduceComponentsFullData = ()=>{
  const GEOMETRY_DATA = [...];
  const componentDataItem = {
      componentCode: "FC_GEOMETRY",
      fullData: GEOMETRY_DATA.map((data) => {
          const {
          ident: { id, eeid, entity_name: entityName, entityType },
          content,
          } = data;

          return { entityId: id, eeid, entityName, content, entityType };
      }),
  };

  const produceComponents = [componentDataItem];
  return { repoName, author, produceComponents, productCode }
}

const onEventCallback = ({ operation, status, payload }) => {
  // 根据事件类型处理不同业务场景
};

注意

由于 S3 对于 URL 上特殊符号签名的校验规则与华为不匹配，如等号(=)导致签名失败，因此文件修改@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js；去除对 params.url 的 uriEncode

• 源码

export function createS3Headers(params: S3Params, payloadParams : S3PayloadParams | null = null) : Map<string, string> {
...
- let canonicalRequest = params.method + "\n" + uriEncode(params.url) + "\n" + params.query;
+ let canonicalRequest = params.method + "\n" + params.url + "\n" + params.query;
...
}

• 混淆代码

38390 let o = t.method + "\n" + t.url + "\n" + t.query;

修改 query 参数的签名编码

• 源码

export function getS3Params (config : S3Config | undefined, url: string, method : string) : S3Params {
...

+ path = path.split('?');

return {
-    url: path,
+    url: path[0],
-    query: "",
+    query: path[1] || "",
...
}

修复 xhr.getResponseHeader('Content-Range') 报错

• 源码

- const contentRange = xhr.getResponseHeader('Content-Range')?.split('/')[1];
+ const contentRange = undefined;