# 公共维度查询与写入

公共维度用于把多个数据集中的同一业务维度字段关联起来，让跨指标、跨数据集的适用维度能够按同一逻辑维度对齐。

## 命令入口

```bash
guancli metric public-dim list [keyword]
guancli metric public-dim get <public_dim_id>
guancli metric public-dim fd-map <ds_id>
guancli metric public-dim create --file /tmp/public_dim.json --dry-run
guancli metric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json
guancli metric public-dim owner <public_dim_id> --business-owner <user_id>
guancli metric public-dim delete <public_dim_id>
guancli metric public-dim delete <public_dim_id> --confirm
```

`public-dim` 也可写成 `public-dimension` 或 `pubdim`。

## 通用原则

- 默认使用当前已登录环境，不询问 profile；只有用户明确指定其它环境时才追加 `--profile <profile>`。
- 用户只给公共维度名称时，先用 `guancli metric public-dim list <keyword>` 搜索候选。
- 用户只给数据集/字段中文名时，先用 `guancli ds search`、`guancli ds get <dsId> --brief` 查询 `dsId` 和 `fdId`。
- 新建/编辑前先生成 JSON，并用 `--dry-run` 或人工摘要让用户确认。
- 公共维度删除是不可恢复操作，必须先做依赖检查，再让用户确认。

## 查询

列表：

```bash
guancli metric public-dim list 日期 --limit 50 --offset 0 --order-by utimeDesc
```

详情：

```bash
guancli metric public-dim get <public_dim_id>
```

查询某个数据集字段是否已被公共维度占用：

```bash
guancli metric public-dim fd-map <ds_id>
```

`fd-map` 返回 `fdId -> { id, name }`，用于新建/编辑公共维度时避免选择已被其它公共维度使用的字段。

## 新建/编辑入参

| 字段 | 中文 | 说明 |
| --- | --- | --- |
| `name` | 公共维度名称 | 必填；最长 50；仅支持中文、字母、数字、下划线 |
| `businessOwner` | 责任人 ID | 必填；公共维度业务侧解释对象 |
| `relatedFields` | 关联的数据集字段 | 必填，至少一个；元素为 `{ "dsId": "...", "fdId": "..." }` |

`relatedFields` 规则：

- 每个元素都必须同时有 `dsId` 和 `fdId`。
- 同一个公共维度里的字段类型必须兼容/相同；后端会校验，不同类型会失败。
- Web 会禁用已被其它公共维度使用的字段；CLI 创建前应对每个涉及的数据集调用 `fd-map`，发现字段已归属其它公共维度时先向用户说明并重新选择。
- 同一个公共维度内不要重复选择同一数据集的同一字段。

## JSON 模板

```json
{
  "name": "日期",
  "businessOwner": "<user_id>",
  "relatedFields": [
    { "dsId": "<ds_id_1>", "fdId": "<date_fd_id_1>" },
    { "dsId": "<ds_id_2>", "fdId": "<date_fd_id_2>" }
  ]
}
```

## 新建流程

1. 收集公共维度名称、责任人、要关联的数据集字段。
2. 对每个数据集运行 `guancli ds get <dsId> --brief` 核对字段存在和字段类型。
3. 对每个数据集运行 `guancli metric public-dim fd-map <dsId>`，确认字段未被其它公共维度使用。
4. 生成 JSON 文件并 dry-run：

```bash
guancli metric public-dim create --file /tmp/public_dim.json --dry-run
```

5. 向用户摘要名称、责任人、关联字段、字段类型；用户确认后提交：

```bash
guancli metric public-dim create --file /tmp/public_dim.json
```

## 编辑流程

1. 先获取详情：

```bash
guancli metric public-dim get <public_dim_id>
```

2. 基于现有详情生成 patch 或完整 JSON。默认 `edit` 会把详情转换成提交 payload 后合并 patch。
3. 如果修改关联字段，重新检查字段类型和 `fd-map` 占用。
4. dry-run：

```bash
guancli metric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json --dry-run
```

5. 用户确认后提交：

```bash
guancli metric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json
```

只转移责任人时可用：

```bash
guancli metric public-dim owner <public_dim_id> --business-owner <user_id>
```

## 删除流程

删除前先执行依赖检查：

```bash
guancli metric public-dim delete <public_dim_id>
```

该命令会调用：

```text
GET /api/metric-platform/public-dimensions/depend-check/<public_dim_id>
```

如果返回 `isDepended=true`，说明已有指标在使用该公共维度。Web 的行为是提示“删除后将影响有公共维度的指标计算准确性”，用户确认后仍允许删除。

用户明确确认后执行：

```bash
guancli metric public-dim delete <public_dim_id> --confirm
```

提交删除接口：

```text
POST /api/metric-platform/public-dimensions/delete/<public_dim_id>
```

不要把“依赖检查通过/已提示风险”描述成已经删除成功；只有 delete 接口成功返回后才算删除完成。