@dazitech/cli 3.0.9 → 3.1.0

package/dist/docs/onto//350/204/232/346/234/254/350/277/220/350/241/214/347/272/240/351/224/231_/345/225/206/345/212/241/346/210/220/346/234/254/346/226/271/346/241/210/345/274/200/345/217/221/350/277/207/347/250/213.md

@@ -1,213 +0,0 @@
-# 脚本运行纠错 · 商务成本方案开发过程记录
-
-**文档 ID**: `onto/script-run-troubleshooting`  
-**级别**: **执行脚本前必读（强制）** — 在终端执行 `dazi onto script publish` / `script run` / `function run` / `save-test-arguments` **之前**须通读  
-**场景**: 本体 init / seed / 函数发布与运行过程中的 API 误用、SQL 聚合、CLI 参数等真实踩坑记录（潘达石化 · 商务成本本体方案）  
-**适用**: 编写 `setup/`、`functions/` 脚本及终端发布验证时对照；智能体见提示词 `onto/script-publish-run`
-
----
-
-## 一、遇到的坑
-
-### 1. setup 脚本 API 误用（多次尝试才正确）
-
-| 错误写法                                      | 正确写法                                                                    | 说明                         |
-| --------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------- |
-| `s.onto.sync_metrics()`                       | 删除，平台自动同步                                                          | `sync_metrics` 方法不存在    |
-| `s.cubes.upsert(...)`                         | `s.register_cube(...)`                                                      | `cubes` 属性不存在           |
-| `s.onto.define_object_type(code, label=name)` | `s.onto.define_object_type(code, name, description=desc)`                   | 参数名为 `name` 而非 `label` |
-| `define_link_type(..., from_object_type=...)` | `define_link_type(..., from_object_type_code=..., to_object_type_code=...)` | 参数名以 `_code` 结尾        |
-
-**教训**：参考利润示例脚本的 API 用法，不要猜测方法名。
-
-### 2. 函数聚合查询返回类型错误
-
-**问题代码**：
-
-```python
-total_row = p.sql.query_one(f"SELECT sum(amount) AS grand_total FROM ...")
-grand_total = float(total_row.get("grand_total", 0))  # float 无 .get()
-```
-
-**原因**：`p.sql.query_one()` 对聚合查询返回的是数值（float），而非包含字段名的字典行。
-
-**修复**：
-
-```python
-total_rows = p.sql.query(f"SELECT sum(amount) AS grand_total FROM ...")
-total_row = total_rows[0] if total_rows else {}
-grand_total = float(total_row.get("grand_total", 0) or 0)
-```
-
-受影响的函数：
-
-- `cost_fn_category_breakdown.py`
-- `cost_fn_department_breakdown.py`
-- `cost_fn_top_cost_types.py`
-
-### 3. 函数输出方式错误（`output.print_json`）
-
-**问题代码**：
-
-```python
-def main():
-    result = _ontology_fn_body(p)
-    output.print_json(result)  # AttributeError: 'OutputModule' has no attribute 'print_json'
-```
-
-**原因**：本体函数运行时平台注入 `ctx`、`space`、`onto` 等；**结果须由 `main()` return**，不能调用 `output.print_json()`（setup/flow 脚本中的 `output` 模块与本体函数不同）。
-
-**正确写法**（与销售/利润示例一致）：
-
-```python
-def _ontology_fn_body(p):
-    params = dict(p.get_params() or {})
-    # ... SQL via p.sql.query(...)
-    return p.function_result(
-        columns=["col_a", "col_b"],
-        data=[{"col_a": 1, "col_b": 2}],
-        row_count=1,
-    )
-
-
-def main():
-    s = space.get(ctx.space_id or "")
-    _Ports = type(
-        "_Ports",
-        (),
-        {
-            "get_params": lambda self: dict(ctx.params or {}),
-            "function_result": lambda self, **kw: onto.function_result(**kw),
-        },
-    )
-    p = _Ports()
-    p.sql = s.sql
-    return _ontology_fn_body(p)
-```
-
-**禁止**：`output.print_json`、`print()` 作为最终输出、仅 `return {"key": val}` 裸 dict（应使用 `onto.function_result` / `p.function_result`）。
-
-**模板**：`资源/examples/onto/_templates/ontology_function_template.py`（`dazi examples show onto/template/ontology-function`）。完整说明见 [function-guide · 函数脚本结构](./function-guide.md#函数脚本结构标准模板)。
-
-### 4. CLI 参数认知错误
-
-#### 坑 A：`function run` 不支持 `--arguments-json-file`
-
-```powershell
-# 错误 — 提示 unknown option
-dazi onto function run cost.fn.get_summary --space space__ljzeng --arguments-json-file "xxx.json"
-
-# 正确 — 先 save-test-arguments 保存默认参数，run 时不传文件
-dazi onto function run cost.fn.get_summary --space space__ljzeng
-```
-
-#### 坑 B：`save-test-arguments` 用错 ID 类型
-
-```powershell
-# 错误 — 用了 function_id（平台不认）
-dazi onto function save-test-arguments cost.fn.get_summary --space space__ljzeng ...
-
-# 正确 — 用 ofn_ 开头的内部注册 ID
-dazi onto function save-test-arguments ofn_97a01c967ed24b03 --space space__ljzeng ...
-```
-
-**获取方法**：`dazi onto function list --space space__ljzeng`，返回 JSON 中的 `id` 字段即为 ofn_xxx。
-
----
-
-## 二、正确 CLI 操作清单
-
-前提：在 `dazi-work` 根目录执行，所有路径相对于根目录。
-
-### 1. 发布初始化脚本（setup 类型）
-
-```powershell
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/setup/cost_ontology_init.py --space space__ljzeng --type setup
-```
-
-### 2. 执行初始化脚本
-
-```powershell
-dazi onto script run --file 项目/潘达石化/本体/ontos/商务成本本体方案/setup/cost_ontology_init.py --space space__ljzeng
-```
-
-### 3. 发布灌数脚本（data 类型）
-
-```powershell
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/setup/cost_seed_data.py --space space__ljzeng --type data
-```
-
-### 4. 执行灌数脚本
-
-```powershell
-dazi onto script run --file 项目/潘达石化/本体/ontos/商务成本本体方案/setup/cost_seed_data.py --space space__ljzeng
-```
-
-### 5. 发布本体函数（必须带 `--register-function-id`）
-
-```powershell
-# 每个函数单独发布
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/functions/cost_fn_get_summary.py --space space__ljzeng --register-function-id cost.fn.get_summary
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/functions/cost_fn_category_breakdown.py --space space__ljzeng --register-function-id cost.fn.category_breakdown
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/functions/cost_fn_department_breakdown.py --space space__ljzeng --register-function-id cost.fn.department_breakdown
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/functions/cost_fn_top_cost_types.py --space space__ljzeng --register-function-id cost.fn.top_cost_types
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/functions/cost_fn_budget_vs_actual.py --space space__ljzeng --register-function-id cost.fn.budget_vs_actual
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/functions/cost_fn_mom_analysis.py --space space__ljzeng --register-function-id cost.fn.mom_analysis
-dazi onto script publish 项目/潘达石化/本体/ontos/商务成本本体方案/functions/cost_fn_yoy_analysis.py --space space__ljzeng --register-function-id cost.fn.yoy_analysis
-```
-
-### 6. 查询函数内部 ID（用于保存默认参数）
-
-```powershell
-dazi onto function list --space space__ljzeng
-```
-
-从 JSON 输出中提取每个函数的 `id`（格式为 `ofn_xxx`）。
-
-### 7. 保存默认测试参数（test_arguments）
-
-```powershell
-# 先查 list 获取 ofn_xxx，再逐个保存
-dazi onto function save-test-arguments <ofn_internal_id> --space space__ljzeng --arguments-json-file 项目/潘达石化/本体/ontos/商务成本本体方案/functions/test_arguments/<function_id>.json
-```
-
-### 8. 运行函数验证
-
-```powershell
-dazi onto function run <function_id> --space space__ljzeng
-```
-
-**注意**：运行时不传 `--arguments-json-file`，参数来自第 7 步预存的 test_arguments。
-
----
-
-## 三、修改函数代码后的正确流程
-
-如果函数代码有 bug 修复，重复以下步骤：
-
-1. **重新发布**（版本号自动 +1）
-2. **运行验证**：`dazi onto function run <function_id> --space space__ljzeng`
-3. **重新保存 test_arguments**（如果参数有变化）
-
----
-
-## 四、关键 CLI 命令速查
-
-| 目的                | 命令                                                                                           |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| 发布 setup 脚本     | `dazi onto script publish <path> --space <space> --type setup`                                 |
-| 发布 data 脚本      | `dazi onto script publish <path> --space <space> --type data`                                  |
-| 发布函数（注册 ID） | `dazi onto script publish <path> --space <space> --register-function-id <fn.id>`               |
-| 执行脚本            | `dazi onto script run --file <path> --space <space>`                                           |
-| 运行函数            | `dazi onto function run <function_id> --space <space>`                                         |
-| 查询函数列表+ID     | `dazi onto function list --space <space>`                                                      |
-| 保存默认参数        | `dazi onto function save-test-arguments <ofn_id> --space <space> --arguments-json-file <json>` |
-
-## 五、相关文档
-
-| 文档 | 说明 |
-| ---- | ---- |
-| [本体脚本编写指南](./本体脚本编写指南.md) | 目录约定、发布顺序、test_arguments |
-| [本体函数开发指南](./function-guide.md) | 函数生命周期、**标准 main 模板**、`save-test-arguments` |
-| [DaziScript SDK 参考](./dazi_script_sdk_reference.md) | `s.sql` / `s.onto` / Cube API |
-| [故障排查](../guides/troubleshooting.md) | CLI 环境、401、侧栏空白等 |