业务实体管理 Skill

1. Scenario Description

在 Dataphin 数据规划 / 数据资产建设中对「业务实体（Biz Entity）」做全生命周期管理。业务实体用于描述数据仓库逻辑模型中的核心业务概念，主要分为两类：

• 业务对象（BIZ_OBJECT）：用于承载对象类实体，如客户、商品、门店，通常用于维度逻辑表建模。
• 业务活动（BIZ_PROCESS）：用于承载事件/快照/流程类实体，如下单、支付、发货，通常用于事实逻辑表与指标建模。

业务实体必须挂在「数据板块（BizUnit）」与「主题域（DataDomain）」之下。因此 --biz-unit-id 与 --data-domain-id 是创建、更新的硬前置依赖。

本 Skill 覆盖业务实体的查询、创建、修订、上线、下线、删除和按版本查询。与主题域不同，业务实体存在上线/下线生命周期：创建后通常先处于开发/草稿态，需要 online-biz-entity 后才能作为建模对象被下游使用。

Architecture：Dataphin Tenant → BizUnit（数据板块）→ DataDomain（主题域）→ BizEntity（BIZ_OBJECT / BIZ_PROCESS）→ 维度/事实/汇总逻辑表

涉及 Dataphin OpenAPI

• ListBizEntities — 查询业务实体列表
• GetBizEntityInfo — 获取业务实体详情
• GetBizEntityInfoByVersion — 按版本获取业务实体详情
• CreateBizEntity — 创建业务实体
• UpdateBizEntity — 更新业务实体
• OnlineBizEntity — 上线业务实体
• OfflineBizEntity — 下线业务实体
• DeleteBizEntity — 删除业务实体

2. Installation

aliyun plugin install --names aliyun-cli-dataphin-public

各操作系统一键安装脚本与版本要求详见 references/cli-installation-guide.md。

3. Environment Variables

凭证与环境变量由父 skill alibabacloud-dataphin-skills 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志）
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

Pre-check: Aliyun CLI >= 3.4.8 required

Run aliyun version to verify >= 3.4.8. If not installed or version too low, install/update from https://aliyuncli.alicdn.com (see references/cli-installation-guide.md for the OS-specific script).

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

5. RAM Policy

最小权限策略详见 套件级 RAM 策略。

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read ../../ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

6. Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

执行任何写操作（create / update / online / offline / delete）前必须向用户确认以下参数，禁止静默提交：

7. Observability (MUST follow for every aliyun command)

版本 {version}（Shell 变量 SKILL_VERSION）来自套件 references/manifest.json 的 version 字段，与 session-id 一同继承父技能 §7。直接加载本子技能时先完成父层初始化；所有 CLI / SDK 调用使用父技能名称与同一版本，跨 Shell 调用须重新注入这些值。

session-id 由父 skill alibabacloud-dataphin-skills 在套件入口加载时生成（32-char 小写 hex），本子 skill 加载时直接继承同一 session-id，不再重新生成。

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag. Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

Example (assuming session-id is a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6):

aliyun dataphin-public list-biz-entities --tenant-id "1234567890123456789" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 skill-version/{version}"

Do not skip, alter the format, or omit --user-agent on any aliyun API command invocation.

8. Core Workflow

TENANT_ID="<大整数租户 ID，字符串>"
BIZ_UNIT_ID="<所属数据板块 ID>"
DATA_DOMAIN_ID="<所属主题域 ID>"
SESSION_ID="<inherited from alibabacloud-dataphin-skills>"
UA="AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/$SESSION_ID skill-version/$SKILL_VERSION"

# 0) 前置：确认数据板块与主题域已存在。业务实体必须同时挂在 biz-unit 与 data-domain 下。
#    若不知道 data-domain-id，可先使用 manage-topic-domain 的 list-data-domains 反查。

# 1) 查询业务实体列表（定位是否已存在，避免重复创建）
aliyun dataphin-public list-biz-entities --tenant-id "$TENANT_ID" \
  --keyword "<业务实体编码/展示名关键字>" \
  --filter-criteria '{"BizUnitIdList":["<数据板块 ID>"],"DataDomainIdList":["<主题域 ID>"]}' \
  --page 1 --page-size 10 \
  --user-agent "$UA" --format json

# 2) 查看某个业务实体详情
aliyun dataphin-public get-biz-entity-info --tenant-id "$TENANT_ID" \
  --type "BIZ_OBJECT" \
  --biz-entity-id "<业务实体 ID>" \
  --user-agent "$UA" --format json

# 3A) 创建业务对象（BIZ_OBJECT）：如客户、商品、门店，用于维度建模
aliyun dataphin-public create-biz-entity --tenant-id "$TENANT_ID" \
  --biz-unit-id "$BIZ_UNIT_ID" \
  --data-domain-id "$DATA_DOMAIN_ID" \
  --type BIZ_OBJECT \
  --biz-object '{"Name":"<业务对象编码>","DisplayName":"<业务对象展示名>","Type":"NORMAL","OwnerUserId":"<负责人用户ID>","Description":"<描述>"}' \
  --user-agent "$UA" --format json

# 3B) 创建业务活动（BIZ_PROCESS）：如交易下单、支付，用于事实建模/指标建模
aliyun dataphin-public create-biz-entity --tenant-id "$TENANT_ID" \
  --biz-unit-id "$BIZ_UNIT_ID" \
  --data-domain-id "$DATA_DOMAIN_ID" \
  --type BIZ_PROCESS \
  --biz-process '{"Name":"<业务活动编码>","DisplayName":"<业务活动展示名>","Type":"BIZ_EVENT","OwnerUserId":"<负责人用户ID>","Description":"<描述>"}' \
  --user-agent "$UA" --format json

# 4) 上线业务实体（创建后如需被下游建模使用，通常需要上线）
aliyun dataphin-public online-biz-entity --tenant-id "$TENANT_ID" \
  --biz-unit-id "$BIZ_UNIT_ID" \
  --type "BIZ_OBJECT" \
  --biz-entity-id "<业务实体 ID>" \
  --comment "<上线备注>" \
  --user-agent "$UA" --format json

# 5) 更新业务实体（注意：按类型回填完整 JSON，关联列表不回填会被清空）
aliyun dataphin-public update-biz-entity --tenant-id "$TENANT_ID" \
  --biz-unit-id "$BIZ_UNIT_ID" \
  --data-domain-id "$DATA_DOMAIN_ID" \
  --biz-entity-id "<业务实体 ID>" \
  --type BIZ_OBJECT \
  --biz-object '{"Name":"<业务对象编码>","DisplayName":"<新展示名>","Type":"NORMAL","OwnerUserId":"<负责人用户ID>","Description":"<新描述>","RefBizEntityIdList":[]}' \
  --user-agent "$UA" --format json

# 6) 下线业务实体
aliyun dataphin-public offline-biz-entity --tenant-id "$TENANT_ID" \
  --biz-unit-id "$BIZ_UNIT_ID" \
  --type "BIZ_OBJECT" \
  --biz-entity-id "<业务实体 ID>" \
  --comment "<下线备注>" \
  --user-agent "$UA" --format json

# 7) 删除业务实体（不可回滚；删除前必须先确认无逻辑表/指标依赖）
aliyun dataphin-public delete-biz-entity --tenant-id "$TENANT_ID" \
  --biz-unit-id "$BIZ_UNIT_ID" \
  --type "BIZ_OBJECT" \
  --biz-entity-id "<业务实体 ID>" \
  --user-agent "$UA" --format json

类型分支：BIZ_OBJECT（业务对象）

用于描述对象类实体，如客户、商品、门店。创建/更新时传 --type BIZ_OBJECT，并传 --biz-object JSON。

类型分支：BIZ_PROCESS（业务活动）

用于描述事件/快照/流程类实体，如下单、支付、发货。创建/更新时传 --type BIZ_PROCESS，并传 --biz-process JSON。

字段语义速查

执行前确认（写操作必备 / HITL）

本 skill 的 create / update / online / offline / delete 均为写操作，执行前必须向用户二次确认：

• 即将执行的命令全文（脱敏后）
• 影响范围（哪个 tenant / biz-unit / data-domain / 业务实体）
• 是否可回滚（delete 不可回滚；update 可能清空未回填的关联列表）
• 替代方案（可先用 --cli-dry-run 只打印请求不实际调用；可先 list/get 反查）

仅当用户明确回复「确认 / yes / 执行」后才发起写命令。

9. Success Verification

写操作「同步返回 Code: OK」不等于业务生效，需按动作做反查校验（详见 references/acceptance-criteria.md）：

1. create/update：同步响应含 Code: OK，再用 list-biz-entities 按 keyword + filter 反查，或 get-biz-entity-info 按 ID 回读字段。
2. online/offline：上线/下线可能存在异步状态变化，需 list-biz-entities / get-biz-entity-info 轮询确认状态字段变化。
3. delete：删除后 get-biz-entity-info 应查不到或返回空；若存在逻辑表/指标依赖，服务端可能拒绝删除，需先清理下游依赖。

# 反查确认（创建/更新后按 biz-unit + data-domain + keyword 过滤）
aliyun dataphin-public list-biz-entities --tenant-id "$TENANT_ID" \
  --keyword "<业务实体编码>" \
  --filter-criteria '{"BizUnitIdList":["<数据板块 ID>"],"DataDomainIdList":["<主题域 ID>"]}' \
  --user-agent "$UA" --format json

10. Cleanup

# 删除业务实体（不可回滚，需二次确认；删除前先 get/list 确认目标和依赖）
aliyun dataphin-public delete-biz-entity --tenant-id "$TENANT_ID" \
  --biz-unit-id "$BIZ_UNIT_ID" \
  --type "BIZ_OBJECT" \
  --biz-entity-id "<业务实体 ID>" \
  --user-agent "$UA" --format json

删除前须确认业务实体未被维度逻辑表、事实逻辑表、汇总逻辑表、指标或其它业务实体依赖，否则服务端可能拒绝删除。必要时先 offline-biz-entity，再执行删除。

11. Command Tables

详见 references/related-commands.md。

12. Best Practices + Reference Links

1. 大整数 ID（tenant-id / biz-unit-id / data-domain-id / biz-entity-id / version-id）一律字符串传参。
2. 写操作（create/update/online/offline/delete）必须执行前 HITL 二次确认。
3. --type 与 JSON 分支必须一致：BIZ_OBJECT 只传 --biz-object；BIZ_PROCESS 只传 --biz-process。
4. --biz-object / --biz-process 内字段必须使用 OpenAPI PascalCase（如 DisplayName、OwnerUserId），不要使用页面内部 REST 字段名。
5. update 前先 get-biz-entity-info 回读现值，尤其是 RefBizEntityIdList；未回填的关联列表会被清空。
6. 「常见坑」每条标来源 [Agent 自主发现] / [人工注入]。

常见坑

[Agent 自主发现] OpenAPI JSON 字段与页面内部 REST 字段不同

• 现象：页面内部接口常见字段为 cn / owner / bizObjectType=1，但 OpenAPI metadata 要求 DisplayName / OwnerUserId / Type=NORMAL。
• 结论：外部 skill 必须以 OpenAPI metadata 为准，--biz-object / --biz-process 使用 PascalCase 字段。

[Agent 自主发现] update-biz-entity 会清空未回填的关联列表

• 现象：OpenAPI metadata 明确标注 RefBizEntityIdList 在 update 时「若不填写：原有的值会被清空」。
• 结论：更新前必须先 get 回读并确认关联列表，若要保留关联，必须在 JSON 中完整回填。

[Agent 自主发现] online-biz-entity 的 comment 描述写成“下线备注”

• 现象：online-biz-entity --help 与 metadata 中 --comment 文案均显示为“下线备注”，但上线命令同样必填该字段。
• 结论：这是文案复用，不影响使用；上线时仍传上线备注。

Reference Links

• references/cli-installation-guide.md
• 套件级 RAM 策略
• references/acceptance-criteria.md
• references/related-commands.md