generate-analytics-star-schema

生成 CDS 分析星型架构

生成 CDS 分析模型——一个星型架构，由立方体视图（@Analytics.dataCategory: #CUBE）、一个或多个维度视图（#DIMENSION）和文本视图（#TEXT）组成，基于 RAP 业务对象或普通 DDIC 表构建。

此技能结合 ARC-1（SAP 系统访问）和 mcp-sap-docs（文档与最佳实践），复现 SAP Joule 的“CDS 分析模型生成”功能（基础范围 + 扩展范围）。基础范围 = 立方体 + 复用现有维度。扩展范围 = 还可生成新维度，并从 DDIC 表开始（不仅限于 RAP BO）。

前提条件 — 请先阅读

• 需要带有分析注解的 SAP_BASIS 7.5x。 使用 SAPManage(action="probe")（rap.available）进行验证。如果 RAP/CDS 不可用，请停止。
• 输出是一组相互依赖的 CDS 视图（立方体 → 维度 → 文本）。必须先创建为非激活草稿，再一起激活，以便 SAP 激活器一次性解析交叉引用。本技能正是为此使用 SAPWrite(action="batch_create", activateAtEnd: true)。

智能默认值（静默应用，不要询问）

设置	默认值	原因
对象类型	DDLS	立方体/维度/文本都是 CDS 数据定义
包	$TMP	快速原型设计；使用可传输包前请先询问
激活	batch_create + activateAtEnd: true	在一次最终传递中解析交叉引用
授权	#NOT_REQUIRED（立方体/维度）	分析接口视图的标准设置
命名	ZI_<X>_Cube、ZI_<X>_Dim、ZI_<X>_Txt	清晰表示星型架构中的角色（与模板使用的大小写一致）

输入

用户提供以下任一项：

• RAP 业务对象根实体 / 行为池（例如 ZBP_R_TRAVEL 或 ZI_Travel），或
• DDIC 表（例如 ZTRAVEL），或
• 用作事实数据源的接口 CDS 视图。

可选：指定哪些数值字段是度量、哪些字段是维度、目标包，以及生成新维度视图还是复用现有视图。

第 1 步：解析并读取数据源

1a. RAP BO 输入 — 查找绑定的 CDS 根实体

如果用户指定了行为池类（ZBP_*），请读取类元数据，查找其绑定的根实体：

SAPRead(type="CLAS", name="<ZBP_class>", format="structured")

查找绑定的根实体引用。然后读取该 CDS 根实体（下一步）。如果用户已指定 CDS 根实体 / 接口视图，请跳到 1c。

1b. DDIC 表输入 — 读取表结构

SAPRead(type="TABL", name="<table>")

记录包含类型的字段列表。识别候选键、维度字段（外键、特征）和数值度量字段（金额、数量、计数）。

1c. CDS 视图输入 — 读取数据源和元素

SAPRead(type="DDLS", name="<view>")
SAPRead(type="DDLS", name="<view>", include="elements")

元素列表会对字段进行分类。请逐一判断：

• 度量：数值型、可累加（金额 / 数量 / 计数）→ 在立方体中使用 @Aggregation.default: #SUM
• 维度：用于切片分析的特征（区域、客户、日期）→ 复用现有维度视图，或生成新视图
• 币种/计量单位：与每个金额/数量度量配对

第 2 步：发现可复用的维度

对于每个维度字段，在生成新视图前，先检查是否已有可复用的维度视图：

SAPSearch(query="*<dimension_keyword>*", searchType="object", objectType="DDLS")

如果存在已发布的 #DIMENSION 视图（例如 I_Country、I_CalendarDate），请通过关联复用。否则生成新的 ZI_<X>_DIM（扩展范围）。

步骤 3：查找当前分析注解

依据当前文档生成：

search("CDS analytical model cube Analytics.dataCategory CUBE dimension representativeKey")
search("ObjectModel.foreignKey.association text association Semantics.text")

在摘要中引用文档 ID。关键事实（7.58）：

• Cube：@Analytics: { dataCategory: #CUBE, internalName: #LOCAL } + @ObjectModel: { supportedCapabilities: [ #ANALYTICAL_PROVIDER ], modelingPattern: #ANALYTICAL_CUBE }
• Cube 至少需要 1 个度量；度量带有 @Aggregation.default: #SUM（或 #MIN/#MAX/#AVG）；没有 @Aggregation.default 的数值字段会被视为维度
• Cube→维度关联必须为 [1..1]；@ObjectModel.foreignKey.association: '_Dim' 应放在 Cube 中的维度键字段上
• 维度：@Analytics.dataCategory: #DIMENSION + @ObjectModel: { representativeKey: '<key>', supportedCapabilities: [ #ANALYTICAL_DIMENSION ], modelingPattern: #ANALYTICAL_DIMENSION }
• 文本视图使用 @ObjectModel.dataCategory: #TEXT（ObjectModel. 命名空间——不是 @Analytics.dataCategory）+ @Semantics.text: true + @Semantics.language: true

步骤 4：编写模型

Cube 模板

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: 'Sales Cube'
@Analytics: {
  dataCategory: #CUBE,
  internalName: #LOCAL
}
@ObjectModel: {
  supportedCapabilities: [ #ANALYTICAL_PROVIDER ],
  modelingPattern: #ANALYTICAL_CUBE
}
define view entity ZI_Sales_Cube
  as select from zsales_data
  association [1..1] to ZI_Region_Dim as _Region
    on _Region.RegionId = $projection.RegionId
{
      @ObjectModel.foreignKey.association: '_Region'
  key region_id   as RegionId,
  key calyear     as CalendarYear,

      @Semantics.amount.currencyCode: 'CurrencyCode'
      @Aggregation.default: #SUM
      amount       as SalesAmount,

      currency     as CurrencyCode,

      @Aggregation.default: #SUM
      @EndUserText.label: 'Number of Records'
      abap.int8'1' as RecordCount,

      _Region
}

维度模板

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: 'Region Dimension'
@Analytics.dataCategory: #DIMENSION
@ObjectModel: {
  representativeKey: 'RegionId',
  supportedCapabilities: [ #ANALYTICAL_DIMENSION ],
  modelingPattern: #ANALYTICAL_DIMENSION
}
define view entity ZI_Region_Dim
  as select from zregion
  association [0..1] to ZI_Region_Txt as _Text
    on _Text.RegionId = $projection.RegionId
{
      @ObjectModel.text.association: '_Text'
  key region_id as RegionId,
      _Text
}

文本视图模板

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: 'Region - Text'
@ObjectModel.dataCategory: #TEXT
@ObjectModel.representativeKey: 'RegionId'
define view entity ZI_Region_Txt
  as select from zregion_t
{
  key region_id as RegionId,

      @Semantics.language: true
  key spras     as Language,

      @Semantics.text: true
      regiontext  as RegionName
}

（文本视图独立存在——它不声明关联，因此不带 @ObjectModel.foreignKey.association。链接是单向的：维度通过 _Text + @ObjectModel.text.association 关联到此文本视图，而不是反过来。）

组合规则（编写前必须遵守）：

• Cube 至少有 1 个度量（@Aggregation.default）。
• 每个金额度量都有 @Semantics.amount.currencyCode，且投影了货币字段；每个数量度量都有 @Semantics.quantity.unitOfMeasure，且投影了计量单位字段。
• 每个 Cube→维度关联都是 [1..1]，且维度键字段带有 @ObjectModel.foreignKey.association。
• 每个维度都有 representativeKey。
• 文本视图使用 @ObjectModel.dataCategory: #TEXT + @Semantics.text/language。

步骤 5：先以树形结构展示计划，再批量创建

写入前向用户展示模型树：

Cube: ZI_Sales_Cube  (from zsales_data)
  Measures: SalesAmount (SUM, currency CurrencyCode), RecordCount (SUM)
  Dimensions:
    ZI_Region_Dim (new) → ZI_Region_Txt (new)

确认后，使用延迟激活一次性创建所有视图，以便交叉引用能够一起解析：

SAPWrite(action="batch_create", activateAtEnd=true, objects=[
  { type: "DDLS", name: "ZI_Region_Txt",  source: "<text_ddl>",      package: "$TMP" },
  { type: "DDLS", name: "ZI_Region_Dim",  source: "<dimension_ddl>", package: "$TMP" },
  { type: "DDLS", name: "ZI_Sales_Cube",  source: "<cube_ddl>",      package: "$TMP" }
])

按依赖优先级排序数组（文本 → 维度 → Cube），这样即使在较旧版本中 activateAtEnd 回退为逐个对象激活，依赖链仍能正确解析。使用 activateAtEnd: true 时，ARC-1 会将这三个对象都写入为非活动草稿，并对整个依赖图执行一次最终激活。

如果未能按预期使用带 activateAtEnd 的 batch_create（较旧版本），则回退为：使用 SAPWrite(action="create", ...) 创建每个对象，然后对所有已创建对象执行一次 SAPActivate(objects=[...])。

步骤 6：验证

SAPRead(type="DDLS", name="ZI_Sales_Cube", include="elements")

确认 Cube 已上线，且其维度关联和度量均已解析。

步骤 7：提供查询层

Cube 是基础；最终用户实际使用的是查询。提供以下选项：

“要我在此 Cube 上生成分析查询（可供使用的 KPI 视图）吗？→ generate-cds-analytical-query”

错误处理

错误	原因	修复方法
Cube 没有度量	所有数值字段都被视为维度	至少为一个数值字段添加 @Aggregation.default: #SUM
关联基数错误	Cube→维度关联不是 [1..1]	将基数改为 [1..1]
foreignKey.association 位置错误	注解放在了关联上，而不是键字段上	将其移到 Cube 中的维度键字段上
文本视图被拒绝	为 #TEXT 使用了 @Analytics.dataCategory，而不是 @ObjectModel.dataCategory	文本视图使用 ObjectModel 命名空间
交叉引用未解析	同级对象尚不存在时就逐个激活了对象	使用带 activateAtEnd: true 的 batch_create
缺少代表键	维度没有 representativeKey	添加 @ObjectModel.representativeKey

说明

• 基础范围与扩展范围： 基础范围 = 重用现有维度（步骤 2 查找已发布的 #DIMENSION 视图）。扩展范围 = 还会生成新的 ZI_*_DIM + ZI_*_TXT，并接受将 DDIC 表用作事实源（步骤 1b）。
• 此技能用于构建模型；可供使用的查询是单独的步骤（generate-cds-analytical-query）。
• 对于事务型 RAP 服务（非分析型），请使用 generate-rap-service。
• 如果存在 SAP 标准维度（I_CalendarDate、I_Country、I_Currency），请重用，而不是重新生成——在步骤 2 中使用 SAPSearch。