@qingflow-tech/qingflow-cli 1.0.39 → 1.0.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +2 -2
  2. package/package.json +1 -1
  3. package/pyproject.toml +1 -1
  4. package/skills/qingflow-cli/SKILL.md +6 -4
  5. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md +2 -2
  6. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +75 -32
  7. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +52 -17
  8. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +48 -2
  9. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md +1 -0
  10. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md +2 -1
  11. package/skills/qingflow-cli/reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md +9 -0
  12. package/skills/qingflow-cli/reference/QINGFLOW_CLI_EXPLORATION_REPORT.md +1 -1
  13. package/skills/qingflow-cli/reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md +1 -2
  14. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md +2 -2
  15. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +2 -0
  16. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md +26 -0
  17. package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +16 -4
  18. package/skills/qingflow-cli/reference/charts_upsert_bar.example.json +2 -2
  19. package/skills/qingflow-cli/reference/charts_upsert_dashboard_starter.example.json +5 -5
  20. package/skills/qingflow-cli/reference/charts_upsert_minimal.example.json +1 -1
  21. package/skills/qingflow-cli/reference/portal_sections_five_types.example.json +21 -1
  22. package/skills/qingflow-cli/reference/portal_sections_standard_workbench.example.json +128 -0
  23. package/skills/qingflow-mcp-setup/SKILL.md +2 -0
  24. package/src/qingflow_mcp/builder_facade/models.py +183 -0
  25. package/src/qingflow_mcp/builder_facade/service.py +722 -74
  26. package/src/qingflow_mcp/cli/commands/builder.py +62 -2
  27. package/src/qingflow_mcp/cli/commands/common.py +12 -3
  28. package/src/qingflow_mcp/cli/formatters.py +1 -0
  29. package/src/qingflow_mcp/cli/main.py +2 -0
  30. package/src/qingflow_mcp/response_trim.py +1 -0
  31. package/src/qingflow_mcp/tools/ai_builder_tools.py +515 -22
  32. package/src/qingflow_mcp/tools/record_tools.py +28 -2
@@ -49,6 +49,32 @@ CLI 注册见全局包 **`qingflow_mcp/cli/commands/imports.py`**(`template` /
49
49
 
50
50
  ## 4. 命令要点
51
51
 
52
+ ### 4.0 文件形态、CSV 源数据与字段映射
53
+
54
+ - 当前 `import verify/start` 主链路面向官方 Excel 模板(`.xlsx` / `.xls`),不是直接把任意 CSV 交给后端。
55
+ - CSV 可以作为源数据或中间表,但必须先映射到官方模板列名,再写入模板副本;不要改模板表头。
56
+ - 字段映射以 `record schema import` / 模板列为准:源列名可以是用户习惯名,目标列名必须是官方模板 header。
57
+ - 关联字段批量导入优先使用稳定 `record_id` 或 schema 明确支持的唯一搜索值;显示名可能重复时不要猜。
58
+ - 成员/部门字段必须使用 schema/candidate 范围内的值;选项字段优先使用模板里的选项文案。
59
+
60
+ CSV 源数据示例(规划用):
61
+
62
+ ```csv
63
+ 客户名称,关联客户,状态,负责人
64
+ 上海示例客户,CUST_RECORD_ID_001,有效,张三
65
+ ```
66
+
67
+ 映射到模板后的行语义:
68
+
69
+ ```json
70
+ {
71
+ "客户名称": "上海示例客户",
72
+ "关联客户": "CUST_RECORD_ID_001",
73
+ "状态": "有效",
74
+ "负责人": "张三"
75
+ }
76
+ ```
77
+
52
78
  ### 4.1 模板
53
79
 
54
80
  ```bash
@@ -1,7 +1,7 @@
1
1
  # `app_schema_apply` / `builder schema apply`:字段类型与场景总表
2
2
 
3
3
  > **口径**:`field.type` 枚举以 **`qingflow --json builder contract --tool-name app_schema_apply`**(及包内 `PublicFieldType`)为准;**形状校验**以 `qingflow_mcp` 的 **`FieldPatch`**(`builder_facade/models.py`)与 **`app_schema_apply` 编排**(`builder_facade/service.py`)为准。
4
- > **CLI**:`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用数组] [--publish|--no-publish] [--add-fields-file …] [--update-fields-file …] [--remove-fields-file …]`;**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀,并把 `--profile` 放在 `builder` 之前。
4
+ > **CLI**:`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用对象] [--publish|--no-publish] [--add-fields-file …] [--update-fields-file …] [--remove-fields-file …]`;**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀,并把 `--profile` 放在 `builder` 之前。
5
5
  > **新建应用主规则**:`add_fields[]` 里必须有且仅有一个顶层字段标记 `as_data_title: true`;数据封面可选,只能在顶层 `attachment` 字段标记 `as_data_cover: true`。
6
6
  > **权限**:包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**;已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
7
7
 
@@ -35,6 +35,18 @@
35
35
 
36
36
  **`relation_mode`**:仅 **`relation`** 使用,取值为 **`single`** 或 **`multiple`**(多关联字段能力受 **`verification.relation_field_limit_verified`** 等约束,见交付文 §6)。
37
37
 
38
+ ### 1.1 智能体友好字段类型别名
39
+
40
+ 主路径可以写更符合直觉的字段类型;工具写入前自动归一化,读回和排障时仍使用 canonical 类型:
41
+
42
+ | 智能体写法 | canonical 类型 |
43
+ |------------|----------------|
44
+ | `multiline` / `multiline_text` / `textarea` | `long_text` |
45
+ | `select` / `single_choice` / `dropdown` | `single_select` |
46
+ | `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
47
+
48
+ 完整映射以 `builder contract --tool-name app_schema_apply` 的 `allowed_values.field.type_aliases` 为准。
49
+
38
50
  ---
39
51
 
40
52
  ## 2. 按类型的必填 / 常用可选(写意图)
@@ -48,7 +60,7 @@
48
60
  | `q_linker` | **`q_linker_binding`**:`inputs`、`request`、**`outputs[]` 每项须含 `target_field`**(能解析到本表单字段) | `request.url` 等须符合**租户/后端远程查询策略**;读回 JSON 可能**缺** `outputs[].target_field`,会导致本地再编译失败(见 §5) |
49
61
  | `code_block` | **`code_block_binding`**:`inputs`、`code`、**`outputs[]` + `target_field`**;代码体须能被规范识别 **`qf_output` 赋值** | **`auto_trigger`**、按钮文案;勿与 **`code_block_config.code_content`** 与 **`binding.code`** 冲突 |
50
62
 
51
- 别名:契约会把 `title`/`label` 映射到 **`name`** 等;建议直接用规范键。
63
+ 别名:契约会把 `title`/`label` 映射到 **`name`** 等;字段类型自然别名见 §1.1。
52
64
 
53
65
  ---
54
66
 
@@ -58,7 +70,7 @@
58
70
  |------|----------------|------|
59
71
  | 编辑已有应用 | `--app-key`;可选 `--no-publish` | **不要**与 `--package-id`、`--create-if-missing` 同用 |
60
72
  | 包内新建应用 | `--package-id`、`--app-name`(或 title 映射)、**`--create-if-missing`**;初始 `add-fields-file` 至少包含一个 `as_data_title: true` 字段 | 创建后可得到新 **`app_key`**(以响应为准) |
61
- | 多应用一次性新建 | `--package-id`、**`--create-if-missing`**、`--apps-file` | 应用包/系统里有 2 个以上应用,或同批应用之间有 `relation` 时使用;`--apps-file` 可为数组或 `{package_id, apps}` 对象;`apps[].client_key` 可被 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用 |
73
+ | 多应用一次性新建 | `--package-id`、**`--create-if-missing`**、`--apps-file` | 应用包/系统里有 2 个以上应用,或同批应用之间有 `relation` 时使用;`--apps-file` 主写法为 `{package_id, apps}` 对象,raw apps array / singleton wrapper array 仅兼容;`apps[].client_key` 可被 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用 |
62
74
  | 仅增字段 | `--add-fields-file`(JSON 数组) | 与 **`update_fields`/`remove_fields`** 可同次组合(以契约为准) |
63
75
  | 改字段 | `--update-fields-file` | 每项 **`selector`**(`name`/`que_id`/`field_id`)+ **`set`** |
64
76
  | 删字段 | `--remove-fields-file` | 每项至少 **`name`/`que_id`/`field_id`** 之一 |
@@ -82,7 +94,7 @@
82
94
 
83
95
  **一次性新建应用**:`--package-id` + `--app-name` + `--create-if-missing` + [schema_apply_add_fields_all_types.json](./schema_apply_add_fields_all_types.json) 是当前推荐示例;它已包含唯一数据标题和可选数据封面(`q_linker` 使用 `https://httpbin.org/get`,`relation` 指向可读模板应用 `ead8ims5i401`)。
84
96
 
85
- **一次性新建多个应用**:用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`;`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用,工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径,尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景;不要为了拿 `app_key` 先逐个创建再二次补关联字段。
97
+ **一次性新建多个应用**:用 `builder schema apply --package-id <TAG_ID> --create-if-missing --apps-file tmp/apps.json`,其中 `tmp/apps.json` 主写法为 `{ "package_id": 123, "apps": [...] }`,每个 `apps[]` 写顶层 `icon + color`;`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用,`apps[].app_name` 可被 `target_app` 引用,工具会编译成真实 `target_app_key`。这是应用包/系统搭建的默认路径,尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景;不要为了拿 `app_key` 先逐个创建再二次补关联字段。
86
98
 
87
99
  **限制(平台硬性)**:每应用 **至多一个** `relation`;`--app-key` 向已有应用追加时须 **字段名不重复**、且 **不能**在已有 relation 上再增第二个。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**,本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`,须修复或删除该题。
88
100
 
@@ -2,7 +2,7 @@
2
2
  {
3
3
  "name": "示例柱状图",
4
4
  "chart_type": "bar",
5
- "dimension_field_ids": ["REPLACE_WITH_FIELD_ID"],
6
- "indicator_field_ids": ["REPLACE_WITH_FIELD_ID"]
5
+ "group_by": ["REPLACE_WITH_DIMENSION_FIELD_NAME"],
6
+ "metric": "sum(REPLACE_WITH_NUMERIC_FIELD_NAME)"
7
7
  }
8
8
  ]
@@ -2,7 +2,7 @@
2
2
  {
3
3
  "name": "数据总量",
4
4
  "chart_type": "target",
5
- "indicator_field_ids": [],
5
+ "metric": "count(*)",
6
6
  "visibility": {
7
7
  "mode": "workspace",
8
8
  "selectors": {},
@@ -13,8 +13,8 @@
13
13
  {
14
14
  "name": "按状态分布",
15
15
  "chart_type": "bar",
16
- "dimension_field_ids": ["REPLACE_WITH_STATUS_FIELD_ID"],
17
- "indicator_field_ids": ["REPLACE_WITH_COUNT_OR_NUMERIC_FIELD_ID"],
16
+ "group_by": ["REPLACE_WITH_STATUS_FIELD_NAME"],
17
+ "metric": "count(*)",
18
18
  "visibility": {
19
19
  "mode": "workspace",
20
20
  "selectors": {},
@@ -25,8 +25,8 @@
25
25
  {
26
26
  "name": "按时间趋势",
27
27
  "chart_type": "line",
28
- "dimension_field_ids": ["REPLACE_WITH_DATE_FIELD_ID"],
29
- "indicator_field_ids": ["REPLACE_WITH_COUNT_OR_NUMERIC_FIELD_ID"],
28
+ "group_by": ["REPLACE_WITH_DATE_FIELD_NAME"],
29
+ "metric": "count(*)",
30
30
  "visibility": {
31
31
  "mode": "workspace",
32
32
  "selectors": {},
@@ -2,7 +2,7 @@
2
2
  {
3
3
  "name": "数据总量",
4
4
  "chart_type": "target",
5
- "indicator_field_ids": [],
5
+ "metric": "count(*)",
6
6
  "visibility": {
7
7
  "mode": "workspace",
8
8
  "selectors": {},
@@ -37,7 +37,27 @@
37
37
  },
38
38
  "config": {
39
39
  "gridTitle": "业务入口",
40
- "beingShowTitle": true
40
+ "beingShowTitle": true,
41
+ "items": [
42
+ {
43
+ "type": 1,
44
+ "jumpMode": 1,
45
+ "linkAppKey": "APP_KEY_MAIN",
46
+ "linkFormType": 1,
47
+ "title": "核心业务",
48
+ "customTitle": "核心业务",
49
+ "beingCustomTitle": false
50
+ },
51
+ {
52
+ "type": 1,
53
+ "jumpMode": 1,
54
+ "linkAppKey": "APP_KEY_TASK",
55
+ "linkFormType": 1,
56
+ "title": "待处理业务",
57
+ "customTitle": "待处理业务",
58
+ "beingCustomTitle": false
59
+ }
60
+ ]
41
61
  }
42
62
  },
43
63
  {
@@ -0,0 +1,128 @@
1
+ [
2
+ {
3
+ "title": "业务入口",
4
+ "source_type": "grid",
5
+ "position": {
6
+ "pc": {"x": 0, "y": 0, "cols": 24, "rows": 4},
7
+ "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 4}
8
+ },
9
+ "config": {
10
+ "gridTitle": "业务入口",
11
+ "beingShowTitle": true,
12
+ "items": [
13
+ {
14
+ "type": 1,
15
+ "jumpMode": 1,
16
+ "linkAppKey": "APP_KEY_DEVICE",
17
+ "linkFormType": 1,
18
+ "title": "设备台账",
19
+ "customTitle": "设备台账",
20
+ "beingCustomTitle": false
21
+ },
22
+ {
23
+ "type": 1,
24
+ "jumpMode": 1,
25
+ "linkAppKey": "APP_KEY_REPAIR",
26
+ "linkFormType": 1,
27
+ "title": "故障报修",
28
+ "customTitle": "故障报修",
29
+ "beingCustomTitle": false
30
+ },
31
+ {
32
+ "type": 1,
33
+ "jumpMode": 1,
34
+ "linkAppKey": "APP_KEY_MAINTENANCE",
35
+ "linkFormType": 1,
36
+ "title": "保养管理",
37
+ "customTitle": "保养管理",
38
+ "beingCustomTitle": false
39
+ }
40
+ ]
41
+ }
42
+ },
43
+ {
44
+ "title": "设备总数",
45
+ "source_type": "chart",
46
+ "role": "metric",
47
+ "position": {
48
+ "pc": {"x": 0, "y": 4, "cols": 6, "rows": 5},
49
+ "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 5}
50
+ },
51
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_TOTAL"}
52
+ },
53
+ {
54
+ "title": "正常设备",
55
+ "source_type": "chart",
56
+ "role": "metric",
57
+ "position": {
58
+ "pc": {"x": 6, "y": 4, "cols": 6, "rows": 5},
59
+ "mobile": {"x": 0, "y": 9, "cols": 6, "rows": 5}
60
+ },
61
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_NORMAL"}
62
+ },
63
+ {
64
+ "title": "维修中设备",
65
+ "source_type": "chart",
66
+ "role": "metric",
67
+ "position": {
68
+ "pc": {"x": 12, "y": 4, "cols": 6, "rows": 5},
69
+ "mobile": {"x": 0, "y": 14, "cols": 6, "rows": 5}
70
+ },
71
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_REPAIRING"}
72
+ },
73
+ {
74
+ "title": "本月报修",
75
+ "source_type": "chart",
76
+ "role": "metric",
77
+ "position": {
78
+ "pc": {"x": 18, "y": 4, "cols": 6, "rows": 5},
79
+ "mobile": {"x": 0, "y": 19, "cols": 6, "rows": 5}
80
+ },
81
+ "chart_ref": {"app_key": "APP_KEY_REPAIR", "chart_id": "CHART_ID_REPAIR_MONTH"}
82
+ },
83
+ {
84
+ "title": "设备状态分布",
85
+ "source_type": "chart",
86
+ "position": {
87
+ "pc": {"x": 0, "y": 9, "cols": 8, "rows": 7},
88
+ "mobile": {"x": 0, "y": 24, "cols": 6, "rows": 7}
89
+ },
90
+ "chart_ref": {"app_key": "APP_KEY_DEVICE", "chart_id": "CHART_ID_STATUS_DIST"}
91
+ },
92
+ {
93
+ "title": "故障类型分布",
94
+ "source_type": "chart",
95
+ "position": {
96
+ "pc": {"x": 8, "y": 9, "cols": 8, "rows": 7},
97
+ "mobile": {"x": 0, "y": 31, "cols": 6, "rows": 7}
98
+ },
99
+ "chart_ref": {"app_key": "APP_KEY_REPAIR", "chart_id": "CHART_ID_FAULT_DIST"}
100
+ },
101
+ {
102
+ "title": "维修完成趋势",
103
+ "source_type": "chart",
104
+ "position": {
105
+ "pc": {"x": 16, "y": 9, "cols": 8, "rows": 7},
106
+ "mobile": {"x": 0, "y": 38, "cols": 6, "rows": 7}
107
+ },
108
+ "chart_ref": {"app_key": "APP_KEY_REPAIR", "chart_id": "CHART_ID_REPAIR_TREND"}
109
+ },
110
+ {
111
+ "title": "异常设备",
112
+ "source_type": "view",
113
+ "position": {
114
+ "pc": {"x": 0, "y": 16, "cols": 12, "rows": 11},
115
+ "mobile": {"x": 0, "y": 45, "cols": 6, "rows": 11}
116
+ },
117
+ "view_ref": {"app_key": "APP_KEY_DEVICE", "view_key": "VIEW_KEY_ABNORMAL_DEVICES"}
118
+ },
119
+ {
120
+ "title": "待处理工单",
121
+ "source_type": "view",
122
+ "position": {
123
+ "pc": {"x": 12, "y": 16, "cols": 12, "rows": 11},
124
+ "mobile": {"x": 0, "y": 56, "cols": 6, "rows": 11}
125
+ },
126
+ "view_ref": {"app_key": "APP_KEY_REPAIR", "view_key": "VIEW_KEY_PENDING_WORK_ORDERS"}
127
+ }
128
+ ]
@@ -7,6 +7,8 @@ metadata:
7
7
 
8
8
  # Qingflow MCP Setup
9
9
 
10
+ > **Skill 版本**:`qingflow-skills-2026.06.23.1`(入口文档版本;如需确认 CLI 包版本,使用 `qingflow --version` 或 `qingflow --json version`)。
11
+
10
12
  ## Overview
11
13
 
12
14
  This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.
@@ -1,5 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
+ import re
3
4
  from enum import Enum
4
5
  from typing import Any
5
6
 
@@ -70,17 +71,36 @@ class PublicExternalVisibilityMode(str, Enum):
70
71
 
71
72
 
72
73
  FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
74
+ "multiline": PublicFieldType.long_text,
75
+ "multiline_text": PublicFieldType.long_text,
76
+ "multi_line": PublicFieldType.long_text,
77
+ "multi_line_text": PublicFieldType.long_text,
73
78
  "textarea": PublicFieldType.long_text,
79
+ "longtext": PublicFieldType.long_text,
80
+ "long-text": PublicFieldType.long_text,
74
81
  "amount": PublicFieldType.amount,
75
82
  "currency": PublicFieldType.amount,
76
83
  "mobile": PublicFieldType.phone,
77
84
  "user": PublicFieldType.member,
78
85
  "users": PublicFieldType.member,
79
86
  "select": PublicFieldType.single_select,
87
+ "single_choice": PublicFieldType.single_select,
88
+ "single-choice": PublicFieldType.single_select,
89
+ "single choice": PublicFieldType.single_select,
90
+ "choice": PublicFieldType.single_select,
91
+ "dropdown": PublicFieldType.single_select,
80
92
  "radio": PublicFieldType.single_select,
81
93
  "checkbox": PublicFieldType.multi_select,
82
94
  "multi_select": PublicFieldType.multi_select,
83
95
  "multi-select": PublicFieldType.multi_select,
96
+ "multi select": PublicFieldType.multi_select,
97
+ "multiselect": PublicFieldType.multi_select,
98
+ "multi_choice": PublicFieldType.multi_select,
99
+ "multi-choice": PublicFieldType.multi_select,
100
+ "multi choice": PublicFieldType.multi_select,
101
+ "multiple_choice": PublicFieldType.multi_select,
102
+ "multiple-choice": PublicFieldType.multi_select,
103
+ "multiple choice": PublicFieldType.multi_select,
84
104
  "departments": PublicFieldType.department,
85
105
  "qlinker": PublicFieldType.q_linker,
86
106
  "q_linker": PublicFieldType.q_linker,
@@ -1796,6 +1816,65 @@ class ChartFilterRulePatch(StrictModel):
1796
1816
  return self
1797
1817
 
1798
1818
 
1819
+ class ChartMetricPatch(StrictModel):
1820
+ op: str = "count"
1821
+ field_name: str | None = Field(default=None, validation_alias=AliasChoices("field", "field_name", "fieldName", "name"))
1822
+ alias: str | None = None
1823
+
1824
+ @model_validator(mode="before")
1825
+ @classmethod
1826
+ def normalize_metric(cls, value: Any) -> Any:
1827
+ if isinstance(value, str):
1828
+ raw = value.strip()
1829
+ match = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*)\s*\(\s*(.*?)\s*\)", raw)
1830
+ if match:
1831
+ op = match.group(1).strip().lower()
1832
+ field = match.group(2).strip()
1833
+ payload: dict[str, Any] = {"op": op}
1834
+ if field and field != "*":
1835
+ payload["field_name"] = field
1836
+ return payload
1837
+ if raw:
1838
+ return {"op": "sum", "field_name": raw}
1839
+ return {"op": "count"}
1840
+ if not isinstance(value, dict):
1841
+ return value
1842
+ payload = dict(value)
1843
+ if "operation" in payload and "op" not in payload:
1844
+ payload["op"] = payload.pop("operation")
1845
+ if "agg" in payload and "op" not in payload:
1846
+ payload["op"] = payload.pop("agg")
1847
+ if "aggregate" in payload and "op" not in payload:
1848
+ payload["op"] = payload.pop("aggregate")
1849
+ if "aggregation" in payload and "op" not in payload:
1850
+ payload["op"] = payload.pop("aggregation")
1851
+ return payload
1852
+
1853
+ @model_validator(mode="after")
1854
+ def validate_metric(self) -> "ChartMetricPatch":
1855
+ normalized_op = str(self.op or "count").strip().lower()
1856
+ op_aliases = {
1857
+ "average": "avg",
1858
+ "mean": "avg",
1859
+ "total": "sum",
1860
+ "cnt": "count",
1861
+ "count_all": "count",
1862
+ }
1863
+ self.op = op_aliases.get(normalized_op, normalized_op)
1864
+ if self.field_name is not None:
1865
+ field_name = str(self.field_name).strip()
1866
+ self.field_name = field_name or None
1867
+ if self.alias is not None:
1868
+ alias = str(self.alias).strip()
1869
+ self.alias = alias or None
1870
+ supported = {"count", "sum", "avg", "max", "min"}
1871
+ if self.op not in supported:
1872
+ raise ValueError(f"chart metric op must be one of {sorted(supported)}")
1873
+ if self.op != "count" and not self.field_name:
1874
+ raise ValueError(f"chart metric op '{self.op}' requires field")
1875
+ return self
1876
+
1877
+
1799
1878
  class ChartUpsertPatch(StrictModel):
1800
1879
  chart_id: str | None = None
1801
1880
  name: str
@@ -1803,6 +1882,17 @@ class ChartUpsertPatch(StrictModel):
1803
1882
  dimension_field_ids: list[str] = Field(default_factory=list)
1804
1883
  indicator_field_ids: list[str] = Field(default_factory=list)
1805
1884
  filters: list[ChartFilterRulePatch] = Field(default_factory=list)
1885
+ group_by: list[str] = Field(default_factory=list)
1886
+ rows: list[str] = Field(default_factory=list)
1887
+ columns: list[str] = Field(default_factory=list)
1888
+ metric: ChartMetricPatch | None = None
1889
+ metrics: list[ChartMetricPatch] = Field(default_factory=list)
1890
+ x_metric: ChartMetricPatch | None = None
1891
+ y_metric: ChartMetricPatch | None = None
1892
+ left_metric: ChartMetricPatch | None = None
1893
+ right_metric: ChartMetricPatch | None = None
1894
+ value_metric: ChartMetricPatch | None = None
1895
+ target_metric: ChartMetricPatch | None = None
1806
1896
  question_config: list[dict[str, Any]] = Field(default_factory=list)
1807
1897
  user_config: list[dict[str, Any]] = Field(default_factory=list)
1808
1898
  config: dict[str, Any] = Field(default_factory=dict)
@@ -1820,10 +1910,74 @@ class ChartUpsertPatch(StrictModel):
1820
1910
  payload["chart_type"] = payload.pop("type")
1821
1911
  if "dimension_fields" in payload and "dimension_field_ids" not in payload:
1822
1912
  payload["dimension_field_ids"] = payload.pop("dimension_fields")
1913
+ if "dimensions" in payload and "dimension_field_ids" not in payload and "group_by" not in payload:
1914
+ payload["group_by"] = payload.pop("dimensions")
1915
+ if "groupBy" in payload and "group_by" not in payload:
1916
+ payload["group_by"] = payload.pop("groupBy")
1917
+ if "where" in payload and "filters" not in payload:
1918
+ payload["filters"] = payload.pop("where")
1919
+ if "filter_rules" in payload and "filters" not in payload:
1920
+ payload["filters"] = payload.pop("filter_rules")
1921
+ if "filterRules" in payload and "filters" not in payload:
1922
+ payload["filters"] = payload.pop("filterRules")
1823
1923
  if "indicator_fields" in payload and "indicator_field_ids" not in payload:
1824
1924
  payload["indicator_field_ids"] = payload.pop("indicator_fields")
1825
1925
  if "metric_field_ids" in payload and "indicator_field_ids" not in payload:
1826
1926
  payload["indicator_field_ids"] = payload.pop("metric_field_ids")
1927
+ metric_slots: list[Any] = []
1928
+ generic_metric_keys = ("metric", "metrics")
1929
+ axis_metric_keys = (
1930
+ "x_metric",
1931
+ "xMetric",
1932
+ "y_metric",
1933
+ "yMetric",
1934
+ "left_metric",
1935
+ "leftMetric",
1936
+ "right_metric",
1937
+ "rightMetric",
1938
+ "value_metric",
1939
+ "valueMetric",
1940
+ "target_metric",
1941
+ "targetMetric",
1942
+ )
1943
+
1944
+ def has_metric_value(key: str) -> bool:
1945
+ entry = payload.get(key)
1946
+ return entry is not None and entry != "" and entry != []
1947
+
1948
+ if any(has_metric_value(key) for key in generic_metric_keys) and any(has_metric_value(key) for key in axis_metric_keys):
1949
+ raise ValueError(
1950
+ "chart metric input is ambiguous: use either metric/metrics or axis-specific "
1951
+ "x_metric/y_metric, left_metric/right_metric, value_metric/target_metric, not both"
1952
+ )
1953
+ if "metric" in payload and "metrics" not in payload:
1954
+ payload["metrics"] = [payload["metric"]]
1955
+ for key in ("x_metric", "xMetric", "left_metric", "leftMetric", "value_metric", "valueMetric"):
1956
+ if key in payload:
1957
+ slot_value = payload.get(key)
1958
+ if slot_value is not None:
1959
+ metric_slots.append(slot_value)
1960
+ canonical = {
1961
+ "xMetric": "x_metric",
1962
+ "leftMetric": "left_metric",
1963
+ "valueMetric": "value_metric",
1964
+ }.get(key)
1965
+ if canonical and canonical not in payload:
1966
+ payload[canonical] = payload.pop(key)
1967
+ for key in ("y_metric", "yMetric", "right_metric", "rightMetric", "target_metric", "targetMetric"):
1968
+ if key in payload:
1969
+ slot_value = payload.get(key)
1970
+ if slot_value is not None:
1971
+ metric_slots.append(slot_value)
1972
+ canonical = {
1973
+ "yMetric": "y_metric",
1974
+ "rightMetric": "right_metric",
1975
+ "targetMetric": "target_metric",
1976
+ }.get(key)
1977
+ if canonical and canonical not in payload:
1978
+ payload[canonical] = payload.pop(key)
1979
+ if metric_slots and "metrics" not in payload:
1980
+ payload["metrics"] = metric_slots
1827
1981
  raw_type = payload.get("chart_type")
1828
1982
  if isinstance(raw_type, str):
1829
1983
  normalized = raw_type.strip().lower()
@@ -1850,8 +2004,31 @@ class ChartUpsertPatch(StrictModel):
1850
2004
  payload["dimension_field_ids"] = [str(item) for item in payload["dimension_field_ids"] if item is not None and str(item).strip()]
1851
2005
  if isinstance(payload.get("indicator_field_ids"), list):
1852
2006
  payload["indicator_field_ids"] = [str(item) for item in payload["indicator_field_ids"] if item is not None and str(item).strip()]
2007
+ for key in ("group_by", "rows", "columns"):
2008
+ if isinstance(payload.get(key), str):
2009
+ payload[key] = [payload[key]]
2010
+ if isinstance(payload.get(key), list):
2011
+ payload[key] = [str(item) for item in payload[key] if item is not None and str(item).strip()]
1853
2012
  return payload
1854
2013
 
2014
+ @model_validator(mode="after")
2015
+ def apply_semantic_chart_fields(self) -> "ChartUpsertPatch":
2016
+ if self.group_by and not self.dimension_field_ids:
2017
+ self.dimension_field_ids = list(self.group_by)
2018
+ if self.rows and not self.dimension_field_ids:
2019
+ self.dimension_field_ids = list(self.rows)
2020
+ semantic_metrics: list[ChartMetricPatch] = []
2021
+ if self.metrics:
2022
+ semantic_metrics.extend(self.metrics)
2023
+ for metric in (self.x_metric, self.y_metric, self.left_metric, self.right_metric, self.value_metric, self.target_metric):
2024
+ if metric is not None and metric not in semantic_metrics:
2025
+ semantic_metrics.append(metric)
2026
+ if semantic_metrics and not self.metrics:
2027
+ self.metrics = semantic_metrics
2028
+ if self.metrics and not self.metric:
2029
+ self.metric = self.metrics[0]
2030
+ return self
2031
+
1855
2032
 
1856
2033
  class ChartPartialPatch(StrictModel):
1857
2034
  chart_id: str | None = None
@@ -1993,6 +2170,7 @@ class PortalViewRefPatch(StrictModel):
1993
2170
  class PortalSectionPatch(StrictModel):
1994
2171
  title: str
1995
2172
  source_type: str = Field(validation_alias=AliasChoices("source_type", "sourceType"))
2173
+ role: str | None = Field(default=None, validation_alias=AliasChoices("role", "zone", "section_role", "sectionRole"))
1996
2174
  position: PortalComponentPositionPatch | None = None
1997
2175
  dash_style_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_style_config", "dashStyleConfigBO"))
1998
2176
  config: dict[str, Any] = Field(default_factory=dict)
@@ -2010,6 +2188,9 @@ class PortalSectionPatch(StrictModel):
2010
2188
  raw_type = payload.get("source_type", payload.get("sourceType"))
2011
2189
  if isinstance(raw_type, str):
2012
2190
  payload["source_type"] = raw_type.strip().lower()
2191
+ raw_role = payload.get("role", payload.get("zone", payload.get("section_role", payload.get("sectionRole"))))
2192
+ if isinstance(raw_role, str):
2193
+ payload["role"] = raw_role.strip().lower()
2013
2194
  if "chartRef" in payload and "chart_ref" not in payload:
2014
2195
  payload["chart_ref"] = payload.pop("chartRef")
2015
2196
  if "viewRef" in payload and "view_ref" not in payload:
@@ -2216,6 +2397,8 @@ class ChartGetResponse(StrictModel):
2216
2397
  base: dict[str, Any] = Field(default_factory=dict)
2217
2398
  visibility: dict[str, Any] = Field(default_factory=dict)
2218
2399
  filters: list[list[dict[str, Any]]] = Field(default_factory=list)
2400
+ group_by: list[str] = Field(default_factory=list)
2401
+ metrics: list[dict[str, Any]] = Field(default_factory=list)
2219
2402
  config: dict[str, Any] = Field(default_factory=dict)
2220
2403
 
2221
2404