@anov/cic-standard-sdk 0.0.1

package/README.md

@@ -0,0 +1,229 @@
+# CIC 标准库 (Component Interaction Configuration)
+
+​CIC（Common Intermediate Configuration，大屏可视化交换格式）​​ 是一套面向可视化大屏项目的 ​​ 结构化序列化标准 ​​，聚焦于定义中间层的通用配置规则。其核心目标是解决大屏项目在跨平台迁移、批量导入/导出及版本化管理中的关键痛点——通过 ​​ 标准化数据格式、组件交互逻辑与资源引用方式 ​​，赋予大屏内容“一次创建，多端复用”的序列化能力，系统性解决多组件协作、跨环境一致性及可扩展性难题。本仓库提供了该协议的 TypeScript 类型定义、JSON Schema 校验文件以及核心 SDK 工具库。
+
+## 目录结构
+
+```
+CIC-Standard-1.0/
+├── types/              # TypeScript 类型定义（核心协议）
+│   ├── index.ts        # 入口，定义 CICConfig, CICPage
+│   ├── componets.ts    # 组件实例与结构定义
+│   ├── events.ts       # 事件与 DSL 定义
+│   ├── variables.ts    # 变量与作用域定义
+│   ├── dataSources.ts  # 数据源定义
+│   ├── deps.ts         # 资源依赖定义
+│   ├── meta.ts         # 元数据定义
+│   └── registry.ts     # 组件注册表定义
+├── sdk/                # 核心工具库
+│   └── CICSDK.ts       # SDK 类定义与实现
+├── schema/             # JSON Schema 定义
+│   └── cic.schema.json # Draft-07 标准 Schema
+├── examples/           # 示例文件
+│   └── full-demo.json  # 完整功能演示配置
+├── tests/              # 单元测试
+│   └── sdk.test.ts     # SDK 测试用例
+├── dist/               # 构建产物
+│   ├── cic-sdk.es.js   # ESM 格式
+│   ├── cic-sdk.cjs.js  # CJS 格式
+│   └── cic-sdk.umd.js  # UMD 格式
+└── vite.config.ts      # Vite 构建配置
+```
+
+## 1. 协议核心概念
+
+CIC 协议通过 JSON 描述一个完整的应用页面结构与行为：
+
+- **Config**: 全局配置根节点，包含页面列表、全局变量、资源依赖等。
+- **Page**: 页面定义，包含布局配置、组件树、页面级数据源。
+- **Component**: 组件实例，分为 View (视图)、Container (容器)、Logic (逻辑) 三类。
+- **Event**: 强大的事件 DSL，支持变量操作、页面跳转、组件控制、自定义脚本等，支持条件执行与调度（Order/Delay）。
+- **Variable**: 多级作用域（Global > Page > Component）的变量管理，支持 string/number/object/array/function。
+- **DataSource**: 统一的数据源定义（REST, WebSocket, Static），支持轮询与依赖。
+
+## 2. SDK 使用指南
+
+SDK 提供了操作 CIC 标准的常用工具方法，现已重构为面向对象的 `CICSDK` 类，内置 **Ajv** 引擎进行全量 JSON Schema 校验，并支持 Vite 构建与 Tree-shaking。
+
+### 安装与引入
+
+推荐使用 `pnpm` 安装依赖：
+
+```bash
+pnpm install cic-standard-sdk
+```
+
+```typescript
+import { CICSDK } from 'cic-standard-sdk';
+import { CICConfig } from 'cic-standard-sdk/types';
+
+const config: CICConfig = { ... };
+const sdk = new CICSDK(config); // 实例化时自动执行 Schema 校验
+```
+
+### 常用 API
+
+**1. 验证配置**（`sdk/CICSDK.ts:174`）
+
+SDK 集成了完整的 JSON Schema (Draft-07)，可验证字段类型、必填项、枚举值等。
+
+```typescript
+// 静态方法校验
+const result = CICSDK.validateConfig(myConfig)
+if (!result.valid) {
+  console.error('配置校验失败:', result.error)
+  // 输出示例: "/meta/layout/type must be string; /version must have required property 'version'"
+}
+
+// 实例化时自动校验，失败抛出异常
+try {
+  const sdk = new CICSDK(myConfig)
+} catch (e) {
+  console.error(e.message)
+}
+```
+
+**2. 查找组件**（`sdk/CICSDK.ts:47`、`sdk/CICSDK.ts:62`）
+
+```typescript
+// 按 ID 查找（支持跨页面）
+const comp = sdk.findComponent('comp_btn_01')
+if (comp) {
+  console.log('找到组件:', comp.role)
+}
+
+// 查找组件所属页面
+const page = sdk.findPageByComponent('comp_btn_01')
+console.log('所在页面:', page?.id)
+```
+
+**3. 获取变量值（自动处理作用域）**（`sdk/CICSDK.ts:80`、`sdk/CICSDK.ts:109`）
+
+```typescript
+// 优先查找组件级 -> 页面级 -> 全局
+const val = sdk.getVariable({ pageId: 'p1', componentId: 'c1' }, 'theme')
+
+// 通过引用字符串获取
+const val2 = sdk.getVariableByRef('global.theme')
+```
+
+**4. 遍历组件树**（`sdk/CICSDK.ts:125`、`sdk/CICSDK.ts:220`）
+
+```typescript
+// 遍历整个配置的所有组件
+sdk.walkComponents((comp, page, parent) => {
+  console.log(`遍历到: ${comp.id} (页面: ${page.id})`)
+  // 返回 false 可停止遍历
+  return true
+})
+```
+
+**5. 静态工具**（`sdk/CICSDK.ts:199`、`sdk/CICSDK.ts:220`）
+
+### 生成器 API（严格校验 + 规范化）
+
+- `createDataSource/validateDataSource/normalizeDataSource`（`sdk/generators/dataSource.ts`）
+- `createComponent/validateComponent/normalizeComponent`（`sdk/generators/component.ts`）
+- `createPage/validatePage/normalizePage`（`sdk/generators/page.ts`）
+- `createMeta/validateMeta/normalizeMeta`（`sdk/generators/meta.ts`）
+- `createLayout/validateLayout/normalizeLayout`（`sdk/generators/meta.ts`）
+- `createVariables/validateVariables/normalizeVariables`（`sdk/generators/variables.ts`）
+- `createDependency/validateDependency/normalizeDependency`（`sdk/generators/dependency.ts`）
+- `createRegistryComponent/validateRegistryComponent/normalizeRegistryComponent`（`sdk/generators/registry.ts`）
+
+所有生成器返回统一 `Result<T>`：`{ ok: boolean; value?: T; errors?: any[] }`。`normalizeX` 在校验失败时抛出错误，方便在构建或运行时快速失败。
+
+```typescript
+// 解析路径取值
+const val = CICSDK.getValueByPath(someObj, 'a.b[0].c', 'default')
+
+// 深度遍历组件树片段
+CICSDK.traverseTree(someComponent, c => {
+  console.log(c.id)
+})
+```
+
+## 3. 开发与测试
+
+本项目使用 Vite 进行构建，Vitest 进行单元测试，推荐使用 `pnpm` 管理依赖。
+
+### 命令脚本
+
+- `pnpm install`: 安装依赖
+- `pnpm run dev`: 启动开发模式
+- `pnpm run build`: 构建 SDK（输出 `dist/`）
+- `pnpm test`: 运行单元测试
+
+### 构建产物
+
+- `dist/cic-sdk.es.js`: ESM 格式，适用于现代前端项目（Vite/Webpack）。
+- `dist/cic-sdk.cjs.js`: CJS 格式，适用于 Node.js `require`。
+- `dist/cic-sdk.umd.js`: UMD 格式，适用于 `<script>` 引入。
+
+在 `package.json` 中已配置 `exports` 字段与 `sideEffects: false`，支持 Tree‑shaking 与正确的导入解析。
+
+## 4. JSON Schema 校验
+
+`schema/cic.schema.json` 提供了完整的协议约束。
+
+### 在 VS Code 中启用智能提示
+
+在你的 JSON 配置文件头部添加 `$schema` 字段：
+
+```json
+{
+  "$schema": "./schema/cic.schema.json",
+  "version": "1.0.0",
+  "meta": { ... }
+}
+```
+
+这将启用：
+
+- 字段自动补全
+- 枚举值提示（如 `type`: `view` | `container`）
+- 结构校验（必填字段检查）
+
+### 常见报错与排查
+
+- Ajv 错误输出包含 `instancePath`：根据路径定位到具体字段（如 `/pages/0/components/1/role must be equal to constant`）。
+- 组件判别联合：`view` 必须提供 `component`；`container` 必须提供 `children`；`logic` 必须提供 `component`（`LogicRef`）。
+- 数值字段：如 `pollInterval/timeout` 必须为数字；生成器在 `defaults` 指定时会注入确定性默认。
+
+### 最佳实践
+
+- 严格模式：默认不做隐式容错，缺失必填即报错；通过 `options.defaults` 明确提供默认值。
+- 按需引入：仅从 `CICSDK` 静态导出使用所需生成器函数，减少打包体积。
+- ID 规范：通过生成器的 `generateId` 自动生成 `uuid`，避免冲突。
+
+## 5. Schema 与 Mock 脚本
+
+### Schema 生成脚本（`scripts/generate-schema.ts`）
+
+- 通过配置项裁剪复杂度、保留必要字段，输出更简洁可用的 JSON Schema。
+
+### Mock 生成与清洗（`scripts/generate-mock.ts`）
+
+- 基于 Schema 随机生成后，使用 `deepClean` 进行规范化：
+  - 修正非法数组项、补齐 `id`（uuid）、规范 `url`/`ws` 链接。
+  - 为 `code` 字段提供可执行的默认实现。
+
+示例输出能直接通过 Ajv 校验并用于演示与测试。
+
+## 5. 示例说明
+
+请查看 `examples/full-demo.json`，它展示了：
+
+- 如何定义全局主题变量。
+- 如何引入外部 ECharts 库与字体资源。
+- 如何配置 REST 数据源。
+- 如何构建包含图表与按钮的组件树。
+- 如何通过点击事件触发变量更新与自定义逻辑。
+
+## 安全声明
+
+CIC 允许执行动态代码（Custom Events, Logic Components）。在生产环境中渲染不可信的 CIC 配置时，请务必：
+
+1. 使用 iframe 或 Web Worker 隔离渲染环境。
+2. 限制代码执行的上下文访问权限。
+3. 对 `CustomRemoteEvent` 加载的外部脚本进行域名白名单控制。