# CPS BI SDK

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

## 安装

```bash
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`

## 快速接入

```tsx
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} onSchemaChange={(next) => console.log(next)} />
      <DashboardViewer schema={schema} />
    </DashboardConfigProvider>
  )
}
```

## 运行时机制

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

## 开发命令

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

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

```bash
# .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`](/Users/shitingting/Documents/code/cps-bi-sdk/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`

建议固定使用以下顺序：

```bash
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 平台策略允许且影响面可控时，才考虑撤包。
