@guandata/guanetl 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## @guandata/guanetl 0.1.14 - 2026-06-09
+
+- 移除 `delete` 命令。ETL / 数据集删除属于高风险操作，后续不再通过 guanetl 暴露。
+- 修复 `edit -> export -> save` 保存已绑定输出数据集时，导出空 `dataSource` 覆盖服务端绑定并触发保存保护的问题。
+- `run --wait` 明确区分触发响应状态与最终执行结果，避免把触发任务的 `FINISHED` 误读为 ETL 执行成功。
+- 修复 ETL 导出与 merge 过程中部分节点字段丢失问题，并补充相关测试覆盖。
+
+## @guandata/guanetl 0.1.13 - 2026-06-04
+
+- `lint` 增加字段 raw name 与 alias/displayName 疑似误用诊断，帮助识别 SQL/算子字段引用风险。
+- `create` / `save` 增加目录树类型 preflight，区分 ETL 目录和 DATA_SET 输出目录，并支持必要时跳过检查。
+- `save` 增加输出数据集绑定风险检查，提前拦截可能创建重名输出或输出数据集 rename 未同步的 payload。
+- `export` 成功后会输出静态检查提示，并补充 `BasicCalculator` / `Formula.Expr` 字段引用、类型和函数说明。
+
 ## @guandata/guanetl 0.1.12 - 2026-06-03
 
 - `import` 去掉对 guanetl-server 的依赖，改为基于 BI 数据集 schema 在本地生成 SQL。

package/README.md

@@ -27,6 +27,10 @@ guanetl save --dir <work_dir>
 
 > **触发成功 ≠ ETL 执行成功**：`run` 返回"执行已触发"仅表示后端接受了请求。使用 `run --wait` 等待终态，FAILED 时会展示真实错误消息。
 
+新建 ETL 时注意目录树不同：`create --parent-dir` 使用 ETL 目录树 id，输出数据集目录使用 DATA_SET 目录树 id。可用 `guancli etl tree` / `guancli ds tree` 分别查询，或用 `guanetl mkdir-pair` 成对创建。
+
+`export` 成功后会自动输出本地静态检查提示；其中 `BasicCalculator` 的每个 `Formula` 都应显式填写 `Type`，否则可能导致下游原生 GroupBy/Join 节点出现静态类型警告。
+
 也可以为 AI Coding Assistant 安装 Skill：
 
 ```bash
@@ -35,6 +39,20 @@ guanetl install-skill
 
 ## 版本更新
 
+### @guandata/guanetl 0.1.14
+
+- 移除 `delete` 命令。ETL / 数据集删除属于高风险操作，后续不再通过 guanetl 暴露。
+- 修复 `edit -> export -> save` 保存已绑定输出数据集时，导出空 `dataSource` 覆盖服务端绑定并触发保存保护的问题。
+- `run --wait` 明确区分触发响应状态与最终执行结果，避免把触发任务的 `FINISHED` 误读为 ETL 执行成功。
+- 修复 ETL 导出与 merge 过程中部分节点字段丢失问题，并补充相关测试覆盖。
+
+### @guandata/guanetl 0.1.13
+
+- `lint` 增加字段 raw name 与 alias/displayName 疑似误用诊断，帮助识别 SQL/算子字段引用风险。
+- `create` / `save` 增加目录树类型 preflight，区分 ETL 目录和 DATA_SET 输出目录，并支持必要时跳过检查。
+- `save` 增加输出数据集绑定风险检查，提前拦截可能创建重名输出或输出数据集 rename 未同步的 payload。
+- `export` 成功后会输出静态检查提示，并补充 `BasicCalculator` / `Formula.Expr` 字段引用、类型和函数说明。
+
 ### @guandata/guanetl 0.1.12
 
 - `import` 去掉对 guanetl-server 的依赖，改为基于 BI 数据集 schema 在本地生成 SQL。

package/package.json

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

package/skills/guanetl/SKILL.md

@@ -139,23 +139,28 @@ guanetl run <etl_id> --wait            # 可选：保存后触发执行并等待
 
 **再次修改已 save 过的 ETL 时**：即使本地还保留着上次的工作目录，也必须重新执行 `guanetl edit <etl_id> --dir <新目录>` 拉取服务端最新版本，不要在旧工作目录上直接改了再 save。原因：服务端版本可能已经变化，直接复用旧 base 会导致合并冲突（如"输出数据集目录中存在同名文件"）。
 
+如果 `save` 在 direct-save 前提示输出数据集绑定风险，按提示处理，不要手动删除旧输出数据集。常见原因是本地改动把已有 `OUTPUT_DATASET` 节点的 dsId/dataSource 绑定丢掉、新建了同目录同名输出节点，或用 `guands dataset rename` 改了输出数据集名但 `etl.go` 的 `outputDsName` 没同步。修复优先级：重新 `edit` 到新目录、保持原输出节点 id、同步 `outputDsName`，确实要新输出时改 `outputDsName` 或 `parentDirId`。
+
 ### 新建 ETL
 
 1. 先用 `guancli` 查输入数据集和字段。
-2. 如需在指定子目录下创建，先查目录树并按需创建子目录：
+2. 如需在指定子目录下创建，先分别确认 ETL 目录树和数据集目录树。两棵树相互独立，同名目录的 id 也不同，不能把 `guancli etl get` 输出节点里的 ParentDirId 当作 `create --parent-dir` 使用。
 
 ```bash
-guancli etl tree
-guanetl mkdir "ODS" --parent <parent_dir_id>
+guancli etl tree       # ETL 所在目录，用于 create --parent-dir
+guancli ds tree        # 输出数据集目录，用于 create --output-parent-dir / BasicOutputDatasetInDir
+guanetl mkdir-pair "ODS" --etl-parent <etl_parent_id> --ds-parent <ds_parent_id>
 ```
 
 3. 执行：
 
 ```bash
 guanetl create --name "ETL名称" --dir <work_dir>
-guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <dir_id>
+guanetl create --name "ETL名称" --dir <work_dir> --parent-dir <etl_dir_id> --output-parent-dir <dataset_dir_id>
 ```
 
+`create` / `save` 会校验目录 id 类型：`--parent-dir` 必须来自 ETL 树，输出数据集目录必须来自 DATA_SET 树。只有在确认目录 id 正确但当前账号无法读取目录树时，才使用 `--skip-dir-check`。
+
 4. 在 `etl/` 中实现 ETL。
 5. 再执行 `export -> preview -> save`。
 6. 需要立即执行时：`run <etl_id> --wait`。
@@ -286,6 +291,8 @@ guanetl task cancel <t1> <t2>             # 批量取消多个任务
 - 能用专用节点时，不要先写 `SQL_SCRIPT`。
 - 等值 JOIN 优先 `JOIN_DATA`，不要用 SQL 模拟。
 - 输入字段 schema 优先维护在 `BasicInputDataset(..., []Field{...})` 中。
+- 新版 ETL 默认以输入字段 `alias` / 展示名作为算子列名；字段存在别名时，SQL 和直接列名算子优先使用展示名，raw name 只作为底层数据集元数据理解。
+- ETL 执行时以真实数据集字段元数据为准；如果需要设置或确认展示名，先用 `guands dataset fields <dsId>` / `guands dataset alias <dsId> --fd-id <fdId> --alias "展示名"`，不要只在 `etl.go` 手写 alias 后假设服务端会采用。
 - 新增 SQL 节点时，要同步新增对应 `.sql` 文件。
 - 对 `edit` 导入出来的 ETL，优先局部修改，不要为“重构”大面积推翻。
 - **文件访问边界**：只允许访问以下路径，不要主动探索或读取用户未明确授权的其他目录：
@@ -309,7 +316,7 @@ guanetl task cancel <t1> <t2>             # 批量取消多个任务
 | `BasicFilterRows` | 行筛选 | 按条件过滤数据 | combineType: `AND`/`OR` |
 | `BasicJoinData` | 等值 JOIN | 两表关联 | **优先用这个，不要写 SQL JOIN** |
 | `BasicGroupBy` | 分组聚合 | SUM/COUNT/AVG 等 | 聚合类型: `SUM`/`COUNT`/`AVG`/`MIN`/`MAX` |
-| `BasicCalculator` | 新增计算列 | 公式计算新字段 | - |
+| `BasicCalculator` | 新增计算列 | 公式计算新字段 | `Formula` 必须包含 `Name`/`Type`/`Expr`/`Key`；字段引用用 `[展示名]` |
 | `BasicRemoveDuplicates` | 去重 | 按指定列去重 | - |
 | `BasicAppendRows` | 上下合并 | 多表 UNION | unionType: `INCLUDE_SHARED`/`INCLUDE_ALL` |
 | `BasicSqlScript` | 自定义 SQL | 上述节点无法满足时 | SQL 放独立 `.sql` 文件，上游用 `input1`/`input2` 引用 |

package/skills/guanetl/references/ETL_AI_DEVELOP.md

@@ -62,6 +62,17 @@ orders := BasicInputDataset("id_1001", "订单", "ds_orders", []Field{
 - `meta.json` 主要保留 ETL 名称等元信息。
 - 字段相关报错时，优先检查 `[]Field`，不要先怀疑 `meta.json`。
 
+## 字段 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 的字段强制变成展示名列。
+- SQL 节点使用上游表 `input1`、`input2` 的当前列名。字段有中文展示名时，SQL 里应写展示名并用反引号，例如 ``SELECT `门店ID` FROM input1``。
+- `SELECT_COLUMNS`、`FILTER_ROWS`、`REMOVE_DUPLICATES`、`GROUP_BY` 等直接列名算子，也以当前上游列名为准。
+- 底层数据集读取和数据集元数据仍保留原始 `name`，所以 `guancli` / `guands` 输出字段时要同时关注 `name` 和 `alias`。
+- 不确定时先执行 `guanetl lint`；它会提示疑似把 raw name 写进新版 ETL 算子的情况。
+
 ## 最常用函数
 
 ### 输入 / 输出
@@ -74,6 +85,13 @@ BasicOutputDatasetInDir(id, name string, source Node, outputDsName, parentDirId
 
 `BasicOutputDatasetInDir` 允许指定输出数据集的父目录 ID，避免落到根目录。目录 ID 可通过 `guancli ds tree` 获取。
 
+新建 ETL 时有两类目录 id，不能混用：
+
+- `guanetl create --parent-dir` 使用 ETL 目录树 id，可通过 `guancli etl tree` 获取。
+- `BasicOutputDatasetInDir(..., parentDirId, ...)` / `guanetl create --output-parent-dir` 使用 DATA_SET 目录树 id，可通过 `guancli ds tree` 获取。
+- 同名目录在两棵树中的 id 通常不同；需要成对创建时优先使用 `guanetl mkdir-pair`。
+- `create` / `save` 默认会校验目录 id 类型，确认 id 正确但账号无法读取目录树时，可加 `--skip-dir-check` 跳过。
+
 ### 选列
 
 ```go
@@ -94,7 +112,8 @@ BasicFilterRows(id, name string, source Node, combineType string, conditions []F
 ```
 
 - `combineType` 只能是 `AND` 或 `OR`
-- 高频操作符：`EQ` `NE` `LT` `LE` `GT` `GE` `IN` `BT` `IS_NULL` `NOT_NULL` `CONTAINS` `NOT_CONTAINS` `STARTSWITH` `NOT_STARTSWITH` `ENDSWITH` `NOT_ENDSWITH`
+- 高频操作符：`EQ` `NE` `LT` `LE` `GT` `GE` `IN` `BT` `CONTAINS` `NOT_CONTAINS` `STARTSWITH` `NOT_STARTSWITH` `ENDSWITH` `NOT_ENDSWITH`
+- 当前 `BasicFilterRows` 不支持 `IS_NULL` / `NOT_NULL`；null 过滤请改用 SQL 节点（如 ``WHERE `列名` IS NULL`` / ``IS NOT NULL``）。
 
 ### 等值 JOIN
 
@@ -112,6 +131,66 @@ BasicGroupBy(id, name string, source Node, groupByColumns []GroupByColumn, aggre
 
 - 聚合类型只用：`SUM` `COUNT` `COUNT_DISTINCT` `MIN` `MAX` `AVG` `FIRST_NOT_NULL`
 
+### 计算列
+
+```go
+BasicCalculator(id, name string, source Node, formulas []Formula, position Position)
+```
+
+`Formula` 必须写完整四个字段：
+
+```go
+Formula{
+    Name: "订单金额等级",
+    Type: "STRING",
+    Expr: "IF([金额] >= 1000, \"大额\", \"普通\")",
+    Key:  "formula_amount_level",
+}
+```
+
+- `Name` 是新增列名。
+- `Type` 是新增列类型，只用：`INT` `DOUBLE` `STRING` `TIMESTAMP` `LONG` `SHORT` `FLOAT` `DATE` `BOOL` `DECIMAL` `ARRAY`。
+- `Expr` 是服务端公式表达式，字段引用必须写成 `[字段名]`。
+- `Key` 在同一个 `CALCULATOR` 节点内必须唯一；建议用稳定字符串，不要留空。
+
+`Expr` 规则：
+
+- 字段名遵循“字段 name / alias / showName 规则”：上游字段有 `alias` 时，公式里通常写展示名，例如 `[门店ID]`，不要写 raw name `[store_id]`。
+- 字符串字面量用双引号，例如 `"大额"`。
+- 数值、比较、逻辑可以按 Spark SQL 表达式写，例如 `[金额] * 1.13`、`[数量] > 0 AND [金额] > 0`。
+- 空值判断优先用 `IS NULL` / `IS NOT NULL` 或 `COALESCE`，不要写 `= NULL`。
+- 多个公式之间尽量不要互相依赖；如果需要依赖前一个新增列，拆成两个 `BasicCalculator` 节点更稳。
+
+常用函数（按 Spark SQL 表达式执行，函数名大小写不敏感；这里列 AI 写 ETL 时最常用、最稳的集合）：
+
+| 类别 | 函数 / 写法 | 示例 |
+|---|---|---|
+| 文本截取 | `LEFT` `RIGHT` `SUBSTRING` | `LEFT([门店编码], 2)` |
+| 文本处理 | `CONCAT` `UPPER` `LOWER` `TRIM` `LENGTH` `REPLACE` | `CONCAT([省份], "-", [城市])` |
+| 数值处理 | `ABS` `ROUND` `CEIL` `FLOOR` | `ROUND([金额], 2)` |
+| 空值处理 | `COALESCE` | `COALESCE([金额], 0)` |
+| 条件判断 | `IF`、`CASE WHEN ... THEN ... ELSE ... END` | `IF([金额] > 0, "有效", "无效")` |
+| 日期时间 | `CURRENT_DATE` `CURRENT_TIMESTAMP` `DATE_FORMAT` | `DATE_FORMAT([下单日期], "yyyy-MM")` |
+
+示例：
+
+```go
+calc := BasicCalculator("id_1002", "新增计算列", inputA, []Formula{
+    {
+        Name: "含税金额",
+        Type: "DOUBLE",
+        Expr: "ROUND([金额] * 1.13, 2)",
+        Key:  "formula_tax_amount",
+    },
+    {
+        Name: "门店前缀",
+        Type: "STRING",
+        Expr: "LEFT([门店ID], 2)",
+        Key:  "formula_store_prefix",
+    },
+}, Position{X: 320, Y: 100})
+```
+
 ### SQL
 
 ```go
@@ -133,7 +212,8 @@ node := BasicSqlScript(
 SQL 规则：
 
 - 上游节点在 SQL 中用 `input1`、`input2` 这类名字引用。
-- 特殊列名、中文列名、带空格列名，用反引号。
+- 特殊列名、中文列名、带空格列名，以及 `AS` 输出别名中的非 ASCII 标识符，都必须用反引号。
+- 输入数据集字段存在 `alias` / `displayName` / `showName` 时，优先使用展示名而不是 raw name。
 - 新增 SQL 节点时，要同步新增 `.sql` 文件。
 
 ## 推荐骨架
@@ -170,6 +250,7 @@ func DefineETL() []Node {
 4. `JOIN_DATA` / `GROUP_BY` / `FILTER_ROWS` 的枚举值合法吗？
 5. 新增 SQL 文件了吗？文件名和代码引用一致吗？
 6. 输入字段 schema 足够支撑后续节点吗？
+7. `BasicCalculator` 的每个 `Formula` 都显式填写 `Type` 了吗？缺失会在 `export` 后提示 warning，并可能导致下游原生 `GROUP_BY` / `JOIN_DATA` 静态检查出现类型不匹配。
 
 ## 验证顺序
 
@@ -181,6 +262,17 @@ func DefineETL() []Node {
 
 如果 `export` 没过，不要直接 `save`。
 
+## save 输出数据集冲突
+
+`save` 会先拉取服务端当前 ETL，再把本地 `_exported.json` 合并进去。修改已保存 ETL 时，输出节点必须保留服务端已有输出数据集绑定，否则 direct-save 可能把它当成“创建新输出数据集”，触发“输出数据集目录中存在同名文件”。
+
+- 再次修改已保存 ETL，优先重新执行 `guanetl edit <etl_id> --dir <新目录>`，不要长期复用旧工作目录。
+- 修改已有输出 schema 时，保持原 `OUTPUT_DATASET` 节点 id。
+- 如果用 `guands dataset rename` 改过 ETL 输出数据集名称，必须同步 `etl.go` 中 `BasicOutputDataset(..., outputDsName, ...)` 或 `BasicOutputDatasetInDir(..., outputDsName, ...)` 的名称。
+- 不要为了绕过同名错误手动删除旧输出数据集；旧输出通常仍被 ETL 依赖。
+- 如果确实要创建新输出数据集，必须改 `outputDsName` 或 `parentDirId`，避免与旧输出同目录同名。
+- `save` 如果在 direct-save 前提示输出绑定风险，先修本地 `etl.go` / `meta.json`，再重新 `export -> preview -> save`。
+
 ## Appendix: Framework Surface
 
 这部分只列 AI 写 ETL 时最值得记住的公开函数和合法枚举。
@@ -239,6 +331,17 @@ BasicFilterColumnValue(columnName string)
 ReadSQLFile(filename string)
 ```
 
+### Formula 结构
+
+```go
+type Formula struct {
+    Name string `json:"name"`
+    Type string `json:"type"`
+    Expr string `json:"expr"`
+    Key  string `json:"key"`
+}
+```
+
 ### 合法枚举
 
 筛选组合：
@@ -252,11 +355,14 @@ ReadSQLFile(filename string)
 - `LT` `LE` `GT` `GE`
 - `IN`
 - `BT`
-- `IS_NULL` `NOT_NULL`
 - `CONTAINS` `NOT_CONTAINS`
 - `STARTSWITH` `NOT_STARTSWITH`
 - `ENDSWITH` `NOT_ENDSWITH`
 
+当前限制：
+
+- `BasicFilterRows` 暂不支持 `IS_NULL` / `NOT_NULL`；null 过滤请使用 `BasicSqlScript`。
+
 JOIN 类型：
 
 - `INNER`