@guandata/guanetl 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -1,8 +1,16 @@
 # Changelog
 
+## @guandata/guanetl 0.1.16 - 2026-06-17
+
+- `save --dry-run` 增加保存影响预览基础能力，帮助在提交前检查关键配置变化。
+- `run` 会在执行前提示上游数据集失败状态，降低基于异常上游继续执行的风险。
+- `schedule` 修复上游触发调度的默认输入处理，减少调度配置误差。
+- `export` / `save` 增强输入字段类型校验，并在 `preview` 中提示 LEFT JOIN 桥接列全空样本。
+
 ## @guandata/guanetl 0.1.15 - 2026-06-15
 
 - `save` 增强输出数据集保护，保留级联相关配置，并对追加写入场景的行数据结构提前校验。
+- `preview` 对 `LEFT_OUTER` JOIN 的右表桥接列增加全 null 样本告警，提示检查 join 键值域是否匹配。
 - 补充多输出数据集和追加写入保存流程说明，降低 ETL 保存时误改输出配置的风险。
 
 ## @guandata/guanetl 0.1.14 - 2026-06-09

package/README.md

@@ -25,7 +25,7 @@ guanetl save --dir <work_dir>
 
 标准 ETL 写入闭环：`create/edit → export → preview → save → run --wait`。
 
-> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息。
+> **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息。触发前会检查直接上游数据集状态；若发现上游处于失败态，会先输出警告但继续执行，可用 `--skip-upstream-check` 跳过检查。
 
 新建 ETL 时注意目录树不同：`create --parent-dir` 使用 ETL 目录树 id，输出数据集目录使用 DATA_SET 目录树 id。可用 `guancli etl tree` / `guancli ds tree` 分别查询，或用 `guanetl mkdir-pair` 成对创建。
 
@@ -39,6 +39,13 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.16
+
+- `save --dry-run` 增加保存影响预览基础能力，帮助在提交前检查关键配置变化。
+- `run` 会在执行前提示上游数据集失败状态，降低基于异常上游继续执行的风险。
+- `schedule` 修复上游触发调度的默认输入处理，减少调度配置误差。
+- `export` / `save` 增强输入字段类型校验，并在 `preview` 中提示 LEFT JOIN 桥接列全空样本。
+
 ### @guandata/guanetl 0.1.15
 
 - `save` 增强输出数据集保护，保留级联相关配置，并对追加写入场景的行数据结构提前校验。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanetl",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "观远 ETL 本地开发工具 - 拉取、编辑、导出、预览、保存 ETL",
   "bin": {
     "guanetl": "bin/run.js"

package/skills/guanetl/SKILL.md

@@ -133,6 +133,7 @@ guanetl edit <etl_id> --dir <work_dir>
 ```bash
 guanetl export --dir <work_dir>
 guanetl preview <node_id> --dir <work_dir>
+guanetl save --dir <work_dir> --dry-run
 guanetl save --dir <work_dir>
 guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待完成
 ```
@@ -143,6 +144,8 @@ guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待
 
 只追加输出列是安全例外：新增列、不改名、不删已有列、不改已有列类型，并保持原 `OUTPUT_DATASET` 节点 id 和 `outputDsName` 时，可以原地 `save`，保存前仍需 `preview` 目标输出确认结果。改列名、删列、改类型、换输入数据集、重接输出链路或更换输出节点 id 都按下游绑定风险处理。
 
+保存前优先执行 `save --dry-run` 查看影响报告；`--format json` 可用于自动化检查。dry-run 不调用 direct-save，若报告出现阻断风险，先修 `etl/` 后重新 `export -> preview -> save --dry-run`。
+
 ### 新建 ETL
 
 1. 先用 `guancli` 查输入数据集和字段。
@@ -185,6 +188,8 @@ guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --o
 3. 将本地修改合并到服务端版本
 4. 调用 direct-save API 写入
 
+`save --dry-run` 只执行到合并和保存影响检查，不执行第 4 步。
+
 用户不需要手写服务端保存 payload。只要 `etl/` 修改正确、`export` 通过，`save` 就能完成服务端保存。
 
 ### run --wait 与任务状态
@@ -193,6 +198,7 @@ guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --o
 
 - 不加 `--wait` 时，`run` 只触发并返回 `taskId`。
 - 加 `--wait` 后，CLI 会轮询任务状态直到终态（FINISHED / FAILED / CANCELED），FAILED 时会展示真实错误消息。
+- 触发前，`run` 会检查直接上游数据集状态；若发现上游处于 `FAILED`/`失败` 态，会先输出警告但继续触发执行。确认不需要检查时可加 `--skip-upstream-check`。
 - 如果不加 `--wait` 后想查状态：`task status <taskId>` 或 `task wait <taskId>`。
 
 ### 排查执行失败
@@ -250,12 +256,16 @@ guanetl schedule <etl_id> --disable                                # 关闭调
 
 ```bash
 # 任一上游数据集更新后执行
+guanetl schedule <etl_id> --trigger upstream
 guanetl schedule <etl_id> --trigger upstream --inputs <dsId1>,<dsId2>
 
 # 全部上游数据集更新后执行
+guanetl schedule <etl_id> --trigger upstream-all
 guanetl schedule <etl_id> --trigger upstream-all --inputs <dsId1>,<dsId2>
 ```
 
+不指定 `--inputs` 时，`guanetl` 会读取 ETL 当前输入数据集并默认全部监听；指定 `--inputs` 时只监听列出的 dsId。
+
 ### 定时调度类型说明
 
 | cron-type | 参数 | 说明 |
@@ -295,6 +305,7 @@ guanetl task cancel <t1> <t2>             # 批量取消多个任务
 - 输入字段 schema 优先维护在 `BasicInputDataset(..., []Field{...})` 中。
 - 新版 ETL 默认以输入字段 `alias` / 展示名作为算子列名；字段存在别名时，SQL 和直接列名算子优先使用展示名，raw name 只作为底层数据集元数据理解。
 - ETL 执行时以真实数据集字段元数据为准；如果需要设置或确认展示名，先用 `guands dataset fields <dsId>` / `guands dataset alias <dsId> --fd-id <fdId> --alias "展示名"`，不要只在 `etl.go` 手写 alias 后假设服务端会采用。
+- 本地字段解析优先级为 `alias -> displayName/showName/title -> name`；遇到同一来源下有效字段名重复，先消除歧义再继续写算子。
 - 新增 SQL 节点时，要同步新增对应 `.sql` 文件。
 - 对 `edit` 导入出来的 ETL，优先局部修改，不要为“重构”大面积推翻。
 - **文件访问边界**：只允许访问以下路径，不要主动探索或读取用户未明确授权的其他目录：

package/skills/guanetl/references/ETL_AI_DEVELOP.md

@@ -62,12 +62,48 @@ orders := BasicInputDataset("id_1001", "订单", "ds_orders", []Field{
 - `meta.json` 主要保留 ETL 名称等元信息。
 - 字段相关报错时，优先检查 `[]Field`，不要先怀疑 `meta.json`。
 
+## ODS 展示格式字符串先解析再声明数值
+
+`guancli ds get` 只能告诉你字段声明类型；ODS / mock / 平台导出表可能把 UI 展示值原样存成 `STRING`，例如 `"13小时31分"`、`"27.69%"`、`"90"`。写 DWD 前先执行 `guancli ds preview <dsId>` 看样本；如果 preview 提示 STRING 样本像展示格式，不能在 `BasicInputDataset` 里直接把该字段声明成 `DOUBLE` / `LONG` 后聚合。
+
+`guanetl export` 会通过数据集详情接口校验输入字段 schema：服务端字段是 `STRING` 时，`BasicInputDataset` 不能把它声明成 `DOUBLE` / `LONG` / `DATE` 等非 STRING 类型。
+
+推荐先用 `BasicCalculator` 或 SQL 显式解析成新的数值列，再让下游聚合引用新列：
+
+```go
+calc := BasicCalculator("id_1002", "解析展示格式度量", inputA, []Formula{
+    {
+        Name: "下单转化率_数值",
+        Type: "DOUBLE",
+        Expr: "CAST(REPLACE([下单转化率], \"%\", \"\") AS DOUBLE) / 100",
+        Key:  "formula_order_rate_value",
+    },
+    {
+        Name: "营业时长_分钟",
+        Type: "DOUBLE",
+        Expr: "CAST(IF(REGEXP_EXTRACT([营业时长], \"([0-9.]+)小时\", 1) = \"\", \"0\", REGEXP_EXTRACT([营业时长], \"([0-9.]+)小时\", 1)) AS DOUBLE) * 60 + CAST(IF(REGEXP_EXTRACT([营业时长], \"([0-9.]+)分\", 1) = \"\", \"0\", REGEXP_EXTRACT([营业时长], \"([0-9.]+)分\", 1)) AS DOUBLE)",
+        Key:  "formula_open_minutes",
+    },
+    {
+        Name: "店铺分_数值",
+        Type: "DOUBLE",
+        Expr: "CAST([店铺分] AS DOUBLE)",
+        Key:  "formula_store_score_value",
+    },
+}, Position{X: 320, Y: 100})
+```
+
+- 百分比字符串先去 `%`，再确认业务语义是 `27.69` 还是 `0.2769`。
+- 中文时长要统一成明确单位，例如分钟或秒。
+- 纯数字字符串可能是编码 / ID；确认不是维度编码后再 cast。
+
 ## 字段 name / alias / showName 规则
 
 后端 ETL 的展示名语义主要来自字段 `alias`，有些接口或前端上下文会叫 `displayName` / `showName`。
 
 - 新版 ETL 默认使用输入字段别名：如果数据集字段有 `alias`，进入 ETL 算子后的列名通常是 `alias`；没有 `alias` 时才是原始 `name`。
 - 输入字段别名的事实源是数据集字段元数据；可用 `guands dataset fields <dsId>` 回读，用 `guands dataset alias <dsId> --fd-id <fdId> --alias "展示名"` 更新。`BasicInputDataset(..., []Field{...})` 中的字段 schema 主要用于导入/导出和本地 lint，不会把一个未设置过数据集 alias 的字段强制变成展示名列。
+- 本地校验按 `alias -> displayName/showName/title -> name` 解析有效字段名；同一来源下两个字段解析成相同有效名会被视为歧义，建模前应先改名或明确上游输出。
 - SQL 节点使用上游表 `input1`、`input2` 的当前列名。字段有中文展示名时，SQL 里应写展示名并用反引号，例如 ``SELECT `门店ID` FROM input1``。
 - `SELECT_COLUMNS`、`FILTER_ROWS`、`REMOVE_DUPLICATES`、`GROUP_BY` 等直接列名算子，也以当前上游列名为准。
 - 底层数据集读取和数据集元数据仍保留原始 `name`，所以 `guancli` / `guands` 输出字段时要同时关注 `name` 和 `alias`。
@@ -304,7 +340,8 @@ func DefineETL() []Node {
 
 1. `guanetl export --dir <work_dir>`
 2. 需要看结果时：`guanetl preview <node_id> --dir <work_dir>`
-3. 确认无误后：`guanetl save --dir <work_dir>`
+3. 保存前先看影响：`guanetl save --dir <work_dir> --dry-run`
+4. 确认无误后：`guanetl save --dir <work_dir>`
 
 如果 `export` 没过，不要直接 `save`。
 
@@ -319,6 +356,7 @@ func DefineETL() []Node {
 - 不要为了绕过同名错误手动删除旧输出数据集；旧输出通常仍被 ETL 依赖。
 - 如果确实要创建新输出数据集，必须同时更换 `OUTPUT_DATASET` 节点 id，并设置新的 `outputDsName` 或 `parentDirId`；只改名称会被视为已有输出绑定风险。
 - `save` 如果在 direct-save 前提示输出绑定风险，先修本地 `etl.go` / `meta.json`，再重新 `export -> preview -> save`。
+- `save --dry-run` 只生成保存影响报告，不调用 direct-save；需要机器可读结果时加 `--format json`。报告里出现阻断级输出绑定风险时，必须先修本地定义，不能继续真实 `save`。
 
 ## Appendix: Framework Surface