@guandata/guanvis 0.1.28 → 0.1.30

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

@@ -160,6 +160,10 @@ registerMetricChart(card.build());
 | `.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)` | 添加排序 |
 | `.addColorBy(metric(...))` | 添加颜色指标 |
@@ -174,6 +178,42 @@ registerMetricChart(card.build());
 | `.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

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

@@ -5,7 +5,7 @@
 - **接口**：`POST /api/manual/template/transfer`（标准 multipart/form-data，表单字段名 `new-file`）
 - **认证**：随底层 `guancli fetch` 使用 `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 生成备份记录，并等待导出成功；备份失败或超时则中止上传。Card/Selector ID 不做在线探测；如果资源包不包含 Page，则不会执行在线覆盖检查。更新已有仪表板时应按新版本策略生成新的 Page/Card/Selector ID。
+- **ID 策略**：`needIdMapping=false`，保持资源 ID 不变。同 ID 资源会被覆盖更新。为避免部分 BI 版本在导入前探测 Card 时缓存"找不到相关卡片"，`guanvis publish/upload` 的在线覆盖检查只探测目标环境已有 Page ID；检测到同 ID Page 时默认拒绝上传，只有明确加 `--allow-overwrite` 才允许覆盖。加 `--allow-overwrite` 后，CLI 会先调用资源包导出为冲突 Page 生成备份记录，并等待导出成功；备份失败或超时则中止上传。Card/Selector ID 不做在线探测；如果资源包不包含 Page，则不会执行在线覆盖检查。checkout 工程表示修改指定 Page，不在 CLI 内复制新版本或手写 ID 映射。
 - **通用性**：不需要目标系统开启"一键迁移"开关，所有客户环境可用
 - **异步执行**：上传成功后返回 `taskId`，后端异步完成导入
 
@@ -13,7 +13,7 @@
 
 若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先说明风险并确认方案；不要直接修改 ZIP 内部文件后上传。
 
-修改或重新发布已存在的仪表板资源时，默认按“新版本仪表板”处理：先从目标 BI 线上环境同步最新资源状态，再基于同步后的内容生成新的 Page/Card/Selector ID，并给仪表板名称追加版本号后发布。用户可能已经在 BI 上手工改过页面布局、卡片配置、筛选器或说明文本；如果只按本地旧文件 `publish`，同 ID 资源会被覆盖，导致线上改动丢失。只有用户明确要求覆盖原资源时，才允许保留原 ID 并同 ID 发布。
+checkout 工程表示“基于线上快照修改指定 Page”，不会新建 Page，也不要通过复制 checkout JSON、改 ID 或自建 ID map 来生成新版本。若用户要求保留原页面并另存新版本，应先调用 BI 自身 Page Save/复制能力，由 BI 处理资源 ID 映射，再对新 Page 执行 checkout/edit。用户可能已经在 BI 上手工改过页面布局、卡片配置、筛选器或说明文本；如果按旧 checkout 工程同 ID `publish`，线上改动会被覆盖。发布前应使用 `--dry-run` 检查覆盖对象，只有用户明确要求覆盖原资源时，才允许加 `--allow-overwrite` 同 ID 发布。
 
 ## 认证与 CLI 集成
 
@@ -23,7 +23,7 @@
 
 ## 硬约束
 
-- `schema.js` 由 `init` 命令自动生成，不允许 AI 或人工修改。
+- `schema.js` 由 `init` 命令生成；`checkout` 会尽量生成 schema，但数据集无权限、已删除或跨环境残留时只提示 warning 并继续生成可编辑工程。不允许 AI 或人工修改 `schema.js`，缺失时后续用 `guanvis init <dsId> -d <dir> --force` 补齐。
 - card 脚本必须调用 `registerCard(card.build())`（目录模式）或返回 `card.build()`（单文件模式）。
 - metric chart 脚本必须调用 `registerMetricChart(card.build())`。
 - text card 脚本必须调用 `registerTextCard(textCard.build())`。
@@ -48,6 +48,7 @@
 
 - `.setId(id)` 的 ID **必须**为严格 24 位字母数字字符串（正则：`^[a-zA-Z0-9]{24}$`），与后端 `RandUtil.uuid` 格式一致。若生成或手填的 ID 以数字开头，建议重新生成一组，避免 BI 前端某些路径把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误。
 - **生成 ID**：先运行 `guanvis genid <数量>` 生成足够的 ID，在编写脚本时直接填入每个 card/selector/page 的 `.setId()` 调用中。
-- **线上更新默认策略**：已发布过或线上正在使用的仪表板，后续修改默认生成新的 Page/Card/Selector ID，并给 Page 名称追加版本号后发布，保留旧版本不覆盖。
+- **布局组件 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 任务。
-- **显式覆盖场景**：只有用户明确要求覆盖原仪表板时，才保持 `.setId()` 不变，并在 `publish/upload` 时加 `--allow-overwrite` 允许同 ID Page 覆盖；多次同 ID 发布会覆盖资源（因为 transfer API 的 `needIdMapping=false`），其中 Card/Selector ID 不做在线覆盖检查。覆盖前备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包；需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。
+- **显式覆盖场景**：checkout 工程发布时保持 `.setId()` 不变，并在用户确认覆盖后加 `--allow-overwrite` 允许同 ID Page 覆盖；多次同 ID 发布会覆盖资源（因为 transfer API 的 `needIdMapping=false`），其中 Card/Selector ID 不做在线覆盖检查。覆盖前备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包；需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。