/manage-biz-entity

name: manage-biz-entity
description: |-
  管理 Dataphin 业务实体（业务对象/业务活动）的查询、创建、更新、上线、下线、删除。
  当用户要管理业务实体、业务对象、业务活动，或进行维度/事实/汇总逻辑建模前的业务模型配置时进入。
  触发词：业务实体、业务对象、业务活动、biz entity、biz object、biz process、BIZ_OBJECT、BIZ_PROCESS、维度建模、事实建模。
  关键限制：--type 决定 JSON 分支；BIZ_OBJECT 用 --biz-object，BIZ_PROCESS 用 --biz-process；JSON 字段必须使用 OpenAPI PascalCase；写操作需 HITL 确认。

业务实体管理 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](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 > > ```bash > 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](https://ram.console.aliyun.com/manage/ak) > 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](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 策略](../../ram-policies.md)。

> **[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）前必须向用户确认以下参数，禁止静默提交：

| 参数 | 必填 | 描述 | 默认值 | |---|---|---|---| | `--tenant-id` | 是 | 租户 ID（大整数，**字符串传**） | — | | `--biz-unit-id` | 是（create/update/online/offline/delete） | 所属数据板块（业务单元）ID | — | | `--data-domain-id` | 是（create/update） | 所属主题域 ID | — | | `--biz-entity-id` | 是（get/update/online/offline/delete/by-version） | 目标业务实体 ID | — | | `--type` | 是 | 业务实体大类：`BIZ_OBJECT` 或 `BIZ_PROCESS` | — | | `--biz-object` | BIZ_OBJECT 创建/更新时是 | 业务对象 JSON；仅当 `--type BIZ_OBJECT` 使用 | — | | `--biz-process` | BIZ_PROCESS 创建/更新时是 | 业务活动 JSON；仅当 `--type BIZ_PROCESS` 使用 | — | | `--comment` | 是（online/offline） | 上线/下线备注 | — | | `--version-id` | 是（by-version） | 业务实体版本 ID | — |

7. Observability (MUST follow for every aliyun command)

**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/manage-biz-entity/{session-id}

Example (assuming session-id is `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`):

aliyun dataphin-public list-biz-entities --tenant-id "1234567890123456789" \
  --user-agent AlibabaCloud-Agent-Skills/manage-biz-entity/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

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/manage-biz-entity/$SESSION_ID"

# 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" --f