@josephyan/qingflow-cli 1.0.11 → 1.1.2

package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md

@@ -0,0 +1,237 @@
+# Builder 报表（QingBI）创建与变更 SOP：`qingflow builder charts apply`
+
+稳定命令：**`qingflow builder charts apply`**（子命令 **`builder charts apply`**；**`qingflow build charts apply`** 等价）。
+
+实现要点：`builder_facade/models.py`（**`ChartUpsertPatch`**、**`ChartPartialPatch`**、**`ChartApplyRequest`**、**`ChartFilterRulePatch`**）、`builder_facade/service.py`（**`chart_apply`** / **`_build_public_chart_config_payload`**）、`cli/commands/builder.py`（**`--upsert-file`** / **`--patch-file`** / **`--remove-chart-ids-file`** / **`--reorder-chart-ids-file`**）。已对应用 **`ead8ims5i401`** 与工时测试应用实跑：**新建/更新 `target`、常规图表、`summary` / `gauge` / `scatter` / `dualaxes`，按 `chart_id` 更新（改名 + `visibility`）、仅 `reorder`**。
+
+> **权限**：**`data_manage`**（与其它搭建写一致，`chart_apply` 内 **`_guard_app_permission`**）。
+
+> **读取链路**：`builder chart get` / `chart_get` 读取基础信息时优先走前端同源的 **`/qingbi/charts/qflow/baseinfo/{chartId}`** 可见性链路；仅当该 qflow 路由明确不存在/不适用时才退回 BI 管理详情 **`/qingbi/charts/baseinfo/{chartId}`**。配置详情 **`/qingbi/charts/{chartId}/configs`** 仍可能需要 **`CHART_SEE`**，不可用时会尝试从 qflow 数据接口返回的 embedded config 降级。不要把中间 **`CHART_SEE` / 40002** 直接当成“用户看不到报表”。
+
+> **契约**：`qingflow --json builder contract --tool-name app_charts_apply`  
+> （`--tool-name` 为契约索引。）
+
+> **与「应用发布」的关系**：契约 **execution_notes** 写明 **`app_charts_apply` 为 immediate-live，不走 `app_publish`**。改报表不等价于 **`builder publish verify`**。
+
+> **能力边界**：`builder charts apply` 只创建/更新 **应用源 QingBI 报表**（生成 `dataSourceType=qingflow`）。**数据集 BI 报表不在此工具创建/编辑**；先在 QingBI 中创建数据集报表，再用 **`builder associated-resource apply`** 以 `report_source: "dataset"` 关联到轻流应用。
+
+---
+
+## 1. CLI 形态
+
+```bash
+qingflow --json builder charts apply \
+  --app-key "<APP_KEY>" \
+  [--upsert-file UPSERT_JSON] \
+  [--patch-file PATCH_JSON] \
+  [--remove-chart-ids-file REMOVE_JSON] \
+  [--reorder-chart-ids-file REORDER_JSON] \
+  > tmp/builder_charts_apply.json
+```
+
+- 四个文件参数均可省略，但 **`ChartApplyRequest`** 要求 **至少一项非空**（**upsert** / **patch** / **remove** / **reorder**），否则校验报错。
+- 各文件均为 **JSON 数组**（与 `load_list_arg` 一致）。
+- 大 JSON 必须 **落盘**，见主技能 **builder** 行。
+- 完整系统里一次要创建很多报表时，主路径按应用或主题分批提交，推荐每批 **4-8 个 `upsert_charts`**。超过 8 个时 CLI 会在写入前返回 `CHART_UPSERT_BATCH_TOO_LARGE`，并给出 `details.suggested_batch_payloads[]`；直接逐个执行这些 payload，不要提交原始大数组。
+
+---
+
+## 2. 推荐顺序（读 → 写 → 核对）
+
+| 步骤 | 动作 | CLI |
+|------|------|-----|
+| ① 解析应用 | 确认 **`app_key`** | **`builder app resolve --app-key …`** |
+| ② 读报表字段 | 取 **`chart_fields[]`** 中的 **显示名**、**`field_id`**（如 **`field_数字`**）或 **`bi_field_id`**，供 `group_by` / `metric` / `where` 用；可直接复制 **`chart_fields[].chart_apply_examples`** 作为 apply 片段 | **`builder app get --app-key … fields`** |
+| ③ 读现有报表 | 已有 **`chart_id`**、重名风险 | 先看 **`builder app get --app-key …`** 的 compact `charts`；不足时再用 **`builder app get --app-key … charts`** |
+| ④ 应用变更 | upsert / remove / reorder | **`builder charts apply …`** |
+| ⑤ 再读列表 | 确认顺序与条目 | 再次 **`builder app get --app-key …`**；需要完整报表清单时再下钻 `builder app get charts` |
+
+---
+
+## 3. `upsert_charts[]` 形状（**`ChartUpsertPatch`**）
+
+| 键 | 说明 |
+|----|------|
+| **`name`** | 必填；新建时即图表名；**更新**时可改名。 |
+| **`chart_type`** | 以 `qingflow --json builder contract --tool-name app_charts_apply` 的 `$.contract.allowed_values["chart.chart_type"]` 为准；当前公开面已覆盖 QingBI 常用类型，如 **`target` / `indicator` / `summary` / `pie` / `bar` / `columnar` / `line` / `table` / `detail` / `area` / `stacked_area` / `funnel` / `waterfall` / `gauge` / `heatmap` / `histogram` / `treemap` / `radar` / `stacked_bar` / `stacked_column` / `scatter` / `ring` / `rose` / `dualaxes` / `map`** 等；最终仍以 contract 为准。 |
+| **`chart_id`** | 可选。**有则按 id 命中更新**；无则 **按 `name` 精确匹配**：0 个 → **创建**；多个 → **歧义报错**（须带 **`chart_id`**）。 |
+| **`metric`** / **`metrics`** | **主推语义指标写法**：`"count(*)"`、`"sum(金额)"`、`"avg(工时)"`、`"max(评分)"`、`"min(耗时)"`，也支持对象 `{"op":"sum","field":"金额"}`。字段必须来自 **`chart_fields[]`**。 |
+| **`group_by`** | **主推维度写法**：字段显示名、`field_id` 或 `bi_field_id` 数组，例如 `["使用状态"]`。 |
+| **`where`** / **`filters`** | 统一固定筛选写法：**`field`/`field_name`**（可用 **`chart_fields[].title`** / **`field_id`** / **`bi_field_id`**）+ **`op`/`operator`** + **`value`/`values`** → 写入配置 **`beforeAggregationFilterMatrix`**。 |
+| **`dimension_field_ids`** / **`indicator_field_ids`** | 兼容/高级写法；旧 payload 可继续用，但智能体主路径优先写 `group_by` + `metric(s)`。 |
+| **`visibility`** | 可选；编译为 QingBI **`visibleAuth`**；**仅更新 visibility** 时不重算其它授权结构（见契约）。**更新**时 **省略** 可保留原可见性。 |
+| **`config`** | 透传高级键：`aggregate`、`beforeAggregationFilterMatrix`、`afterAggregationFilterMatrix`、`chartStyleConfigs`、`displayLimitConfig`、`rawDataConfigDTO`、`query_condition_field_ids` 等；未列键会 **merge 进根**（实现 **`_build_public_chart_config_payload`**）。主路径不要手写 `selectedMetrics` / `xMetrics` / `leftMetrics`。 |
+| **`question_config`** / **`user_config`** | 可选；分别 POST **`/chart/{id}/question/config`** 与 **`/user/config`**。 |
+
+**配置是否重算**：若已存在图表且本次 **未显式**改 **`metric(s)` / `group_by` / `where` / `dimension_field_ids` / `indicator_field_ids` / `filters` / `config`**（Pydantic **`model_fields_set`**），实现可 **跳过** **`qingbi_report_update_config`**；**新建**总会写配置。
+
+**报表筛选 operator**：推荐使用 `eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty`；兼容 `equal` / `equals` / `=` / `!=` / `any_of` / `one_of` / `empty` 等别名。CLI 会自动转成 QingBI 字符串判断符（如 `equal`、`anyMatch`、`isNull`）和 BI 前端需要的 `judgeValue` 文本值；单选/多选筛选入参可传选项文本或 option id，CLI 会按 QingBI 路径转成文本。智能体不要手写 `judgeType`、`judgeValue`、`beforeAggregationFilterMatrix`。
+
+**读回语义**：`builder chart get` / `chart_get` 会返回语义化 `group_by`、`metrics`、`filters`；`config.*` 仅作为 raw 诊断，不作为智能体更新主输入。
+
+示例：
+
+```json
+{"field_name": "使用状态", "operator": "eq", "value": "正常"}
+```
+
+### 3.1 推荐语义写法
+
+指标卡：
+
+```json
+{"name": "正常设备数", "chart_type": "target", "metric": "count(*)", "where": [{"field": "使用状态", "op": "eq", "value": "正常"}]}
+```
+
+字段聚合：
+
+```json
+{"name": "维修费用总额", "chart_type": "target", "metric": "sum(维修费用)"}
+```
+
+分组图表：
+
+```json
+{"name": "设备状态分布", "chart_type": "bar", "group_by": ["使用状态"], "metric": "count(*)"}
+```
+
+双轴图：
+
+```json
+{"name": "预算执行对比", "chart_type": "dualaxes", "group_by": ["月份"], "left_metric": "sum(预算金额)", "right_metric": "sum(实际金额)"}
+```
+
+字段发现返回的 `chart_fields[].chart_apply_examples` 会给出同样语义的可复制片段：
+
+- `count_by_field`：按该字段分组计数，适合 bar/columnar/pie 类分布图。
+- `filtered_count`：按该字段固定筛选后计数，适合 target/indicator 指标卡。
+- `sum_metric`：仅数值字段提供，适合金额/数量/工时等合计指标卡。
+
+拿到片段后只改 `name`、`chart_type` 和筛选值即可，不要改写成 `indicator_field_ids` / `config.aggregate` / `selectedMetrics`。
+
+### 3.2 BI 类型与后端字段映射
+
+CLI 对外推荐使用 **`group_by` + `metric(s)`**；旧的 **`dimension_field_ids`** 和 **`indicator_field_ids`** 仍兼容。字段来源必须是 **`app_get_fields.chart_fields`** 的 QingBI datasource 字段。部分 QingBI 类型后端字段槽位不同，CLI 会自动转换：
+
+| `chart_type` | 后端要求 | CLI 处理 |
+|--------------|----------|----------|
+| **`summary`** | `xDimensions` / `yDimensions` + `selectedMetrics` | `rows` 写入 `xDimensions`，`columns` 写入 `yDimensions`，`metrics` 写入 `selectedMetrics`。 |
+| **`scatter`** | `selectedDimensions` + 单个 `xMetrics` + 单个 `yMetrics` | `x_metric` / `y_metric` 分别写入 X/Y；也兼容 `metrics` 前两个。 |
+| **`dualaxes`** | `selectedDimensions` + `leftMetrics` / `rightMetrics` | `left_metric` / `right_metric` 分别写入左/右轴；也兼容 `metrics` 前两个。 |
+| **`gauge`** | 无维度，且必须有两个不重复指标 | `value_metric` / `target_metric` 为主；只给一个真实指标时，第二指标自动补 **`数据总量`**。 |
+| **`histogram`** | 最多 1 个维度，且必须 1 个普通数值指标 | 不能省略指标，不能使用默认 **`数据总量`** / count，不能使用文本字段或聚合公式字段；推荐 `metric: "sum(数值字段)"` 或 `metric: "avg(数值字段)"`。 |
+| **`heatmap`** | 2 个维度 + 1 个指标 | 不满足时 CLI 会提前返回 `diagnostics`，不要等后端裸 810xx。 |
+| **`waterfall` / `map`** | 1 个维度 + 1 个指标 | `map` 的维度应选位置/地区含义字段。 |
+| **`treemap`** | 1-2 个维度 + 1 个指标 | 维度过少/过多都会被前置校验。 |
+
+这些转换用于避免“报表配置未完成”。若用户显式在 `config` 中提供 `xDimensions`、`xMetrics`、`leftMetrics` 等高级字段，应以 contract 与后端校验为准。
+
+低频报表失败时优先看 **`chart_results[].diagnostics`**：
+
+- **`81002`** 通常会翻译为 `WRONG_METRIC_COUNT_OR_TYPE`，代表指标数量或指标类型不满足当前图表。
+- **`81005`** 通常会翻译为 `CHART_FIELD_ID_REPEAT`，代表某个维度/指标槽位里出现重复 `fieldId`。
+- `diagnostics.next_action` 是下一步修复建议；不要只把裸后端码返回给用户。
+
+### 3.3 应用源报表 vs 数据集报表
+
+- **应用源 BI 报表**：使用 `builder charts apply` 创建/更新，配置里保持 `dataSourceType=qingflow`。
+- **数据集 BI 报表**：当前 CLI 不创建、不编辑；只能在已有报表基础上，用 `builder associated-resource apply` 关联到应用，传 `report_source: "dataset"`。
+- 不要把 dataset 报表的 `chart_id` 交给 `builder charts apply --patch-file` 更新；工具会拒绝，避免误写应用源配置。
+
+---
+
+## 3.4 已有报表局部更新：`patch_charts`
+
+`patch_charts` 用于已有报表的小参数替换，工具会读当前 base/config、合并 `set/unset`，再按后端要求保存整份配置。
+
+```json
+[
+  {
+    "chart_id": "CHART_ID",
+    "set": {
+      "name": "本月工时总览",
+      "visibility": {"mode": "workspace"}
+    }
+  }
+]
+```
+
+- patch 项直接用真实定位字段 `chart_id` + `set` / 可选 `unset`，不要写字面量 `selector` key。
+- 改名称、可见性、筛选、单个 config 片段时优先用 `patch_charts`。
+- 新建或提供完整目标配置才用 `upsert_charts`。
+
+---
+
+## 4. 创建流程（实现摘要）
+
+1. **读** 应用表单 **`fields`** + QingBI datasource **`chart_fields`**；报表维度/指标/筛选/查询条件字段以 **`chart_fields`** 为权威，表单字段只用于补充显示名/类型。
+2. **无 `chart_id` 且无名或名未命中**：**`qingbi_report_create`**（临时 **`chartId`** 形如 **`mcp_<hex>`**），再以 **`chartName`/`chartType`** 做 **读回确认**，得到 **最终 `chart_id`**。  
+3. **有名唯一命中** 或 **`chart_id` 命中**：必要时 **`qingbi_report_update_base`**（改名、类型、**`visibleAuth`**）。  
+4. **新建或 config 有变**：**`qingbi_report_update_config`**（**`_build_public_chart_config_payload`**）；特殊 BI 类型会按上文转换后端字段。
+
+---
+
+## 5. **remove** / **reorder**
+
+- **`--remove-chart-ids-file`**：字符串 id 数组 → **`qingbi_report_delete`**。  
+- 删除成功后工具会用单个 **`chart_id`** 回读验证是否已不存在；**纯删除不会再读全量报表列表**。若返回 **`readback_status: unavailable`** 或 **`still_exists`**，表示删除请求已发出但回读未确认，**不要盲目重复删除**，可稍后用 **`builder chart get --chart-id …`** 确认。
+- **`--reorder-chart-ids-file`**：期望的 **展示顺序前缀**；实现会 **反转** 后调 **`qingbi_report_reorder`**；验证时要求列表 **`chart_list_source == "sorted"`** 且前缀与请求一致。
+
+---
+
+## 6. 响应与排障
+
+| 字段 | 含义 |
+|------|------|
+| **`chart_results[]`** | 每项 **`status`**: **`created`** / **`updated`** / **`removed`** / **`failed`**。 |
+| **`verification.charts_verified`** | 新建/更新/排序通过报表清单回读验证；删除通过单个 **`chart_id`** 回读验证。 |
+| **`partial_success` / `CHART_APPLY_PARTIAL`** | 部分 **`upsert/remove`** 失败。若同时 `write_executed=true` / `write_may_have_succeeded=true`，先读回报表列表，不要整批重试。 |
+| **`CHART_READBACK_PENDING`** | 变更已提交但列表读回未完成。 |
+| **`CHART_DELETE_READBACK_PENDING`** | 删除请求已完成，但单个 **`chart_id`** 回读未确认已删除。 |
+| **`CHART_UPSERT_BATCH_TOO_LARGE`** | 一次 upsert 图表数超过 8；CLI 写前阻断，`write_executed=false`，按 `details.suggested_batch_payloads[]` 分批执行。 |
+| **`chart_results[].readback_status`** | 删除结果专用：**`deleted`** / **`still_exists`** / **`unavailable`**。只要 **`delete_executed=true`**，**`safe_to_retry_delete=false`**，不要直接重复删除。 |
+
+常见问题：**重名**须 **`chart_id`**；**`chart_id` 不存在**；报表字段必须来自 **`app get fields.chart_fields`**，**record schema 可见** 或 **普通表单 fields 可见** 不等于 QingBI 可用；系统字段如 **申请人/申请时间/编号** 只有出现在 **`chart_fields`** 时才可用于报表；字段标题重复时用 **`bi_field_id`** 或 **`field_queId`** 精确指定；**子表等**类型是否可做维度/指标以后端为准。
+
+`CHART_APPLY_PARTIAL` 恢复规则：
+
+- 先看 `details.failed_chart_names`、`details.failed_delete_chart_ids` 和 `details.readback_first`。
+- 若 `details.readback_first=true`，先 `builder app get --app-key <APP_KEY> charts` 或 `chart get` 确认哪些报表已经存在/已更新。
+- 只重试 `details.suggested_retry_payload` 里的失败项；不要重放原始 `upsert_charts` 全量数组。
+- 如果失败项已经在读回中存在但配置未确认，按失败项名称或 `chart_id` 做一次最小 patch。
+
+`CHART_UPSERT_BATCH_TOO_LARGE` 处理规则：
+
+- 这是写前阻断，不是后端失败；`write_executed=false`，可以安全按建议重试。
+- 直接复制执行 `details.suggested_batch_payloads[]`，每次只跑一个 payload。
+- 不要改报表名称、不要拆成单个图表反复试、不要重放原始大数组。
+
+---
+
+## 7. 示例文件（可复制）
+
+- **目标图（契约极简）**：[charts_upsert_minimal.example.json](./charts_upsert_minimal.example.json)  
+- **柱状（须替换 `field_id`）**：[charts_upsert_bar.example.json](./charts_upsert_bar.example.json)  
+- **重排**：[charts_reorder.example.json](./charts_reorder.example.json)  
+- **删除**：[charts_remove.example.json](./charts_remove.example.json)
+
+---
+
+## 8. 本环境实测（`ead8ims5i401`）
+
+| 操作 | 载荷要点 | 结果 |
+|------|-----------|------|
+| 新建 **bar** | **`group_by`: [`状态`]**，**`metric`: `sum(金额)`** | **`chart_id`: `mcp_3a35981aff4f4f57`**，`status: created`，**`verified: true`** |
+| **更新** | 同上 id，**`name`** 改为 **`CLI图表探针_柱状_已改名`**，补 **`visibility`** workspace | **`status: updated`**，**`verified: true`** |
+| **reorder** | **`[mcp_3a35981aff4f4f57, mcp_fb104267c5c249ca]`** | **`success`**，**`chart_order_verified: true`** |
+
+（环境中另有早期探针 **`mcp_fb104267c5c249ca`（target）**，供门户 **`chart_ref`** 使用。）
+
+---
+
+## 9. 交叉引用
+
+- [SKILL.md](../SKILL.md)  
+- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)  
+- [QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md)（**`chart_ref`**）  
+- [QINGFLOW_CLI_FIELD_DATA_TYPES.md](./QINGFLOW_CLI_FIELD_DATA_TYPES.md)（成员侧 **`kind`** 与搭建 **`type`** 对照理解业务）

package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md

@@ -0,0 +1,137 @@
+# Builder 字段匹配规则：按钮传参与关联视图/报表筛选
+
+本文只适用于 **Builder 侧 MatchRule**：
+
+- `builder button apply` 的新增数据按钮传参
+- `builder associated-resource apply` 的关联视图 / 关联报表筛选条件
+
+它不是 `record_access` 分析筛选 DSL，也不是普通视图 `filters`。
+
+统一语义：
+
+- 固定筛选用 `field_name + operator + value/values`，例如视图 `filters`、报表 `filters`。
+- 当前记录上下文匹配用 `target_field + operator + source_field/value`，例如关联资源 `match_mappings`、新增数据按钮传参。
+- 不要直接写 `judgeType`、`judgeValues`、`matchRules`；CLI 会按目标协议自动编译。
+- 单选 / 多选 / 布尔这类选项值，入参可写选项文本或 option id；视图 / 按钮 / 工作流路径会编译成 Qingflow 需要的 id + details，QingBI 报表路径会编译成 BI 前端需要的文本 `judgeValue`。
+
+---
+
+## 1. 默认写法
+
+优先使用语义化映射，不手写后端 raw `que_relation` / `match_rules`。
+
+### 1.1 新增数据按钮
+
+```json
+[
+  {
+    "client_key": "add_worklog",
+    "button_text": "快捷添加工时",
+    "trigger_action": "addData",
+    "trigger_add_data_config": {
+      "target_app_key": "WORKLOG_APP",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联员工"},
+        {"source_field": "员工名称", "target_field": "员工姓名"}
+      ],
+      "default_values": {
+        "状态": "待提交"
+      }
+    }
+  }
+]
+```
+
+`field_mappings` 表示从当前记录动态带值；`default_values` 只表示静态默认值。
+
+### 1.2 关联视图 / 报表
+
+跨应用关联必须显式传 `target_app_key`。若关联的是当前应用自己的视图或报表，可以省略 `target_app_key`，CLI 会默认使用命令里的 `--app-key`。
+
+```json
+[
+  {
+    "client_key": "employee_worklogs",
+    "graph_type": "view",
+    "target_app_key": "WORKLOG_APP",
+    "view_key": "WORKLOG_VIEW",
+    "match_mappings": [
+      {"target_field": "关联员工", "source_field": "数据ID"},
+      {"target_field": "状态", "value": "待提交"}
+    ]
+  }
+]
+```
+
+动态条件用 `source_field`；静态条件用 `value`。
+
+`operator` 推荐使用 `eq` / `neq` / `in` / `contains` / `gte` / `lte` / `is_empty` / `not_empty`；兼容 `equal` / `equals` / `=` / `!=` / `any_of` / `one_of` / `empty` 等别名。`field_name` / `field` 可作为 `target_field` 别名；静态单值可写 `value`，也兼容单元素 `values`。
+
+示例：
+
+```json
+{"target_field": "客户ID", "operator": "eq", "source_field": "数据ID"}
+{"target_field": "状态", "operator": "eq", "value": "有效"}
+```
+
+---
+
+## 2. 系统字段
+
+系统字段可以参与匹配：
+
+| 写法 | field_id | 含义 |
+| --- | --- | --- |
+| `数据ID` / `row_record_id` / `apply_id` / `_id` | `-17` | 当前记录真实 record/apply ID |
+| `编号` / `数据编号` / `record_number` | `0` | 前端可见数据编号，可能是自定义编号 |
+
+也可以显式写：
+
+```json
+{"source_field": {"field_id": -17}, "target_field": "关联员工"}
+```
+
+注意：`数据ID` 和 `编号` 不是同一个东西。要把当前记录填入目标引用字段时，用 `数据ID`。
+
+---
+
+## 3. 类型兼容规则
+
+| 目标 / 源字段类型 | 可匹配对象 |
+| --- | --- |
+| 引用字段 | 同目标应用的引用字段，或当前源应用记录的 `数据ID(-17)` |
+| `数据ID(-17)` | 指向当前源应用的目标引用字段；也可匹配 ID 兼容的文本/数字字段 |
+| `编号(0)` | 文本、长文本、数字、金额、编号类字段 |
+| 成员字段 | 成员字段 |
+| 部门字段 | 部门字段 |
+| 单选 / 多选 / 布尔 | 选项类字段或静态选项值 |
+| 日期 / 日期时间 | 日期类字段互通 |
+| 文本 / 长文本 / 电话 / 邮箱 | 文本类字段互通 |
+| 数字 / 金额 | 数值类字段互通 |
+
+附件、子表、代码块、Q-Linker、地址字段默认不作为匹配字段。
+
+---
+
+## 4. 常见错误处理
+
+| 错误场景 | 下一步 |
+| --- | --- |
+| 字段不存在 | 重新 `builder app get --app-key APP_KEY fields` / `builder app get --app-key APP_KEY`，用准确字段标题或 `field_id` |
+| 类型不兼容 | 按上表换兼容的源字段 / 目标字段 |
+| 引用来源不一致 | 目标引用字段指向了别的应用；换成指向当前源应用的引用字段 |
+| 同时传 semantic 与 raw | 同一项里只能二选一：`field_mappings/match_mappings` 或 raw `que_relation/match_rules` |
+
+---
+
+## 5. 关联资源 ID 口径
+
+`associated_item_id` 是应用级关联资源池里的 `form_asos_chart.id`，最终口径来自：
+
+```bash
+qingflow --json builder app get --app-key APP_KEY
+```
+
+或同等 `app_get.associated_resources[].associated_item_id`。
+
+它不是 `chart_id`、`chart_key`、`view_key`。但新版 `builder associated-resource apply` 在部分入口可接受 `chart_id` / `chart_key` / `view_key` 作为 selector，并自动解析成后端需要的 `associated_item_id`；写 view config 或排障时仍以读回的 `associated_item_id` 为准。

package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md

@@ -0,0 +1,263 @@
+# Builder 门户创建与变更 SOP：`qingflow builder portal`
+
+搭建侧稳定入口：**`qingflow builder portal`**：`list` / `get` / **`apply`** / **`delete`**（与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同，见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**）。
+
+实现要点来自 CLI 打包内的 `builder_facade/models.py`（`PortalApplyRequest`、`PortalSectionPatch`）、`builder_facade/service.py`（`portal_apply` / `portal_delete`）、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**：**新建**（`--no-publish`）、**`--publish` 更新**（网关 **503** 恢复后已重试成功）、**五类区块可稳定落库**；**`filter`（`type:6`）经 CLI 直传未落库** 见 **§3.4 / §8**。另已对测试包 **`1414907`** 实跑 **`portal delete`**：临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
+
+> **权限**：**更新**需 **`edit_portal`**；**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**，不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
+
+> **契约**：`qingflow --json builder contract --tool-name portal_apply`；删除契约：`qingflow --json builder contract --tool-name portal_delete`
+
+---
+
+## 1. 读：`list` → `get`
+
+```bash
+qingflow --json builder portal list > tmp/builder_portal_list.json
+
+qingflow --json builder portal get --dash-key "<DASH_KEY>" > tmp/builder_portal_get.json
+qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
+```
+
+- **`list`** 可能带 **`PORTAL_PERMISSION_READ_UNAVAILABLE`**，**`verified: false`** 仍可能有可用 **`items[]`**。
+- **`get`**：**`--dash-key`** 必填；默认 **`--being-draft`** 为草稿。
+
+---
+
+## 2. 写：`apply` 两种模式（互斥）
+
+**不可同时**出现 **`--dash-key`** 与 **`--package-id`**。
+
+| 模式 | 必备参数 | 含义 |
+|------|----------|------|
+| **新建** | **`--package-id`** + **`--dash-name`** | **`--sections-file` 须非空**。 |
+| **更新** | **`--dash-key`** | 不要带 **`package_id`**。 |
+
+| 参数 | 说明 |
+|------|------|
+| **`--publish` / `--no-publish`** | 默认 **`--publish`**。仅 **`--no-publish`** 时不会调用发布接口；契约说明 **`publish=false` 不宣称线上已变**。 |
+| **`--payload-file`** | 完整门户 JSON 对象；**标准字段写 `dash_name`**。新版 CLI 兼容 **`name -> dash_name`**、单页 **`pages[0].components -> sections`**，但 agent 默认不要依赖兼容别名。 |
+| **`--sections-file`** | JSON **数组**；**全量替换**。省略时仅改基础信息，且 **`hide_copyright` / `dash_global_config` / `config`** 不能单独提交（**`PORTAL_SECTIONS_REQUIRED`**）。 |
+| **`--layout-preset`** | 可选：**`auto` / `dashboard_2col` / `dashboard_3col`**。当区块未显式写 **`position`** 时由工具生成大屏布局。 |
+| **`--visibility-file`** | 与 **`--auth-file`** 不能同时用。 |
+| **`--icon`** / **`--color`** | 新建门户必须显式传合法的非 `template` 图标和颜色；候选用 `qingflow --json builder icon catalog`。编辑已有门户时省略则保留现状。 |
+| **`--hide-copyright`** / **`--dash-global-config-file`** / **`--config-file`** | 见契约；部分键 **依赖与 `sections` 同批提交**。 |
+
+**图标规则**：CLI 不按门户名自动猜图标；智能体需要自行选择业务贴合的 `icon + color`。读回结果里的 `icon_config` 可直接用于前端资源卡片展示。
+
+---
+
+## 3. `sections[]`：六类组件与回读 `type`
+
+### 3.1 公共键
+
+- **`title`**（必填）、**`source_type`**（必填，小写）、可选 **`position`**（**`pc`/`mobile`** 各 **`x,y,cols,rows`**；省略则由**实现自动排布**）。
+- **`config`**、**`dash_style_config`**：按类型 Optional。默认只写 snake_case 规范键。
+
+### 3.1.0 Payload 字段口径
+
+推荐完整 payload 直接使用 CLI 标准键：
+
+```json
+{
+  "dash_name": "产品研发数据大屏",
+  "package_id": 1414909,
+  "layout_preset": "dashboard_2col",
+  "pages": [
+    {
+      "title": "研发总览",
+      "components": [
+        {
+          "title": "部门分布",
+          "source_type": "chart",
+          "chart_ref": {"app_key": "APP_KEY", "chart_id": "CHART_ID"}
+        }
+      ]
+    }
+  ]
+}
+```
+
+`name` 只是兼容别名；如果遇到旧版 CLI 报 **`name Extra inputs are not permitted`**，不要反复重试，改成 **`dash_name`** 或升级 CLI。
+
+### 3.1.1 布局硬规则：PC 24 栅格，mobile 6 栅格
+
+**门户 PC 端不是 12 栅格，而是 24 栅格。**如果把两列写成 **`x=0/6, cols=6`**，所有组件只会占左半屏，工具会返回 **`PORTAL_LAYOUT_HALF_WIDTH`**。
+
+推荐：
+
+| 场景 | PC 写法 |
+|------|---------|
+| 不确定布局 | **省略 `position`**，或传 **`--layout-preset auto`** |
+| 两列可视化图表 | **`x=0/12, cols=12`**，图表 **`rows >= 7`** |
+| 三列可视化图表 | **`x=0/8/16, cols=8`**，图表 **`rows >= 7`** |
+| 四个指标卡 | **`x=0/6/12/18, cols=6, rows=5`** |
+| 具体数据视图 / 明细表 | 优先 **`cols=12`** 或 **`cols=24`**，视图 **`rows >= 11`** |
+
+mobile 写法固定按 **6 栅格**：通常 **`x=0, cols=6`**。如果只写了 PC position，CLI 会自动补 mobile position，并返回 **`PORTAL_MOBILE_POSITION_MISSING`** 提醒。
+
+图表卡片过小时会返回 **`PORTAL_CHART_CARD_TOO_SMALL`**；指标卡按 **`pc.cols >= 6, pc.rows >= 5`** 校验，普通可视化图表按 **`pc.cols >= 8, pc.rows >= 7`** 校验。指标区图表建议写 `role: "metric"`；此时必须引用 `target` / `indicator` 图表，否则返回 **`PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH`**，应先用 `app_charts_apply` 创建缺失指标卡再组门户。标准工作台数量也会进入 `layout_diagnostics.standard_template_counts`：指标卡推荐 4-6 个、BI 图表 2-3 个、业务视图 1-2 个，超出或不足会返回 `PORTAL_STANDARD_*_COUNT_OUT_OF_RANGE`。
+
+### 3.1.2 推荐门户模板：业务工作台
+
+默认按 **业务入口 → 核心指标 → BI 可视化 → 业务视图** 搭建。门户首屏应直接呈现可用工作台，不要做营销页、说明页或大面积装饰区。
+
+| 区域 | 推荐组件 | PC 布局 | 要点 |
+|------|----------|---------|------|
+| 顶部业务入口 | **`grid`** + 可选 **待办 `task`** | `grid x=0,y=0,cols=12,rows=4`；待办 `x=12,y=0,cols=12,rows=4` | `grid` 放 2-6 个核心业务入口；待办用于当前用户任务概览。当前公开 `portal apply --sections-file` 暂未支持 `source_type=task`，不要伪造；见下方边界说明。 |
+| 核心指标 | **`chart`** 指标卡 + `role: "metric"` | 4 张：`x=0/6/12/18,y=4,cols=6,rows=5` | 指标卡推荐高度 **5**。24 栅格下单卡最小 `cols=6`，所以一行 4 张最稳；如果要 5 个指标，拆成两行。 |
+| BI 可视化 | **`chart`** 图表 | 3 张：`x=0/8/16,y=9,cols=8,rows=7`；或 2 张：`x=0/12,cols=12,rows=7` | 可视化图表推荐高度 **7**，一行 2-3 个，1-2 行。 |
+| 业务数据视图 | **`view`** | `x=0/12,y=16,cols=12,rows=11`；或单表 `cols=24,rows=11` | 数据视图推荐高度 **11**，一行 1-2 个，1-2 行。只挂业务视图，不要创建或引用默认的 **全部数据 / 我的数据** 当主门户视图。 |
+
+mobile 固定按 **6 栅格** 从上到下堆叠：通常所有组件 `x=0, cols=6`，`y` 按 PC 顺序递增。若顶部同时有 `grid + task`，mobile 建议先业务入口 `y=0,rows=4`，再待办 `y=4,rows=4`，核心指标从 `y=8` 开始；若当前公开 CLI 只能写 `grid`，核心指标可从 `y=4` 开始。
+
+**当前工具边界**：
+
+- 公开 `sections-file` 稳定支持：**`grid` / `chart` / `view` / `text` / `link`**；`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理，不作为主路径。
+- **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状，不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`；只有工具后续显式支持 `task`，或维护者走 raw 门户写入链路时，才使用待办槽位。
+- 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)**。该示例使用当前公开 CLI 可稳定写入的组件，顶部先用一个业务入口 `grid` 占满 24 栅格；如果工具已支持待办组件，再把顶部拆成 `grid cols=12 + task cols=12`。
+- `grid` 必须写 **`config.items[]`**；只写 `gridTitle` / `beingShowTitle` 会生成空入口容器，工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
+
+**待办组件 raw 形状参考**（仅用于工具实现对齐，当前不要作为 `--sections-file` 输入）：
+
+```json
+{
+  "type": 8,
+  "position": {
+    "pc": {"x": 12, "y": 0, "cols": 12, "rows": 4},
+    "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 4}
+  },
+  "taskConfig": {
+    "beingShowTitle": true,
+    "componentTaskTitle": "待办",
+    "beingShowHint": true,
+    "componentTaskHint": "及时处理待办，可以有效提升流程效率",
+    "dashTaskConfigList": [
+      {"type": 1, "title": "all.taskTodo", "beingCheck": true, "ordinal": 0},
+      {"type": 2, "title": "all.taskTimeout", "beingCheck": true, "ordinal": 1},
+      {"type": 3, "title": "all.taskUpcomingTimeout", "beingCheck": true, "ordinal": 2},
+      {"type": 4, "title": "all.taskRemind", "beingCheck": true, "ordinal": 3}
+    ]
+  }
+}
+```
+
+### 3.2 `source_type` ↔ 回读 `components[].type`（搭建侧）
+
+| `source_type` | 回读 `type`（数字） | 搭建侧含义 |
+|---------------|---------------------|------------|
+| **`chart`** | **9** | QingBI 图表块 |
+| **`view`** | **10** | 应用视图块 |
+| **`grid`** | **2** | 九宫格 |
+| **`filter`** | **6** | 筛选条 |
+| **`text`** | **5** | 富文本说明 |
+| **`link`** | **4** | 外链 |
+
+CLI 校验（`PortalSectionPatch`）：**chart** 须 **`chart_ref`**；**view** 须 **`view_ref`**；**text** 须 **`text`**；**link** 须 **`url`**。**grid** / **filter** 无额外 ref，**`config` 形状由后端接受为准**。
+
+### 3.3 **`chart`**：几乎总须 **`builder charts apply` 先建报表**
+
+- `portal` 只做 **`chart_ref` 解析**（`app_key` + **`chart_id`** 优先，否则 **唯一 `chart_name`**）。
+- 若 **`builder app get charts`** 为空，先 **`builder charts apply --app-key … --upsert-file`** 创建（契约 **minimal_example** 如 **`target` + `indicator_field_ids: []`**），从响应 **`chart_results[].chart_id`** 取 id 再写 **`chart_ref`**.
+
+### 3.4 **`filter`**：`config` **整包**即接口里的 **`filterConfig`**
+
+实现：组件为 **`{"type": 6, "filterConfig": deepcopy(section.config)}`**。
+
+- **理论上**与 solution 编译器一致：外层 **`{"filterConfig": [ … ], "graphList": [ … ]}`**；**`graphList`** 常含 **`graphType`**（如 **`CHART`**）、**`graphKey`** 或 **`graphRef`（`entity_id` / `chart_id`）** 等。
+- **本环境 CLI 直写实测（多次 `--publish`）**：在已验证 **chart / view / grid / text / link** 均可落库的前提下，**`source_type: filter` 始终未出现在 `draft_result.components` 中**；尝试过：**空数组**、**仅 `graphList` + QingBI `chart_id`**、**`graphKey` 为门户 `dashChartId`**、**`chart` 排在 **`filter` 前**、**仅 2 块（chart+filter）** 等，回读仍 **只有 chart（`count: 1`）** 或 **五类缺 `type: 6`**。  
+  **结论**：当前宜 **在搭建界面创建筛选条**，再 **`builder portal get` 反抓** 原始 `filterConfig` 形状；或向后端确认 **POST `/dash/{dashKey}`** 对 **`type: 6`** 的必填字段。**自动化不要默认认为 `filter` 已写入。**
+- portal `filter` 组件仍按 raw `filterConfig` 处理，不纳入视图 / 报表 / 关联资源的统一筛选 DSL 主链路。
+
+### 3.5 **`grid` / `text` / `link` / `view`**
+
+- **grid**：**`config`** 并入 **`gridConfig`**；业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`。空 `config` 或空 `items` 只会生成空入口容器，并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
+- **text** / **link**：**`text`** / **`url`** 必填。
+- **view**：**`view_ref`**；**`view_key`** 来自 **`builder app get views`**。
+
+---
+
+## 4. 前置数据
+
+| 目的 | 命令 |
+|------|------|
+| **`package_id`** | **`builder app resolve --app-key …`** → **`package_ids`** |
+| **`view_key`** | **`builder app get --app-key … views`** |
+| **`chart_id`** | **`builder app get charts`** 或 **`charts apply` 创建** |
+
+---
+
+## 5. 新建最小例（`--no-publish`）
+
+见上文 **§2** 与 **`visibility`** 最小对象；**`sections`** 可先用 **单块 `view`**。成功后拿 **`dash_key`** 再 **更新 / 发布**。
+
+---
+
+## 6. 更新与替换语义
+
+- **`--dash-key`** + **`--sections-file`**：**列表即全量**；没写进去的区块会被拿掉。
+- 仅改 **可见性 / 图标 / 分组**：**不传 `--sections-file`**，且不要单独带 **§2** 所列「仅在有 sections 时允许」的键。
+
+---
+
+## 7. 删除：`delete`
+
+```bash
+qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_portal_delete.json
+```
+
+- **只按 `dash_key` 删除一个门户**；先用 `builder portal list/get` 确认目标，不要按名称猜。
+- 返回成功时重点看：**`delete_executed`**、**`readback_status`**、**`safe_to_retry_delete`**、`summary.removed`。
+- **`delete_executed=true` + `readback_status=deleted`**：删除已执行且回读确认不存在。
+- **`delete_executed=true` + `readback_status=unavailable|still_exists`**：DELETE 已发出，但回读不可确认或短时间仍存在；**不要盲目重复删除**，稍后用 `builder portal get/list` 确认。
+- DELETE 本身失败时才按 `status=failed` / `error_code` 处理。
+
+---
+
+## 8. **发布**（`--publish`）
+
+- **默认会发布**：未显式 **`--no-publish`** 即 **`publish: true`**；公开入口仍是 **`portal_apply`**，发布动作由工具内部执行并回读 **`being_draft=false`**。
+- **已发布线索**：成功路径上 **`published: true`**；**`live_result.publishStatus`** 常见 **`2`** 表示已发布（以你环境枚举为准）。
+- **`partial_success` + `PORTAL_READBACK_PENDING`**：草稿/线上 **组件数量或元数据** 与「本次期望」不一致时会出现；**`PORTAL_*_VERIFICATION_INCOMPLETE`** 警告。应 **`builder portal get --dash-key …`**（草稿与 **`--no-being-draft` 线上**）**肉眼核对**区块是否齐全，而不是仅信 **`verified: true`**。
+- **网关 503**：**与 CLI 无关**；环境恢复后重试 **`portal get` / `portal apply`**。（本轮在网关恢复后 **`portal apply` 已成功**。）
+
+---
+
+## 9. 本环境实测摘要
+
+| 步骤 | 命令要点 | 结果 |
+|------|-----------|------|
+| 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、`--no-publish`、单 **view** | **`dash_key`: `ecdcell64s02`** |
+| 补报表 | **`builder charts apply`**，`name: 门户探针_目标图`，**`target`** | **`chart_id`: `mcp_fb104267c5c249ca`** |
+| 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**；**`filter` 仍不落库** → **`partial_success`**，**`components expected 6, got 5`**（与 **§3.4** 一致） |
+| **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块（仅 `type: 9`）** |
+| **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](./portal_sections_five_types.example.json)**（**grid / text / link / view / chart**） | **`status: success`**，**`types: [2,4,5,9,10]`**，**`published: true`** |
+| 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**，**`delete_executed: true`**，**`readback_status: deleted`**，**`summary.removed: 1`** |
+
+**推荐工作台模板示例**：[portal_sections_standard_workbench.example.json](./portal_sections_standard_workbench.example.json)
+
+**含 `filter` 的六类示例（`filter` 是否落库视环境/后端而定）**：[portal_sections_all_types.example.json](./portal_sections_all_types.example.json)
+
+---
+
+## 10. 排障
+
+| 现象 | 处理 |
+|------|------|
+| `portal apply accepts exactly one selector mode` | **`dash-key`** vs **`package-id`** 二选一。 |
+| `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件；若多写了 **`filter`** 而回读少一块，见 **§3.4**（**CLI 写 filter 可能整体不生效**）；也可能是 **异步回读**，可再 **`get`** 一次。 |
+| **`published: true` 但 `verified: false`** | 读 **§7**；用 **`get` 草稿+线上**对照。 |
+| **503** | 网关/运维；稍后重试。 |
+| 缺 **chart** | **[QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)**：`builder charts apply`；或换有报表的应用。 |
+| **VISIBILITY_CONFLICT** | 只用 **`--visibility-file`**。 |
+| `delete_executed=true` 但 `readback_status=unavailable|still_exists` | DELETE 已发出，回读未确认；不要重复删除，稍后 `builder portal get/list` 复核。 |
+
+---
+
+## 11. 交叉引用
+
+- [SKILL.md](../SKILL.md)
+- [QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md)
+- [QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md)
+- [QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md](./QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md)
+- [QINGFLOW_CLI_EXPLORATION_REPORT.md](./QINGFLOW_CLI_EXPLORATION_REPORT.md)