377 lines
14 KiB
Markdown
377 lines
14 KiB
Markdown
# dashboard block data_config SSOT
|
||
|
||
Block 的 `data_config` 字段因 `type` 不同而变化。本文档是 dashboard block `data_config` 的单一事实来源（SSOT），包含组件类型、字段结构、筛选格式、约束和可复制模板。
|
||
|
||
## 支持的组件类型（`type` 枚举）
|
||
|
||
| type 值 | 说明 |
|
||
|---------|------|
|
||
| `column` | 柱状图 |
|
||
| `bar` | 条形图 |
|
||
| `line` | 折线图 |
|
||
| `pie` | 饼图 |
|
||
| `ring` | 环形图 |
|
||
| `area` | 面积图 |
|
||
| `combo` | 组合图 |
|
||
| `scatter` | 散点图 |
|
||
| `funnel` | 漏斗图 |
|
||
| `wordCloud` | 词云 |
|
||
| `radar` | 雷达图 |
|
||
| `statistics` | 指标卡 |
|
||
| `text` | 文本（支持 Markdown） |
|
||
|
||
## 字段类型与操作符速查（AI 决策用）
|
||
|
||
> 先用 `+field-list` / `+field-get` 确认字段 `type`；本节使用当前字段接口里的 canonical 类型名：`number`、`text`、`select`、`datetime`、`checkbox`、`user`。
|
||
|
||
```
|
||
text: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
|
||
number: is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty
|
||
select（multiple=false）: is, isNot, isEmpty, isNotEmpty
|
||
select（multiple=true）: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
|
||
datetime: is, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty
|
||
checkbox: is (value: true/false)
|
||
user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
|
||
```
|
||
|
||
## data_config 通用结构
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `table_name` | string | 关联数据表名称 |
|
||
| `series` | `[{ "field_name": "xxx", "rollup": "SUM" }]` | 指标/Y 轴（与 `count_all` 二选一）。rollup 支持 `SUM` / `MAX` / `MIN` / `AVERAGE` |
|
||
| `count_all` | boolean | COUNTA 聚合，统计所有记录数（与 `series` 二选一） |
|
||
| `group_by` | `[{ "field_name": "xxx", "mode": "integrated", "sort": {...} }]` | X 轴分组维度。`mode` 必填，`sort` 可选，见下方说明 |
|
||
| `filter` | object | 筛选条件 |
|
||
| `filter.conjunction` | `"and"` / `"or"` | 筛选逻辑 |
|
||
| `filter.conditions` | `[{ "field_name", "operator", "value" }]` | 筛选条件数组，value 类型因字段类型而异（见下方 filter 格式规则） |
|
||
|
||
### text 类型特殊结构
|
||
|
||
`text` 类型组件用于展示富文本内容，**不需要数据源配置**（无 `table_name`、`series`、`group_by`、`filter`）。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `text` | string | **必填**。支持 Markdown 语法，详见下方说明 |
|
||
|
||
**支持的 Markdown 语法：**
|
||
|
||
| 语法 | 示例 | 效果 |
|
||
|------|------|------|
|
||
| 一级标题 | `# 标题` | 大标题 |
|
||
| 二级标题 | `## 标题` | 中标题 |
|
||
| 三级标题 | `### 标题` | 小标题 |
|
||
| 加粗 | `**文字**` | **文字** |
|
||
| 斜体 | `*文字*` | *文字* |
|
||
| 删除线 | `~~文字~~` | ~~文字~~ |
|
||
| 有序列表 | `1. 项目` | 1. 项目 |
|
||
| 无序列表 | `- 项目` | - 项目 |
|
||
|
||
> **注意**：以上未提及的 Markdown 语法（如链接、图片、代码块、表格等）均不支持。
|
||
|
||
## group_by 详细说明
|
||
|
||
### mode 枚举
|
||
|
||
| mode | 含义 | 适用场景 |
|
||
|------|------|----------|
|
||
| `integrated` | 聚合分组（默认） | 绝大部分场景，按字段值分组统计 |
|
||
| `enumerated` | 多值拆分统计 | 多选、人员等多值字段，将每个选项/人员拆开独立统计 |
|
||
|
||
> 多选、人员等多值字段默认用 `enumerated`；其他字段默认用 `integrated`。
|
||
|
||
### sort 排序
|
||
|
||
| sort.type | 含义 | 典型场景 |
|
||
|-----------|------|----------|
|
||
| `group` | 按横轴值排序 | 按月份升序、按品类名字母序 |
|
||
| `value` | 按纵轴值排序 | 按销售额从大到小 |
|
||
| `view` | 按数据源记录顺序 | 保持原表行序（不常用） |
|
||
|
||
`sort.order`：`asc`（升序）/ `desc`（降序）
|
||
|
||
只要写 `sort` 对象，就需要明确排序方向。CLI 会把 `sort.type` 为 `group` 或 `view` 且缺少 `order` 的情况规范化为 `order:"asc"`；`sort.type:"value"` 必须显式写 `order:"asc"` 或 `order:"desc"`，因为指标值排序方向会改变业务含义。
|
||
|
||
如果表中行序就是业务顺序，首次创建 block 时就一次性设置 `sort:{"type":"view","order":"asc"}` 保留行序，避免创建后再二次更新排序条件。
|
||
|
||
示例 — 柱状图按销售额降序：
|
||
|
||
```json
|
||
{
|
||
"table_name": "订单表",
|
||
"series": [{ "field_name": "金额", "rollup": "SUM" }],
|
||
"group_by": [{ "field_name": "类别", "mode": "integrated", "sort": {"type": "value", "order": "desc"} }]
|
||
}
|
||
```
|
||
|
||
## filter 格式规则
|
||
|
||
**基本结构：**
|
||
|
||
```json
|
||
{
|
||
"filter": {
|
||
"conjunction": "and",
|
||
"conditions": [
|
||
{ "field_name": "字段名", "operator": "操作符", "value": "值" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**多条件示例（and/or）：**
|
||
|
||
```json
|
||
{
|
||
"filter": {
|
||
"conjunction": "and",
|
||
"conditions": [
|
||
{ "field_name": "状态", "operator": "is", "value": "已完成" },
|
||
{ "field_name": "金额", "operator": "isGreater", "value": 1000 }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**操作符：**
|
||
|
||
| 操作符 | 含义 | 是否需要 value |
|
||
|--------|------|---------------|
|
||
| `is` | 等于 | 是 |
|
||
| `isNot` | 不等于 | 是 |
|
||
| `contains` | 包含 | 是 |
|
||
| `doesNotContain` | 不包含 | 是 |
|
||
| `isEmpty` | 为空 | 否 |
|
||
| `isNotEmpty` | 不为空 | 否 |
|
||
| `isGreater` | 大于 | 是 |
|
||
| `isGreaterEqual` | 大于等于 | 是 |
|
||
| `isLess` | 小于 | 是 |
|
||
| `isLessEqual` | 小于等于 | 是 |
|
||
|
||
**各字段类型的 value 格式：**
|
||
|
||
| 字段类型 | value 类型 | 适用操作符 | 示例 |
|
||
|----------|-----------|-----------|------|
|
||
| `text` | string | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | `{"field_name":"姓名","operator":"contains","value":"张"}` |
|
||
| `number` | number | is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | `{"field_name":"金额","operator":"isGreater","value":0}` |
|
||
| `select` (`multiple=false`) | string（选项名） | is, isNot, isEmpty, isNotEmpty | `{"field_name":"状态","operator":"is","value":"已完成"}` |
|
||
| `select` (`multiple=true`) | string[]（选多个）/ string（选单个） | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | 多选传数组如 `["标签1","标签2"]`；单选传单个字符串 |
|
||
| `datetime` / `created_at` / `updated_at` | number（Unix 毫秒时间戳，13位） | is, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | `{"field_name":"创建日期","operator":"isGreater","value":1704038400000}` |
|
||
| `checkbox` | boolean | is | `{"field_name":"已审核","operator":"is","value":true}` |
|
||
| `user` / `created_by` / `updated_by` | string 或 string[]（用户 ID，格式 `ou_xxx`）。不知道 `open_id` 时先用 `lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user` 查 id。 | is, isNot, isEmpty, isNotEmpty | `{"field_name":"负责人","operator":"is","value":"ou_xxxxxxxxxxxxxxxx"}` |
|
||
| 所有类型（为空/不为空） | 不需要 value | isEmpty, isNotEmpty | `{"field_name":"备注","operator":"isEmpty"}` |
|
||
|
||
> `value` 类型为 `string | number | boolean | string[]`，需根据字段类型匹配正确格式
|
||
|
||
## 约束与本地校验
|
||
|
||
- 必填与互斥
|
||
- 图表类型必填：`table_name`
|
||
- text 类型必填：`text`
|
||
- 互斥：`series` 与 `count_all` 二选一，且至少提供其一（仅图表类型）
|
||
- text 类型**不支持**：`series`、`count_all`、`group_by`、`filter`
|
||
- 长度/结构
|
||
- `group_by` 最多 2 个；每项 `field_name` 必填
|
||
- `group_by[].sort.type` 取值 `group|value|view`；`order` 取值 `asc|desc`
|
||
- 规范化（CLI 自动处理；`--no-validate` 时不生效，`data_config` 原样透传给后端）
|
||
- `series[].rollup` 自动转成大写（如 `sum` → `SUM`）
|
||
- `group_by[].sort.type/order` 自动转成小写
|
||
- `group_by[].sort.type` 为 `group` 或 `view` 且缺少 `order` 时，自动补 `order:"asc"`；`value` 排序不会自动补方向
|
||
- 本地校验（可通过 `--no-validate` 跳过）
|
||
- `+dashboard-block-create` 默认对 `data_config` 做轻量校验；失败会聚合错误并给出修复建议
|
||
- `+dashboard-block-update` 不做强类型校验，由后端验证具体字段
|
||
- 仅需传入合法 JSON；CLI 不会擅自改写你的业务含义
|
||
|
||
## 可复制模板
|
||
|
||
**按意图选择模板：**
|
||
- 比较不同类别数值 → 柱状图 / 条形图
|
||
- 看趋势变化 → 折线图 / 面积图
|
||
- 看占比分布 → 饼图 / 环形图 / 词云
|
||
- 多指标对比 → 组合图
|
||
- 看两变量关系 → 散点图
|
||
- 看流程转化 → 漏斗图
|
||
- 看多维度评分 → 雷达图
|
||
- 显示单个指标 → 指标卡（统计数字或记录数）
|
||
|
||
最小柱状图：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
|
||
"group_by": [{ "field_name": "分组字段", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
最小饼图/环形图（按分类字段统计行数占比）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"count_all": true,
|
||
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
折线图（按月趋势）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"series": [{ "field_name": "金额", "rollup": "SUM" }],
|
||
"group_by": [{ "field_name": "月份", "mode": "integrated", "sort": {"type":"group","order":"asc"} }]
|
||
}
|
||
```
|
||
|
||
条形图（横向柱状图）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
|
||
"group_by": [{ "field_name": "分组字段", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
面积图（趋势填充）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
|
||
"group_by": [{ "field_name": "时间字段", "mode": "integrated", "sort": {"type":"group","order":"asc"} }]
|
||
}
|
||
```
|
||
|
||
组合图（柱+线等多指标对比）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"series": [
|
||
{ "field_name": "指标1", "rollup": "SUM" },
|
||
{ "field_name": "指标2", "rollup": "SUM" }
|
||
],
|
||
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
散点图（两变量相关性）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"series": [{ "field_name": "Y轴字段（数值/指标）", "rollup": "SUM" }],
|
||
"group_by": [{ "field_name": "X轴字段（分类/维度）", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
漏斗图（流程转化）：
|
||
|
||
先判断用户要看的数值语义：
|
||
|
||
- **当前数量**：统计每个当前状态/阶段下有多少记录，例如“各环节当前数量”“当前阶段分布”。源表有状态/阶段字段时，直接用 `count_all:true` + `group_by`。
|
||
- **累计数量**：统计到达该阶段及其后续阶段（后缀和）的累计数量，例如“流程转化”“从 A 到 B 各环节转化”。此口径假设流程单向、无跳阶/回退、记录不删除；不满足时须用状态变更历史，不能对当前快照累加。如果表中已有累计数量字段或阶段汇总表，直接用该字段画漏斗图；否则先计算累计数量，创建并写入 helper 汇总表后再画图。
|
||
|
||
当前数量：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"count_all": true,
|
||
"group_by": [{ "field_name": "状态字段", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
累计数量：
|
||
|
||
```json
|
||
{
|
||
"table_name": "流程汇总表名",
|
||
"series": [{ "field_name": "累计数量", "rollup": "SUM" }],
|
||
"group_by": [{ "field_name": "阶段字段", "mode": "integrated", "sort": {"type":"view","order":"asc"} }]
|
||
}
|
||
```
|
||
|
||
如果只有当前状态数据但用户要看流程转化，需要先按业务阶段顺序计算每个阶段的累计数量，再创建 helper 汇总表（如：阶段、累计数量），用 `+record-batch-create` 一次写入后，按“累计数量”模板创建漏斗图。helper 表行序就是业务顺序时，首次创建 block 时一次性设置好 `group_by.sort`。
|
||
|
||
> ⚠️ 注意:helper 汇总表仅用于源表无法直接聚合出目标形态的场景（如上面的累计数量漏斗图）。只要能在源表上直接用 `group_by` + `rollup`（含 `AVERAGE`）算出，就不需要新建 helper 表。
|
||
|
||
词云（文本频率）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"count_all": true,
|
||
"group_by": [{ "field_name": "文本字段", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
雷达图（多维度评分）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "表名",
|
||
"series": [
|
||
{ "field_name": "维度1", "rollup": "SUM" },
|
||
{ "field_name": "维度2", "rollup": "SUM" },
|
||
{ "field_name": "维度3", "rollup": "SUM" }
|
||
],
|
||
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
|
||
}
|
||
```
|
||
|
||
指标卡（统计数字）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "数据表",
|
||
"series": [{ "field_name": "数字", "rollup": "SUM" }]
|
||
}
|
||
```
|
||
|
||
指标卡（统计记录数）：
|
||
|
||
```json
|
||
{
|
||
"table_name": "数据表",
|
||
"count_all": true
|
||
}
|
||
```
|
||
|
||
文本组件（Markdown 富文本）：
|
||
|
||
```json
|
||
{
|
||
"text": "# 🚀 一级标题\n这是一个 **加粗** *斜体* ~~删除线~~ 的示例。\n\n## 📌 二级标题\n1. 有序列表项 1\n2. 有序列表项 2\n\n### 📌 三级标题\n- 无序列表项 1\n- 无序列表项 2"
|
||
}
|
||
```
|
||
|
||
> **注意**：text 类型组件不需要 `table_name`、`series`、`group_by`、`filter` 等数据源相关字段。
|
||
|
||
## 常见错误与修复
|
||
|
||
- 同时存在 `series` 与 `count_all`
|
||
- 现象：后端/本地校验报互斥错误
|
||
- 修复：见「关键约束」章节的二选一规则
|
||
- 缺少 `table_name`
|
||
- 现象：本地校验缺少必填字段
|
||
- 修复：指定数据源表名（使用表名，非表 ID）
|
||
- `series[].rollup` 大小写/取值不合法
|
||
- 现象：本地校验提示枚举不支持
|
||
- 修复：改为 `SUM|MAX|MIN|AVERAGE` 中之一（不区分大小写，CLI 会统一为大写；计数请使用 `count_all:true`）
|
||
- `group_by` 超出 2 个或字段名为空
|
||
- 修复：保留前 2 个，或补齐 `field_name`
|
||
- 排序枚举不合法
|
||
- 修复：`group_by.sort.type` 仅能为 `group|value|view`；`order` 为 `asc|desc`
|
||
- filter 写法不规范
|
||
- 修复：`conjunction` 取 `and|or`；`conditions[].operator` 必须在本页表格列举的范围内；除 `isEmpty/isNotEmpty` 外需提供 `value`
|
||
|
||
## 坑点
|
||
|
||
- **`count_all` 与 `series` 二选一** — 两者不能同时使用
|
||
- **filter `value` 类型因字段而异** — 文本/单选为 string，数字为 number，日期为毫秒时间戳，多选/人员可为 string[]，复选框为 boolean；`isEmpty`/`isNotEmpty` 不需要 value
|
||
- **`data_config` 结构随 `type` 变化** — 不同组件类型的字段不同，创建前务必确认类型对应的字段
|
||
- **表名用 name，不是 ID** — `table_name` 对应的是表名称（如「订单表」），不是 `table_id`
|