# 白洞门店云开放接口 SDK 发布说明

## 发布目标

JavaScript SDK 用于服务端系统接入白洞门店云开放接口。发布时必须保证签名规则、错误码、分页参数、重试策略、类型声明和变更记录同步更新。

## 语义化版本

- 主版本：签名规则、构造参数或返回结构出现不兼容变更。
- 次版本：新增开放资源方法、错误码、类型声明或向后兼容能力。
- 修订版本：文档、示例、内部校验或兼容性修正。

## 发布前校验

在仓库根目录执行：

```bash
node home-frontend/assets/whitehole-open-api-sdk.verify.js
```

校验脚本会检查：

- `whitehole-open-api-sdk.js` 可被 Node.js 解析。
- `SDK_VERSION` 与变更记录中的最新版本一致。
- `OPEN_API_ERROR_CODES` 覆盖当前错误码表。
- `buildPageQuery` 会限制 `pageSize` 不超过 100。
- 429 响应会按 `retry` 配置重试。
- 请求签名只使用路径部分，不把查询参数放入签名。
- `whitehole-open-api-sdk.d.ts` 包含客户端、分页、错误码和经营指标方法类型。
- `whitehole-open-api-sdk.CHANGELOG.md` 包含当前版本说明。
- `whitehole-open-api-sdk.package.json` 与 `SDK_VERSION` 保持一致，并限制包内文件范围。
- `whitehole-open-api-sdk.README.md` 包含服务端使用示例和密钥安全提醒。
- 临时生成标准 `package.json` 后执行 `npm pack --dry-run`，确认包可以打包。

## 静态交付与私有包发布

官网当前提供静态文件下载。若要发布到私有 npm 仓库，请在独立发布目录准备下列文件：

- `whitehole-open-api-sdk.js`
- `whitehole-open-api-sdk.d.ts`
- `whitehole-open-api-sdk.README.md`
- `whitehole-open-api-sdk.CHANGELOG.md`
- `whitehole-open-api-sdk.RELEASE.md`
- `whitehole-open-api-sdk.package.json`

发布前将 `whitehole-open-api-sdk.package.json` 重命名或复制为 `package.json`，再执行：

```bash
node whitehole-open-api-sdk.verify.js
npm pack --dry-run
```

确认打包内容只包含 SDK 主文件、类型声明、README、变更记录和发布说明后，再执行内部 npm 仓库的发布命令。

## 发布检查清单

- 更新 `SDK_VERSION`。
- 更新 `whitehole-open-api-sdk.package.json` 的 `version`。
- 更新 `whitehole-open-api-sdk.CHANGELOG.md`。
- 更新 `whitehole-open-api-sdk.README.md` 的使用说明。
- 新增资源方法时同步更新 `whitehole-open-api-sdk.d.ts`。
- 新增错误码时同步更新 `OPEN_API_ERROR_CODES` 和官网错误码表。
- 执行发布前校验脚本。
- 执行 `npm pack --dry-run` 并核对包内文件列表。
- 确认示例中没有真实 appKey、appSecret 或业务密钥。