@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanvis/references/metric-chart-reference.md

@@ -0,0 +1,258 @@
+# 指标平台指标卡片（MetricChart）创建指引
+
+本指引用于创建“用指标平台已有指标创建的卡片”，后端类型为 `CARD_TYPE.METRIC_CHART` / `cdType=13`。它不同于普通数据集字段的 `SINGLE_VALUE` / `KPI_CARD`。
+
+## 固定流程
+
+1. 查询指标 ID：
+
+```bash
+guancli metric search '销售额年同比增长率'
+```
+
+`guancli metric search --name-like ...` 不是当前 CLI 参数；搜索词用位置参数。
+
+2. 生成指标快照：
+
+```bash
+guanvis metric-init <metricId1> <metricId2> -d ./my_dashboard/
+```
+
+3. 编写 `card_*.js`：
+
+```javascript
+var card = createMetricChart(ChartType.PIVOT_TABLE, "销售指标分析")
+    .setId("card12345678901234567890")
+    .addRow(metricDim("销售额", "区域"))
+    .addMetric(metric("销售额"));
+
+registerMetricChart(card.build());
+```
+
+4. 本地验证用 `guanvis preview/pack`。发布后若 `guancli card get/preview` 对 `METRIC_CHART` 报 `None.get`，不要据此判断卡片失败；优先使用指标卡编辑态数据接口或页面访问验证数据返回。
+
+## 兼容约束
+
+- `MetricChartMeta.defaultView` 不要写 `"chart"`；后端 `ChartView` 不包含该值，导入后查询会报 `ChartView does not contain 'chart'`。
+- `PIVOT_TABLE` 的 `column` 区域必须包含 `metaType: "MPH"` 的“度量名”占位列。guanvis 会在未显式添加 column 时自动补齐。
+- `PIVOT_TABLE` 的 `metric` / `sorting` zoneInfo 需要 `needAggregation: true`；普通维度、筛选 zone 不聚合。
+- 指标字段使用 `id` 表示 metric id；维度字段使用 `fdId` + `dsId` / `publicDimensionId`。不要把 metric id 当普通数据集 `fdId` 使用。
+- `preview` / `pack` / `publish` 会像普通数据集卡片一样给 MetricChart 注入主题视觉配置，只写 `settings` 与 `meta.chartMain.props`，不会修改 `zoneData`、`dsInfo`、`defaultView`。显式通过 `.setProps()` / `.setTableSetting()` / `.setAxis()` 等写入的配置优先保留。
+
+## 顶层内容参数
+
+| 路径 | 中文含义 | 说明 |
+|---|---|---|
+| `chartType` | 图表类型 | 使用 `ChartType.PIVOT_TABLE`、`BASIC_COLUMN`、`BASIC_LINE` 等枚举 |
+| `metricIds` | 卡片引用的指标 ID 列表 | 由 `.addMetric(metric(...))` 自动收集；后端用它维护 card-metric 关系 |
+| `metrics` | 指标详情列表 | 后端编辑态会补充；资源包创建通常不手写 |
+| `columns` | 卡片级字段列表 | 指标卡片临时/动态字段可放这里；默认空数组 |
+| `meta.chartMain.zoneInfo` | 区域规格 | 描述 row/column/metric/filter/sort 等区域的标题、数量限制、是否聚合 |
+| `meta.chartMain.zoneData` | 区域字段 | 真实拖入的维度、指标、筛选、排序等字段 |
+| `meta.chartMain.props` | 图表属性 | 透视表设置、图例、数据标签、坐标轴、主题色、辅助线等 |
+| `meta.chartMain.config` | 图表配置 | 汇总阈值、自由钻取、KPI 趋势默认值等 |
+| `meta.chartMain.dynamicZoneInfo` | 动态字段配置 | 动态维度/指标映射；复杂场景可通过 `.setRawConfig` / `.setProps` 透传 |
+| `meta.summary` | 汇总配置 | 汇总字段、标签、位置和汇总类型 |
+| `hasDrill` / `drillViews` | 钻取配置 | 是否有钻取与钻取路径；普通创建可先不写 |
+
+## zoneData 区域
+
+| 区域 | 中文 | 可放字段 | 常见用途 |
+|---|---|---|---|
+| `row` | 维度/行 | 公共维度、适用维度、动态维度、MPH | 分组维度、X 轴、透视表行 |
+| `column` | 对比/列 | 公共维度、适用维度、动态维度、MPH | 透视表列、系列拆分；透视表默认需要 MPH |
+| `metric` | 数值 | 指标字段 | 主指标 |
+| `metric_additional` | 副轴数值 | 指标字段 | 组合图副轴、双轴图 |
+| `colorBy` | 颜色 | 指标字段 | 数值渐变着色 |
+| `sizeBy` | 大小 | 指标字段 | 气泡大小 |
+| `tooltip` | 更多提示 | 指标字段 | tooltip 附加指标 |
+| `filters` | 筛选 | 维度或指标 | 明细筛选、聚合筛选、结果筛选 |
+| `sorting` | 排序 | 维度或指标 | 升序/降序、自定义排序 |
+| `split` | 拆分 | 公共维度 | 小多图拆分 |
+| `ignoreFilters` | 忽略筛选 | 筛选字段 | 忽略外部联动筛选 |
+
+## 字段参数
+
+### 维度字段（DimensionZoneObj）
+
+| 参数 | 中文含义 |
+|---|---|
+| `dsId` | 数据集 ID |
+| `fdId` | 字段 ID |
+| `name` / `alias` | 字段名 / 显示别名 |
+| `fdType` | 字段类型，如 `STRING`、`DATE`、`LONG` |
+| `metaType` | 元类型，维度为 `DIM`，度量名占位为 `MPH` |
+| `granularity` / `parentFdName` | 日期粒度 / 原日期字段名 |
+| `formula` | 卡片级字段公式 |
+| `consolidation` | 公共维度归并信息 |
+| `alignedDimension` | 指标 level 计算字段的对齐维度 |
+| `baseFdType` / `timeFormat` | 技术字段类型 / 字符串时间解析格式 |
+| `fieldFormat.numberFormat` | 数值格式 |
+| `fieldFormat.headerFormat` | 表头格式 |
+| `fieldFormat.conditionFormat` | 条件格式 |
+| `fieldFormat.linkFormat` | 链接格式 |
+| `hasSubTotal` | 是否显示小计 |
+| `key` | 前端字段实例 key；guanvis 自动生成 |
+| `subZoneId` / `dzId` | 子区域 ID / 动态字段 ID |
+| `publicDimensionId` | 公共维度 ID |
+| `isDrill` | 是否为自由钻取字段 |
+| `annotation` | 字段释义 |
+| `isHidden` | 是否隐藏 |
+
+### 指标字段（MetricZoneObj）
+
+| 参数 | 中文含义 |
+|---|---|
+| `id` | 指标 ID |
+| `name` / `alias` | 指标名 / 显示别名 |
+| `fdType` | 值类型 |
+| `metaType` | 固定为 `METRIC` |
+| `fieldFormat.numberFormat` | 数据格式 |
+| `fieldFormat.conditionFormat` | 条件格式 |
+| `fieldFormat.headerFormat` | 表头格式 |
+| `fieldFormat.itemSetting` | 颜色/项目设置，常用于 `colorBy` |
+| `subtotalSetting.isDisplayed` | 小计/总计是否显示 |
+| `subtotalSetting.isAggrDsBased` | 小计是否基于聚合数据集 |
+| `subtotalSetting.aggrType` | 小计聚合方式 |
+| `advCalc` | 高级计算，如排名、占比 |
+| `filter` | 指标业务限定 |
+| `miniChart` | 表格内迷你图的前端字段配置；不要直接手写，使用 `.setMiniChart()`，样式使用 `.setMiniChartSetting()` |
+| `formula` / `formulaField` | 复合/原子拆分公式 |
+| `parentFdName` / `granularity` | 日期派生字段信息 |
+| `key` / `subZoneId` / `dzId` | 字段实例 key / 子区域 / 动态字段 |
+| `isDrill` | 是否钻取字段 |
+| `isHidden` | 是否隐藏 |
+
+### 筛选字段（FilterZoneObj）
+
+| 参数 | 中文含义 |
+|---|---|
+| `id` | 指标 ID；当筛选指标时使用 |
+| `dsId` / `fdId` | 数据集 ID / 字段 ID；当筛选维度时使用 |
+| `filterType` | 筛选类型，如 `IN`、`NI`、`GT`、`GE`、`LT`、`LE`、`EQ`、`NE`、`BT` |
+| `filterValue` | 筛选值数组；`BT` 需要两个值 |
+| `filterLevel` | 筛选层级：`DETAIL` 明细、`AGGREGATION` 聚合、`RESULT` 结果 |
+| `fieldFilterSettings` | 字段筛选器设置 |
+| `compareColumn` | 是否对比列 |
+| `advFilter` / `advFilterContent` | 高级筛选表达式及内容 |
+| `refKey` | 关联来源 metric 字段 key，用于带业务限定指标筛选 |
+
+### 排序字段（SortingZoneObj）
+
+| 参数 | 中文含义 |
+|---|---|
+| `id` | 指标 ID；指标排序时使用 |
+| `dsId` / `fdId` | 维度字段来源 |
+| `ordering` | 排序方向：`ASC` / `DESC` |
+| `customSort.turnedOn` | 是否启用自定义排序 |
+| `customSort.sortOrder` | 自定义排序值列表 |
+| `isPinYinOrder` | 是否按拼音排序 |
+| `associateFieldSorting` | 关联字段排序 |
+| `advCalc` | 按高级计算结果排序 |
+| `refKey` | 关联来源 metric 字段 key |
+
+## DSL 方法
+
+| 方法 | 中文含义 |
+|---|---|
+| `createMetricChart(chartType, name)` | 创建指标卡片 |
+| `.addMetric(metric(...))` | 添加主指标 |
+| `.addMetricGroup(createMetricGroup(...))` | 添加数值组或嵌套数值组 |
+| `.addMainViceGroup(createMainViceGroup(...))` | 添加主副指标组，仅透视表 |
+| `.addMetricAdditional(metric(...))` | 添加副轴指标 |
+| `.addRow(metricDim(...))` | 添加行/类目维度 |
+| `.addColumn(metricDim(...))` | 添加列/对比维度 |
+| `.addDynamicRow(name, fields, options?)` | 添加动态维度组，候选字段写入 row |
+| `.addDynamicColumn(name, fields, options?)` | 添加动态维度组，候选字段写入 column |
+| `.addDynamicMetric(name, fields, options?)` | 添加动态指标组，候选指标写入 metric |
+| `.addDynamicMetricAdditional(name, fields, options?)` | 添加动态指标组，候选指标写入副轴 |
+| `.addFilter(field, type, values)` | 添加筛选 |
+| `.addSort(field)` | 添加排序；字段排序方向用 `sortType: SortOrder.ASC/DESC` |
+| `.addColorBy(metric(...))` | 添加颜色指标 |
+| `.addSize(metric(...))` | 添加大小指标 |
+| `.addTooltip(metric(...))` | 添加 tooltip 指标 |
+| `.addSplit(metricDim(...))` | 添加拆分维度 |
+| `.setProps(obj)` | 设置 `chartMain.props` |
+| `.setConfig(obj)` / `.setRawConfig(key, value)` | 设置 `chartMain.config` |
+| `.setSummary(metric(...), options?)` | 设置 `meta.summary`；`options` 支持 `label`、`position`，旧的原始对象签名继续兼容 |
+| `.setSummaryStyle(config)` | 设置汇总指标名称与数值样式 |
+| `.setSpecialValue(config)` | 设置特殊值显示；仅支持前端开放该属性的图表类型 |
+| `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 设置卡片标题显隐与样式 |
+| `.setColumns(columns)` | 设置 `content.columns` 与 dsInfo.columns |
+| `.setTableSetting(obj)` | 设置表格行为与视觉样式 |
+| `.setTableCellMerge(obj)` | 设置透视表单元格合并 |
+| `.setPieSetting(obj)` / `.setPieCenterText(obj)` | 设置饼图属性 |
+| `.setTreemapDataLabel(obj)` / `.setFunnelDataLabel(obj)` | 设置矩形树图分层数据标签、漏斗图各类数据标签 |
+| `.setSplitSetting(obj)` | 设置拆分图属性 |
+| `.setBarSetting(obj)` | 设置柱形图/条形图的柱体宽度、间距和圆角；帕累托图还支持数据点显隐 |
+| `.setStackSplitSetting(obj)` | 设置分组堆积柱形图/条形图的堆积分组模式 |
+| `.setWaterfallSetting(obj)` | 设置瀑布图的正负值颜色和累计值 |
+| `.setParetoSetting(obj)` | 设置帕累托图的累计曲线名称和百分比精度 |
+| `.setMapSetting(obj)` | 设置地图专属属性 |
+| `.setBubbleSetting(obj)` | 设置气泡半径 |
+| `.setRadarSetting(obj)` | 设置雷达图显示属性 |
+| `.setBoxPlotSetting(obj)` | 设置箱线图属性 |
+| `.setHeatMapSetting(obj)` | 设置热力图属性 |
+| `.setShapeColorType(type)` | 设置图形填充 |
+| `.setLineSetting(obj)` | 设置折线显示 |
+| `.setComboSetting(obj)` | 设置组合图的显示方式、折线或符号样式 |
+| `.setAuxiliaryLine(obj)` | 设置辅助线 |
+| `.setGrandTotal(obj)` | 设置透视表/分组表行列总计及样式；字段小计通过 `metricDim()` / `metric()` overrides 配置 |
+| `.setFreeDrill(enabled, position)` | 设置 `config.freeDrillConfig` |
+| `.setRowThreshold(thresholds)` | 设置 `config.rowThreshold` |
+
+## 动态维度 / 动态指标
+
+动态字段是显式能力。只有调用 `.addDynamicRow()` / `.addDynamicColumn()` / `.addDynamicMetric()` / `.addDynamicMetricAdditional()` 时，guanvis 才会生成候选字段的 `dzId` 和 `meta.chartMain.dynamicZoneInfo`；普通 `.addRow()` / `.addMetric()` 仍生成静态字段。
+
+```javascript
+var region = metricDim("销售额", "区域");
+var city = metricDim("销售额", "城市");
+var sales = metric("销售额");
+var profit = metric("利润");
+
+var card = createMetricChart(ChartType.PIVOT_TABLE, "指标动态分析")
+    .setId("metriccard12345678901234")
+    .addDynamicRow("分析维度", [region, city], {
+        defaultValue: [region],
+        multiSelect: false
+    })
+    .addDynamicMetric("分析指标", [sales, profit], {
+        defaultValue: [sales],
+        multiSelect: true,
+        orderType: DynamicFieldOrder.CLICK
+    });
+
+registerMetricChart(card.build());
+```
+
+`options`：
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `defaultValue` | 第一个候选字段 | 推荐传候选数组里的字段对象；字符串只在唯一命中 `name` / `alias` / `fdId` / `id` 时可用 |
+| `multiSelect` | 根据 zone `maxCount` 推断 | `maxCount=1` 时强制单选；指标卡 row 默认单选 |
+| `orderType` | `DynamicFieldOrder.PRESET` | `PRESET` 按候选顺序，`CLICK` 按用户点击顺序 |
+| `id` | 自动生成 | 可选，显式指定 `dzId`，用于稳定 diff |
+
+`hidden` 和 `selectType` 不开放配置；资源包固定写 `hidden: false`、`selectType: "SEARCHBOX"`。动态字段不写 `stateValue.dzFieldValues`，前端加载卡片时会根据 `dynamicZoneInfo.dzMappings.defaultValue` 初始化默认选中值。
+
+复杂配置可直接放到 `metric()` / `metricDim()` 的 overrides 中：
+
+```javascript
+var card = createMetricChart(ChartType.PIVOT_TABLE, "复杂指标透视表")
+    .addRow(metricDim("销售额", "区域", {
+        hasSubTotal: true,
+        fieldFormat: { headerFormat: { alignment: "center" } }
+    }))
+    .addMetric(metric("销售额", {
+        alias: "销售额",
+        subtotalSetting: { isDisplayed: true, isAggrDsBased: true, aggrType: "SUM" },
+        fieldFormat: { numberFormat: NumberFormat.currency("¥", 0) }
+    }))
+    .addSort(metric("销售额", { sortType: SortOrder.DESC }))
+    .setTableSetting({ fixedHeaderInfo: { X: false } })
+    .setConfig({ rowThreshold: [] });
+
+registerMetricChart(card.build());
+```

package/skills-bundle/guanvis/references/publish-and-constraints.md

@@ -0,0 +1,60 @@
+## 在线同步机制
+
+`publish` 和 `upload` 命令通过 BI 的 transfer API 直接将资源包上传到目标系统：
+
+- **接口**：`POST /api/manual/template/transfer`（标准 multipart/form-data，表单字段名 `new-file`）
+- **认证**：随底层 BI 请求通道使用 `Cookie: uIdToken=...`
+- **关键 header**：`raw-backend-response: TRUE`（绕过前端代理层，直达后端）
+- **ID 策略**：`needIdMapping=false`，保持资源 ID 不变。同 ID 资源会被覆盖更新。为避免部分 BI 版本在导入前探测 Card 时缓存"找不到相关卡片"，`guanvis publish/upload` 的在线覆盖检查只探测目标环境已有 Page ID；检测到同 ID Page 时默认拒绝上传，只有明确加 `--allow-overwrite` 才允许覆盖。加 `--allow-overwrite` 后，CLI 会先调用资源包导出为冲突 Page 生成备份记录，并等待导出成功；`/api/task/{taskId}` 是备份成功或失败的权威终态，资源包列表只在任务成功但结果未直接返回 packageId 时用于补齐 packageId，不用列表状态覆盖任务结论。目标 BI 不支持通过该 taskId 查询任务或响应缺少任务状态时，兼容回退到资源包列表判定。备份失败或超时则中止上传。Card/Selector ID 不做在线探测。checkout 工程表示修改指定 Page，不在 CLI 内复制新版本或手写 ID 映射。
+- **Page 归属校验**：资源包只要包含 Card/Selector，就必须同时包含 Page，且每个 Card/Selector 的 ID 必须出现在至少一个 Page 的 `cdIds` 中。只有 Card/Selector、没有 Page，或包内存在未被任何 Page 引用的 Card/Selector 时，`preview/pack/publish/upload` 会提示在 `page.js` 中放置对应资源并将 Page 与 Card/Selector 同包发布。该约束用于避免导入端生成 `pg_id` 为空、无法访问且会与页面草稿 `origin_cd_id` 冲突的孤儿卡片。
+- **通用性**：不需要目标系统开启"一键迁移"开关，所有客户环境可用
+- **异步执行**：上传成功后返回 `taskId`，后端异步完成导入
+
+`upload` 只是上传器，不是自定义资源包制作入口。默认只允许上传由 `guanvis pack` 原样生成的 ZIP；禁止手工生成、解包修改或重打包资源包。
+
+若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先说明风险并确认方案；不要直接修改 ZIP 内部文件后上传。
+
+checkout 工程表示“基于线上快照修改指定 Page”，不会新建 Page，也不要通过复制 checkout JSON、改 ID 或自建 ID map 来生成新版本。若用户要求保留原页面并另存新版本，用 `guanvis page save-as <pgId> --suffix _guanvis`（或 `--name <新名>`）做 BI 原生整页另存为，由服务端处理资源 ID 映射，再对副本 Page 执行 checkout/edit（细节见 `checkout-editing.md` §5）。用户可能已经在 BI 上手工改过页面布局、卡片配置、筛选器或说明文本；如果按旧 checkout 工程同 ID `publish`，线上改动会被覆盖。发布前应使用 `--dry-run` 检查覆盖对象，只有用户明确要求覆盖原资源时，才允许加 `--allow-overwrite` 同 ID 发布。
+
+## 认证与 CLI 集成
+
+- 所有 API 调用通过底层 CLI 代理执行
+- 认证由底层 CLI 负责：guancli 使用 `GUANCLI_PROFILE=<profile>` 固定本次任务环境，认证检查和后续发布使用同一值；未指定环境时沿用当前默认，仅用户明确要求修改默认环境时才用 `auth use`；guancli-lite 使用 `GUANCLI_BASE_URL`/`GUANCLI_TOKEN` 环境变量
+- CLI 二进制路径通过 `GUANCLI_PATH` 环境变量指定，或自动在 PATH 中查找 `guancli-lite`/`guancli`
+
+## 硬约束
+
+- `schema.js` 由 `init` 命令生成；`checkout` 会尽量生成 schema，但数据集无权限、已删除或跨环境残留时只提示 warning 并继续生成可编辑工程。不允许 AI 或人工修改 `schema.js`。只有目标 `schema.js` 是普通文件时才允许跳过或覆盖；同名目录及其他特殊文件会明确报错。目标文件已存在且未传 `--force` 时，`init` 不解析 `--alias`、不校验 dsId/权限、不调用认证或 BI API，保留原文件，向 stderr 输出“WARNING: schema.js 未更新，如需重刷请加 `--force`”并以成功状态退出，使调用方继续后续步骤；stdout 同时标记“已跳过”。缺失字段或需要重刷时用 `guanvis init <dsId> -d <dir> --force` 显式覆盖。
+- `dynamic-parameters.js` 由 `guanvis parameter` 或 `checkout` 生成，不手改；`publish` 只校验项目实际引用的参数，不创建或更新线上参数。
+- `charts/` 下的自定义图表内容文件（`<cdId>.js/.html/.css` 与 `<cdId>_assets/` 内嵌资源）是**可编辑事实源**：checkout 从线上卡片反编译生成，直接编辑即可修改图表，pack/publish 通过 `loadContent` 自动回填。重跑 checkout 会用线上版本重建这些文件（`--refresh-base` 不触碰 charts/）。
+- card 脚本必须调用 `registerCard(card.build())`（目录模式）或返回 `card.build()`（单文件模式）。
+- metric chart 脚本必须调用 `registerMetricChart(card.build())`。
+- text card 脚本必须调用 `registerTextCard(textCard.build())`。
+- image card 脚本必须调用 `registerImageCard(imageCard.build())`。
+- custom chart 脚本必须调用 `registerCustomChart(chart.build())`。
+- selector 脚本必须调用 `registerSelector(selector.build())`。
+- `fdId` 和 `dsId` 必须匹配目标 BI 系统的真实值（通过 schema.js 保证）。
+- card 文件名建议 `card_NN_xxx.js` 控制执行顺序。
+- selector 文件名建议 `selector_NN_xxx.js`，在 card 之后执行。
+- page 文件必须命名为 `page.js`。
+- 包含 Card/Selector 时必须提供 `page.js`，并把包内每个 Card/Selector 放入至少一个 Page；禁止 Card-only 或孤儿 Card/Selector 资源包。
+- 筛选器的 `linkTo(cardIndex)` 中 cardIndex 基于过滤后的可联动目标序列（0-based）：普通图表和 MetricChart 按注册/布局顺序，文本/图片等不可联动资源不占序号，杜邦子图追加在末尾。
+- 资源包 ZIP 是派生产物，不是可编辑源文件；不要手工编辑或重打包 ZIP。
+- **文件访问边界**：只允许访问以下路径，不要主动探索或读取用户未明确授权的其他目录：
+  - 当前工作目录（`-d` 指定的目录或 cwd）
+  - `guancli` / `guanvis` CLI 工具的输出
+  - 用户在对话中明确提到或授权的路径
+  - 禁止为了"查找参考代码""寻找类似实现"而主动扫描用户机器上的其他项目目录，这会引起安全顾虑。
+
+### ID 管理
+
+所有 Card、Selector 和 Page **必须**调用 `.setId(id)` 设置显式 ID。未设置 ID 会在 JS 校验和 Go 校验两层报错，阻止生成。
+
+- **新建资源 ID** 应使用 `guanvis genid` 生成；`genid` 输出格式为 `^[a-z][0-9a-f]{23}$`。新建校验接受字母开头的 24 位小写字母数字 ID（`^[a-z][a-z0-9]{23}$`），因此已有的固定小写测试 ID 仍可使用，但混合大小写和数字开头 ID 会被拦截。
+- **已有资源兼容**：checkout/attach 把线上 ID 视为不透明标识并原样保留，不校验格式；只检查非空、唯一和引用关系，避免已有资源因历史或未来 ID 形态变化而无法原地编辑。
+- 存量本地源码工程若包含已发布的非规范 ID，不要按新建校验提示替换 ID；应 checkout/attach 后继续使用线上原 ID，避免收藏、订阅、权限和外部引用断链。
+- **生成 ID**：先运行 `guanvis genid <数量>` 生成足够的 ID，在编写脚本时直接填入每个 card/selector/page 的 `.setId()` 调用中。
+- **布局组件 ID 例外**：Tab、Panel、AreaTitle、CardGroup、SelGroup 使用 `guanvis gen-layout-id <prefix>` 生成，形如 `tab_AbCdEf`、`panel_AbCdEf`、`areaTitle_AbCdEf`、`cardGroup_AbCdEf`、`selGroup_AbCdEf`，不适用 24 位 `genid` 规则。
+- **线上更新默认策略**：新建工程发布新 Page；checkout 工程只修改 checkout 指定的 Page，不负责复制新版本。
+- **覆盖前检查**：发布前可先运行 `guanvis publish <dir> --dry-run` 或 `guanvis upload <zip> --dry-run`，只构建/解析资源并列出将被覆盖的线上 Page，不提交 transfer 任务。
+- **显式覆盖场景**：checkout 工程发布时保持 `.setId()` 不变，并在用户确认覆盖后加 `--allow-overwrite` 允许同 ID Page 覆盖；多次同 ID 发布会覆盖资源（因为 transfer API 的 `needIdMapping=false`），其中 Card/Selector ID 不做在线覆盖检查。覆盖前备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源；备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包。需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。