@guandata/guanvis 0.1.30 → 0.1.31

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guanvis 0.1.31 - 2026-07-15
+
+- 新增仪表板筛选栏布局配置，支持网格或流式排列、间距、内边距、标签位置和操作区位置。
+- 增强已有仪表板 checkout 后的编辑能力，图表属性和页面布局修改会在保留线上未修改配置的基础上稳定回写。
+- 覆盖页面前的备份不再额外包含上游数据集和数据账号，减少普通用户因上游资源权限不足而无法更新页面的情况。
+
 ## @guandata/guanvis 0.1.30 - 2026-07-08
 
 - 支持 checkout 线上页面到本地工程，并增强已有仪表板的编辑、差异查看和回写流程。

package/README.md

@@ -47,10 +47,16 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 `guanvis upload` 只是上传器，不是自定义资源包制作入口。资源包应由 DSL 源文件通过 `guanvis pack` / `guanvis publish` 生成；不要手工生成、解包修改或重打包 ZIP。需要批量重绑资源或迁移已有页面时，先确认方案，不要直接改 ZIP 上传。
 
-使用 `--allow-overwrite` 覆盖线上 Page 时，CLI 会先为冲突 Page 创建资源迁移导出备份记录，并等待备份导出成功；备份失败或超时会中止覆盖。Card/Selector ID 不做在线覆盖检查。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。
+使用 `--allow-overwrite` 覆盖线上 Page 时，CLI 会先为冲突 Page 创建资源迁移导出备份记录，并等待备份导出成功；备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源，避免普通用户因缺少上游资源所有者权限而无法备份。备份失败或超时会中止覆盖。Card/Selector ID 不做在线覆盖检查。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.31
+
+- 新增仪表板筛选栏布局配置，支持网格或流式排列、间距、内边距、标签位置和操作区位置。
+- 增强已有仪表板 checkout 后的编辑能力，图表属性和页面布局修改会在保留线上未修改配置的基础上稳定回写。
+- 覆盖页面前的备份不再额外包含上游数据集和数据账号，减少普通用户因上游资源权限不足而无法更新页面的情况。
+
 ### @guandata/guanvis 0.1.30
 
 - 支持 checkout 线上页面到本地工程，并增强已有仪表板的编辑、差异查看和回写流程。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"

package/skills/guanvis/SKILL.md

@@ -31,7 +31,9 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
-**Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是“base JSON + 链式 DSL 操作 = 目标 JSON”。它不会修改 base JSON，重复执行同一组 JS 操作应产出相同 payload。已有卡片可继续串接常用 `createCard` 后续操作，包括标题/描述、`setRawSettings`、图例/标签/坐标轴/表格/拆分等视觉设置。Zone 操作按链式顺序真实执行：`addRow/addMetric/...` 追加字段，`insertMetric(index, field)` 插入字段，`removeMetric(selector)` 删除字段并保守清理其它 zone 中同字段引用，`moveMetric(selector, index)` 调整顺序，`updateMetric(selector, patch)` / `patchMetric(...)` 修改已有字段属性并保留未设置字段配置；`setRows/setMetrics/...` 和 `clearRows/clearMetrics/...` 是整 zone 重建，不会继承被替换字段的格式，并会在验证时提示 warning。已有 selector 额外用 `.addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 修改联动。Page 筛选区也按有序操作执行：`setFilterLayout` 整体设置，`clearFilterLayout` 清空，`addFilterLayoutItem` 追加去重，`insert/remove/moveFilterSelector` 局部调整；筛选器在快捷筛选区和画布间移动优先用动作级 API：`moveFilterSelectorToCanvas(selectorId, x, y, w, h)` / `moveCanvasSelectorToFilter(selectorId, index?)`，筛选器组用 `moveSelectorGroupToCanvas(group, x, y, w, h)` / `moveCanvasSelectorGroupToFilter(group, index?)`。checkout 生成的 page 布局默认用 card/selector ID 字符串；发布前可用 `guanvis diff <dir>` 或 `preview` 输出里的 `changeSummary` 查看 base JSON 到最终 payload 的路径级影响面；没有 DSL 操作覆盖的需求，先扩展 DSL，不要改 `.guanvis` JSON。
+**Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是“base JSON + 链式 DSL 操作 = 目标 JSON”。它不会修改 base JSON，重复执行同一组 JS 操作应产出相同 payload。已有卡片可继续串接常用 `createCard` 后续操作，包括标题/描述、`setRawSettings`、图例/标签/坐标轴/表格/拆分等视觉设置。Zone 操作按链式顺序真实执行：`addRow/addMetric/...` 追加字段，`insertMetric(index, field)` 插入字段，`removeMetric(selector)` 删除字段并保守清理其它 zone 中同字段引用，`moveMetric(selector, index)` 调整顺序，`updateMetric(selector, patch)` / `patchMetric(...)` 修改已有字段属性并保留未设置字段配置；`setRows/setMetrics/...` 和 `clearRows/clearMetrics/...` 是整 zone 重建，不会继承被替换字段的格式，并会在验证时提示 warning。已有 selector 额外用 `.addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 修改联动。Page 筛选区也按有序操作执行：`setFilterLayout` 整体设置，`clearFilterLayout` 清空，`addFilterLayoutItem` 追加去重，`insert/remove/moveFilterSelector` 局部调整；筛选栏布局使用 `setFilterPanelLayout()`；颜色、字体和背景继续由主题管理。筛选器在筛选栏和画布间移动优先用动作级 API：`moveFilterSelectorToCanvas(selectorId, x, y, w, h)` / `moveCanvasSelectorToFilter(selectorId, index?)`，筛选器组用 `moveSelectorGroupToCanvas(group, x, y, w, h)` / `moveCanvasSelectorGroupToFilter(group, index?)`。checkout 生成的 page 布局默认用 card/selector ID 字符串；发布前可用 `guanvis diff <dir>` 或 `preview` 输出里的 `changeSummary` 查看 base JSON 到最终 payload 的路径级影响面；没有 DSL 操作覆盖的需求，先扩展 DSL，不要改 `.guanvis` JSON。
+
+**字段显示名与 Card 标题**：`createCard()` 第二参数是 Card 标题，与字段显示名相互独立。所有数据图表的图例、轴标题、表头、Tooltip 或指标标签都可能使用字段显示名；需要与物理字段名或 calcField 内部名分开时设置 `alias`，如 `f("营收", { alias: "本月营收" })`、`calcField("整体毛利率_kpi", formula, { alias: "整体毛利率" })`。其中 `SINGLE_VALUE`、`KPI_CARD`、`KPI_TREND` 和仪表盘/进度类图表尤其明显。
 
 1. **工厂函数**：数据集图表用 `createCard()`；已有线上卡片用 `attachCard(cardId, jsonPath)`；指标平台指标卡片用 `createMetricChart()`；筛选器/筛选器组/文本/图片/杜邦/Tab/页面用 `createSelector()` / `createSelectorGroup()` / `createTextCard()` / `createImageCard()` / `createDuPontChart()` / `createAreaTitle()` / `createCardGroup()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`；checkout JSON 不可复制改造，新卡片必须 create，老卡片才 attach
 2. **注册函数**：`registerCard(card.build())` / `registerMetricChart(card.build())` / `registerSelector(sel.build())` / `registerTextCard(text.build())` / `registerImageCard(image.build())` / `registerDuPontChart(dupont.build())` / `registerPage(page.build())`
@@ -213,6 +215,13 @@ var page = createPage("销售仪表板")
     .setDescription("综合销售分析")
     .setBackgroundColor("#f5f5f5")
     .setCardMargin(8)
+    .setFilterPanelLayout({
+        type: FilterPanelLayoutType.GRID,
+        spacing: FilterPanelSpacing.MIDDLE,
+        padding: { top: 8, right: 12, bottom: 8, left: 12 },
+        labelPosition: "top",
+        actionOrder: "right"
+    })
     .addRow([{ card: 0, w: 4 }, { card: 1, w: 8 }], 4)
     .addFullWidthCard(2, 6)
     .addHalfWidthCards(3, 4, 6);
@@ -220,6 +229,8 @@ var page = createPage("销售仪表板")
 registerPage(page.build());
 ```
 
+`setFilterPanelLayout()` 只配置筛选栏的纯布局字段。颜色、字体、背景和控件视觉样式不在该接口范围内，继续跟随主题；字段和值详见 `references/builder-reference.md` 的“筛选栏布局”。
+
 **仪表板主题**：项目目录下没配 `themes/` 时，`preview`/`pack`/`publish` 自动使用 skill 自带的简约主题（embed 在二进制里的 `simple.json`，不依赖租户线上主题列表）。如需切换租户自定义主题或带明确风格的默认主题，请参考 `references/theme.md`，通过 `guanvis theme preference` 写入 `themes/.preference.json`；租户默认“浅色”/“深色”没有特殊样式，不作为可选主题。**JS DSL 不再提供主题相关接口**——任何 `setDashboardTheme(...)` 或 `page.setTheme(...)` 调用都会因函数未定义而报错。
 
 指标平台 MetricChart 也会在 `preview`/`pack`/`publish` 阶段自动应用主题视觉配置：透视表会补表格/合计样式，柱线饼等会补坐标轴、图例、数据标签和主题色。主题只写 `settings` 与 `meta.chartMain.props`，不改 `zoneData`、`dsInfo`、`defaultView` 等影响指标查询的字段。
@@ -351,7 +362,7 @@ guanvis pack ./project
 
 **资源包安全约束**：`upload` 只是上传器，不是制作自定义资源包的入口。除非用户明确批准，否则不得上传手工生成、解包修改、重打包或批量替换内部内容后的 ZIP。需要批量重绑数据集、字段、卡片或页面 ID 时，先讨论方案，不要直接改 ZIP。
 
-**线上仪表板更新策略**：新建工程发布的是新 Page；checkout 工程发布的是对 checkout 指定 Page 的覆盖式修改，不承担“复制新版本”职责。需要保留原页面并生成新版本时，不要在 guanvis CLI 内手工复制 JSON 或改 ID map；应先使用 BI 自身 Page Save/复制能力生成新 Page，让 BI 处理 ID 映射，再 checkout 新 Page 继续编辑。对 checkout 工程同 ID 发布时，命令必须显式加 `--allow-overwrite` 允许同 ID Page 覆盖；发布前可用 `--dry-run` 查看会覆盖哪些线上 Page。Card/Selector ID 不做在线覆盖检查。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：当 CLI 提示将覆盖线上 Page 时，必须先停止发布，向用户说明将覆盖的 Page ID、名称和覆盖后可能替换原页面布局，等用户明确确认“覆盖”后才可以重跑并加 `--allow-overwrite`。使用 `--allow-overwrite` 时，CLI 会先为冲突 Page 发起资源包导出备份并等待导出成功；备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
+**线上仪表板更新策略**：新建工程发布的是新 Page；checkout 工程发布的是对 checkout 指定 Page 的覆盖式修改，不承担“复制新版本”职责。需要保留原页面并生成新版本时，不要在 guanvis CLI 内手工复制 JSON 或改 ID map；应先使用 BI 自身 Page Save/复制能力生成新 Page，让 BI 处理 ID 映射，再 checkout 新 Page 继续编辑。对 checkout 工程同 ID 发布时，命令必须显式加 `--allow-overwrite` 允许同 ID Page 覆盖；发布前可用 `--dry-run` 查看会覆盖哪些线上 Page。Card/Selector ID 不做在线覆盖检查。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：当 CLI 提示将覆盖线上 Page 时，必须先停止发布，向用户说明将覆盖的 Page ID、名称和覆盖后可能替换原页面布局，等用户明确确认“覆盖”后才可以重跑并加 `--allow-overwrite`。使用 `--allow-overwrite` 时，CLI 会先为冲突 Page 发起资源包导出备份并等待导出成功；备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源，避免普通用户因缺少上游资源所有者权限而无法备份。备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
 
 ## 文件结构约定
 

package/skills/guanvis/references/api-reference.md

@@ -107,7 +107,7 @@ f("订单日期", { granularity: Granularity.DAY })     // 按天
 > **重要**：`schema.js` 中的 `displayType` 是生成 `calcField()` 公式时的 SQL 方言事实源。数据库直连数据集会把公式下推到目标库执行，不能把平台聚合枚举或伪函数直接写进公式。例如 PostgreSQL 去重计数应写 `COUNT(DISTINCT [客户ID])`，不要写 `COUNT_DISTINCT([客户ID])`；如果只是单独统计去重人数，应改用 `f("客户ID", { aggrType: AggrType.COUNT_DISTINCT })`。
 
 `calcField(name, formula, opts?)` 参数：
-- `name`：字段显示名
+- `name`：字段名；需要保留内部命名但使用不同展示名时，通过 `opts.alias` 设置
 - `formula`：SQL 表达式，用 `[字段名]` 引用数据集字段
 - `opts.calculationType`：`"aggregation"`（默认）, `"normal"`, `"window"`（窗口计算）
 - `opts.fdType`：默认 `"DOUBLE"`，可改为 `"LONG"`、`"STRING"` 等
@@ -434,7 +434,7 @@ createCard(ChartType.PIVOT_TABLE, "品牌同比分析")
     .addRow(f("品牌"))
     .addMetric(yoyRate)
     .addSort(f("品牌", {
-        ordering: "ASC",
+        sortType: SortOrder.ASC,
         customSort: {
             turnedOn: true,
             sortOrder: ["华东", "华南", "华北"]

package/skills/guanvis/references/builder-reference.md

@@ -17,7 +17,7 @@
 | `.addDynamicMetricAdditional(name, fields, options?)` | 添加动态数值组，候选字段写入副轴 |
 | `.addColorBy(field)` | 按指标值渐变着色（接受度量字段，不是维度）|
 | `.addTooltip(field)` / `.addFilter(field)` | 提示/筛选 |
-| `.addSort(field)` / `.addSplit(field)` / `.addSize(field)` | 排序/拆分/大小 |
+| `.addSort(field)` / `.addSplit(field)` / `.addSize(field)` | 排序/拆分/大小；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
 | `.setSplitSetting({ rows, columns })` | 拆分行列数（默认各 3），需配合 `.addSplit(field)` |
 | `.setColorByColors(preset_or_config)` | colorBy 渐变色。传 `ColorByPreset.RedGreen` 等预设名称，或 `{ startColor, endColor, middleColor?, steps? }` 自定义 hex 颜色 |
@@ -66,7 +66,7 @@
 | `.addMetric(metric)` | 添加指标平台指标；至少一个 |
 | `.addDynamicRow(name, fields, options?)` / `.addDynamicColumn(name, fields, options?)` | 添加指标平台动态维度组 |
 | `.addDynamicMetric(name, fields, options?)` / `.addDynamicMetricAdditional(name, fields, options?)` | 添加指标平台动态指标组 |
-| `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序 |
+| `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
 | `.setShowTitle()` / `.setShowLegend()` / `.setDataLabel()` / `.setAxis()` / `.setTableSetting()` / `.setRawSettings()` | 常用图表设置，和普通 CardBuilder 一致 |
 | `.setProps(obj)` / `.setRawProps(key, value)` | 设置指标卡片 `meta.chartMain.props` |
 | `.setConfig(obj)` / `.setRawConfig(key, value)` | 设置指标卡片 `meta.chartMain.config` |
@@ -355,6 +355,7 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.removeLayoutItem(cardRef)` | 从当前 Page 根布局移除已放置的 card/selector/layout component；主要给动作级移动 API 使用 |
 | `.addFilterSelectorGroup(group)` | 添加一个筛选栏筛选器组 |
 | `.addFilterSelector(selectorId)` | 显式添加一个未分组的筛选栏 selector，并控制其与筛选器组的顺序 |
+| `.setFilterPanelLayout(config)` | 配置筛选栏的布局相关属性；见下方“筛选栏布局” |
 | `.setFilterLayout(items)` | 整体设置快捷筛选区的 selector / filter selectorGroup ID 列表；checkout 场景会覆盖 base `filterLayout` |
 | `.clearFilterLayout()` | 清空快捷筛选区；常用于把已有快捷筛选器改成画布内普通筛选器卡片 |
 | `.addFilterLayoutItem(items)` | 向快捷筛选区追加 selector / filter selectorGroup ID，已存在则跳过 |
@@ -372,6 +373,32 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.setLayoutSetting(config)` | 原始 layout 配置 |
 | `.build()` | 构建 |
 
+#### 筛选栏布局
+
+```javascript
+page.setFilterPanelLayout({
+    type: FilterPanelLayoutType.GRID,
+    spacing: FilterPanelSpacing.MIDDLE,
+    padding: { top: 8, right: 12, bottom: 8, left: 12 },
+    labelPosition: "top",
+    actionOrder: "right"
+});
+```
+
+所有字段均可选，多次调用按字段增量合并。
+
+`padding` 支持 `top/right/bottom/left` 和`0 ~ 32`内的整数；非数字、`NaN`、`Infinity` 等非法值会产生 warning 并丢弃。
+
+| 字段 | 可选值 | 写入 `page.meta.filterLayoutSettings` |
+|------|--------|----------------------------------------|
+| `type` | `FilterPanelLayoutType.GRID` / `PARAGRAPH` | `layoutType` |
+| `spacing` | `FilterPanelSpacing.SMALL` / `MIDDLE` / `LARGE` | `selPadding` |
+| `padding` | `{ top?, right?, bottom?, left? }` | `paddingValue` |
+| `labelPosition` | `"top"` / `"left"` | `selName.position` |
+| `actionOrder` | `"left"` / `"right"` | `opStyle.order` |
+
+该方法只覆盖上述布局字段。checkout 会在 `.guanvis/base/page.json` 保留完整线上配置，pack/publish 时在此基础上合并布局补丁，因此颜色、字体和背景不会丢失；新页面的视觉字段由主题补齐。
+
 ### AreaTitleBuilder
 
 `areaTitle` 是 Page 根布局里的区域小标题，不是 Card，不绑定数据集，也不会生成 page-card relation。ID 必须以 `areaTitle_` 开头，建议用 `guanvis gen-layout-id areaTitle` 生成。

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

@@ -165,7 +165,7 @@ registerMetricChart(card.build());
 | `.addDynamicMetric(name, fields, options?)` | 添加动态指标组，候选指标写入 metric |
 | `.addDynamicMetricAdditional(name, fields, options?)` | 添加动态指标组，候选指标写入副轴 |
 | `.addFilter(field, type, values)` | 添加筛选 |
-| `.addSort(field)` | 添加排序 |
+| `.addSort(field)` | 添加排序；字段排序方向用 `sortType: SortOrder.ASC/DESC` |
 | `.addColorBy(metric(...))` | 添加颜色指标 |
 | `.addSize(metric(...))` | 添加大小指标 |
 | `.addTooltip(metric(...))` | 添加 tooltip 指标 |
@@ -227,7 +227,7 @@ var card = createMetricChart(ChartType.PIVOT_TABLE, "复杂指标透视表")
         subtotalSetting: { isDisplayed: true, isAggrDsBased: true, aggrType: "SUM" },
         fieldFormat: { numberFormat: NumberFormat.currency("¥", 0) }
     }))
-    .addSort(metric("销售额", { ordering: SortOrder.DESC }))
+    .addSort(metric("销售额", { sortType: SortOrder.DESC }))
     .setTableSetting({ fixedHeaderInfo: { X: false }, isDefaultExpandedGroupedTable: true, defaultExpandCols: 0 })
     .setConfig({ rowThreshold: [] });
 

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

@@ -51,4 +51,4 @@ checkout 工程表示“基于线上快照修改指定 Page”，不会新建 Pa
 - **布局组件 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 不做在线覆盖检查。覆盖前备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包；需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。
+- **显式覆盖场景**：checkout 工程发布时保持 `.setId()` 不变，并在用户确认覆盖后加 `--allow-overwrite` 允许同 ID Page 覆盖；多次同 ID 发布会覆盖资源（因为 transfer API 的 `needIdMapping=false`），其中 Card/Selector ID 不做在线覆盖检查。覆盖前备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源；备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包。需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。