@dazitech/cli 3.0.7 → 3.0.9

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,620 @@
+# 规划示例 · 产品销售本体方案
+
+**文档 ID**: `onto/planning-example-product-sales`
+
+> **推荐**：本体规划阶段**首选参考示例**。覆盖物理表、**表间关系**、Cube、本体链接、函数与 **test_arguments** 完整落地；表/Cube/对象命名遵循 [本体命名规范](./本体命名规范_物理表Cube与对象.md)。  
+> 补充示例（利润分析域）：[规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md)
+
+**占位符**（复制到工作区 `plans/` 后替换为实际值）：
+
+| 占位符 | 含义 | 权威来源 |
+| ------ | ---- | -------- |
+| `<space-id>` | 数据空间 ID | `项目/<业务名>/本体/ontos/<实现名>/README.md` |
+| `<业务名>` | 业务项目目录名 | 工作区 `项目/` 下文件夹 |
+| `<实现名>` | 本体实现单元名 | 如 `产品销售本体方案` |
+| `<item-path>` | 实现单元根路径 | `项目/<业务名>/本体/ontos/<实现名>` |
+
+---
+
+## 一、空间概述
+
+| 项目     | 说明 |
+| -------- | ---- |
+| 空间 ID  | `<space-id>`（示例：`space__acme`） |
+| 空间名称 | `<空间名称>`（与平台数据空间显示名一致） |
+| 空间状态 | 空白空间（无表、无 Cube、无本体）或已有他域表共存 |
+| 规划日期 | （填写定稿日期） |
+| 实现单元 | `<item-path>/` |
+
+---
+
+## 二、需求分析
+
+### 2.1 业务背景
+
+某制造企业（示例）产品销售场景，需构建**产品销售本体**，以业务语言描述「产品」「销售订单」及其关系，支撑：
+
+- 按产品大类、SKU 的销售量与销售额分析
+- 按区域、客户类型、渠道的销售分布
+- 同比、环比趋势与 Top N 产品排行
+- 客户分层与渠道结构分析
+
+### 2.2 核心业务问题
+
+| 问题           | 说明                         |
+| -------------- | ---------------------------- |
+| 卖了多少       | 销量、销售额、订单数         |
+| 哪些产品卖得好 | 产品排行、品类结构、动销 SKU |
+| 谁在买         | 客户/区域贡献、客户分层      |
+| 通过什么渠道卖 | 直销/经销/电商等渠道占比     |
+| 趋势如何       | 同比、环比、季节性           |
+
+### 2.3 规划范围说明
+
+**物理表清单**（命名见 [命名规范 §2](./本体命名规范_物理表Cube与对象.md#2-物理表类别与前缀)）：
+
+| 表名 | 前缀类别 | **347 分类** | 显示名 | 说明 | 角色 |
+| ---- | -------- | ------------ | ------ | ---- | ---- |
+| **`dim_date`** | 时间维（**强制**） | **时间维** | 日期维表 | 全空间共享；PK **`date_key`** | 时间维 |
+| `dim_product` | dim | **维度表** | 产品维表 | 可售产品主数据 | dim |
+| `dim_customer` | dim | **维度表** | 客户维表 | 购买方主数据 | dim |
+| `dim_channel` | dim | **维度表** | 渠道维表 | 销售渠道主数据 | dim |
+| **`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` 步骤对齐。
+
+---
+
+## 三、物理层设计
+
+### 3.0 时间维：dim_date（强制）
+
+**用途**：全空间共享日历；事实表通过 **`date_key`** 关联；Cube 时间维与 YoY/MoM 函数优先基于本表。
+
+| 字段名 | 类型 | 显示名 | 说明 |
+| ------ | ---- | ------ | ---- |
+| **date_key** | Int32 | 日期键 | YYYYMMDD，主键 |
+| calendar_date | Date | 自然日 | |
+| year | Int16 | 公历年 | |
+| quarter | Int8 | 季度 | 1–4 |
+| month | Int8 | 月 | 1–12 |
+| week_of_year | Int8 | 周 | |
+| day_of_week | Int8 | 星期 | |
+| is_weekend | UInt8 | 是否周末 | 0/1 |
+| year_month | String | 年月 | 如 2025-06 |
+
+**排序键**：`ORDER BY (date_key)` · **引擎**：`MergeTree()`
+
+### 3.1 维度表：dim_product
+
+**用途**：可售产品（油品、化工品等）主数据。
+
+| 字段名 | 类型 | 显示名 | 说明 |
+| ------ | ---- | ------ | ---- |
+| product_id | String | 产品 ID | 主键 |
+| 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)`
+
+### 3.2 事实表：fact_sales_order_line
+
+**用途**：订单行粒度销售流水；Cube 与 SalesOrder 对象的主事实源。
+
+| 字段名 | 类型 | 显示名 | 说明 |
+| ------ | ---- | ------ | ---- |
+| order_id | String | 订单 ID | |
+| order_line_id | String | 订单行 ID | 主键组合 |
+| **date_key** | Int32 | 日期键 | 关联 dim_date |
+| order_date | Date | 订单日期 | |
+| product_id | String | 产品 ID | 关联 dim_product |
+| product_category | String | 产品大类 | 冗余 |
+| customer_id | String | 客户 ID | 关联 dim_customer |
+| customer_region | String | 销售区域 | 冗余 |
+| customer_type | String | 客户类型 | 冗余 |
+| channel_id | String | 渠道 ID | 关联 dim_channel |
+| quantity | Int32 | 销售数量 | |
+| unit_price | Float64 | 成交单价 | |
+| discount_amount | Float64 | 折扣金额 | |
+| sales_amount | Float64 | 销售金额 | |
+| currency | String | 币种 | |
+| order_status | String | 订单状态 | |
+
+**排序键**：`ORDER BY (date_key, order_id, order_line_id)`
+
+**业务规则**：
+
+- 灌数：`date_key = toYYYYMMDD(order_date)`
+- 分析默认过滤 `order_status IN ('已完成', '已发货')`
+- `sales_amount` 与 `quantity * unit_price - discount_amount` 口径一致
+
+### 3.3 维度表：dim_customer、dim_channel
+
+#### dim_customer
+
+| 字段名 | 类型 | 显示名 | 说明 |
+| ------ | ---- | ------ | ---- |
+| customer_id | String | 客户 ID | 主键 |
+| customer_code | String | 客户编码 | |
+| customer_name | String | 客户名称 | |
+| customer_region | String | 销售区域 | |
+| customer_type | String | 客户类型 | |
+| industry | String | 所属行业 | |
+| created_at | DateTime | 创建时间 | |
+
+#### dim_channel
+
+| 字段名 | 类型 | 显示名 | 说明 |
+| ------ | ---- | ------ | ---- |
+| 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`）描述业务对象语义，二者应 **一一对应、分层不混用**。
+
+**关系模型（星型）**：以 **`fact_sales_order_line`** 为事实表，关联 **`dim_date`** 与三张业务维表。
+
+```text
+                         dim_date
+                        (date_key PK)
+                              ▲
+                              │ many_to_one
+                              │
+    dim_product ◄─────────────┼─────────────► dim_customer
+  (product_id PK)             │              (customer_id PK)
+         ▲                    │                    ▲
+         │                    │                    │
+         │         fact_sales_order_line          │
+         │              (order_line)              │
+         └──────────────────┼────────────────────┘
+                            │
+                            ▼
+                      dim_channel
+                     (channel_id PK)
+```
+
+**关系清单（5 条）**：
+
+| 关系 ID | **347 分类** | 类型 | 从表 | 到表 | 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 | 订单行关联产品 |
+| rel_sales_customer | **主数据关联** | many_to_one | fact_sales_order_line | dim_customer | customer_id → customer_id | 订单行关联客户 |
+| rel_sales_channel | **主数据关联** | many_to_one | fact_sales_order_line | dim_channel | channel_id → channel_id | 订单行关联渠道 |
+
+**join_sql 示例**：
+
+| 关系 | join_sql |
+| ---- | -------- |
+| rel_sales_date | `fact_sales_order_line.date_key = dim_date.date_key` |
+| rel_sales_product | `fact_sales_order_line.product_id = dim_product.product_id` |
+| rel_sales_customer | `fact_sales_order_line.customer_id = dim_customer.customer_id` |
+| rel_sales_channel | `fact_sales_order_line.channel_id = dim_channel.channel_id` |
+
+**实施 API**（`setup/sales_ontology_init.py`，表 register 之后、Cube 之前）：
+
+```python
+s.tables.add_relationship(
+    from_table="fact_sales_order_line",
+    to_table="dim_product",
+    join_sql="fact_sales_order_line.product_id = dim_product.product_id",
+    join_keys=[{"from": "product_id", "to": "product_id"}],
+    relationship_type="many_to_one",
+    description="销售订单行关联产品",
+)
+```
+
+**冗余列说明**（不单独建关系）：`product_category`、`customer_region`、`customer_type` 为事实表冗余，与维表字段重复便于聚合。
+
+**与本体链接对照**：
+
+| 物理表关系 | 对应本体链接 |
+| ---------- | ------------ |
+| rel_sales_product | order_contains_product |
+| rel_sales_customer | order_belongs_customer |
+| rel_sales_channel | order_via_channel |
+| rel_sales_date | （时间维，函数/Cube 层 JOIN，可无独立链接类型） |
+
+---
+
+## 四、Cube 层设计
+
+### 4.0 Cube 清单与类别
+
+| Cube | 类别 | **347 分类** | 事实源 | 时间维 | 支撑对象 |
+| ---- | ---- | ------------ | ------ | ------ | -------- |
+| **SalesCube** | Process | **流程型** | fact_sales_order_line | dim_date（year/month/quarter） | SalesOrder, SalesAnalysis |
+| **ProductSalesCube** | Subject | **主体型** | fact_sales_order_line | 同上 | Product |
+| **CustomerSalesCube** | Subject | **主体型** | fact_sales_order_line | 同上 | Customer |
+| **ChannelSalesCube** | Subject | **主体型** | fact_sales_order_line | 同上 | SalesChannel |
+
+> 时间智能 **不单独建 Cube**；`SalesCube` 维度含 `date_key` 及自 `dim_date` JOIN 的 `year`、`month`、`year_month`、`quarter`（见 [命名规范 §4.2](./本体命名规范_物理表Cube与对象.md#42-cube-类别)）。
+
+所有 Cube 均以 **`fact_sales_order_line`** 为事实源；产品名称等可在函数 SQL 中 LEFT JOIN **`dim_product`**。
+
+### 4.1 SalesCube（Process · 销售分析主 Cube）
+
+**目的**：全局销售分析、SalesOrder / SalesAnalysis 读模型
+
+**维度**：order_id, order_line_id, date_key, order_date, year, month, year_month, quarter, 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（Subject · 产品销售）
+
+**目的**：Product 对象 bind_source；按产品聚合
+
+**维度**：product_id, product_category, year, month（来自 dim_date）
+
+**度量**：quantity, sales_amount, order_count
+
+**派生度量**：avg_unit_price
+
+### 4.3 CustomerSalesCube（Subject · 客户销售）
+
+**维度**：customer_id, customer_region, customer_type, year, month
+
+**度量**：quantity, sales_amount, order_count
+
+**派生度量**：avg_order_value
+
+### 4.4 ChannelSalesCube（Subject · 渠道销售）
+
+**维度**：channel_id, year, month
+
+**度量**：quantity, sales_amount, order_count
+
+---
+
+## 五、本体层设计
+
+### 5.1 对象类型（5 种）
+
+| code | 分类 | **347 分类** | 名称 | bind_source | 主物理支撑 |
+| ---- | ---- | ------------ | ---- | ------------- | ---------- |
+| Product | Master | **主数据** | 产品 | ProductSalesCube | dim_product |
+| Customer | Master | **主数据** | 客户 | CustomerSalesCube | dim_customer |
+| SalesChannel | Reference | **参考** | 销售渠道 | ChannelSalesCube | dim_channel |
+| SalesOrder | Transaction | **事务** | 销售订单 | SalesCube | fact_sales_order_line |
+| SalesAnalysis | Analytical | **分析** | 销售分析 | SalesCube | fact_sales_order_line |
+
+> 对象 **`code` 无前缀**（Palantir 式业务名）；分类写入规划表，不写入 `code`。详见 [命名规范 §5](./本体命名规范_物理表Cube与对象.md#5-本体对象palantir-思想与分类)。
+
+### 5.2 对象属性（摘要）
+
+#### Product（Master）
+
+| 属性 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（Transaction）
+
+| 属性 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
+
+与 `销售示例/setup/sales_ontology_init.py` 中属性映射一致（约 29 个属性）；实施时改 `space_id`，**表名按本规划**（脚本示例可能仍为旧表名，迁移中）。
+
+### 5.3 链接类型（8 种）
+
+| 链接 code              | **347 分类** | 名称           | 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  | 指标按渠道切片       |
+
+### 5.4 三层对照总表
+
+| 对象 code | 分类 | Cube | 主 fact / dim |
+| --------- | ---- | ---- | ------------- |
+| Product | Master | ProductSalesCube | dim_product |
+| Customer | Master | CustomerSalesCube | dim_customer |
+| SalesChannel | Reference | ChannelSalesCube | dim_channel |
+| SalesOrder | Transaction | SalesCube | fact_sales_order_line |
+| SalesAnalysis | Analytical | SalesCube | fact_sales_order_line |
+| （时间） | — | SalesCube 时间维 | dim_date |
+
+---
+
+## 六、本体函数设计
+
+### 6.1 函数清单
+
+| 函数 ID                           | **347 分类** | 功能         | 参数                                              |
+| --------------------------------- | ------------ | ------------ | ------------------------------------------------- |
+| 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 **`dim_product`** 补全 product_name
+
+**参数**：limit（默认 10）, metric（sales_amount / quantity）, start_date, end_date
+
+**返回值**：rank, product_id, product_name, product_category, sales_amount, quantity, share_pct
+
+> 参考实现：`资源/examples/onto/销售示例/functions/sales_fn_*.py`（复制到 `<item-path>/functions/`）。
+
+### 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
+.\<item-path>\functions\save_test_arguments.ps1
+```
+
+JSON 格式须含 `v`、`arguments`、`object_type_code`（与平台函数定义一致）；各 `.py` 内 `TEST_ARGUMENTS` 常量与 JSON **保持同步**。
+
+---
+
+## 七、实施计划
+
+> **dazi-vscode v3** · 空间 `<space-id>` · 脚本目录 `setup/`、`functions/`  
+> 发布示例：  
+> `dazi onto script publish <item-path>/setup/sales_ontology_init.py --space <space-id> --type setup`
+
+### 7.1 阶段一：物理层（高）
+
+| 步骤 | 任务 | 说明 |
+| ---- | ---- | ---- |
+| 1 | 创建 **dim_date** | 时间维（强制） |
+| 2 | 创建 dim_product | 产品维表 |
+| 3 | 创建 **fact_sales_order_line** | 含 **date_key** |
+| 4 | 创建 dim_customer、dim_channel | 业务维表 |
+| 5 | 注册表到空间 | **TABLE_REGISTRY** + `register_with_meta` |
+| 6 | **注册表间关系（4 条）** | 含 fact → dim_date |
+
+### 7.2 阶段二：Cube 层（高）
+
+| 步骤 | 任务 |
+| ---- | ---- |
+| 7 | 注册 SalesCube / ProductSalesCube 等 **4 个 Cube**（无独立 Time Cube） |
+| 8 | 配置派生度量；SalesCube 含 dim_date 时间维 |
+
+### 7.3 阶段三：本体层（高）
+
+| 步骤 | 任务                                                         |
+| ---- | ------------------------------------------------------------ |
+| 9    | define_object_type（5 种）                                   |
+| 10   | bind_source                                                  |
+| 11   | define_property（约 29 个）                                  |
+| 12   | define_link_type（8 种）                                     |
+| 13   | sync_metric_refs                                             |
+| 14   | **CATEGORY_REGISTRY** + `s.categories.apply_registry`（347 对齐） |
+
+### 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） |
+
+### 7.5 快速实施路径
+
+本仓库 **`资源/examples/onto/销售示例/setup/sales_ontology_init.py`** 含完整 init 逻辑（含 **`TABLE_REGISTRY`** 与 `register_with_meta`），与本文 §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) 发布执行
+
+---
+
+## 八、风险与验收
+
+### 8.1 风险
+
+| 等级 | 风险               | 缓解措施                     |
+| ---- | ------------------ | ---------------------------- |
+| 中   | 空间为空，无现网表 | 按本方案建表或对接 ERP 导数  |
+| 低   | 产品表与销售表口径 | 种子数据脚本统一生成         |
+| 低   | 函数与 Cube 不同步 | init 末尾 `sync_metric_refs` |
+
+### 8.2 验收标准
+
+| 验收项 | 标准 |
+| ------ | ---- |
+| dim_date | 可查询，**date_key** 连续覆盖 seed 日期范围 |
+| fact_sales_order_line | 可查询，**date_key** 与 dim_date 可 JOIN |
+| 维表 | dim_product / dim_customer / dim_channel 完整 |
+| 表/列元数据 | 侧栏与表预览显示名、说明与 §3.x 一致 |
+| **表间关系** | **4 条**（含 fact → dim_date） |
+| Cube | **4 个** Cube；SalesCube 含时间维 |
+| 对象类型 | 5 种 + 分类列；8 种链接 |
+| **347 平台分类** | 侧栏分类名与附录 B 一致；init 重跑幂等 |
+| 函数 | get_summary、top_products 可运行 |
+| test_arguments | 各 function_id 已 save-test-arguments |
+| 数据 | 种子灌入后指标与手工 SQL 一致 |
+
+---
+
+## 九、预期成果
+
+| 分析能力   | 说明                           |
+| ---------- | ------------------------------ |
+| 产品销售   | SKU/品类销量、销售额、排行     |
+| 客户价值   | 区域分布、客户分层             |
+| 渠道结构   | 各渠道销售占比                 |
+| 趋势分析   | 同比、环比                     |
+| 业务语义   | 产品—订单—客户—渠道链接可导航  |
+
+---
+
+## 附录 B：347 分类挂载对照表（CATEGORY_REGISTRY）
+
+与 `销售示例/setup/sales_ontology_init.py` 顶部 **`CATEGORY_REGISTRY`** 一一对应；平台 `category_name` **=** 347 标准中文名（见 [349 方案](./本体分类规划与SDK扩展方案.md)）。
+
+### B.1 物理表（table）
+
+| 347 分类 | 表名 |
+| -------- | ---- |
+| 时间维 | dim_date |
+| 维度表 | dim_product, dim_customer, dim_channel |
+| 事实表 | fact_sales_order_line |
+
+### B.2 Cube（cube）
+
+| 347 分类 | Cube |
+| -------- | ---- |
+| 流程型 | SalesCube |
+| 主体型 | ProductSalesCube, CustomerSalesCube, ChannelSalesCube |
+
+### B.3 对象类型（object）
+
+| 347 分类 | code |
+| -------- | ---- |
+| 主数据 | Product, Customer |
+| 参考 | SalesChannel |
+| 事务 | SalesOrder |
+| 分析 | SalesAnalysis |
+
+### 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 |
+| -------- | --------- |
+| 归属关系 | 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` 跳过。建议分类：
+
+| 347 分类 | function_id |
+| -------- | ----------- |
+| 总览分析 | sales.fn.get_summary |
+| 趋势分析 | sales.fn.yoy_analysis, sales.fn.mom_analysis |
+| 结构分析 | sales.fn.top_products, sales.fn.customer_segmentation, sales.fn.channel_mix |
+| 组织分析 | sales.fn.region_breakdown |
+
+---
+
+## 附录：规划完整性自检清单
+
+定稿前逐项勾选（完整说明见 [本体规划指南 · 规划文档完整性自检清单](./本体规划指南.md#规划文档完整性自检清单)）。
+
+| # | 检查项 | 本方案 |
+| - | ------ | ------ |
+| 1 | 业务场景 | ☑ |
+| 2 | 物理表 | ☑（dim_date + fact + 3 dim） |
+| 2a | dim_date / date_key | ☑（§3.0、§3.2） |
+| 2b | fact 含 date_key | ☑ |
+| 2c | 表前缀规范 | ☑（fact_/dim_） |
+| 3 | 表间关系 | ☑（**4 条**） |
+| 4 | Cube 层 | ☑（**4 个**，§4.0 含类别） |
+| 4a–4b | Cube 类别/命名 | ☑ |
+| 5 | 对象类型 | ☑（5 种 + 分类） |
+| 5a–5c | 对象分类/三层对照 | ☑（§5.1、§5.4） |
+| 6 | bind_source | ☑ |
+| 7 | 链接类型 | ☑（8 种） |
+| 8 | 函数清单 | ☑ |
+| 9 | test_arguments | ☑ |
+| 10 | 实施与验收 | ☑ |
+| 6a–6e | 347 平台分类 | ☑（附录 B + init 步骤 10） |
+
+---
+
+## 十、相关文档
+
+| 文档 | 路径 |
+| ---- | ---- |
+| 本体命名规范 | [本体命名规范_物理表Cube与对象.md](./本体命名规范_物理表Cube与对象.md) |
+| 本体规划指南 | [本体规划指南.md](./本体规划指南.md) |
+| 本体脚本编写指南 | [本体脚本编写指南.md](./本体脚本编写指南.md) |
+| 函数开发 | [function-guide.md](./function-guide.md) |
+| 参考实现（init/seed/函数） | `资源/examples/onto/销售示例/` → 复制到 `<item-path>/` |
+| **内置脚本示例** | `资源/examples/onto/销售示例/`（`dazi examples sync` 后复制到实现单元） |
+| 补充示例（利润） | [规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md) · `资源/examples/onto/利润示例/` |
+| 349 · 分类方案 | [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md) |
+
+---
+
+**方案版本**：v1.3（表/Cube/对象命名对齐 [命名规范](./本体命名规范_物理表Cube与对象.md)）  
+**创建日期**：（定稿日）  
+**适用**：复制到 `<item-path>/plans/`；`<space-id>` 以该实现单元 `README.md` 为准  
+**状态**：规划示例（公共模板）