CPS BI SDK

前端可嵌入 BI 仪表盘 SDK，提供 Builder（编辑态）与 Viewer（运行态）两套能力。

安装

pnpm add cps-bi-sdk react react-dom echarts echarts-for-react

当前手动发包验证基线：

• Node：^20.19.0 || >=22.12.0
• pnpm：>=10.30.0
• peerDependencies：react/react-dom >=17、echarts >=5、echarts-for-react >=3

快速接入

import {
  DashboardBuilder,
  DashboardConfigProvider,
  DashboardViewer,
  type DashboardDataExecuteRequest,
  type DashboardSchema,
  type WidgetManifest
} from "cps-bi-sdk"
const widgets: WidgetManifest[] = [
  {
    name: "Metric",
    icon: null,
    widgetCode: "metric-card",
    kind: "builtin",
    category: "view",
    minWidth: 4,
    minHeight: 3,
    defaultConfig: {},
    component: ({ data }) => <pre>{JSON.stringify(data)}</pre>
  }
]

function App({ schema }: { schema: DashboardSchema }) {
  return (
    <DashboardConfigProvider
      services={{
        dataSourceAdapters: {
          "metric-card": {
            execute: async ({ component, trigger }: DashboardDataExecuteRequest) => {
              return [{ widgetCode: component.widgetCode, trigger: trigger.type }]
            }
          }
        }
      }}
      widgets={widgets}
    >
      <DashboardBuilder
        initialSchema={schema}
        resetKey={`${schema.id}:${schema.version}:${schema.updateTime}`}
        onSchemaChange={(next) => console.log(next)}
      />
      <DashboardViewer schema={schema} />
    </DashboardConfigProvider>
  )
}

当宿主切换模板版本、发布成功后回写远端快照，或需要清空 Builder 内部的选中态 / undo / redo / dirty 状态时，请更新 resetKey。initialSchema 负责提供初始内容，resetKey 负责显式触发编辑器会话重置。

运行时机制

• 数据注入：宿主通过 services.dataSourceAdapters 注册 adapter，SDK 内部 data runtime coordinator 自动注入 AbortSignal / scene / trigger。
• 降级渲染：内置 loading / empty / error fallback，可通过 emptyRender / errorRender 覆盖。
• 联动引擎：通过 notifyUpdate / onReceiveUpdate 传递事件，支持目标匹配（uniqueCode/widgetCode）。
• 熔断保护：事件总线内置 TTL 与 1 秒频率阈值拦截，避免联动风暴放大。

开发命令

pnpm typecheck
pnpm gate:test
pnpm build
pnpm bench:linkage
pnpm check:exports
pnpm pack:inspect
pnpm pack:smoke

Agent 或本地定向测试默认走固定门禁入口：

# .gate-test-targets
tests/builder/dashboard-builder.test.tsx
tests/viewer/dashboard-viewer.test.tsx

pnpm gate:test

.gate-test-targets 为本地忽略文件；只有临时排障时，才建议直接执行 pnpm gate:test -- <files...>。

发布检查清单

1. 执行质量门禁：pnpm typecheck && pnpm gate:test && pnpm build。
2. 执行性能基准：pnpm bench:linkage。
3. 执行导出检查：pnpm check:exports。
4. 执行真实打包与安装验证：pnpm pack:inspect && pnpm pack:smoke。
5. 确认 docs/tasks/roadmap.md 与 docs/tasks/backlog.md 状态已更新。

npm 官方手动发版

1. 确认当前登录的是目标账号：npm whoami。
2. 确认 npm 官方 registry 生效：npm config get registry，期望结果为 https://registry.npmjs.org/。
3. 检查目标包名是否空闲：npm view cps-bi-sdk version || true。
4. 如需发新版本，先更新 package.json 中的 version。
5. 执行发布前校验：pnpm release:manual:check。
6. 正式发布：npm publish。
7. 发布后验证：
   • npm view cps-bi-sdk
   • npm install cps-bi-sdk react react-dom echarts echarts-for-react

建议固定使用以下顺序：

npm whoami
npm config get registry
npm view cps-bi-sdk version || true
pnpm typecheck
pnpm gate:test
pnpm build
pnpm pack:inspect
pnpm check:exports
pnpm pack:smoke
npm publish
npm view cps-bi-sdk

如果 npm view cps-bi-sdk version 返回 404，说明当前名字还未发布，可继续首发；如果返回已存在版本，则需要先改包名。

版本与回滚约定

• 版本策略：手动发包阶段继续遵守 SemVer；功能新增升 minor，修复升 patch，破坏性变更升 major。
• 回滚原则：不要覆盖同一版本重新发包；优先发布新的修复版本，或调整 dist-tag 回退流量。
• 故障处理：如果错误版本已经被消费，优先发布补丁版本；只有在 npm 平台策略允许且影响面可控时，才考虑撤包。