@dazitech/cli 3.0.9 → 3.1.0

package/dist/docs/onto//350/204/232/346/234/254/350/277/220/350/241/214/345/270/270/350/247/201/351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -0,0 +1,242 @@
+# 脚本运行常见错误处理
+
+**文档 ID**: `onto/script-run-troubleshooting`  
+**级别**: **执行脚本前必读（强制）** — 在终端执行 `dazi onto script publish` / `script run` / `function run` / `save-test-arguments` **之前**须通读  
+**适用**: 本体 `setup/`、`functions/` 脚本编写、发布与运行；智能体见提示词 `onto/script-publish-run`
+
+> 路径占位：`<项目路径>` = `项目/<业务名>/本体/ontos/<实现名>`，`<空间>` 取自实现单元 `README.md`。
+
+---
+
+## 1. setup 脚本 API 误用
+
+| 错误写法 | 正确写法 | 说明 |
+| -------- | -------- | ---- |
+| `s.onto.sync_metrics()` | 删除；必要时 `s.sync_metric_refs()` | `sync_metrics` 不存在 |
+| `s.cubes.upsert(...)` | `s.register_cube(...)` | 无 `s.cubes` |
+| `define_object_type(code, label=name)` | `define_object_type(code, name=...)` | 第二参数为 `name` |
+| `define_object_type(title=...)` | `define_object_type(name=...)` | 参数名为 `name` |
+| `bind_source(source_type=..., source_name=...)` | `bind_source(obj_code, "dazi_cube", config={"cube": "CubeName"})` | 见利润/销售示例 |
+| `define_property(object_type_code=..., title=...)` | `define_property(obj_code, code, name, ...)` | 位置参数 |
+| `define_link_type(title=..., from_object_type=...)` | `define_link_type(name=..., from_object_type_code=..., to_object_type_code=...)` | 以 `_code` 结尾 |
+
+**教训**：对照 `资源/examples/onto/利润示例`、`销售示例` 的 init，勿猜 API。
+
+---
+
+## 2. SQL 聚合：`query_one` 返回类型
+
+**现象**：`float' object has no attribute 'get'`
+
+```python
+# 错误
+total_row = p.sql.query_one("SELECT sum(amount) AS grand_total FROM ...")
+grand_total = float(total_row.get("grand_total", 0))
+```
+
+**原因**：聚合场景下 `query_one()` 可能返回标量而非字典行。
+
+**修复**：
+
+```python
+total_rows = p.sql.query("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)
+```
+
+---
+
+## 3. 函数输出：禁止 `output.print_json`
+
+**现象**：`AttributeError: 'OutputModule' has no attribute 'print_json'`
+
+本体函数须 **`return`** 结构化结果，不能当 setup 脚本用 `output` 打印 JSON。
+
+```python
+def _ontology_fn_body(p):
+    rows = p.sql.query("SELECT ...")
+    return p.function_result(columns=[...], data=rows, row_count=len(rows))
+
+def main():
+    s = space.get(ctx.space_id or "")
+    # 组装 p（见 ontology_function_template.py）
+    return _ontology_fn_body(p)
+```
+
+**禁止**：`output.print_json()`、`main(params: dict)`、裸 `return {"k": v}` 代替 `function_result`。
+
+**模板**：`资源/examples/onto/_templates/ontology_function_template.py`
+
+---
+
+## 4. CLI 参数误用
+
+### 4.1 `function run` 不支持 `--arguments-json-file`
+
+```powershell
+# 错误
+dazi onto function run <function_id> --space <空间> --arguments-json-file xxx.json
+
+# 正确：先 save-test-arguments，再 run（不带 JSON 文件）
+dazi onto function run <function_id> --space <空间>
+```
+
+### 4.2 `save-test-arguments` 须用 `ofn_xxx` 内部 ID
+
+```powershell
+# 错误 — function_id 字符串
+dazi onto function save-test-arguments profit.fn.get_summary --space <空间> ...
+
+# 正确 — list 返回的 id 字段
+dazi onto function list --space <空间>
+dazi onto function save-test-arguments ofn_xxxxxxxx --space <空间> `
+  --arguments-json-file <项目路径>/functions/test_arguments/<function_id>.json
+```
+
+### 4.3 函数发布未带 `--register-function-id`
+
+仅 `script publish` 时代码入库，**不会**出现在 Onto → 函数列表，`function run` 失败。
+
+```powershell
+dazi onto script publish <项目路径>/functions/xxx_fn.py --space <空间> `
+  --register-function-id <domain>.fn.<name>
+dazi onto function list --space <空间>   # 必须能看到该 id
+```
+
+可选同时挂载平台分类：`--register-platform-category 总览分析`
+
+---
+
+## 5. 函数「未注册」（规划有、侧栏无）
+
+| 现象 | 根因 |
+| ---- | ---- |
+| `CATEGORY_REGISTRY` / plans 列了 N 个函数 | 规划清单 ≠ 已发布函数 |
+| `functions/` 文件数 < 规划数 | 脚本未写完 |
+| `function list` 只有 1 条 | 多数未 `publish --register-function-id` |
+
+**结论**：init **不负责**注册本体函数；每个 `functions/*.py` 须单独 publish 并注册。
+
+**门禁**：规划函数数 = `functions/*.py` 数 = `function list` 条数。
+
+---
+
+## 6. 平台分类挂载时机
+
+**推荐**：与灌数一样，使用独立 `setup/*_category_mount.py`，放在流程**最后**：
+
+```
+init → seed → 发布全部函数 → category_mount
+```
+
+| 方式 | 何时 |
+| ---- | ---- |
+| **`*_category_mount.py`**（推荐） | 全量 `CATEGORY_REGISTRY` + `apply_registry`；函数齐后一次执行 |
+| `--register-platform-category` | 单函数 publish 时内联（与 category_mount 幂等可并存） |
+| init 内 `apply_registry` | **不推荐**（函数未 publish 时 function 段被跳过，须重跑 init） |
+
+`skip_missing=True` 时，未注册函数会被跳过；**补发函数后只重跑 category_mount**，无需重跑 init。
+
+---
+
+## 7. 平台分类字典报错
+
+**现象**：
+
+```
+ValueError: 平台分类字典中不存在分类: kind='table', category='维度表'
+```
+
+（旧版日志可能显示乱码，非脚本 UTF-8 损坏。）
+
+**原因**：`category` 须为**平台标准分类中文名**（如「维度表」「事实表」），且测试环境 backend 须含完整平台分类字典。
+
+**处理**：
+
+1. 确认 `CATEGORY_REGISTRY` 使用标准名，与 [本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md) 一致  
+2. 部署含 `s.categories` 与表类中文名索引的 backend 版本  
+
+---
+
+## 8. 表/列显示名未写入
+
+仅用 `register` + `sync_columns` 时，列 `description` **不会**自动写入规划中的业务说明。
+
+**推荐**：
+
+```python
+s.tables.register_with_meta(
+    table_name,
+    display_name=meta["display_name"],
+    description=meta.get("description"),
+    columns=meta["columns"],
+    force_column_meta=True,
+)
+```
+
+见 [本体脚本编写指南 · 表注册](./本体脚本编写指南.md#表注册-table_registry--register_with_meta)。
+
+---
+
+## 9. 标准 CLI 顺序（通用）
+
+在 `dazi-work` 根目录，将 `<项目路径>`、`<空间>` 替换为实际值。
+
+```powershell
+# 1. init
+dazi onto script publish <项目路径>/setup/xxx_ontology_init.py --space <空间> --type setup
+dazi onto script run --file <项目路径>/setup/xxx_ontology_init.py --space <空间>
+
+# 2. seed（如有）
+dazi onto script publish <项目路径>/setup/xxx_seed_data.py --space <空间> --type data
+dazi onto script run --file <项目路径>/setup/xxx_seed_data.py --space <空间>
+
+# 3. 每个本体函数
+dazi onto script publish <项目路径>/functions/xxx_fn.py --space <空间> `
+  --register-function-id <domain>.fn.<name> `
+  --register-platform-category <平台分类名>
+
+# 4. 平台分类挂载（最后一步，类灌数）
+dazi onto script publish <项目路径>/setup/xxx_category_mount.py --space <空间> --type setup
+dazi onto script run --file <项目路径>/setup/xxx_category_mount.py --space <空间>
+
+# 5. 测试参数与验证
+dazi onto function list --space <空间>
+dazi onto function save-test-arguments <ofn_id> --space <空间> --arguments-json-file ...
+dazi onto function run <function_id> --space <空间>
+```
+
+---
+
+## 10. 修改脚本后的重发流程
+
+| 脚本类型 | 操作 |
+| -------- | ---- |
+| setup / data | `script publish` → `script run` |
+| 本体函数 | `script publish`（含 `--register-function-id`）→ `function run` → 参数变更时重做 `save-test-arguments` |
+
+---
+
+## 11. 命令速查
+
+| 目的 | 命令 |
+| ---- | ---- |
+| 发布 setup | `dazi onto script publish <path> --space <空间> --type setup` |
+| 发布 data | `dazi onto script publish <path> --space <空间> --type data` |
+| 发布并注册函数 | `... --register-function-id <id> [--register-platform-category <分类>]` |
+| 执行脚本 | `dazi onto script run --file <path> --space <空间>` |
+| 运行函数 | `dazi onto function run <function_id> --space <空间>` |
+| 函数列表 | `dazi onto function list --space <空间>` |
+| 保存默认参数 | `dazi onto function save-test-arguments <ofn_id> --space <空间> --arguments-json-file <json>` |
+
+---
+
+## 12. 相关文档
+
+| 文档 | 说明 |
+| ---- | ---- |
+| [本体脚本编写指南](./本体脚本编写指南.md) | 目录、四阶段实施、test_arguments |
+| [本体函数开发指南](./function-guide.md) | 函数模板、`save-test-arguments` |
+| [DaziScript SDK 参考](./dazi_script_sdk_reference.md) | API 与 `s.categories` |
+| [本体开发优化总结](./本体开发优化总结.md) | 表显示名、平台分类、函数四阶段 |
+| [故障排查](../guides/troubleshooting.md) | CLI 环境、401、侧栏空白 |

package/dist/docs/onto//350/247/204/345/210/222/347/244/272/344/276/213_/344/272/247/345/223/201/351/224/200/345/224/256/346/234/254/344/275/223/350/247/204/345/210/222/346/226/271/346/241/210.md

@@ -2,7 +2,9 @@
 
 **文档 ID**: `onto/planning-example-product-sales`
 
-> **推荐**：本体规划阶段**首选参考示例**。覆盖物理表、**表间关系**、Cube、本体链接、函数与 **test_arguments** 完整落地；表/Cube/对象命名遵循 [本体命名规范](./本体命名规范_物理表Cube与对象.md)。  
+> **只读参照**：本体规划阶段**首选结构示例**（非可复制模板）。覆盖物理表、**表间关系**、Cube、本体链接、函数与 **test_arguments** 完整落地；**不得**整篇粘贴为本项目 `plans/`。须独立撰写并写差异说明（见 [本体规划指南 · 任务模式](./本体规划指南.md#任务模式与反模式)）。
+
+> 表/Cube/对象命名遵循 [本体命名规范](./本体命名规范_物理表Cube与对象.md)。  
 > 补充示例（利润分析域）：[规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md)
 
 **占位符**（复制到工作区 `plans/` 后替换为实际值）：
@@ -53,7 +55,7 @@
 
 **物理表清单**（命名见 [命名规范 §2](./本体命名规范_物理表Cube与对象.md#2-物理表类别与前缀)）：
 
-| 表名 | 前缀类别 | **347 分类** | 显示名 | 说明 | 角色 |
+| 表名 | 前缀类别 | **平台分类** | 显示名 | 说明 | 角色 |
 | ---- | -------- | ------------ | ------ | ---- | ---- |
 | **`dim_date`** | 时间维（**强制**） | **时间维** | 日期维表 | 全空间共享；PK **`date_key`** | 时间维 |
 | `dim_product` | dim | **维度表** | 产品维表 | 可售产品主数据 | dim |
@@ -62,7 +64,7 @@
 | **`fact_sales_order_line`** | fact | **事实表** | 销售订单行事实表 | 订单行粒度销售流水；含 **`date_key`** | fact |
 
 > 规划原则：**先**定义业务对象（Product、SalesOrder 等）与链接，**再**反推 Cube 与物理表。事实表通过 `date_key` 关联 `dim_date`，支撑同比/环比与时间层次分析。  
-> init 脚本 `资源/examples/onto/销售示例/setup/sales_ontology_init.py` 顶部 **`TABLE_REGISTRY`** 与上表及 §3.x 字段 **显示名/说明** 一一对应，经 `s.tables.register_with_meta` 注册；**`CATEGORY_REGISTRY`** 与 [附录 B](#附录-b347-分类挂载对照表category_registry) 及 `apply_registry` 步骤对齐。
+> init 脚本 `资源/examples/onto/销售示例/setup/sales_ontology_init.py` 顶部 **`TABLE_REGISTRY`** 与上表及 §3.x 字段 **显示名/说明** 一一对应，经 `s.tables.register_with_meta` 注册；**`CATEGORY_REGISTRY`** 与 [附录 B](#附录-b平台-分类挂载对照表category_registry) 及 `apply_registry` 步骤对齐。
 
 ---
 
@@ -189,7 +191,7 @@
 
 **关系清单（5 条）**：
 
-| 关系 ID | **347 分类** | 类型 | 从表 | 到表 | join_keys | 说明 |
+| 关系 ID | **平台分类** | 类型 | 从表 | 到表 | join_keys | 说明 |
 | ------- | ------------ | ---- | ---- | ---- | --------- | ---- |
 | rel_sales_date | **时间关联** | many_to_one | fact_sales_order_line | dim_date | date_key → date_key | 订单行关联日历 |
 | rel_sales_product | **主数据关联** | many_to_one | fact_sales_order_line | dim_product | product_id → product_id | 订单行关联产品 |
@@ -235,7 +237,7 @@ s.tables.add_relationship(
 
 ### 4.0 Cube 清单与类别
 
-| Cube | 类别 | **347 分类** | 事实源 | 时间维 | 支撑对象 |
+| Cube | 类别 | **平台分类** | 事实源 | 时间维 | 支撑对象 |
 | ---- | ---- | ------------ | ------ | ------ | -------- |
 | **SalesCube** | Process | **流程型** | fact_sales_order_line | dim_date（year/month/quarter） | SalesOrder, SalesAnalysis |
 | **ProductSalesCube** | Subject | **主体型** | fact_sales_order_line | 同上 | Product |
@@ -299,7 +301,7 @@ s.tables.add_relationship(
 
 ### 5.1 对象类型（5 种）
 
-| code | 分类 | **347 分类** | 名称 | bind_source | 主物理支撑 |
+| code | 分类 | **平台分类** | 名称 | bind_source | 主物理支撑 |
 | ---- | ---- | ------------ | ---- | ------------- | ---------- |
 | Product | Master | **主数据** | 产品 | ProductSalesCube | dim_product |
 | Customer | Master | **主数据** | 客户 | CustomerSalesCube | dim_customer |
@@ -339,7 +341,7 @@ s.tables.add_relationship(
 
 ### 5.3 链接类型（8 种）
 
-| 链接 code              | **347 分类** | 名称           | from          | to            | 说明                 |
+| 链接 code              | **平台分类** | 名称           | from          | to            | 说明                 |
 | ---------------------- | ------------ | -------------- | ------------- | ------------- | -------------------- |
 | order_contains_product | **归属关系** | 订单包含产品   | SalesOrder    | Product       | 订单行对应产品       |
 | order_belongs_customer | **归属关系** | 订单归属客户   | SalesOrder    | Customer      | 订单归属客户         |
@@ -367,7 +369,7 @@ s.tables.add_relationship(
 
 ### 6.1 函数清单
 
-| 函数 ID                           | **347 分类** | 功能         | 参数                                              |
+| 函数 ID                           | **平台分类** | 功能         | 参数                                              |
 | --------------------------------- | ------------ | ------------ | ------------------------------------------------- |
 | sales.fn.get_summary              | **总览分析** | 销售总览     | start_date, end_date（可选）                      |
 | sales.fn.yoy_analysis             | **趋势分析** | 同比分析     | start_date, end_date                              |
@@ -458,24 +460,22 @@ JSON 格式须含 `v`、`arguments`、`object_type_code`（与平台函数定义
 | 11   | define_property（约 29 个）                                  |
 | 12   | define_link_type（8 种）                                     |
 | 13   | sync_metric_refs                                             |
-| 14   | **CATEGORY_REGISTRY** + `s.categories.apply_registry`（347 对齐） |
-
-### 7.4 阶段四：函数与数据（中）
+### 7.4 阶段四：灌数、函数与分类（中）
 
 | 步骤 | 任务                                                                 |
 | ---- | -------------------------------------------------------------------- |
-| 14   | 从 `销售示例/functions/sales_fn_*.py` 复制并适配（SQL 表名按本规划） |
-| 15   | seed 灌数：**dim_date** + 维表 + fact（写入 date_key） |
-| 16   | publish + run 验证                                                   |
-| 17   | **`save-test-arguments`** 写入各函数 `test_arguments`（侧栏预填；见 §6.4） |
+| 14   | seed 灌数：**dim_date** + 维表 + fact（写入 date_key） |
+| 15   | 从 `销售示例/functions/sales_fn_*.py` 复制并适配；**publish --register-function-id** |
+| 16   | `function run` + **`save-test-arguments`**（侧栏预填；见 §6.4） |
+| 17   | **`sales_category_mount.py`**：`CATEGORY_REGISTRY` + `apply_registry`（**最后**，类灌数） |
 
-### 7.5 快速实施路径
+### 7.5 实施阶段参考（须 plans 已定稿后）
 
-本仓库 **`资源/examples/onto/销售示例/setup/sales_ontology_init.py`** 含完整 init 逻辑（含 **`TABLE_REGISTRY`** 与 `register_with_meta`），与本文 §2.3、§3.x 对齐：
+`资源/examples/onto/销售示例/setup/sales_ontology_init.py` 含完整 init 逻辑，与本文 §2.3、§3.x 对齐，供 **对照实施** 时参考：
 
-1. 复制 `sales_ontology_init.py`、`sales_seed_data.py` → 实现单元 `setup/`（`dazi examples sync` 或侧栏 **帮助 → 示例**）
-2. 将 init/seed 内 `space_id` 改为 README 中的 `<space-id>`
-3. 按 [快速启动](./本体规划指南.md) 发布执行
+1. 确认 `plans/` 已定稿并通过自检（快速启动 §3 门禁）
+2. 按需借鉴或复制示例 init/seed，**按本实现 plans 改造**表名与元数据
+3. 改 `space_id` 后按 [本体脚本编写指南](./本体脚本编写指南.md) 发布执行
 
 ---
 
@@ -500,7 +500,7 @@ JSON 格式须含 `v`、`arguments`、`object_type_code`（与平台函数定义
 | **表间关系** | **4 条**（含 fact → dim_date） |
 | Cube | **4 个** Cube；SalesCube 含时间维 |
 | 对象类型 | 5 种 + 分类列；8 种链接 |
-| **347 平台分类** | 侧栏分类名与附录 B 一致；init 重跑幂等 |
+| **平台侧栏分类** | 侧栏分类名与附录 B 一致；`category_mount` 重跑幂等 |
 | 函数 | get_summary、top_products 可运行 |
 | test_arguments | 各 function_id 已 save-test-arguments |
 | 数据 | 种子灌入后指标与手工 SQL 一致 |
@@ -519,13 +519,13 @@ JSON 格式须含 `v`、`arguments`、`object_type_code`（与平台函数定义
 
 ---
 
-## 附录 B：347 分类挂载对照表（CATEGORY_REGISTRY）
+## 附录 B：平台分类挂载对照表（CATEGORY_REGISTRY）
 
-与 `销售示例/setup/sales_ontology_init.py` 顶部 **`CATEGORY_REGISTRY`** 一一对应；平台 `category_name` **=** 347 标准中文名（见 [349 方案](./本体分类规划与SDK扩展方案.md)）。
+与 `销售示例/setup/sales_category_mount.py` 顶部 **`CATEGORY_REGISTRY`** 一一对应；平台 `category_name` **=** 平台标准分类中文名（见 [本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)）。**init 不含分类挂载**；本附录在 **全部函数 publish 后** 由 `category_mount` 脚本执行。
 
 ### B.1 物理表（table）
 
-| 347 分类 | 表名 |
+| 平台分类 | 表名 |
 | -------- | ---- |
 | 时间维 | dim_date |
 | 维度表 | dim_product, dim_customer, dim_channel |
@@ -533,14 +533,14 @@ JSON 格式须含 `v`、`arguments`、`object_type_code`（与平台函数定义
 
 ### B.2 Cube（cube）
 
-| 347 分类 | Cube |
+| 平台分类 | Cube |
 | -------- | ---- |
 | 流程型 | SalesCube |
 | 主体型 | ProductSalesCube, CustomerSalesCube, ChannelSalesCube |
 
 ### B.3 对象类型（object）
 
-| 347 分类 | code |
+| 平台分类 | code |
 | -------- | ---- |
 | 主数据 | Product, Customer |
 | 参考 | SalesChannel |
@@ -549,23 +549,23 @@ JSON 格式须含 `v`、`arguments`、`object_type_code`（与平台函数定义
 
 ### B.4 表间关系（relation）
 
-| 347 分类 | 从表 → 到表 |
+| 平台分类 | 从表 → 到表 |
 | -------- | ----------- |
 | 时间关联 | fact_sales_order_line → dim_date |
 | 主数据关联 | fact_sales_order_line → dim_product / dim_customer / dim_channel |
 
 ### B.5 链接类型（link）
 
-| 347 分类 | link code |
+| 平台分类 | link code |
 | -------- | --------- |
 | 归属关系 | order_contains_product, order_belongs_customer, order_via_channel, product_has_orders, customer_places_orders |
 | 分析归因 | analysis_by_product, analysis_by_customer, analysis_by_channel |
 
 ### B.6 本体函数（function）
 
-init 脚本**不**注册函数；函数发布后单独执行 `apply_registry` 的 `function` 段，或 `skip_missing=True` 跳过。建议分类：
+函数在 `functions/` 中 **publish 注册**；`sales_category_mount.py` 在 **init + seed + 全部函数 publish 之后** 统一 `apply_registry`（含 function 段，`skip_missing=True` 可重跑）。建议分类：
 
-| 347 分类 | function_id |
+| 平台分类 | function_id |
 | -------- | ----------- |
 | 总览分析 | sales.fn.get_summary |
 | 趋势分析 | sales.fn.yoy_analysis, sales.fn.mom_analysis |
@@ -595,7 +595,7 @@ init 脚本**不**注册函数；函数发布后单独执行 `apply_registry`
 | 8 | 函数清单 | ☑ |
 | 9 | test_arguments | ☑ |
 | 10 | 实施与验收 | ☑ |
-| 6a–6e | 347 平台分类 | ☑（附录 B + init 步骤 10） |
+| 6a–6e | 平台侧栏分类 | ☑（附录 B + `sales_category_mount.py`） |
 
 ---
 
@@ -610,7 +610,7 @@ init 脚本**不**注册函数；函数发布后单独执行 `apply_registry`
 | 参考实现（init/seed/函数） | `资源/examples/onto/销售示例/` → 复制到 `<item-path>/` |
 | **内置脚本示例** | `资源/examples/onto/销售示例/`（`dazi examples sync` 后复制到实现单元） |
 | 补充示例（利润） | [规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md) · `资源/examples/onto/利润示例/` |
-| 349 · 分类方案 | [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md) |
+| 分类方案 | [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md) |
 
 ---
 

package/dist/docs/onto//350/247/204/345/210/222/347/244/272/344/276/213_/345/210/251/346/266/246/345/210/206/346/236/220/346/234/254/344/275/223/346/226/271/346/241/210.md

@@ -2,6 +2,8 @@
 
 **文档 ID**: `onto/planning-example-profit`
 
+> **只读参照**：本文档供学习 GL 域规划**结构**与验收口径，**不得**整篇复制为本项目 `plans/` 充数。新建实现须在 `plans/` **独立撰写**，并含「与参照示例的差异说明」章节（见 [本体规划指南 · 任务模式](./本体规划指南.md#任务模式与反模式)）。
+
 > 表/Cube/对象命名遵循 [本体命名规范](./本体命名规范_物理表Cube与对象.md)。  
 > 工程模式参考：[规划示例_产品销售本体规划方案.md](./规划示例_产品销售本体规划方案.md)
 
@@ -59,7 +61,7 @@
 
 **物理表清单**（命名见 [命名规范 §2](./本体命名规范_物理表Cube与对象.md#2-物理表类别与前缀)）：
 
-| 表名 | 前缀类别 | **347 分类** | 显示名 | 说明 | 角色 |
+| 表名 | 前缀类别 | **平台分类** | 显示名 | 说明 | 角色 |
 | ---- | -------- | ------------ | ------ | ---- | ---- |
 | **`dim_date`** | 时间维（**强制**） | **时间维** | 日期维表 | 与 sales 域共用；PK **`date_key`** | 时间维 |
 | `dim_account` | dim | **维度表** | 科目维表 | 会计科目主数据 | dim |
@@ -68,7 +70,7 @@
 | **`fact_budget_entry`** | fact | **事实表** | 预算明细 | 预算行粒度编制数据；含 **date_key** | fact |
 
 > 规划原则：先定义 **Account、JournalEntry、BudgetLine** 等业务对象与链接，再反推 Cube 与物理表。旧版 `profit_analysis_fact`（订单粒度）**不作为主模型**。  
-> init 脚本 `资源/examples/onto/利润示例/setup/profit_ontology_init.py` 顶部 **`TABLE_REGISTRY`** 与上表及 §3.x 字段 **显示名/说明** 一一对应，经 `s.tables.register_with_meta` 注册；**`CATEGORY_REGISTRY`** 见 [附录 B](#附录-b347-分类挂载对照表category_registry)。
+> init 脚本 `资源/examples/onto/利润示例/setup/profit_ontology_init.py` 顶部 **`TABLE_REGISTRY`** 与上表及 §3.x 字段 **显示名/说明** 一一对应，经 `s.tables.register_with_meta` 注册；**`CATEGORY_REGISTRY`** 见 [附录 B](#附录-b平台-分类挂载对照表category_registry)，由 **`profit_category_mount.py`** 在流程最后执行（init **不含**分类挂载）。
 
 ## 三、物理层设计
 
@@ -203,7 +205,7 @@
 
 **关系清单（8 条）**：
 
-| 关系 ID | **347 分类** | 类型 | 从表 | 到表 | join_keys | 说明 |
+| 关系 ID | **平台分类** | 类型 | 从表 | 到表 | join_keys | 说明 |
 | ------- | ------------ | ---- | ---- | ---- | --------- | ---- |
 | rel_journal_date | **时间关联** | many_to_one | fact_gl_journal_entry | dim_date | date_key → date_key | 分录关联日历 |
 | rel_budget_date | **时间关联** | many_to_one | fact_budget_entry | dim_date | date_key → date_key | 预算关联日历 |
@@ -244,16 +246,16 @@ s.tables.add_relationship(
 
 ### 4.0 Cube 清单与类别
 
-| Cube | 类别 | **347 分类** | 事实源 | 时间维 | 支撑对象 |
+| Cube | 类别 | **平台分类** | 事实源 | 时间维 | 支撑对象 |
 | ---- | ---- | ------------ | ------ | ------ | -------- |
 | **ActualCube** | Process | **流程型** | fact_gl_journal_entry | dim_date + fiscal_* | JournalEntry, ProfitAnalysis |
 | **AccountActualCube** | Subject | **主体型** | fact_gl_journal_entry | 同上 | Account |
 | **CostCenterActualCube** | Subject | **主体型** | fact_gl_journal_entry | 同上 | CostCenter |
 | **BudgetCube** | Process | **流程型** | fact_budget_entry | 同上 | BudgetLine, BudgetAnalysis |
-| **TimeActualCube** | Subject | **主体型** | fact_gl_journal_entry | 同上 | （时间切片；**init 已注册**，347 建议后续并入 Process） |
+| **TimeActualCube** | Subject | **主体型** | fact_gl_journal_entry | 同上 | （时间切片；**init 已注册**，命名规范建议后续并入 Process） |
 | **BudgetVsActualCube** | Comparison | **对比型** | fact_budget_entry + fact_gl_journal_entry | fiscal_year/period | BudgetAnalysis（预实；**规划目标，init 待补**） |
 
-> 347 §4.2 建议时间增强不单独建 Cube；当前示例 init 仍含 **TimeActualCube** 并归 **主体型**，后续可合并进 ActualCube 后从注册表移除。
+> 命名规范 §4.2 建议时间增强不单独建 Cube；当前示例 init 仍含 **TimeActualCube** 并归 **主体型**，后续可合并进 ActualCube 后从注册表移除。
 
 ### 4.1 ActualCube（Process · 实际发生主 Cube）
 
@@ -322,7 +324,7 @@ s.tables.add_relationship(
 
 ### 5.1 对象类型（6 种）
 
-| code | 分类 | **347 分类** | 名称 | bind_source | 主物理支撑 |
+| code | 分类 | **平台分类** | 名称 | bind_source | 主物理支撑 |
 | ---- | ---- | ------------ | ---- | ------------- | ---------- |
 | Account | Master | **主数据** | 会计科目 | AccountActualCube | dim_account |
 | CostCenter | Master | **主数据** | 成本中心 | CostCenterActualCube | dim_cost_center |
@@ -376,7 +378,7 @@ s.tables.add_relationship(
 
 ### 5.3 链接类型（10 种）
 
-| 链接 code                      | **347 分类** | 名称             | from           | to             | 说明             |
+| 链接 code                      | **平台分类** | 名称             | from           | to             | 说明             |
 | ------------------------------ | ------------ | ---------------- | -------------- | -------------- | ---------------- |
 | entry_belongs_account          | **归属关系** | 分录归属科目     | JournalEntry   | Account        | 分录行对应科目   |
 | entry_belongs_cost_center      | **归属关系** | 分录归属成本中心 | JournalEntry   | CostCenter     | 分录行对应组织   |
@@ -407,7 +409,7 @@ s.tables.add_relationship(
 
 ### 6.1 函数清单
 
-| 函数 ID                      | **347 分类** | 功能         | 参数                                                               |
+| 函数 ID                      | **平台分类** | 功能         | 参数                                                               |
 | ---------------------------- | ------------ | ------------ | ------------------------------------------------------------------ |
 | profit.fn.get_summary        | **总览分析** | 利润总览     | start_date, end_date, cost_center_id（可选）                       |
 | profit.fn.yoy_analysis       | **趋势分析** | 同比分析     | start_date, end_date, pl_category（可选）                          |
@@ -517,22 +519,22 @@ s.tables.add_relationship(
 | 12 | define_property（约 42 个） |
 | 13 | define_link_type（10 种） |
 | 14 | sync_metric_refs |
-| 15 | **CATEGORY_REGISTRY** + `s.categories.apply_registry`（347 对齐） |
 
-### 7.4 阶段四：函数与数据（中）
+### 7.4 阶段四：灌数、函数与分类（中）
 
 | 步骤 | 任务 |
 | ---- | ---- |
-| 15 | profit_ontology_init.py、profit_seed_data.py（含 dim_date / date_key） |
-| 16 | 7 个 profit_fn_*.py |
-| 17 | publish + run → save-test-arguments |
+| 15 | seed 灌数：**dim_date** + 维表 + fact（写入 date_key） |
+| 16 | 7 个 `profit_fn_*.py`：**publish --register-function-id** |
+| 17 | `function run` + **`save-test-arguments`** |
+| 18 | **`profit_category_mount.py`**：`CATEGORY_REGISTRY` + `apply_registry`（**最后**，类灌数） |
 
-### 7.5 快速实施路径
+### 7.5 实施阶段参考（须 plans 已定稿后）
 
-| 来源                                                       | 可复用内容                        | 需改造                         |
-| ---------------------------------------------------------- | --------------------------------- | ------------------------------ |
-| `资源/examples/onto/利润示例/` | init/seed/函数完整示例 | 复制到 `<item-path>/` 后改 `<space-id>` |
-| [规划示例：产品销售](./规划示例_产品销售本体规划方案.md) | 工程模式对照 | 表结构与函数逻辑不同 |
+| 来源 | 用途 | 注意 |
+| ---- | ---- | ---- |
+| `资源/examples/onto/利润示例/` | 对照 API 写法或复制后按 **本实现 plans** 改造 | **禁止**无 plans 直接复制 init |
+| [规划示例：产品销售](./规划示例_产品销售本体规划方案.md) | 跨域工程模式只读对照 | 表结构与函数逻辑不同 |
 
 **seed 数据建议**：
 
@@ -566,7 +568,7 @@ s.tables.add_relationship(
 | **表间关系** | **8 条** |
 | Cube | **5 个** + 派生度量 |
 | 对象 | 6 种 + 分类；10 种链接 |
-| **347 平台分类** | 侧栏分类名与附录 B 一致；`category_mounts` 非空 |
+| **平台侧栏分类** | 侧栏分类名与附录 B 一致；`category_mount` 重跑幂等 |
 | 函数 | get_summary、budget_vs_actual、account_breakdown 可运行 |
 | 数据         | 种子灌入后预实差异可解释                                |
 
@@ -586,13 +588,13 @@ s.tables.add_relationship(
 
 ---
 
-## 附录 B：347 分类挂载对照表（CATEGORY_REGISTRY）
+## 附录 B：平台分类挂载对照表（CATEGORY_REGISTRY）
 
-与 `利润示例/setup/profit_ontology_init.py` 顶部 **`CATEGORY_REGISTRY`** 一一对应（见 [349 方案](./本体分类规划与SDK扩展方案.md)）。
+与 `利润示例/setup/profit_category_mount.py` 顶部 **`CATEGORY_REGISTRY`** 一一对应（见 [本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)）。**init 不含分类挂载**；本附录在 **全部函数 publish 后** 由 `category_mount` 脚本执行。
 
 ### B.1 物理表（table）
 
-| 347 分类 | 表名 |
+| 平台分类 | 表名 |
 | -------- | ---- |
 | 维度表 | dim_account, dim_cost_center |
 | 事实表 | fact_gl_journal_entry, fact_budget_entry |
@@ -601,14 +603,14 @@ s.tables.add_relationship(
 
 ### B.2 Cube（cube）
 
-| 347 分类 | Cube |
+| 平台分类 | Cube |
 | -------- | ---- |
 | 流程型 | ActualCube, BudgetCube |
 | 主体型 | AccountActualCube, CostCenterActualCube, TimeActualCube |
 
 ### B.3 对象类型（object）
 
-| 347 分类 | code |
+| 平台分类 | code |
 | -------- | ---- |
 | 主数据 | Account, CostCenter |
 | 事务 | JournalEntry, BudgetLine |
@@ -616,7 +618,7 @@ s.tables.add_relationship(
 
 ### B.4 表间关系（relation）
 
-| 347 分类 | 从表 → 到表 |
+| 平台分类 | 从表 → 到表 |
 | -------- | ----------- |
 | 时间关联 | fact_gl_journal_entry → dim_date；fact_budget_entry → dim_date |
 | 主数据关联 | fact_gl_journal_entry → dim_account / dim_cost_center；fact_budget_entry → dim_account / dim_cost_center |
@@ -624,7 +626,7 @@ s.tables.add_relationship(
 
 ### B.5 链接类型（link）
 
-| 347 分类 | link code |
+| 平台分类 | link code |
 | -------- | --------- |
 | 归属关系 | entry_belongs_account, entry_belongs_cost_center, budget_for_account, budget_for_cost_center |
 | 分析归因 | analysis_by_account, analysis_by_cost_center, account_contributes_profit, cost_center_contributes_profit |
@@ -633,9 +635,9 @@ s.tables.add_relationship(
 
 ### B.6 本体函数（function）
 
-init **不**注册函数；`apply_registry(..., skip_missing=True)` 跳过未发布函数。建议分类：
+函数在 `functions/` 中 **publish 注册**；`profit_category_mount.py` 在 **init + seed + 全部函数 publish 之后** 统一 `apply_registry`（含 function 段，`skip_missing=True` 可重跑）。建议分类：
 
-| 347 分类 | function_id |
+| 平台分类 | function_id |
 | -------- | ----------- |
 | 总览分析 | profit.fn.get_summary |
 | 趋势分析 | profit.fn.yoy_analysis, profit.fn.mom_analysis |
@@ -658,7 +660,7 @@ init **不**注册函数；`apply_registry(..., skip_missing=True)` 跳过未发
 | 4 | Cube 层 | ☑（**5 个**，§4.0） |
 | 5 | 对象 + 分类 | ☑（§5.1、§5.4） |
 | 6–10 | 同指南 | ☑ |
-| 6a–6e | 347 平台分类 | ☑（附录 B + init 步骤 10） |
+| 6a–6e | 平台侧栏分类 | ☑（附录 B + `profit_category_mount.py`） |
 
 ---
 
@@ -670,11 +672,11 @@ init **不**注册函数；`apply_registry(..., skip_missing=True)` 跳过未发
 | 本体规划指南 | [本体规划指南.md](./本体规划指南.md) |
 | 规划示例（产品销售） | [规划示例_产品销售本体规划方案.md](./规划示例_产品销售本体规划方案.md) |
 | **内置脚本示例** | `资源/examples/onto/利润示例/`（`dazi examples sync`；表名迁移中） |
-| 349 · 分类方案 | [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md) |
+| 分类方案 | [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md) |
 
 ---
 
-**方案版本**：v2.2（+347 分类列与附录 B CATEGORY_REGISTRY）  
+**方案版本**：v2.3（分类挂载迁至 `profit_category_mount.py`，类灌数）  
 **创建日期**：（定稿日）  
 **适用**：复制到 `<item-path>/plans/`；`<space-id>` 以该实现单元 `README.md` 为准  
 **状态**：规划示例（公共模板）

package/dist/examples/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.9",
+  "version": "3.1.0",
   "updatedAt": "2026-06-05T18:00:00.000Z",
   "examples": [
     {