发布治理 SOP

公共 API 演进、版本单一来源与发布门禁的权威口径。 配套门禁：packages/gis-cesium/scripts/check-bundle.mjs（体积）、check-governance.mjs（导出面 / d.ts / 版本 / 弃用）、benchmarks/（数量级基准）。

核心原则

1. 公共 API 一旦发布即承诺。删除、重命名、改签名都是破坏性变更，禁止无迁移路径的直接修改。
2. 破坏性变更必须先走弃用周期，且保留 ≥1 个发布版本，让下游有时间迁移。
3. 版本单一来源。package.json.version 与 src/lib/NexaCesium.ts 的 VERSION 字面量必须同步；check:governance 用门禁兜底，防止双源漂移。

破坏性变更的定义

以下任何一项，只要出现在公共导出面（public-api.baseline.json 覆盖的 380 个导出）上，即属破坏性变更：

变更	示例
删除公共导出	export declare function foo() 被移除
重命名公共导出	FooMixin → FooPlugin（下游 import 名失效）
改变公共签名	函数参数增减、返回类型收窄、class 构造签名变化
改变 export default 对象的成员	nexaGis.foo 被移除或改名

packages/gis-cesium/src/lib/NexaCesium.ts 是唯一 barrel——修改它就是公共导出面变化。

弃用周期 SOP

① 标注     ② 保留     ③ 移除      ④ 记录
@deprecated    ≥1 个版本    版本 bump 时     changelog + 本文件
+ @see 替代    （不删代码）   按 ③ 规则执行   记迁移说明

步骤①：标注弃用（必须带替代说明）

/**
 * @deprecated 请改用 [[newApi]]。
 * @see newApi —— 新实现的完整签名与迁移示例
 */
export declare function oldApi(): void

check:governance 的弃用审查会告警「@deprecated 但缺 @see/替代说明」——新弃用必须消除该告警，存量告警（如 LegacyCombatEntityOptions）作为待治理项逐个收敛。

步骤②：保留 ≥1 个版本。弃用期内的实现可以继续工作，但行为可随版本演进。

步骤③：移除。仅在版本 bump 时移除，且满足：

• 已发布 ≥1 个版本
• 本文件记录了迁移说明
• 显式运行 pnpm --filter @nexa/gis-cesium run check:governance -- --update-baseline 更新基线（--update-baseline 是唯一允许基线变化的入口）

步骤④：记录。变更写入 changelog 与版本说明。

现状：无真实弃用候选，机制先行。首个弃用发生在未来破坏性变更时，此文档即为验收依据。

版本与 changelog

• 版本单一来源：package.json（version: 0.0.101）为唯一事实来源，src/lib/NexaCesium.ts 的 VERSION 字面量与之对齐，check:governance 断言两处相等。
• bump 流程：
  1. 同步 bump package.json.version 与 NexaCesium.ts 的 VERSION
  2. 更新本文件「发布记录」小节
  3. 跑 pnpm --filter @nexa/gis-cesium run check:governance 确认版本一致性通过
  4. 走 CI 全量验证矩阵
• 版本语义：0.0.x 阶段破坏性变更允许存在，但同样必须走弃用周期（机制先行，不因 0.x 豁免）。

自动化门禁

packages/gis-cesium 内的发布前门禁，全部本地可跑，CI 串联全量矩阵（.github/workflows/ci.yml）：

命令	检查内容	失败后果
pnpm --filter @nexa/gis-cesium run check:bundle	dist/lib 产物 raw+gzip 体积上限	exit 1
pnpm --filter @nexa/gis-cesium run check:governance	导出面 vs 基线 / d.ts 完整性 / 版本一致性 / 弃用审查	删除导出、d.ts 断裂、版本漂移 → exit 1
pnpm --filter @nexa/gis-cesium run test:bench	Entity/Primitive 数量级门禁	exit 1
pnpm --filter @nexa/gis-cesium run typecheck	类型检查	exit 1
pnpm exec eslint . --ignore-pattern "**/dist-app/**"	0 error	exit 1

导出面基线的操作规则

• 基线文件：packages/gis-cesium/public-api.baseline.json
• 新增导出 → 提示，不 fail（不破坏兼容）
• 删除/重命名导出 → fail。合法路径只有两条：
  1. 该导出已走弃用周期（步骤①-②），在版本 bump 时显式 --update-baseline
  2. 确认为内部实现误导出（从未发布），评审后显式 --update-baseline
• check:governance 输出用「导出面 N 个 / 无删除 / 无新增」汇总，稳态路径必须三者全绿。

体积阈值的调整 SOP

check:bundle.mjs 顶部 LIMITS 表（当前 es raw ≤ 1_050_000 / gzip ≤ 240_000，umd raw ≤ 800_000 / gzip ≤ 215_000，css ≤ 20_000）。调阈值唯一合法理由：

• 净增能力（新功能新依赖），且已评审无法外置（如大资产改 URL、按需分包）
• 纯重构 / 删减不得上调阈值——调阈值本身就是体积回归的信号

新功能若必须超限，先评审外置方案再调；每次调整在本文件「发布记录」记一笔。

发布前检查单

• [ ] pnpm --filter @nexa/gis-cesium run typecheck 通过
• [ ] pnpm --filter @nexa/gis-cesium run test 基线 281 不降
• [ ] pnpm --filter @nexa/gis-cesium run test:bench 5/5
• [ ] pnpm --filter @nexa/gis-cesium run build:lib 通过
• [ ] pnpm --filter @nexa/gis-cesium run check:bundle 通过
• [ ] pnpm --filter @nexa/gis-cesium run check:governance 通过（含版本一致性）
• [ ] pnpm --filter @nexa/gis-cesium run test:e2e 7/7
• [ ] pnpm exec eslint . --ignore-pattern "**/dist-app/**" 0 error
• [ ] grep 门禁 ≤ 24 不反弹
• [ ] CI（.github/workflows/ci.yml）全绿

发布记录

版本	日期	变更
—（扫描材质/墙体光柱等修复）	2026-08-12	修复 6 个示例案例（扫描扩散材质、墙体光柱、粒子水柱、雷达扫描、Echarts 叠加、GIS 工具）：新增/修订扫描材质 GLSL 与 Effect、雷达波、水柱、Echarts 坐标系绑定等净增能力（无法外置），umd raw 上限 805_000 → 810_000（es raw 仍有余量未调）
—（VideoFusion 迁移）	2026-08-12	迁移 cesium-example VideoFusion（VideoFusionEffect 视频融合投影）：净增新能力（核心 Effect + GLSL，无法外置），umd raw 上限 800_000 → 805_000（es raw 仍有 ~30KB 余量未调），见 video-fusion
0.0.102	2026-08-08	迁移 cesium-example BufferAnalysis：体积门禁 es/umd 上限按 SOP 上调（turf 净增依赖含 jsts，无法外置，es +~417KB / umd +~284KB，见 buffer-analysis）
0.0.101	2026-08-07	版本对齐（消除 package.json 0.0.0 与 VERSION 字面量双源）；接入 P3 发布治理门禁与 CI