@guandata/guanvis 0.1.26 → 0.1.27

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## @guandata/guanvis 0.1.27 - 2026-06-17
+
+- `publish` / `upload` 避免发布前对 Card 做额外导入探测，减少无权限或跨环境场景下的误拦截。
+- 覆盖保护说明同步调整，明确 Page 级覆盖检查和资源包上传边界。
+
 ## @guandata/guanvis 0.1.26 - 2026-06-15
 
 - 修复自定义排序 payload 归一化问题，提升图表排序配置发布兼容性。

package/README.md

@@ -36,10 +36,10 @@ guanvis publish ./my_dashboard/
 # 上传已有 ZIP；只上传 guanvis pack 原样生成的资源包
 guanvis upload ./my_dashboard_package.zip
 
-# 只检查将要覆盖哪些线上资源，不上传
+# 只检查将要覆盖哪些线上 Page，不上传
 guanvis publish ./my_dashboard/ --dry-run
 
-# 明确要覆盖同 ID 线上 Card/Page 时才加；覆盖前会先导出备份记录，备份成功才继续
+# 明确要覆盖同 ID 线上 Page 时才加；覆盖前会先导出备份记录，备份成功才继续
 guanvis publish ./my_dashboard/ --allow-overwrite
 ```
 
@@ -47,10 +47,15 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 `guanvis upload` 只是上传器，不是自定义资源包制作入口。资源包应由 DSL 源文件通过 `guanvis pack` / `guanvis publish` 生成；不要手工生成、解包修改或重打包 ZIP。需要批量重绑资源或迁移已有页面时，先确认方案，不要直接改 ZIP 上传。
 
-使用 `--allow-overwrite` 覆盖线上资源时，CLI 会先为冲突 Card/Page 创建资源迁移导出备份记录，并等待备份导出成功；备份失败或超时会中止覆盖。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。
+使用 `--allow-overwrite` 覆盖线上 Page 时，CLI 会先为冲突 Page 创建资源迁移导出备份记录，并等待备份导出成功；备份失败或超时会中止覆盖。Card/Selector ID 不做在线覆盖检查。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.27
+
+- `publish` / `upload` 避免发布前对 Card 做额外导入探测，减少无权限或跨环境场景下的误拦截。
+- 覆盖保护说明同步调整，明确 Page 级覆盖检查和资源包上传边界。
+
 ### @guandata/guanvis 0.1.26
 
 - 修复自定义排序 payload 归一化问题，提升图表排序配置发布兼容性。
@@ -82,7 +87,7 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 - 新增卡片固定钻取路径能力，可在构建时配置图表点击后的固定下钻路径。
 - 新增杜邦分析图表支持，扩展财务分析类图表构建能力。
-- 发布与上传阶段增加线上资源覆盖保护，默认阻止误覆盖同 ID 线上 Card/Page，并可通过 dry-run 检查影响范围。
+- 发布与上传阶段增加线上资源覆盖保护；当前版本默认阻止误覆盖同 ID 线上 Page，并可通过 dry-run 检查影响范围。
 - 优化卡片诊断信息和联动/点击动作解析，提升复杂页面发布前的可检查性。
 
 ### 0.1.20

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -324,13 +324,14 @@ guanvis pack ./project
 
 `publish` 和 `upload` 使用 BI 的 **transfer API**（`/api/manual/template/transfer`），特点：
 - `needIdMapping=false`：保持资源 ID 不变，重复导入会覆盖同 ID 资源
+- 发布前在线覆盖检查只探测 Page ID，不探测 Card/Selector ID；如果资源包不包含 Page，则不会执行在线覆盖检查，避免部分 BI 版本在导入前缓存"找不到相关卡片"
 - 认证方式：随底层 `guancli fetch` 使用 `Cookie: uIdToken=...`
 - 需要 `raw-backend-response: TRUE` header 绕过前端代理层
 - 不需要目标系统开启"一键迁移"开关，所有环境通用
 
 **资源包安全约束**：`upload` 只是上传器，不是制作自定义资源包的入口。除非用户明确批准，否则不得上传手工生成、解包修改、重打包或批量替换内部内容后的 ZIP。需要批量重绑数据集、字段、卡片或页面 ID 时，先讨论方案，不要直接改 ZIP。
 
-**线上仪表板更新策略**：为了保护已经发布过的仪表板和线上仪表板，默认不要复用原 Page/Card/Selector ID 做覆盖更新。需要调整线上看板时，应先生成一组新的 ID，复制并修改 DSL/JS，给 Page 名称追加版本号（例如 `v2`、`v20260430` 或业务约定版本），再 `publish` 到目标目录。旧版本保留用于回滚和对比。仅当用户明确要求“覆盖原仪表板/复用原 ID”时，才允许同 ID 发布，并且命令必须显式加 `--allow-overwrite`；发布前可用 `--dry-run` 查看会覆盖哪些线上 Card/Page。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：当 CLI 提示将覆盖线上资源时，必须先停止发布，向用户说明将覆盖的 Page/Card ID、名称和覆盖后可能替换原页面布局/卡片配置，等用户明确确认“覆盖”后才可以重跑并加 `--allow-overwrite`。使用 `--allow-overwrite` 时，CLI 会先为冲突资源发起资源包导出备份并等待导出成功；备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
+**线上仪表板更新策略**：为了保护已经发布过的仪表板和线上仪表板，默认不要复用原 Page/Card/Selector ID 做覆盖更新。需要调整线上看板时，应先生成一组新的 ID，复制并修改 DSL/JS，给 Page 名称追加版本号（例如 `v2`、`v20260430` 或业务约定版本），再 `publish` 到目标目录。旧版本保留用于回滚和对比。仅当用户明确要求“覆盖原仪表板/复用原 ID”时，才允许同 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 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
 
 ## 文件结构约定
 

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 资源会被覆盖更新。`guanvis publish/upload` 默认会先探测目标环境已有 Card/Page ID，检测到覆盖风险时拒绝上传；只有明确加 `--allow-overwrite` 才允许覆盖。加 `--allow-overwrite` 后，CLI 会先调用资源包导出为冲突资源生成备份记录，并等待导出成功；备份失败或超时则中止上传。
+- **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。
 - **通用性**：不需要目标系统开启"一键迁移"开关，所有客户环境可用
 - **异步执行**：上传成功后返回 `taskId`，后端异步完成导入
 
@@ -49,5 +49,5 @@
 - `.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 名称追加版本号后发布，保留旧版本不覆盖。
-- **覆盖前检查**：发布前可先运行 `guanvis publish <dir> --dry-run` 或 `guanvis upload <zip> --dry-run`，只构建/解析资源并列出将被覆盖的线上 Card/Page，不提交 transfer 任务。
-- **显式覆盖场景**：只有用户明确要求覆盖原仪表板时，才保持 `.setId()` 不变，并在 `publish/upload` 时加 `--allow-overwrite`；多次同 ID 发布会覆盖资源（因为 transfer API 的 `needIdMapping=false`）。覆盖前备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包；需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。
+- **覆盖前检查**：发布前可先运行 `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 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。