@dazitech/cli 3.0.7 → 3.0.9

package/dist/docs/onto//346/234/254/344/275/223/350/247/204/345/210/222/346/214/207/345/215/227.md

@@ -2,12 +2,15 @@
 
 ## 目标
 
-在 `规划/` 目录中完成本体项目的概念设计，包括：
+在 `plans/` 目录中完成本体实现单元的概念设计，包括：
 
 - 业务域与边界
+- **物理表**与 **表间关系**
+- **Cube 层**（分析语义：维度、度量、派生度量；`bind_source` 的数据来源）
 - 对象类型（Object Type）与关键属性
-- 链接类型（Link Type）与基数
+- 链接类型（Link Type）与基数（**业务对象层**，与表间关系分层写清）
 - 动作（Action）与规则（Rule）的初步清单
+- 本体函数清单及 **test_arguments**（默认测试入参）约定
 
 ## 本体、Cube 与物理表：三者关系与「业务世界」方法
 
@@ -15,9 +18,9 @@
 
 | 层级                          | 是什么                                                                   | 典型职责                                                                                                 | 规划文档里写什么                                                                                                                                                                                                                                                                                    |
 | ----------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **物理表（Table）**           | ClickHouse 等引擎中的事实/维表                                           | 存储、排序键、约束、ETL 落地；面向写入与物理优化                                                         | **首层物理模型宜为业务明细/维表/流水等**，分析向宽表、主题汇总表宜作为**派生层**；**避免**规划落地时默认「每个分析对象各建一张 `fact_*_analysis`」且仅此一层——否则与「每个 Cube 复制一个对象」仍是同一类一对一，只是顺序颠倒。表名、主键/关联列与源系统对齐；**不**把表名直接当作业务对象的唯一名字 |
-| **Cube**                      | 面向分析语义的数据集视图（维度、度量、聚合）                             | 报表、语义查询、指标白名单；`qualified_name` 多以前缀 `CubeName.member` 出现                             | 需要哪些 Cube、维/度量与业务度量的对应；Cube 名可用分析域习惯（如带 `Analytics` / `Cube` 后缀）                                                                                                                                                                                                     |
-| **本体（Ontology 对象类型）** | **业务世界**中的对象类型：身份、类型化**链接**、挂载函数/动作/规则的锚点 | 让业务与产品讨论「客户」「订单」「合同」而非「第几张表第几列」；链接表达有向业务关系，而非仅外键数值相等 | **对象类型 `code`** 用稳定**业务英文标识**（如 `Order`、`Customer`）；与 Cube 名、表名**刻意区分**；`bind_source` 声明「当前由哪个 Cube 支撑该对象的读模型」                                                                                                                                        |
+| **物理表（Table）**           | ClickHouse 等引擎中的事实/维表                                           | 存储、排序键、约束、ETL 落地；面向写入与物理优化                                                         | 表名使用 **`fact_` / `dim_` / `bridge_` 等前缀**（**强制 `dim_date` + `date_key`**）；详见 **[本体命名规范 §347](./本体命名规范_物理表Cube与对象.md)** |
+| **Cube**                      | 面向分析语义的数据集视图（维度、度量、聚合）                             | 报表、语义查询、指标白名单；`qualified_name` 多以前缀 `CubeName.member` 出现                             | **PascalCase + `Cube` 后缀**；标注 Process/Subject/Comparison/Snapshot 类别；见 [命名规范 §4](./本体命名规范_物理表Cube与对象.md#4-cube类别与命名) |
+| **本体（Ontology 对象类型）** | **业务世界**中的对象类型：身份、类型化**链接**、挂载函数/动作/规则的锚点 | 让业务与产品讨论「客户」「订单」「合同」而非「第几张表第几列」；链接表达有向业务关系，而非仅外键数值相等 | **`code` 无前缀** PascalCase 业务名；标注 Master/Transaction/Analytical 等**分类**（非 code 前缀）；见 [命名规范 §5](./本体命名规范_物理表Cube与对象.md#5-本体对象palantir-思想与分类) |
 
 **「业务世界」方法（规划阶段强制自检）**：
 
@@ -25,22 +28,129 @@
 - 接受 **多对一**：多表、多 Cube 可收敛为一种业务对象；一宽表也可拆成多种业务对象。
 - **链接**两端必须是对象类型 **`code`**，不是 Cube 名；表中仅有 `xxx_id` 时，规划文中仍应写清本体链接语义。
 
+### 物理表间关系 vs 本体链接（强制分层）
+
+| 维度 | **物理表间关系** | **本体链接（Link Type）** |
+| ---- | ---------------- | ------------------------- |
+| 所在层 | 数据空间 / ClickHouse | 本体 Ontology |
+| 规划章节 | 物理层设计 → **「表间关系」**（建议 §3.x） | 本体层设计 → **「链接类型」** |
+| 侧栏可见 | **数据资源 → 数据空间 → 表间关系** | **Onto 本体 → 链接** |
+| 实施 API | `s.tables.add_relationship(...)`（init 脚本，**表 register 之后**） | `s.onto.define_link_type(...)` |
+| 典型形态 | 事实表 `many_to_one` 维表（`product_id` → `product_master`） | `SalesOrder` → `Product`（订单包含产品） |
+
+**常见遗漏**：只写本体 `define_link_type`，init 脚本未调用 `add_relationship` → 空间 **`relationship_count` 为 0**，流程多表 JOIN、AI 读空间上下文时缺少关系元数据。
+
+**常见遗漏（TRAE / 智能体）**：规划只写**物理表 + 对象类型 + 函数**，**未写 Cube 层** → init 脚本无 `register_cube`、`bind_source` 无读模型、函数 SQL 与侧栏 **数据资源 → Cube** 无法对照验收。**Cube 层须独立成章，不可省略。**
+
+**规划文档必含「表间关系」小节**，至少列清：
+
+| 列 | 说明 |
+| -- | ---- |
+| 从表 / 到表 | 物理表名，通常 **从事实表到维表** |
+| 关系类型 | 如 `many_to_one` |
+| join_keys | 如 `product_id → product_id` |
+| join_sql | 如 `sales_order_fact.product_id = product_master.product_id` |
+| 对应本体链接 | 可选对照表，便于评审 |
+
+## 物理层元数据：显示名与说明（强制）
+
+规划文档中的物理表字段表，须区分 **显示名** 与 **说明**，以便 init 脚本映射到 `s.tables.register_with_meta`：
+
+| 规划列 | 平台字段 | 用途 | 示例 |
+| ------ | -------- | ---- | ---- |
+| **显示名** | `display_name` | 侧栏、表预览、AI 上下文的短标签 | `凭证 ID`、`借方` |
+| **说明** | `description` | 业务口径、FK 指向、冗余原因 | `关联 dim_date`、 `冗余` |
+
+**表清单**建议列：`表名 | 显示名 | 说明 | 角色`（「中文名」统一改称 **显示名**）。
+
+**字段表**建议列：`字段名 | 类型 | 显示名 | 说明`（原单列「说明」若混有 FK/PK 标记，拆到 **说明** 列；**显示名** 写面向用户的短标签）。
+
+init 脚本在 `setup/*_ontology_init.py` 顶部维护 `TABLE_REGISTRY`，与规划 **一一对应**。内置参考：`资源/examples/onto/利润示例`、`销售示例` 的 init 与 `资源/docs/onto/规划示例_*.md`；详见 [本体脚本编写指南 §表注册](./本体脚本编写指南.md#表注册-table_registry--register_with_meta)。
+
+## 平台分类（347 对齐 · 强制）
+
+规划阶段的 **347 语义分类**（表/Cube/对象/关系/链接/函数）须与平台 **`ads_categories`** 使用**同一套标准中文名**（见 [349 方案](./本体分类规划与SDK扩展方案.md)、[347 §3](./本体命名规范_物理表Cube与对象.md)）。
+
+| 规划要求 | 说明 |
+| -------- | ---- |
+| 各资源表增加 **347 分类** 列 | 物理表、Cube、对象、表间关系、链接、函数清单均须标注 |
+| 附录 B | `plans/<主题>.md` 末尾附 **CATEGORY_REGISTRY 对照表**，与 init 脚本顶部字典逐行一致 |
+| init 步骤 | 资源注册完成后调用 `s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)` |
+| 平级目录 | 6 类资源挂空间默认根下，**不**建多层分类树 |
+
+**英文分类 → 平台中文名**（摘录）：
+
+| 资源 | 英文（规划列） | 347 / 平台分类名 |
+| ---- | -------------- | ---------------- |
+| Cube | Process | 流程型 |
+| Cube | Subject | 主体型 |
+| Cube | Comparison | 对比型 |
+| 对象 | Master | 主数据 |
+| 对象 | Transaction | 事务 |
+| 对象 | Analytical | 分析 |
+| 对象 | Reference | 参考 |
+| 关系 | — | 时间关联 / 主数据关联 / 层级自关联 / 预实关联 / 桥接关联 |
+| 链接 | — | 归属关系 / 分析归因 / 层级关系 / 对比关系 |
+| 函数 | — | 总览分析 / 趋势分析 / 结构分析 / 预实分析 / 组织分析 |
+
+参考附录 B：[规划示例_产品销售](./规划示例_产品销售本体规划方案.md#附录-b347-分类挂载对照表category_registry)、[规划示例_利润分析](./规划示例_利润分析本体方案.md#附录-b347-分类挂载对照表category_registry)。
+
+## 规划文档标准结构（建议章节）
+
+新建 `plans/<主题>.md` 时，**至少**包含下列章节（顺序可微调，**不可缺项**）：
+
+| 章节 | 内容要点 |
+| ---- | -------- |
+| 一、业务场景与边界 | 域定义、分析目标、空间/数据源约束 |
+| 二、物理层设计 | 事实表/维表、字段、主键 |
+| 三、表间关系 | 见上文「表间关系」表格 |
+| **四、Cube 层设计** | **独立成章**；见下文 |
+| 五、本体层设计 | 对象类型、`bind_source`→Cube、属性、链接类型 |
+| 六、本体函数设计 | function_id、参数、返回值、**test_arguments** |
+| 七、实施计划 | 分阶段任务（含 Cube 注册步骤） |
+| 八、风险与验收 | 含 Cube 数量、派生度量、relationship_count |
+| **附录 B：347 分类挂载对照** | `CATEGORY_REGISTRY` 与 init 脚本一致 |
+| **附录：规划完整性自检清单** | 见本文 [§规划文档完整性自检清单](#规划文档完整性自检清单) |
+
+参考全文结构：[规划示例_产品销售本体规划方案.md](./规划示例_产品销售本体规划方案.md)、[规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md)。
+
+## Cube 层设计（强制独立章节）
+
+Cube 是 **表 → 分析语义 → 本体读模型** 的中间层。规划阶段若跳过 Cube，实施阶段将无法完成 `s.register_cube`、`s.onto.bind_source(..., "dazi_cube", ...)` 及 `sync_metric_refs`。
+
+**每个 Cube 至少写清**：
+
+| 列 | 说明 |
+| -- | ---- |
+| Cube 名 | 如 `SalesCube`、`ActualCube`；与对象类型 `code`、表名**区分** |
+| 事实源表 | 主事实表（可多 Cube 共享同一事实表、不同维度切片） |
+| 维度 | 参与 GROUP BY / 筛选的字段列表 |
+| 度量 | 列名、聚合（sum/uniq/count 等）、业务含义 |
+| 派生度量 | 表达式（如 avg = amount/qty）、说明 |
+| 支撑的对象类型 | 哪些 `define_object_type` 通过 `bind_source` 绑定本 Cube |
+
+**自检**：每个需对外分析的对象类型，是否在 Cube 层有**明确**读模型（或文档说明为何共用某 Cube）；init 脚本步骤中是否有 **「注册 N 个 Cube」** 与规划 **N 一致**。
+
 **与业界对象中心实践的对照**：上述分层与「对象优先、数据为 backing」的思路，可与 **Palantir Foundry Ontology**（对象类型、链接、Action、Function 分层）等成熟产品对照阅读；落地脚本时以平台当前 API 与 **`dazi onto`** 能力为准，**不**假设已实现对方全部特性。
 
 ## 必读文档
 
-1. **本体规划示例**：`规划示例_利润分析本体方案.md`（扩展内置于 `docs/onto/`；同步到工作区后为 `资源/docs/onto/规划示例_利润分析本体方案.md`）
-2. **工作区与 CLI**：`guides/workspace-v3.md`、`guides/cli-reference.md`（`dazi docs sync` 后位于 `资源/docs/guides/`）
+1. **本体规划示例（推荐）**：[`规划示例_产品销售本体规划方案.md`](./规划示例_产品销售本体规划方案.md) — 含表间关系、test_arguments 与完整脚本对照（`dazi docs sync` 后位于 `资源/docs/onto/`）
+2. **命名规范（347）**：[`本体命名规范_物理表Cube与对象.md`](./本体命名规范_物理表Cube与对象.md)（`onto/naming-conventions`）— 物理表前缀、`dim_date`、Cube 类别、对象 Palantir 式分类
+3. **补充示例**：[`规划示例_利润分析本体方案.md`](./规划示例_利润分析本体方案.md) — 利润分析域参考
+4. **工作区与 CLI**：`guides/workspace-v3.md`、`guides/cli-reference.md`（`dazi docs sync` 后位于 `资源/docs/guides/`）
+5. **可运行脚本示例**：`资源/examples/onto/销售示例/`（推荐）、`资源/examples/onto/利润示例/`（`dazi examples sync` 或侧栏 **帮助 → 示例**）
 
 ## 产出约定
 
-- **本体方案（规划文档）**：新建/修改的 Markdown **必须**落在 **`项目/{{项目名称}}/规划/<规划主题>.md`**（这是规划阶段的真产出；**不是**改 `本体规划指南.md`）。
+- **本体方案（规划文档）**：新建/修改的 Markdown **必须**落在 **`项目/<业务名>/本体/ontos/<实现名>/plans/<规划主题>.md`**（这是规划阶段的真产出；**不是**改 `本体规划指南.md`）。
 - 进入脚本实现阶段：遵循 **`本体脚本编写指南.md`**（含发布）、**`function-guide.md`**。
+- **执行脚本前必读（强制）**：[`脚本运行纠错_商务成本方案开发过程.md`](./脚本运行纠错_商务成本方案开发过程.md)（`onto/script-run-troubleshooting`）。
 
 ## 空间约束（强制）
 
-- 本体项目创建时已绑定 **数据空间**；`space_id` 以 **`项目/<文件夹名>/README.md`** 为准。
-- 若 README 中无 `space_id`（非扩展「新建项目」创建的本体项目），不得新建规划文件，须先让用户补全空间或重新创建项目。
+- 本体实现单元创建时已绑定 **数据空间**；`space_id` 以 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 为准。
+- 若 README 中无 `space_id`（非扩展「新建本体实现」创建），不得新建规划文件，须先让用户补全空间或重新创建实现单元。
 
 ## LLM 执行指引（必须遵循）
 
@@ -50,22 +160,27 @@
 
 - **工作区根**：VS Code 已打开的文件夹；多根工作区时在设置 **`dazi.workspaceRoot`** 指定。
 - **平台与登录**：`dazi.serverUrl`；`dazi auth login` 或 `dazi auth set-token`（Token 存 `.dazi/auth.json`）。
-- **本体项目即工作单元**（扩展「新建项目」时已选定数据空间，**无需**再建 `onto/<space_id>/` 等平行目录）：
+- **业务项目与本体实现单元**（扩展「新建本体实现」时已选定数据空间，**无需**再建 `onto/<space_id>/` 等平行目录）：
 
 ```text
 <工作区根>/
-  项目/onto_<名称>/
-    README.md       ← 数据空间 ID、项目元信息（规划/实施均以此为准）
-    规划/           ← 规划阶段 Markdown 产出
-    脚本/           ← 本体 Python 脚本
-  资源/docs/onto/   ← 本体指南与规划示例（dazi docs sync）
-  资源/dataspaces/  ← 侧栏下载的表结构 Markdown
+  项目/<业务名>/                    ← 业务项目根
+    本体/                           ← 本体根目录
+      ontos/<实现名>/               ← 本体实现单元（工作单元）
+        README.md                   ← 数据空间 ID、实现元信息（规划/实施均以此为准）
+        快速启动_<实现名>.md
+        plans/                      ← 规划阶段 Markdown 产出
+        setup/                      ← 初始化 / 灌数脚本
+        functions/                  ← 本体函数 / 动作脚本
+          test_arguments/           ← 各 function_id 的 test_arguments JSON（与 .py 内 TEST_ARGUMENTS 同步）
+  资源/docs/onto/                   ← 本体指南与规划示例（dazi docs sync）
+  资源/dataspaces/                  ← 侧栏下载的表结构 Markdown
 ```
 
 ### 规划开始前
 
-1. 从 **`项目/<文件夹名>/README.md`** 读取 **数据空间 ID**（可与设置 `dazi.spaceId` 对照，以 README 为准）。
-2. 未绑定 `space_id` 时 **不得** 新建规划 Markdown，须先让用户通过扩展创建本体项目或明确空间。
+1. 从 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 读取 **数据空间 ID**（可与设置 `dazi.spaceId` 对照，以 README 为准）。
+2. 未绑定 `space_id` 时 **不得** 新建规划 Markdown，须先让用户通过扩展创建本体实现单元或明确空间。
 
 ### 规划阶段最小流程
 
@@ -77,7 +192,7 @@ dazi auth whoami
 dazi docs sync    # 可选：同步帮助文档到 资源/docs/
 ```
 
-**核对数据空间与现网资产**（`<space_id>` 取自当前项目的 `README.md`，勿另猜目录）：
+**核对数据空间与现网资产**（`<space_id>` 取自当前实现单元的 `README.md`，勿另猜目录）：
 
 ```bash
 dazi onto space list
@@ -86,46 +201,81 @@ dazi onto space get <space_id>    # 可选：查看空间详情
 
 **扩展侧栏（规划阶段主要入口）**：
 
-| 目的          | 操作                                                  |
-| ------------- | ----------------------------------------------------- |
-| 确认绑定空间  | 打开 **`项目/onto_<名称>/README.md`** 中的数据空间 ID |
-| 查看表 / Cube | **数据资源** → 对应数据空间 → 展开表、Cube            |
-| 下载表结构    | 表节点右键「下载表信息」→ `资源/dataspaces/`          |
-| 同步帮助文档  | **帮助** → 下载文档（`dazi docs sync`）               |
+| 目的          | 操作                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------- |
+| 确认绑定空间  | 打开 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 中的数据空间 ID               |
+| 查看表 / Cube | **数据资源** → 对应数据空间 → 展开表、Cube                                            |
+| 下载表结构    | 表节点右键「下载表信息」→ `资源/dataspaces/`                                          |
+| 同步帮助文档  | **帮助** → 下载文档（`dazi docs sync`）                                               |
 
 > 规划阶段**不**要求本地 `snapshot.json`、`editorial/` 或 `onto/<space_id>/` 目录；以侧栏 **数据资源** 与项目内文档为准即可。
 
-规划阶段 **只产出 Markdown**：写入 **`项目/<onto_项目>/规划/<主题>.md`**，可参考 **`规划示例_利润分析本体方案.md`**。此阶段不发布脚本。
+规划阶段 **只产出 Markdown**：写入 **`项目/<业务名>/本体/ontos/<实现名>/plans/<主题>.md`**，**首选参考** [`规划示例_产品销售本体规划方案.md`](./规划示例_产品销售本体规划方案.md)。此阶段不发布脚本。
+
+**定稿门槛**：对照 [§规划文档完整性自检清单](#规划文档完整性自检清单)，**尤其第 4 项 Cube 层**；未通过不得进入脚本实施。
 
 ### 进入脚本实施
 
-脚本写在 **`项目/<onto_项目>/脚本/`**（Python，见 `dazi.onto.defaultScriptLang`）。发布与运行见 **`本体脚本编写指南.md`**、**`function-guide.md`**：
+脚本写在 **`项目/<业务名>/本体/ontos/<实现名>/setup/`**（初始化、灌数）与 **`functions/`**（本体函数、动作；Python，见 `dazi.onto.defaultScriptLang`）。发布与运行见 **`本体脚本编写指南.md`**、**`function-guide.md`**：
 
 ```bash
-dazi onto script publish-preview 项目/onto_<名称>/脚本/my_func.py --space <space_id>
-dazi onto script publish 项目/onto_<名称>/脚本/my_func.py \
+dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py --space <space_id>
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
   --space <space_id> \
   --register-function-id <function_id>
 dazi onto function run <function_id> --space <space_id> --params '{}'
+# 函数测试通过后，保存 test_arguments（侧栏「运行函数」预填参数，见本体脚本编写指南）
 ```
 
-亦可在侧栏 **Onto 本体** 使用「发布函数」「运行函数」等命令（与终端 CLI **同源** bundled；`--space` 与项目 README 中的 `space_id` 一致）。
+亦可在侧栏 **Onto 本体** 使用「发布函数」「运行函数」等命令（与终端 CLI **同源** bundled；`--space` 与实现单元 README 中的 `space_id` 一致）。
 
-实施前可用 `dazi onto function list --space <space_id>` 核对平台已有函数定义，**开发入口始终是 `项目/<onto_项目>/脚本/`**，不以历史 `onto/`、`editorial` 目录为约定路径。
+**实施顺序（强制）**：
+
+1. `setup/*_ontology_init.py`：建表 → `tables.register_with_meta` → **`tables.add_relationship`** → Cube → 本体对象/链接 → **`categories.apply_registry`**  
+2. `setup/*_seed_data.py`：灌数（幂等）  
+3. `functions/*.py`：发布并 **`--register-function-id`**  
+4. 运行函数验证 → **`save-test-arguments`** 写入各函数定义的 `test_arguments`
+
+实施前可用 `dazi onto function list --space <space_id>` 核对平台已有函数定义；`dazi onto space get <space_id>` 核对 **`relationship_count`** 是否与规划一致。
 
 ### 失败处理
 
 - 命令失败时输出 **完整错误** 与修复建议（登录、`dazi.serverUrl`、工作区路径、`space_id`），**不得** 静默跳过。
+- init / 函数发布与 CLI 参数常见误用见 **[脚本运行纠错（商务成本方案实录）](./脚本运行纠错_商务成本方案开发过程.md)**（`dazi docs show onto/script-run-troubleshooting`）。
 - v2 → v3 命令对照见 `guides/troubleshooting.md`（`dazi docs sync` 后位于 `资源/docs/guides/`）。
 
-## 自检
-
-- 是否写清对象类型、链接、函数/Action、规则（如适用）
-- **`define_link_type` 与对象类型 code**：链接两端须为**已规划且将先创建**的对象类型 **`code`**（与 `define_object_type` 一致）；**勿**将 **Cube 名** 或表名当作对象类型 `code`。勿混用仅中文名而无稳定 `code`。
-- 是否给出实施步骤、风险与验收
+## 规划文档完整性自检清单
+
+规划 Markdown **定稿前**（进入 `setup/` 脚本编写前），逐项勾选。**任一项未满足则不得开始 init 脚本**（智能体 / TRAE 须先补全规划）。
+
+| # | 检查项 | 通过标准 |
+| - | ------ | -------- |
+| 1 | **业务场景** | 已写清域边界、分析目标、适用空间 |
+| 2 | **物理表** | 每张表有用途、主键/关键字段；事实表与维表角色明确；字段表含 **显示名** 与 **说明** 列 |
+| 2a | **表元数据注册** | `setup/*_init.py` 含 `TABLE_REGISTRY`，表/列 `display_name`、`description` 与规划一致，经 `register_with_meta` 注册 |
+| 3 | **表间关系** | 独立小节；每条含从表/到表、类型、join_keys、join_sql；条数与 init 中 `add_relationship` 一致 |
+| 4 | **Cube 层** | **独立成章**；每个 Cube 含事实源、维度、度量、派生度量；数量与 init 中 `register_cube` 一致 |
+| 5 | **对象类型** | 每个 `code` 稳定英文标识；**非**表名/Cube 名 |
+| 6 | **bind_source** | 每个分析对象已声明绑定哪个 Cube（对照表或属性映射表） |
+| 7 | **链接类型** | 两端为对象类型 `code`；与表间关系分层写清 |
+| 8 | **函数清单** | 每个 `function_id`、参数、返回值；无遗漏核心分析能力 |
+| 9 | **test_arguments** | 每个函数默认入参已列出（或注明无参） |
+| 10 | **实施与验收** | 分阶段计划含 Cube 步骤；验收含 Cube 注册、relationship_count、函数可运行 |
+| 6a | **CATEGORY_REGISTRY** | 规划附录 B 与 init 顶部字典一致；6 类资源齐全 |
+| 6b | **表 347 分类** | 每张表标注时间维/维度表/事实表等标准名 |
+| 6c | **Cube 347 分类** | 每个 Cube 标注流程型/主体型/对比型/快照型 |
+| 6d | **对象/链接/关系 347 分类** | 对象标主数据/事务/分析/参考；链接与关系标扩展类别 |
+| 6e | **分类挂载验收** | init 含 `apply_registry`；侧栏分类名与 347 一致；重跑幂等 |
+
+**命名规范扩展项**（详见 [本体命名规范 §8.4](./本体命名规范_物理表Cube与对象.md#84-自检清单在-本体规划指南-原-10-项基础上扩展)）：`dim_date` / `date_key`、表前缀、Cube 类别、对象分类、三层对照表、**平台分类 6a–6e**。
+
+可将上表复制到 `plans/<主题>.md` 末尾作为 **附录**，评审时逐项打勾。
 
 ## 相关文档
 
 - [本体脚本编写指南](./本体脚本编写指南.md)
 - [本体规划指南](./本体规划指南.md)
-- [本体规划示例文档](./规划示例_利润分析本体方案.md)
+- [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
+- [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
+- [349 · 本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)
+- [脚本运行纠错（商务成本方案实录）](./脚本运行纠错_商务成本方案开发过程.md)

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

@@ -0,0 +1,213 @@
+# 脚本运行纠错 · 商务成本方案开发过程记录
+
+**文档 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、侧栏空白等 |