@dazitech/cli 3.0.7 → 3.0.8

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

@@ -0,0 +1,497 @@
+# 规划示例 · 产品销售本体方案
+
+**文档 ID**: `onto/planning-example-product-sales`
+
+> **推荐**：本体规划阶段**首选参考示例**。覆盖物理表、**表间关系**、Cube、本体链接、函数与 **test_arguments** 完整落地；对应可运行脚本见 `项目/潘达石化/本体/ontos/产品销售本体方案/`。  
+> 补充示例（利润分析域）：[规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md)
+
+---
+
+## 一、空间概述
+
+| 项目     | 说明                                       |
+| -------- | ------------------------------------------ |
+| 空间 ID  | `space__zlj`                               |
+| 空间名称 | 数据空间zlj                                |
+| 空间状态 | 空白空间（无表、无 Cube、无本体）          |
+| 规划日期 | 2026-06-05                                 |
+| 实现单元 | `项目/潘达石化/本体/ontos/产品销售本体方案/` |
+
+---
+
+## 二、需求分析
+
+### 2.1 业务背景
+
+潘达石化产品销售场景，需构建**产品销售本体**，以业务语言描述「产品」「销售订单」及其关系，支撑：
+
+- 按产品大类、SKU 的销售量与销售额分析
+- 按区域、客户类型、渠道的销售分布
+- 同比、环比趋势与 Top N 产品排行
+- 客户分层与渠道结构分析
+
+### 2.2 核心业务问题
+
+| 问题           | 说明                         |
+| -------------- | ---------------------------- |
+| 卖了多少       | 销量、销售额、订单数         |
+| 哪些产品卖得好 | 产品排行、品类结构、动销 SKU |
+| 谁在买         | 客户/区域贡献、客户分层      |
+| 通过什么渠道卖 | 直销/经销/电商等渠道占比     |
+| 趋势如何       | 同比、环比、季节性           |
+
+### 2.3 规划范围说明
+
+**核心物理表（本方案重点）**：
+
+| 表名               | 中文名       | 角色                         |
+| ------------------ | ------------ | ---------------------------- |
+| `product_master`   | **产品表**   | 产品主数据（维表）           |
+| `sales_order_fact` | **销售表**   | 销售订单/订单行事实（事实表）|
+
+**辅助维表（支撑销售表外键语义，建议同期建设）**：
+
+| 表名                 | 中文名     | 角色               |
+| -------------------- | ---------- | ------------------ |
+| `customer_dimension` | 客户维表   | 购买方主数据       |
+| `channel_dimension`  | 渠道维表   | 销售渠道主数据     |
+
+> 规划原则：先定义**业务对象**（Product、SalesOrder 等）与**链接**，再反推物理表；产品表与销售表是读模型的根基，维表避免销售表中出现无法解释的裸 ID。
+
+---
+
+## 三、物理层设计
+
+### 3.1 产品表：product_master
+
+**用途**：存储可售产品（油品、化工品等）主数据，供销售表关联与产品分析。
+
+**表结构**：
+
+| 字段名               | 类型     | 说明           | 主键/索引 |
+| -------------------- | -------- | -------------- | --------- |
+| product_id           | String   | 产品 ID        | PK        |
+| product_code         | String   | 产品编码       |           |
+| product_name         | String   | 产品名称       |           |
+| product_category     | String   | 产品大类       |           |
+| product_subcategory  | String   | 产品小类       |           |
+| brand                | String   | 品牌/牌号      |           |
+| unit                 | String   | 计量单位（吨等）|          |
+| list_price           | Float64  | 挂牌价         |           |
+| cost_price           | Float64  | 成本单价       |           |
+| status               | String   | 状态（在售/停售）|         |
+| created_at           | DateTime | 创建时间       |           |
+| updated_at           | DateTime | 更新时间       |           |
+
+**排序键**：`ORDER BY (product_id)`  
+**引擎**：`MergeTree()`
+
+### 3.2 销售表：sales_order_fact
+
+**用途**：存储订单行粒度销售流水，是 Cube 与 SalesOrder 对象的主要事实来源。
+
+**表结构**：
+
+| 字段名           | 类型    | 说明                         | 主键/索引 |
+| ---------------- | ------- | ---------------------------- | --------- |
+| order_id         | String  | 订单 ID                      |           |
+| order_line_id    | String  | 订单行 ID                    | PK 组合   |
+| order_date       | Date    | 订单日期                     |           |
+| product_id       | String  | 产品 ID → product_master     | FK 语义   |
+| product_category | String  | 产品大类（冗余，便于聚合）   |           |
+| customer_id      | String  | 客户 ID                      |           |
+| customer_region  | String  | 销售区域                     |           |
+| customer_type    | String  | 客户类型（战略/VIP/普通）    |           |
+| channel_id       | String  | 渠道 ID                      |           |
+| quantity         | Int32   | 销售数量                     |           |
+| unit_price       | Float64 | 成交单价                     |           |
+| discount_amount  | Float64 | 折扣金额                     |           |
+| sales_amount     | Float64 | 销售金额（扣折后）           |           |
+| currency         | String  | 币种                         |           |
+| order_status     | String  | 订单状态（已完成/已发货等）  |           |
+
+**排序键**：`ORDER BY (order_date, order_id, order_line_id)`  
+**引擎**：`MergeTree()`
+
+**业务规则**：
+
+- 分析类函数默认过滤 `order_status IN ('已完成', '已发货')`
+- `sales_amount` 为行级实收，与 `quantity * unit_price - discount_amount` 口径一致
+
+### 3.3 辅助维表（建议同期创建）
+
+#### customer_dimension（客户维表）
+
+| 字段名          | 类型     | 说明     |
+| --------------- | -------- | -------- |
+| customer_id     | String   | 客户 ID  |
+| customer_code   | String   | 客户编码 |
+| customer_name   | String   | 客户名称 |
+| customer_region | String   | 销售区域 |
+| customer_type   | String   | 客户类型 |
+| industry        | String   | 所属行业 |
+| created_at      | DateTime | 创建时间 |
+
+#### channel_dimension（渠道维表）
+
+| 字段名       | 类型   | 说明     |
+| ------------ | ------ | -------- |
+| channel_id   | String | 渠道 ID  |
+| channel_code | String | 渠道编码 |
+| channel_name | String | 渠道名称 |
+| channel_type | String | 渠道类型 |
+
+### 3.4 表间关系设计（物理层 · 数据空间）
+
+> **与本体链接的区别**：本节描述 **ClickHouse 物理表之间的 FK/JOIN 关系**，写入数据空间 `ads_dataspace_relationships`，供侧栏 **数据资源 → 表间关系** 展示，并支撑流程节点多表 JOIN、AI 读空间上下文。  
+> **本体层链接**（第五节 `define_link_type`）描述业务对象语义，二者应 **一一对应、分层不混用**。
+
+**关系模型（星型）**：以 **销售表** `sales_order_fact` 为事实表，关联三张维表。
+
+```text
+                    product_master
+                   (product_id PK)
+                          ▲
+                          │ many_to_one
+                          │
+customer_dimension ◄──────┼──────► channel_dimension
+(customer_id PK)          │         (channel_id PK)
+         ▲                │
+         │ many_to_one    │
+         │                │
+         └──── sales_order_fact ────┘
+              (order_line 粒度)
+```
+
+**关系清单（3 条）**：
+
+| 关系 ID（建议）     | 类型        | 从表（事实）       | 到表（维表）         | join_keys                              | 说明                 |
+| ------------------- | ----------- | ------------------ | -------------------- | -------------------------------------- | -------------------- |
+| rel_sales_product   | many_to_one | sales_order_fact   | product_master       | product_id → product_id                | 订单行关联产品       |
+| rel_sales_customer  | many_to_one | sales_order_fact   | customer_dimension   | customer_id → customer_id              | 订单行关联客户       |
+| rel_sales_channel   | many_to_one | sales_order_fact   | channel_dimension    | channel_id → channel_id                | 订单行关联销售渠道   |
+
+**join_sql 示例**（init 脚本中 `s.tables.add_relationship` 使用）：
+
+| 关系               | join_sql                                                              |
+| ------------------ | --------------------------------------------------------------------- |
+| rel_sales_product  | `sales_order_fact.product_id = product_master.product_id`             |
+| rel_sales_customer | `sales_order_fact.customer_id = customer_dimension.customer_id`     |
+| rel_sales_channel  | `sales_order_fact.channel_id = channel_dimension.channel_id`        |
+
+**实施 API**（`setup/sales_ontology_init.py`，表注册之后、Cube 注册之前）：
+
+```python
+s.tables.add_relationship(
+    from_table="sales_order_fact",
+    to_table="product_master",
+    join_sql="sales_order_fact.product_id = product_master.product_id",
+    join_keys=[{"from": "product_id", "to": "product_id"}],
+    relationship_type="many_to_one",
+    description="销售订单行关联产品主数据",
+)
+```
+
+**不建关系的字段说明**：
+
+| 字段               | 原因                                       |
+| ------------------ | ------------------------------------------ |
+| product_category   | 事实表冗余列，非独立维表 FK                |
+| customer_region    | 事实表冗余列，与 customer_dimension 重复   |
+| customer_type      | 事实表冗余列，与 customer_dimension 重复   |
+
+**与本体链接对照**：
+
+| 物理表关系           | 对应本体链接（业务层）   |
+| -------------------- | ------------------------ |
+| rel_sales_product    | order_contains_product   |
+| rel_sales_customer   | order_belongs_customer   |
+| rel_sales_channel    | order_via_channel        |
+
+---
+
+## 四、Cube 层设计
+
+所有 Cube 均以 **销售表** `sales_order_fact` 为事实源；产品表通过 JOIN 或维度冗余参与产品名称等展示（函数层 SQL 可 LEFT JOIN `product_master`）。
+
+### 4.1 SalesCube（销售分析主 Cube）
+
+**目的**：全局销售分析、SalesOrder / SalesAnalysis 读模型
+
+**维度**：order_id, order_line_id, order_date, product_id, product_category, customer_id, customer_region, customer_type, channel_id
+
+**度量**：
+
+| 度量名      | 列名             | 聚合  | 说明     |
+| ----------- | ---------------- | ----- | -------- |
+| quantity    | quantity         | sum   | 销售数量 |
+| sales_amount| sales_amount     | sum   | 销售金额 |
+| discount    | discount_amount  | sum   | 折扣金额 |
+| order_count | order_id         | uniq  | 订单数   |
+| line_count  | order_line_id    | uniq  | 订单行数 |
+
+**派生度量**：
+
+| 度量名          | 表达式                                              | 说明     |
+| --------------- | --------------------------------------------------- | -------- |
+| avg_unit_price  | if(quantity>0, sales_amount/quantity, 0)            | 平均单价 |
+| avg_order_value | if(order_count>0, sales_amount/order_count, 0)      | 客单价   |
+
+### 4.2 ProductSalesCube（产品销售 Cube）
+
+**目的**：Product 对象 bind_source；按产品聚合
+
+**维度**：product_id, product_category
+
+**度量**：quantity, sales_amount, order_count
+
+**派生度量**：avg_unit_price
+
+### 4.3 CustomerSalesCube（客户销售 Cube）
+
+**维度**：customer_id, customer_region, customer_type
+
+**度量**：quantity, sales_amount, order_count
+
+**派生度量**：avg_order_value
+
+### 4.4 ChannelSalesCube（渠道销售 Cube）
+
+**维度**：channel_id
+
+**度量**：quantity, sales_amount, order_count
+
+### 4.5 TimeSalesCube（时间维度 Cube）
+
+**维度**：order_date, year_month, quarter, year
+
+**度量**：sales_amount, quantity, order_count
+
+---
+
+## 五、本体层设计
+
+### 5.1 对象类型（5 种）
+
+| 对象类型 code  | 名称     | 说明                     | bind_source       |
+| -------------- | -------- | ------------------------ | ----------------- |
+| Product        | 产品     | 可售产品业务对象         | ProductSalesCube  |
+| Customer       | 客户     | 购买方业务对象           | CustomerSalesCube |
+| SalesChannel   | 销售渠道 | 渠道业务对象             | ChannelSalesCube  |
+| SalesOrder     | 销售订单 | 订单/订单行业务对象      | SalesCube         |
+| SalesAnalysis  | 销售分析 | 多维度销售指标聚合对象   | SalesCube         |
+
+> 对象类型 `code` 使用稳定英文标识，与表名、Cube 名刻意区分。
+
+### 5.2 对象属性（摘要）
+
+#### Product（产品）— 读模型来自 ProductSalesCube + 产品表补全名称（函数层）
+
+| 属性 code      | 名称       | semantic_role | qualified_name                    |
+| -------------- | ---------- | ------------- | --------------------------------- |
+| id             | 产品 ID    | dimension     | ProductSalesCube.product_id       |
+| category       | 产品大类   | dimension     | ProductSalesCube.product_category |
+| quantity       | 累计销量   | measure       | ProductSalesCube.quantity         |
+| sales_amount   | 累计销售额 | measure       | ProductSalesCube.sales_amount     |
+| order_count    | 订单数     | measure       | ProductSalesCube.order_count      |
+| avg_unit_price | 平均单价   | measure       | ProductSalesCube.avg_unit_price   |
+
+#### SalesOrder（销售订单）
+
+| 属性 code    | 名称     | semantic_role | qualified_name           |
+| ------------ | -------- | ------------- | ------------------------ |
+| id           | 订单 ID  | dimension     | SalesCube.order_id       |
+| line_id      | 订单行   | dimension     | SalesCube.order_line_id  |
+| date         | 订单日期 | dimension     | SalesCube.order_date     |
+| quantity     | 数量     | measure       | SalesCube.quantity       |
+| sales_amount | 销售金额 | measure       | SalesCube.sales_amount   |
+| unit_price   | 成交单价 | measure       | SalesCube.avg_unit_price |
+
+#### Customer / SalesChannel / SalesAnalysis
+
+与 `本体01/setup/sales_ontology_init.py` 中属性映射一致（共约 29 个属性），实施时可复用该脚本结构，仅将 `space_id` 改为 `space__zlj`。
+
+### 5.3 链接类型（8 种）
+
+| 链接 code              | 名称           | from          | to            | 说明                 |
+| ---------------------- | -------------- | ------------- | ------------- | -------------------- |
+| order_contains_product | 订单包含产品   | SalesOrder    | Product       | 订单行对应产品       |
+| order_belongs_customer | 订单归属客户   | SalesOrder    | Customer      | 订单归属客户         |
+| order_via_channel      | 订单经渠道成交 | SalesOrder    | SalesChannel  | 订单销售渠道         |
+| product_has_orders     | 产品有订单     | Product       | SalesOrder    | 产品被哪些订单购买   |
+| customer_places_orders | 客户下单       | Customer      | SalesOrder    | 客户历史订单         |
+| analysis_by_product    | 分析归因产品   | SalesAnalysis | Product       | 指标按产品切片       |
+| analysis_by_customer   | 分析归因客户   | SalesAnalysis | Customer      | 指标按客户切片       |
+| analysis_by_channel    | 分析归因渠道   | SalesAnalysis | SalesChannel  | 指标按渠道切片       |
+
+---
+
+## 六、本体函数设计
+
+### 6.1 函数清单
+
+| 函数 ID                           | 功能         | 参数                                              |
+| --------------------------------- | ------------ | ------------------------------------------------- |
+| sales.fn.get_summary              | 销售总览     | start_date, end_date（可选）                      |
+| sales.fn.yoy_analysis             | 同比分析     | start_date, end_date                              |
+| sales.fn.mom_analysis             | 环比分析     | start_date, end_date                              |
+| sales.fn.top_products             | 产品排行     | limit, metric, start_date, end_date               |
+| sales.fn.customer_segmentation    | 客户分层     | metric, method, start_date, end_date              |
+| sales.fn.region_breakdown         | 区域销售分布 | start_date, end_date                              |
+| sales.fn.channel_mix              | 渠道结构     | start_date, end_date                              |
+
+### 6.2 函数示例：sales.fn.get_summary
+
+**功能**：指定时间范围内销售总览
+
+**返回值**：
+
+| 字段名          | 类型    | 说明         |
+| --------------- | ------- | ------------ |
+| total_sales     | Float64 | 总销售额     |
+| total_quantity  | Int     | 总销量       |
+| order_count     | Int     | 订单数       |
+| avg_order_value | Float64 | 客单价       |
+| product_count   | Int     | 动销 SKU 数  |
+
+### 6.3 函数示例：sales.fn.top_products
+
+**功能**：按销售额或销量 Top N；JOIN **产品表** 补全 product_name
+
+**参数**：limit（默认 10）, metric（sales_amount / quantity）, start_date, end_date
+
+**返回值**：rank, product_id, product_name, product_category, sales_amount, quantity, share_pct
+
+> 参考实现：`项目/潘达石化/本体/ontos/产品销售本体方案/functions/sales_fn_*.py`。
+
+### 6.4 测试参数（test_arguments）
+
+发布并验证函数后，**必须**将默认测试入参写入函数定义，供侧栏 **Onto → 运行函数** 预填。
+
+| 函数 ID | test_arguments 文件 | 默认 arguments |
+| ------- | --------------------- | -------------- |
+| sales.fn.get_summary | `functions/test_arguments/sales.fn.get_summary.json` | start_date, end_date |
+| sales.fn.yoy_analysis | `.../sales.fn.yoy_analysis.json` | 同上 |
+| sales.fn.mom_analysis | `.../sales.fn.mom_analysis.json` | 同上 |
+| sales.fn.top_products | `.../sales.fn.top_products.json` | limit=5, metric=sales_amount, 日期 |
+| sales.fn.customer_segmentation | `.../sales.fn.customer_segmentation.json` | metric, method=quartile, 日期 |
+| sales.fn.region_breakdown | `.../sales.fn.region_breakdown.json` | 日期 |
+| sales.fn.channel_mix | `.../sales.fn.channel_mix.json` | 日期 |
+
+批量入库（dazi-work 根）：
+
+```powershell
+.\项目\潘达石化\本体\ontos\产品销售本体方案\functions\save_test_arguments.ps1
+```
+
+JSON 格式须含 `v`、`arguments`、`object_type_code`（与平台函数定义一致）；各 `.py` 内 `TEST_ARGUMENTS` 常量与 JSON **保持同步**。
+
+---
+
+## 七、实施计划
+
+> **dazi-vscode v3** · 空间 `space__zlj` · 脚本目录 `setup/`、`functions/`  
+> 发布示例：  
+> `dazi onto script publish 项目/潘达石化/本体/ontos/产品销售本体方案/setup/sales_ontology_init.py --space space__zlj --type setup`
+
+### 7.1 阶段一：物理层（高）
+
+| 步骤 | 任务                    | 说明                          |
+| ---- | ----------------------- | ----------------------------- |
+| 1    | 创建 product_master     | **产品表**                    |
+| 2    | 创建 sales_order_fact   | **销售表**                    |
+| 3    | 创建 customer_dimension | 客户维表                      |
+| 4    | 创建 channel_dimension  | 渠道维表                      |
+| 5    | 注册表到空间            | `s.tables.register` + sync    |
+| 6    | **注册表间关系（3 条）**| `s.tables.add_relationship`   |
+
+### 7.2 阶段二：Cube 层（高）
+
+| 步骤 | 任务                                              |
+| ---- | ------------------------------------------------- |
+| 7    | 注册 SalesCube / ProductSalesCube 等 5 个 Cube    |
+| 8    | 配置派生度量 avg_unit_price、avg_order_value      |
+
+### 7.3 阶段三：本体层（高）
+
+| 步骤 | 任务                                                         |
+| ---- | ------------------------------------------------------------ |
+| 9    | define_object_type（5 种）                                   |
+| 10   | bind_source                                                  |
+| 11   | define_property（约 29 个）                                  |
+| 12   | define_link_type（8 种）                                     |
+| 13   | sync_metric_refs                                             |
+
+### 7.4 阶段四：函数与数据（中）
+
+| 步骤 | 任务                                                                 |
+| ---- | -------------------------------------------------------------------- |
+| 14   | 从 `本体01/functions/sales_fn_*.py` 复制并适配到本实现 `functions/` |
+| 15   | `sales_seed_data.py` 灌入演示数据（产品表 + 销售表 + 维表）          |
+| 16   | publish + run 验证                                                   |
+| 17   | **`save-test-arguments`** 写入各函数 `test_arguments`（侧栏预填；见 §6.4） |
+
+### 7.5 快速实施路径
+
+本仓库 **`本体01/setup/sales_ontology_init.py`** 已包含完整 init 逻辑，建议：
+
+1. 复制 `sales_ontology_init.py`、`sales_seed_data.py` → `产品销售本体方案/setup/`
+2. 将 `space_id = "space__0519"` 改为 `"space__zlj"`
+3. 按 [快速启动_产品销售本体方案.md](../快速启动_产品销售本体方案.md) 发布执行
+
+---
+
+## 八、风险与验收
+
+### 8.1 风险
+
+| 等级 | 风险               | 缓解措施                     |
+| ---- | ------------------ | ---------------------------- |
+| 中   | 空间为空，无现网表 | 按本方案建表或对接 ERP 导数  |
+| 低   | 产品表与销售表口径 | 种子数据脚本统一生成         |
+| 低   | 函数与 Cube 不同步 | init 末尾 `sync_metric_refs` |
+
+### 8.2 验收标准
+
+| 验收项   | 标准                                      |
+| -------- | ----------------------------------------- |
+| 产品表   | product_master 可查询，字段完整           |
+| 销售表   | sales_order_fact 可查询，与产品 ID 可关联 |
+| **表间关系** | **3 条**（事实表 → 产品/客户/渠道维表） |
+| Cube     | 5 个 Cube 注册成功，派生度量可算          |
+| 对象类型 | 5 种对象 + 8 种链接定义正确               |
+| 函数     | 至少 get_summary、top_products 可运行     |
+| **test_arguments** | 各 function_id 已 `save-test-arguments`，`function get` 中 **非 null** |
+| 数据     | 种子数据灌入后指标与手工 SQL 一致           |
+
+---
+
+## 九、预期成果
+
+| 分析能力   | 说明                           |
+| ---------- | ------------------------------ |
+| 产品销售   | SKU/品类销量、销售额、排行     |
+| 客户价值   | 区域分布、客户分层             |
+| 渠道结构   | 各渠道销售占比                 |
+| 趋势分析   | 同比、环比                     |
+| 业务语义   | 产品—订单—客户—渠道链接可导航  |
+
+---
+
+## 十、相关文档
+
+| 文档 | 路径 |
+| ---- | ---- |
+| 本体规划指南 | [本体规划指南.md](./本体规划指南.md) |
+| 本体脚本编写指南 | [本体脚本编写指南.md](./本体脚本编写指南.md) |
+| 函数开发 | [function-guide.md](./function-guide.md) |
+| 参考实现（init/seed/函数） | `项目/潘达石化/本体/ontos/产品销售本体方案/setup/`、`functions/` |
+| **内置脚本示例** | `资源/examples/onto/销售示例/`（`dazi examples sync` 后复制到实现单元） |
+| 补充示例（利润） | [规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md) · `资源/examples/onto/利润示例/` |
+
+---
+
+**方案版本**：v1.1  
+**创建日期**：2026-06-05  
+**适用空间**：`space__zlj`  
+**状态**：已落地（规划 + 脚本 + test_arguments）