@qingflow-tech/qingflow-cli 1.1.61 → 1.1.62

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 (81) hide show
  1. package/README.md +3 -3
  2. package/package.json +1 -1
  3. package/pyproject.toml +3 -1
  4. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +1 -1
  5. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +6 -258
  6. package/skills/qingflow-cli/reference/builder/20-build-complete-system.md +2 -2
  7. package/skills/qingflow-cli/reference/builder/30-schema-fields.md +22 -5
  8. package/skills/qingflow-cli/reference/builder/70-portal.md +71 -36
  9. package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md +3 -3
  10. package/skills/qingflow-cli/reference/examples/portal/portal_apply_v1alpha1.example.json +100 -0
  11. package/skills/qingflow-cli/reference/examples/portal/portal_sections_all_types.example.json +6 -7
  12. package/src/qingflow_mcp/app_form_compat.py +3 -0
  13. package/src/qingflow_mcp/app_form_validator.py +89 -20
  14. package/src/qingflow_mcp/builder_facade/app_form.py +629 -112
  15. package/src/qingflow_mcp/builder_facade/models.py +197 -15
  16. package/src/qingflow_mcp/builder_facade/portals_schema.py +397 -0
  17. package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json +15 -1
  18. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/complete.json +112 -38
  19. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/address.json +31 -8
  20. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_classification.json +146 -0
  21. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_extraction.json +146 -0
  22. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_content_generation.json +146 -0
  23. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_document_parsing.json +146 -0
  24. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_generation.json +146 -0
  25. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_image_recognition.json +146 -0
  26. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_machine_translation.json +146 -0
  27. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ai_text_summary.json +146 -0
  28. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/amount.json +6 -10
  29. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/attachment.json +33 -10
  30. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/code_block.json +6 -10
  31. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/data_relation.json +11 -18
  32. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date.json +4 -8
  33. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/date_duration.json +146 -0
  34. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/datetime.json +4 -8
  35. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/department.json +6 -10
  36. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/email.json +4 -8
  37. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/embed_field.json +146 -0
  38. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/image_select.json +146 -0
  39. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/link.json +4 -8
  40. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/location.json +146 -0
  41. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/long_text.json +4 -8
  42. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/member.json +6 -10
  43. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/multi_select.json +4 -8
  44. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/number.json +6 -10
  45. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/ocr.json +146 -0
  46. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/phone.json +4 -8
  47. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/q_linker.json +8 -12
  48. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/relation.json +73 -15
  49. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/rich_text.json +146 -0
  50. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_choice.json +4 -8
  51. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_select.json +4 -8
  52. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/subtable.json +90 -29
  53. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/text.json +4 -8
  54. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/formula.json +43 -0
  55. package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/summary.json +27 -19
  56. package/src/qingflow_mcp/builder_facade/schemas/portals/manifest.json +59 -0
  57. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/complete.json +1397 -0
  58. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/carousel.json +193 -0
  59. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/chart.json +643 -0
  60. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/favourite.json +203 -0
  61. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/filter.json +249 -0
  62. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/grid.json +265 -0
  63. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/link.json +131 -0
  64. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/task.json +199 -0
  65. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/text.json +123 -0
  66. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/components/view.json +196 -0
  67. package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/summary.json +800 -0
  68. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/complete.json +1 -1
  69. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/display.json +1 -1
  70. package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/summary.json +1 -1
  71. package/src/qingflow_mcp/builder_facade/service.py +1359 -92
  72. package/src/qingflow_mcp/cli/commands/builder.py +120 -5
  73. package/src/qingflow_mcp/public_surface.py +2 -0
  74. package/src/qingflow_mcp/server_app_builder.py +34 -5
  75. package/src/qingflow_mcp/session_store.py +14 -1
  76. package/src/qingflow_mcp/solution/compiler/icon_utils.py +73 -0
  77. package/src/qingflow_mcp/solution/executor.py +5 -2
  78. package/src/qingflow_mcp/tools/ai_builder_tools.py +118 -20
  79. package/src/qingflow_mcp/tools/portal_tools.py +4 -54
  80. package/src/qingflow_mcp/tools/portal_writer.py +59 -0
  81. package/src/qingflow_mcp/tools/solution_tools.py +2 -0
@@ -11,13 +11,26 @@ Not responsible for: creating apps or views referenced by the portal. Create or
11
11
  ## Main chain
12
12
 
13
13
  ```text
14
- portal list/get if updating -> verify apps/views and read chart lists only when reusing existing charts -> portal apply with sections[].chart -> portal get readback -> publish state
14
+ portal list/get if updating -> verify apps/views and read chart lists only when reusing existing charts
15
+ -> (offline) builder portal validate --file decl.json
16
+ -> builder portal apply --file decl.json [--schema-version v1alpha1]
17
+ -> builder portal get --dash-key K --schema-kind summary|complete (readback) -> publish state
15
18
  ```
16
19
 
20
+ ## Versioned schema and declaration files
21
+
22
+ - Declarations are versioned: `schema_version` (default `v1alpha1`), `apiVersion: builder.qingflow.com/v1alpha1`. The envelope echoes `schemaVersion` when you pass `--schema-version`.
23
+ - Two document kinds: **summary** = name + layout + component list (five stable component types: `chart/view/grid/text/link`); **complete** = summary superset with global config (`icon/color/hide_copyright/global_config/style_template_id/overall_style`), nine component types (adds `filter/carousel/task/favourite`), component `style_config`, and `visibility` authorization.
24
+ - Read the contract itself: `qingflow --json builder portal schema --schema-kind summary|complete|<component>`; every component type (`chart|view|grid|filter|text|link|carousel|task|favourite`) has a self-contained schema — fetch it before guessing config keys.
25
+ - `builder portal get` defaults to `--schema-kind summary` and returns a canonical `declaration` (the round-trip anchor for replay tooling). Use `--schema-kind raw` for the legacy normalized response and `--schema-kind complete` for the full declaration.
26
+ - Offline validation: `qingflow --json builder portal validate --file decl.json` (accepts `-` for stdin; zero backend calls). Fix issues before applying.
27
+ - Apply main form: `qingflow builder portal apply --file decl.json --schema-version v1alpha1` (apply always publishes automatically; there is no draft-only mode). Legacy patch parameters (`--sections-file`, `--visibility-file`, ...) still work in a compatibility window but emit a deprecation notice; do not use them in new automations. `--payload-file` (raw DTO passthrough) is legacy-only.
28
+
17
29
  ## Demo files
18
30
 
19
31
  | Scenario | Example |
20
32
  |----------|---------|
33
+ | Recommended v1alpha1 declaration (`--file`) | [portal_apply_v1alpha1.example.json](../examples/portal/portal_apply_v1alpha1.example.json) |
21
34
  | Recommended business workbench | [portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json) |
22
35
  | Stable component capability probe | [portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json) |
23
36
  | Raw/experimental all-types probe | [portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json) |
@@ -34,7 +47,7 @@ Start from the portal job, then choose the section strategy. A portal is an asse
34
47
  | Show BI visualizations | Use chart sections | `rows=7`; same-row components share the same `rows` |
35
48
  | Show concrete data views | Use view sections | Use business views, not `全部数据` / `我的数据`; `rows=11` |
36
49
  | Update one existing portal block | Prefer `patch_sections[]` | Do not replace the whole `sections` list unless intentional |
37
- | Need a filter bar | Avoid automation by default | `source_type: "filter"` is raw/unstable and not part of the unified filter DSL |
50
+ | Need a filter bar | Use `source_type: "filter"` with non-empty `config.rules` | Empty-rules filters are rejected (backend read face enumerates filter components by their rule groups); see §3.4 |
38
51
 
39
52
  Short rule: **portal rows are 24-grid layout rows, not form-field rows. Same `y` = same row, same `rows`, `cols` sum 24.**
40
53
 
@@ -50,7 +63,7 @@ Before `portal apply`, verify this short list:
50
63
  | Standard heights | Metric cards `rows=5`; BI charts `rows=7`; data views `rows=11`. Do not mix different heights in one row. |
51
64
  | Standard order | Business entry -> metrics -> BI charts -> data views. Do not put data views before metrics/charts in a dashboard-style portal. |
52
65
  | Default/system views | Do not use `全部数据` / `我的数据` as the main business portal views. Use concrete business views. |
53
- | Filter component | Do not use `source_type: "filter"` as the main automation path; it is raw/unstable and not part of the unified filter DSL. |
66
+ | Filter component | `config.rules` must contain at least one rule group (empty-rules filters are written but invisible in readback; blocked at validation). Rule keys: filterGroupName/filterGroupConfig/filterItemName/que/judge, see §3.4. |
54
67
  | Readback | After apply, run `portal get` and compare section count, refs, and positions before claiming frontend visibility. |
55
68
 
56
69
  Inline QingBI chart creation uses one chart job per section and runs with an internal concurrency limit of 10. If two sections declare the same `app_key + name + chart_type` with identical config, CLI creates/updates once and reuses the chart id. If their config differs, CLI rejects the portal write as a duplicate inline chart conflict.
@@ -66,8 +79,9 @@ Recommended standard workbench skeleton:
66
79
 
67
80
  ## Update existing portal
68
81
 
69
- - Use `--dash-key` for updates and do not send `package_id`.
70
- - Use `patch_sections[]` for targeted section changes when possible.
82
+ - Prefer the declaration-file form: `builder portal apply --file decl.json --schema-version v1alpha1 --dash-key K` (the file may omit `dash_key` and pass it via `--dash-key`; do not send `package_id` for updates; apply publishes automatically).
83
+ - Read the current declaration first with `builder portal get --dash-key K --schema-kind complete`, edit it, `builder portal validate --file`, then apply. `sections` is full-replace semantics.
84
+ - `patch_sections[]` (via `--patch-sections-file`, compatibility window) remains for targeted section changes when a full declaration round-trip is not practical.
71
85
  - `patch_sections[]` selectors may use `order`, `chart_ref.chart_id`, `chart_ref.chart_key`, or `view_ref.view_key`; chart sections read back from portal often only include `chart_id`, so patching by `chart_id` is valid and does not require `app_key`.
72
86
  - If using a business-entry grid, include real `items`; do not submit an empty entry container.
73
87
  - Validate referenced `chart_key`, `chart_id`, `view_key`, or `app_key` before claiming the portal is complete.
@@ -76,7 +90,7 @@ Recommended standard workbench skeleton:
76
90
 
77
91
  搭建侧稳定入口:**`qingflow builder portal`**:`list` / `get` / **`apply`** / **`delete`**(与根命令 **`qingflow portal`** 的「成员可读列表/详情」不同,见 **[QINGFLOW_CLI_EXPLORATION_REPORT.md](../core/QINGFLOW_CLI_EXPLORATION_REPORT.md) §4.6**)。
78
92
 
79
- 实现要点来自 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`**。
93
+ 实现要点来自 CLI 打包内的 `builder_facade/models.py`(`PortalApplyRequest`、`PortalSectionPatch`)、`builder_facade/service.py`(`portal_apply` / `portal_delete`)、`cli/commands/builder.py`。已对 **`package_id=2030703`**、应用 **`ead8ims5i401`** **实跑**:**新建**、**更新**(网关 **503** 恢复后已重试成功;历史记录中的 `--publish/--no-publish` flag 已移除,apply 一律发布)、**五类区块可稳定落库**;**`filter` 声明式写入受控支持(rules 非空,历史「不落库」实测为空规则读面不可见,见 §3.4)**。另已对测试包 **`1414907`** 实跑 **`portal delete`**:临时门户 **`etcivtmv5402`** 删除后回读 **`readback_status=deleted`**。
80
94
 
81
95
  > **权限**:**更新**需 **`edit_portal`**;**新建**按后端 `DashCtrl.createDash` 链路只预检目标包 **`add_app`**,不额外要求包 **`edit_app`**。失败时参见主技能与 **ADMIN** 速查。
82
96
 
@@ -109,8 +123,9 @@ qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
109
123
 
110
124
  | 参数 | 说明 |
111
125
  |------|------|
112
- | **`--publish` / `--no-publish`** | 默认 **`--publish`**。仅 **`--no-publish`** 时不会调用发布接口;契约说明 **`publish=false` 不宣称线上已变**。 |
113
- | **`--payload-file`** | 完整门户 JSON 对象;**标准字段写 `dash_name`**。新版 CLI 兼容 **`name -> dash_name`**、单页 **`pages[0].components -> sections`**,但 agent 默认不要依赖兼容别名。 |
126
+ | **`--file`**(主形态) | 完整门户声明 JSON 对象(支持 **`-`** stdin);与 patch 参数互斥;声明内可带 **`schema_version`**。 |
127
+ | **`--schema-version`** | 固定声明契约版本(缺省读文件内 `schema_version`,再缺省 latest)。传入时声明先过 complete schema 离线校验,**`INVALID_SPEC` 不写**。 |
128
+ | **`--payload-file`**(旧) | 完整门户 JSON 对象透传(兼容窗口);新代码改用 **`--file`**。标准字段写 `dash_name`。 |
114
129
  | **`--sections-file`** | JSON **数组**;**全量替换**。省略时仅改基础信息,且 **`hide_copyright` / `dash_global_config` / `config`** 不能单独提交(**`PORTAL_SECTIONS_REQUIRED`**)。 |
115
130
  | **`--layout-preset`** | 可选:**`auto` / `dashboard_2col` / `dashboard_3col`**。当区块未显式写 **`position`** 时由工具生成大屏布局。 |
116
131
  | **`--visibility-file`** | 与 **`--auth-file`** 不能同时用。 |
@@ -125,7 +140,7 @@ qingflow --json builder portal get --dash-key "<DASH_KEY>" --no-being-draft
125
140
 
126
141
  ### 3.1 公共键
127
142
 
128
- - **`title`**(必填)、**`source_type`**(必填,小写)、可选 **`position`**(**`pc`/`mobile`** 各 **`x,y,cols,rows`**;省略则由**实现自动排布**)。
143
+ - **`source_type`**(必填,小写)、**`title`**(可选——schema 仅强制 `source_type`;新建组件建议提供标题,存量 filter 组件合法无标题,round-trip 透传不要合成)、可选 **`position`**(嵌套 **`pc`/`mobile`** 各 **`x,y,cols,rows`**;平铺别名 **`pc_x/pc_y/pc_w/pc_h`、`mobile_*`** 也接受,`x/y` 与 `w/h/cols/rows` 混写均认;省略则由**实现自动排布**)。
129
144
  - **`config`**、**`dash_style_config`**:按类型 Optional。默认只写 snake_case 规范键。
130
145
 
131
146
  ### 3.1.0 Payload 字段口径
@@ -198,8 +213,8 @@ mobile 固定按 **6 栅格** 从上到下堆叠:通常所有组件 `x=0, cols
198
213
 
199
214
  **当前工具边界**:
200
215
 
201
- - 公开 `sections-file` 稳定支持:**`grid` / `chart` / `view` / `text` / `link`**;`filter` 仍按 **§3.4** 的 raw `filterConfig` 边界处理,不作为主路径。
202
- - **待办 `task` / 常用 `favorite`** 是前端/后端 raw 组件形状,不在当前公开 `source_type` 合约里。智能体不要在 `sections-file` 中写 `source_type: "task"`;只有工具后续显式支持 `task`,或维护者走 raw 门户写入链路时,才使用待办槽位。
216
+ - 声明式(`--file` / complete 档)支持**九类组件**:**`grid` / `chart` / `view` / `text` / `link`**(summary 档稳定面)+ **`carousel` / `task` / `favourite`**(complete 档,配置键见专项 Schema)+ **`filter`**(complete 档受控承载:`config.rules` 至少 1 组,空规则读面不可见、模型层阻断,见 **§3.4**)。
217
+ - **`task`(一个门户最多 1 个)与 `favourite`(一个门户最多 1 个)** 已进入 v1alpha1 complete 声明面(`task`/`favourite` 类型化 config 键),不要再按后端 raw 形状(`taskConfig`/`favouriteConfig`)手拼;声明形态见 `qingflow --json builder portal schema --schema-kind task|favourite`。旧文档中的「task/favorite 不在公开合约里」已过时。
203
218
  - 推荐门户的可直接 apply 示例见 **[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)**。这是唯一推荐复制的业务工作台布局模板:每一行 `cols_sum=24`,同行 `rows` 一致,下一行 `y` 连续。顶部先用一个业务入口 `grid` 占满 24 栅格;如果工具已支持待办组件,再把顶部拆成 `grid cols=12 + task cols=12`。
204
219
  - **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)** 和 **[portal_sections_all_types.example.json](../examples/portal/portal_sections_all_types.example.json)** 仅用于组件能力探针,不作为业务门户布局模板;搭建正式门户时不要从这些探针推导布局。
205
220
  - `grid` 必须写 **`config.items[]`**;只写 `gridTitle` / `beingShowTitle` 会生成空入口容器,工具会返回 **`PORTAL_GRID_ITEMS_EMPTY`**。
@@ -230,16 +245,21 @@ mobile 固定按 **6 栅格** 从上到下堆叠:通常所有组件 `x=0, cols
230
245
 
231
246
  ### 3.2 `source_type` ↔ 回读 `components[].type`(搭建侧)
232
247
 
233
- | `source_type` | 回读 `type`(数字) | 搭建侧含义 |
234
- |---------------|---------------------|------------|
235
- | **`chart`** | **9** | QingBI 图表块 |
236
- | **`view`** | **10** | 应用视图块 |
237
- | **`grid`** | **2** | 九宫格 |
238
- | **`filter`** | **6** | 筛选条 |
239
- | **`text`** | **5** | 富文本说明 |
240
- | **`link`** | **4** | 外链 |
248
+ | `source_type` | 回读 `type`(数字) | 搭建侧含义 | 声明档 |
249
+ |---------------|---------------------|------------|----------|
250
+ | **`chart`** | **9** | QingBI 图表块 | summary |
251
+ | **`view`** | **10** | 应用视图块 | summary |
252
+ | **`grid`** | **2** | 九宫格 | summary |
253
+ | **`text`** | **5** | 富文本说明 | summary |
254
+ | **`link`** | **4** | 外链 | summary |
255
+ | **`filter`** | **6** | 筛选条 | complete(rules 必须非空) |
256
+ | **`carousel`** | **3** | 轮播(数据源应用 + 标题/图片/链接字段) | complete |
257
+ | **`task`** | **8** | 待办(一个门户最多 1 个) | complete |
258
+ | **`favourite`** | **7** | 收藏(一个门户最多 1 个) | complete |
259
+
260
+ 每类组件的详细配置键经专项 Schema 获取:`qingflow --json builder portal schema --schema-kind <类型>`(如 `--schema-kind carousel`、`--schema-kind task`)。`carousel` 的 `title_field/image_field/link_field` 填字段显示名(CLI 编译为 queId);`task.tasks[].task_type` 取值 1=我的待办 2=已超时 3=即将超时 4=催办 5=我发起的 6=抄送我的 7=草稿箱 8=我的已办 9=待完善;`favourite.items[]` 用 `item_type`(1=应用 2=门户)+`link_key` 锚定目标。
241
261
 
242
- CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或兼容旧字段 **`chart_ref`**;**view** 须 **`view_ref`**;**text** 须 **`text`**;**link** 须 **`url`**。**grid** / **filter** 无额外 ref,**`config` 形状由后端接受为准**。
262
+ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或 **`chart_ref`**;**view** 须 **`view_ref`**;**text** 须 **`text`**;**link** 须 **`url`**;**carousel/task/favourite** 须各自类型化 config 键。**grid** / **filter** 无额外 ref,**`config` 形状由专项 Schema 与后端接受为准**。
243
263
 
244
264
  ### 3.3 **`chart`**:一个字段同时支持引用已有图表和内联创建图表
245
265
 
@@ -271,18 +291,33 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或兼容旧字
271
291
  }
272
292
  ```
273
293
 
274
- ### 3.4 **`filter`**:`config` **整包**即接口里的 **`filterConfig`**
294
+ ### 3.4 **`filter`**:声明式筛选条(支持,**rules 必须非空**)
275
295
 
276
- 实现:组件为 **`{"type": 6, "filterConfig": deepcopy(section.config)}`**。
296
+ 声明形态:**`config.graphs`**(受筛选作用的图表引用)+ **`config.rules`**(筛选规则组,至少 1 组),编译为后端 `ComponentFilter`(`graphList` + `filterConfig`)。规则键集:`filterGroupName`(组名)/`filterGroupConfig`(筛选项:`filterItemName` + `que{queId}` + `judge{judgeType,judgeValues}`);代理键 `filterGroupId`/`filterItemId` 为后端自增位移键,声明里不要携带。
297
+
298
+ ```json
299
+ {
300
+ "source_type": "filter",
301
+ "position": {"pc": {"x": 0, "y": 0, "cols": 24, "rows": 3}},
302
+ "config": {
303
+ "graphs": [{"chart_key": "CHART_KEY_1001"}],
304
+ "rules": [
305
+ {
306
+ "filterGroupName": "区域",
307
+ "filterGroupConfig": [
308
+ {"filterItemName": "城市", "que": {"queId": 123456}, "judge": {"judgeType": 3, "judgeValues": ["上海"]}}
309
+ ]
310
+ }
311
+ ]
312
+ }
313
+ }
314
+ ```
277
315
 
278
- - **理论上**与 solution 编译器一致:外层 **`{"filterConfig": [ … ], "graphList": [ … ]}`**;**`graphList`** 常含 **`graphType`**(如 **`CHART`**)、**`graphKey`** 或 **`graphRef`(`entity_id` / `chart_id`)** 等。
279
- - **本环境 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`**。
280
- **结论**:当前宜 **在搭建界面创建筛选条**,再 **`builder portal get` 反抓** 原始 `filterConfig` 形状;或向后端确认 **POST `/dash/{dashKey}`** 对 **`type: 6`** 的必填字段。**自动化不要默认认为 `filter` 已写入。**
281
- - portal `filter` 组件仍按 raw `filterConfig` 处理,不纳入视图 / 报表 / 关联资源的统一筛选 DSL 主链路。
316
+ **关键边界(旧实测记录的真相)**:`rules` 为空的 filter **会被模型层直接拒绝**——后端读面按筛选组(dash_filter_group 行)反查筛选组件,空规则的组件行虽写入但读面枚举不到,表现为「apply 成功、回读缺 type:6」。历史上「filter 不落库」的实测记录(命令式 raw 直传时代、全部空规则组合)即此机制,不是后端拒绝 type:6。存量筛选组件合法无标题(提取产物不带 `title`,不要合成);round-trip 重放已验证(ws40013 基准 337 个 filter 组件一致率 100%)。专项 Schema:`qingflow --json builder portal schema --schema-kind filter`。
282
317
 
283
318
  ### 3.5 **`grid` / `text` / `link` / `view`**
284
319
 
285
- - **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
320
+ - **grid**:**`config`** 并入 **`gridConfig`**;业务入口必须写 **`config.items[]`**。应用入口项推荐 `{ "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY", "linkFormType": 1, "title": "入口名" }`——**`linkFormType` 缺省时编译器按 1(数据列表)补齐**(缺失会让前端跳转目标为空、入口无法点击);1=数据列表、2=表单页。空 `config` 或空 `items` 只会生成空入口容器,并触发 **`PORTAL_GRID_ITEMS_EMPTY`**。
286
321
  - **text** / **link**:**`text`** / **`url`** 必填。
287
322
  - **view**:**`view_ref`**;**`view_key`** 来自 **`builder app get views`**。
288
323
 
@@ -298,9 +333,9 @@ CLI 校验(`PortalSectionPatch`):**chart** 须 **`chart`** 或兼容旧字
298
333
 
299
334
  ---
300
335
 
301
- ## 5. 新建最小例(`--no-publish`)
336
+ ## 5. 新建最小例
302
337
 
303
- 见上文 **§2** 与 **`visibility`** 最小对象;**`sections`** 可先用 **单块 `view`**。成功后拿 **`dash_key`** 再 **更新 / 发布**。
338
+ 见上文 **§2** 与 **`visibility`** 最小对象;**`sections`** 可先用 **单块 `view`**。apply 一律自动发布,成功后拿 **`dash_key`** 直接迭代更新。
304
339
 
305
340
  ---
306
341
 
@@ -325,9 +360,9 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
325
360
 
326
361
  ---
327
362
 
328
- ## 8. **发布**(`--publish`)
363
+ ## 8. **发布**(apply 一律发布)
329
364
 
330
- - **默认会发布**:未显式 **`--no-publish`** 即 **`publish: true`**;公开入口仍是 **`portal_apply`**,发布动作由工具内部执行并回读 **`being_draft=false`**。
365
+ - **不存在「不发布」场景**:`portal apply` 写后**总是自动发布**并回读线上态(`--publish/--no-publish` flag 与声明内 `publish` 字段均已移除;声明里写 `publish: false` 会被明确拒绝)。门户不会停留在草稿-only 状态,也不会出现「apply 成功但工作台导航看不到」的情况。
331
366
  - **已发布线索**:成功路径上 **`published: true`**;**`live_result.publishStatus`** 常见 **`2`** 表示已发布(以你环境枚举为准)。
332
367
  - **`partial_success` + `PORTAL_READBACK_PENDING`**:草稿/线上 **组件数量或元数据** 与「本次期望」不一致时会出现;**`PORTAL_*_VERIFICATION_INCOMPLETE`** 警告。应 **`builder portal get --dash-key …`**(草稿与 **`--no-being-draft` 线上**)**肉眼核对**区块是否齐全,而不是仅信 **`verified: true`**。
333
368
  - **网关 503**:**与 CLI 无关**;环境恢复后重试 **`portal get` / `portal apply`**。(本轮在网关恢复后 **`portal apply` 已成功**。)
@@ -338,10 +373,10 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
338
373
 
339
374
  | 步骤 | 命令要点 | 结果 |
340
375
  |------|-----------|------|
341
- | 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、`--no-publish`、单 **view** | **`dash_key`: `ecdcell64s02`** |
342
- | 503 后重试 | **`--dash-key ecdcell64s02`、`--publish`** + 含 **filter** 的六类 **`sections-file`** | **`published: true`**;**`filter` 仍不落库** → **`partial_success`**,**`components expected 6, got 5`**(与 **§3.4** 一致) |
343
- | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合 | **回读恒为 1 块(仅 `type: 9`)** |
344
- | **稳定可复现** | **`--publish`** + **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
376
+ | 新建门户 | `--package-id 2030703`、`--dash-name "CLI门户探针_可删"`、单 **view**(历史记录,当时带 `--no-publish`;该 flag 已移除) | **`dash_key`: `ecdcell64s02`** |
377
+ | 503 后重试 | **`--dash-key ecdcell64s02`** + 含 **filter** 的六类 **`sections-file`**(历史记录) | **`published: true`**;当时 filter 组合全部**空 rules** → 读面不可见(**§3.4** 机制,非后端拒绝;现空 rules 已被模型层阻断) |
378
+ | **filter 专项** | 仅 **chart + filter** 两块的多种 **`graphList`/`graphRef`/`dashChartId`/`filterGroupConfig`** 组合(历史记录,全部空 rules) | **回读恒为 1 块(仅 `type: 9`)**——空规则读面不可见;含 rules 的声明式写入已由 ws40013 基准验证 |
379
+ | **稳定可复现** | **[portal_sections_five_types.example.json](../examples/portal/portal_sections_five_types.example.json)**(**grid / text / link / view / chart**) | **`status: success`**,**`types: [2,4,5,9,10]`**,**`published: true`** |
345
380
  | 删除门户 | `builder portal delete --dash-key etcivtmv5402` | **`status: success`**,**`delete_executed: true`**,**`readback_status: deleted`**,**`summary.removed: 1`** |
346
381
 
347
382
  **推荐工作台模板示例**:[portal_sections_standard_workbench.example.json](../examples/portal/portal_sections_standard_workbench.example.json)。正式业务门户优先复制这个文件的行布局。
@@ -355,7 +390,7 @@ qingflow --json builder portal delete --dash-key "<DASH_KEY>" > tmp/builder_port
355
390
  | 现象 | 处理 |
356
391
  |------|------|
357
392
  | `portal apply accepts exactly one selector mode` | **`dash-key`** vs **`package-id`** 二选一。 |
358
- | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件;若多写了 **`filter`** 而回读少一块,见 **§3.4**(**CLI 写 filter 可能整体不生效**);也可能是 **异步回读**,可再 **`get`** 一次。 |
393
+ | `PORTAL_READBACK_PENDING` / **`components expected N, got M`** | **`portal get`** 数组件;`filter` 回读缺失多为 **空 rules**(模型层已阻断,检查报错)或 **异步回读**(可再 **`get`** 一次);含规则的 filter 写入正常(见 **§3.4**)。 |
359
394
  | **`published: true` 但 `verified: false`** | 读 **§7**;用 **`get` 草稿+线上**对照。 |
360
395
  | **503** | 网关/运维;稍后重试。 |
361
396
  | 缺 **chart** | 在对应 portal section 写 **`chart`**;或换用已有报表的 **`chart: {"chart_id": "..."}`** / 兼容旧 **`chart_ref`**。 |
@@ -201,8 +201,8 @@ qingflow builder schema apply \
201
201
  - 如果返回 `MULTI_APP_STATIC_VALIDATION_FAILED`,读取 `details.issues[]` 的 `path/error_code/fix_hint` 修 payload;这是写入前失败,通常可以修正后重试,不需要 readback。
202
202
  - 多应用 schema apply 不做事务回滚;如果部分失败,只补失败的 `apps[].row_number`,不要整批重复提交。
203
203
  - 这个模式只负责应用壳与字段;视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
204
- - `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayField`、`config.visibleFields`,并使用已确认的真实 app key。
205
- - 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`:逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后,改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`,不要提交旧 `update_fields` patch。
204
+ - `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayFields[]`(含 `auth`)、`config.twoWayBoundField`,并使用已确认的真实 app key。
205
+ - 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`:逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后,改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`,不要提交旧 `update_fields` patch。
206
206
  - 一个应用可以包含多个 `relation` 字段;不要因为 relation 数量超过 1 就降级成文本。若真实写入失败或 relation readback mismatch,只按实际错误和 `details.relation_repair_plan[]` 做最小修复。
207
207
  - 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时,先按 §3.4 读回,不要直接拆成单应用创建。
208
208
 
@@ -349,7 +349,7 @@ qingflow builder flow apply \
349
349
  | **`address`** | 地址复合字段。 |
350
350
  | **`attachment`** | 附件。 |
351
351
  | **`boolean`** | 是否。 |
352
- | **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`;当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`。 |
352
+ | **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`;当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`。 |
353
353
  | **`subtable`** | 当前 AppForm 使用 `subfields[]` 及 Schema 返回的 camelCase 配置;旧 `subfield_updates` 只作迁移线索。 |
354
354
  | **`q_linker`** | 当前 AppForm 使用 `config.qLinkerBinding`,其 `outputs[].targetField` 必须按字段 Schema 配置。 |
355
355
  | **`code_block`** | 当前 AppForm 使用 `config.codeBlockBinding`,其 `outputs[].targetField` 必须按字段 Schema 配置。 |
@@ -0,0 +1,100 @@
1
+ {
2
+ "schema_version": "v1alpha1",
3
+ "name": "业务工作台",
4
+ "package_tag_id": 2030703,
5
+ "icon": "view-grid",
6
+ "color": "#2468F2",
7
+ "hide_copyright": false,
8
+ "global_config": {
9
+ "auto_refresh": false,
10
+ "interval": 60,
11
+ "export": true
12
+ },
13
+ "visibility": {
14
+ "mode": "workspace",
15
+ "external_mode": "not"
16
+ },
17
+ "layout_preset": "auto",
18
+ "sections": [
19
+ {
20
+ "title": "业务入口",
21
+ "source_type": "grid",
22
+ "position": {
23
+ "pc": { "x": 0, "y": 0, "cols": 24, "rows": 4 }
24
+ },
25
+ "config": {
26
+ "gridTitle": "业务入口",
27
+ "beingShowTitle": true,
28
+ "items": [
29
+ { "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY_DEVICE", "linkFormType": 1, "title": "设备台账" },
30
+ { "type": 1, "jumpMode": 1, "linkAppKey": "APP_KEY_WORKORDER", "linkFormType": 1, "title": "工单管理" }
31
+ ]
32
+ }
33
+ },
34
+ {
35
+ "title": "设备总数",
36
+ "source_type": "chart",
37
+ "role": "metric",
38
+ "position": {
39
+ "pc": { "x": 0, "y": 4, "cols": 6, "rows": 5 }
40
+ },
41
+ "chart": {
42
+ "app_key": "APP_KEY_DEVICE",
43
+ "name": "设备总数",
44
+ "chart_type": "target",
45
+ "metric": "count(*)"
46
+ }
47
+ },
48
+ {
49
+ "title": "异常设备数",
50
+ "source_type": "chart",
51
+ "role": "metric",
52
+ "position": {
53
+ "pc": { "x": 6, "y": 4, "cols": 6, "rows": 5 }
54
+ },
55
+ "chart": {
56
+ "app_key": "APP_KEY_DEVICE",
57
+ "name": "异常设备数",
58
+ "chart_type": "target",
59
+ "metric": "count(*)",
60
+ "filters": [
61
+ { "field_name": "状态", "operator": "eq", "values": ["异常"] }
62
+ ]
63
+ }
64
+ },
65
+ {
66
+ "title": "工单趋势",
67
+ "source_type": "chart",
68
+ "position": {
69
+ "pc": { "x": 0, "y": 9, "cols": 12, "rows": 7 }
70
+ },
71
+ "chart": {
72
+ "app_key": "APP_KEY_WORKORDER",
73
+ "name": "工单趋势",
74
+ "chart_type": "line",
75
+ "metric": "count(*)",
76
+ "group_by": ["创建日期"]
77
+ }
78
+ },
79
+ {
80
+ "title": "工单类型分布",
81
+ "source_type": "chart",
82
+ "position": {
83
+ "pc": { "x": 12, "y": 9, "cols": 12, "rows": 7 }
84
+ },
85
+ "chart_ref": { "app_key": "APP_KEY_WORKORDER", "chart_name": "工单类型分布" }
86
+ },
87
+ {
88
+ "title": "异常设备明细",
89
+ "source_type": "view",
90
+ "position": {
91
+ "pc": { "x": 0, "y": 16, "cols": 24, "rows": 11 }
92
+ },
93
+ "view_ref": {
94
+ "app_key": "APP_KEY_DEVICE",
95
+ "view_key": "VIEW_KEY_ABNORMAL_DEVICES"
96
+ },
97
+ "view_display": { "show_title": true }
98
+ }
99
+ ]
100
+ }
@@ -17,14 +17,13 @@
17
17
  }
18
18
  },
19
19
  "config": {
20
- "filterConfig": [],
21
- "graphList": [
20
+ "graphs": [
22
21
  {
23
- "graphType": "CHART",
24
- "graphKey": "REPLACE_WITH_QINGBI_CHART_ID",
25
- "graphName": "可选_图表显示名"
22
+ "chart_key": "REPLACE_WITH_QINGBI_CHART_ID",
23
+ "chart_name": "可选_图表显示名"
26
24
  }
27
- ]
25
+ ],
26
+ "rules": []
28
27
  }
29
28
  },
30
29
  {
@@ -142,4 +141,4 @@
142
141
  "chart_id": "YOUR_CHART_ID"
143
142
  }
144
143
  }
145
- ]
144
+ ]
@@ -10,6 +10,9 @@ from .json_types import JSONObject
10
10
  TYPE_ALIASES = {
11
11
  "multiline": "long_text",
12
12
  "textarea": "long_text",
13
+ "richtext": "rich_text",
14
+ "rich-text": "rich_text",
15
+ "rich_text": "rich_text",
13
16
  "radio": "single_choice",
14
17
  "boolean": "single_choice",
15
18
  "select": "single_select",
@@ -11,9 +11,15 @@ from .app_form_compat import normalize_app_form_declaration
11
11
  from .builder_facade.app_form_schema import AppFormContractError, compact_schema_errors, schema_error_message
12
12
 
13
13
 
14
+ #: code_block / q_linker 输出目标字段类型。后端写链无类型白名单(FormSvcImpl
15
+ #: 原样落库),运行时 DataSvcImpl.getAnswerValueByString:选项/数字/日期有专门
16
+ #: 分支;attachment 按拆分 URL 写入(专门分支);subtable 整表组装(专门分支);
17
+ #: rich_text/data_relation 走 Question.canImport 兜底按字符串写入(不报错)。
18
+ #: 四者为存量合法配置(提取读得出、apply 必须写回,两闸门同口径)。
14
19
  _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
15
20
  "text",
16
21
  "long_text",
22
+ "rich_text",
17
23
  "number",
18
24
  "amount",
19
25
  "date",
@@ -21,8 +27,17 @@ _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
21
27
  "single_choice",
22
28
  "single_select",
23
29
  "multi_select",
30
+ "attachment",
31
+ # r10 存量实证放行:link(92nl6blfk402)/member(ab9fjvj33001)——后端写链
32
+ # 无类型白名单,运行时同为字符串写入路径
33
+ "link",
34
+ "member",
35
+ "data_relation",
36
+ "subtable",
24
37
  }
25
- _Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}\s]+)\}\}")
38
+ # key 允许含空白(r10 实测存量 key 如「应用包 ID」带空格,\s 排除导致占位符
39
+ # 扫描漏检 → validate 误报「key must appear as {{key}}」)
40
+ _Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}]+)\}\}")
26
41
  _FORMULA_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
27
42
  #: 公式字段引用正则(#queId_<id>$,支持表格嵌套 <id>.<id>)
28
43
  _FORMULA_FIELD_REF_RE = re.compile(r"#queId_([^$]+)\$")
@@ -218,19 +233,32 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
218
233
  widths = ["width" in field for field in fields if isinstance(field, dict)]
219
234
  if widths and any(widths) and not all(widths):
220
235
  errors.append((row_path, "width must be present on every field in the row or omitted from all"))
221
- if widths and all(widths) and sum(field.get("width", 0) for field in fields if isinstance(field, dict)) != 100:
222
- errors.append((row_path, "field widths must total 100"))
236
+ # 行宽契约(与后端语义对齐):任意 1-100 整数 + 全有或全无。
237
+ # 后端 html_width 无取值/总和校验,存量存在 33/34 三等分与字段删除后
238
+ # 留白(如 3×25=75)的行;get 读出的原布局必须能原样过校验
239
+ # (apply(get(S)) ≡ S 命题的必要条件)。
240
+ if widths and all(widths):
241
+ bad = [f.get("width") for f in fields if isinstance(f, dict) and not (isinstance(f.get("width"), int) and 1 <= f["width"] <= 100)]
242
+ if bad:
243
+ errors.append((row_path, "field widths must be an integer between 1 and 100"))
223
244
  for field_index, field in enumerate(fields):
224
245
  if isinstance(field, dict):
225
246
  top_fields.append((f"{row_path}/{field_index}", field))
226
247
  def resolve_local_selector(selector: Any) -> tuple[str, tuple[str, dict[str, Any]] | None]:
227
- """Resolve against the declared body, preserving backend-dependent ID-only cases."""
248
+ """Resolve against the declared body, preserving backend-dependent ID-only cases.
249
+
250
+ 返回态:resolved(唯一定位)/ invalid(定位失败)/ ambiguous(方案 A:name-only
251
+ 命中多个同名字段,调用方须报 AMBIGUOUS_FIELD_SELECTOR)/ unknown(存在未命名
252
+ 字段,后端侧再判)/ schema(结构不完整,交给 Schema 校验)。
253
+ """
228
254
  if not isinstance(selector, dict):
229
255
  return "schema", None
230
256
  raw_que_id = selector.get("queId")
231
257
  que_id = raw_que_id if isinstance(raw_que_id, int) and not isinstance(raw_que_id, bool) else None
232
258
  raw_name = selector.get("name")
233
- name = raw_name if isinstance(raw_name, str) and raw_name else ""
259
+ # name 两侧 strip:存量字段名带前导/尾随空格,queId 已同时给出不构成歧义
260
+ # (与 compiler 侧三个 resolve 函数同口径)。
261
+ name = raw_name.strip() if isinstance(raw_name, str) and raw_name.strip() else ""
234
262
  if raw_que_id is not None and que_id is None:
235
263
  return "schema", None
236
264
  if raw_name is not None and not name:
@@ -239,26 +267,52 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
239
267
  matches = [(path, field) for path, field in top_fields if field.get("queId") == que_id]
240
268
  if len(matches) != 1:
241
269
  return "invalid", None
242
- declared_name = str(matches[0][1].get("name") or "")
270
+ declared_name = str(matches[0][1].get("name") or "").strip()
243
271
  if name and declared_name and name != declared_name:
244
272
  return "invalid", None
245
273
  return "resolved", matches[0]
246
274
  if name:
247
- matches = [(path, field) for path, field in top_fields if str(field.get("name") or "") == name]
275
+ matches = [(path, field) for path, field in top_fields if str(field.get("name") or "").strip() == name]
248
276
  if len(matches) == 1:
249
277
  return "resolved", matches[0]
250
278
  if len(matches) > 1:
251
- return "invalid", None
279
+ return "ambiguous", None
252
280
  if any(not str(field.get("name") or "") for _, field in top_fields):
253
281
  return "unknown", None
254
282
  return "invalid", None
255
283
  return "schema", None
256
284
 
285
+ def ambiguity_message(selector: Any, subject: str) -> str:
286
+ name = str((selector or {}).get("name") or "").strip()
287
+ candidate_ids = sorted(
288
+ {
289
+ field.get("queId")
290
+ for _, field in top_fields
291
+ if str(field.get("name") or "").strip() == name
292
+ and isinstance(field.get("queId"), int)
293
+ and not isinstance(field.get("queId"), bool)
294
+ }
295
+ )
296
+ return (
297
+ f"AMBIGUOUS_FIELD_SELECTOR: {subject} name {name!r} matches multiple fields "
298
+ f"(candidate queIds: {candidate_ids}); duplicate names are allowed but "
299
+ "selectors must use queId to disambiguate"
300
+ )
301
+
257
302
  title_selector = spec.get("dataTitleField")
258
303
  if top_fields:
259
304
  if "dataTitleField" not in spec and "appKey" in payload:
260
305
  pass
261
- elif title_selector is None or resolve_local_selector(title_selector)[0] == "invalid":
306
+ elif title_selector is None:
307
+ # dataTitleField=null 仅在带 appKey 的更新/round-trip 场景放行:后端写链
308
+ # FormSvcImpl.normalizeDataTitleQueId 对 null 自动 fallback 到第一个可用
309
+ # 字段,get 读面在后端未设置时原样输出 null。创建场景(无 appKey)仍需
310
+ # 显式 selector。
311
+ if "appKey" not in payload:
312
+ errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
313
+ elif resolve_local_selector(title_selector)[0] == "ambiguous":
314
+ errors.append(("/spec/dataTitleField", ambiguity_message(title_selector, "dataTitleField")))
315
+ elif resolve_local_selector(title_selector)[0] == "invalid":
262
316
  errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
263
317
  elif title_selector is not None:
264
318
  errors.append(("/spec/dataTitleField", "dataTitleField must be null when body is empty"))
@@ -266,11 +320,15 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
266
320
  cover_selector = spec.get("dataCoverField")
267
321
  if cover_selector is not None:
268
322
  cover_resolution, cover = resolve_local_selector(cover_selector)
269
- if cover_resolution == "invalid":
323
+ if cover_resolution == "ambiguous":
324
+ errors.append(("/spec/dataCoverField", ambiguity_message(cover_selector, "dataCoverField")))
325
+ elif cover_resolution == "invalid":
270
326
  errors.append(("/spec/dataCoverField", "dataCoverField must resolve to exactly one top-level field"))
271
327
  elif cover_resolution == "resolved" and cover is not None and _field_type(cover[1]) != "attachment":
272
328
  errors.append(("/spec/dataCoverField", "dataCoverField must select a top-level attachment field"))
273
- names: dict[str, str] = {}
329
+ # 方案 A(duplicate-field-name):同父级允许同名(后端以 queId 为身份,40013
330
+ # 实测 1624 组),不再报 duplicate name;歧义在 selector 解析处以
331
+ # AMBIGUOUS_FIELD_SELECTOR 显式拒绝。
274
332
  fields_by_id = {
275
333
  field.get("queId"): field
276
334
  for _, field in top_fields
@@ -278,12 +336,6 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
278
336
  }
279
337
  output_targets: dict[str, tuple[str, str]] = {}
280
338
  for path, field in top_fields:
281
- name = str(field.get("name") or "")
282
- if name:
283
- if name in names:
284
- errors.append((f"{path}/name", f"duplicate top-level field name; first declared at {names[name]}"))
285
- else:
286
- names[name] = f"{path}/name"
287
339
  field_type = _field_type(field)
288
340
  if field_type == "data_relation":
289
341
  config = field.get("config") if isinstance(field.get("config"), dict) else {}
@@ -307,7 +359,15 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
307
359
  "is_empty and is_not_empty require a literal operand with values: []",
308
360
  )
309
361
  )
310
- elif operand.get("kind") == "literal" and not values:
362
+ elif (
363
+ operand.get("kind") == "literal"
364
+ and not values
365
+ and operator not in {"subordinate_to", "not_subordinate_to"}
366
+ ):
367
+ # subordinate 两算子放行空 literal:存量「设置后清空」形态
368
+ # (r13 实证 41ce0ad8 六处)——后端写链 checkRelationMatchRules
369
+ # 仅校验 dynamic_range(FormSvcImpl:10448),formula 渲染对空
370
+ # judgeValueDetails 输出 [](Formula:397),读回解析对称,往返保真
311
371
  errors.append(
312
372
  (
313
373
  f"{operand_path}/values",
@@ -329,6 +389,9 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
329
389
  selector = item.get("field") if isinstance(item.get("field"), dict) else {}
330
390
  input_path = f"{path}/config/{binding_name}/inputs/{index}"
331
391
  resolution, selected = resolve_local_selector(selector)
392
+ if resolution == "ambiguous":
393
+ errors.append((f"{input_path}/field", ambiguity_message(selector, f"{binding_name}.inputs[{index}].field")))
394
+ continue
332
395
  if resolution == "invalid":
333
396
  errors.append((f"{input_path}/field", "input field must resolve to exactly one top-level field"))
334
397
  continue
@@ -337,7 +400,10 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
337
400
  selected_name = selected[1].get("name") if selected is not None else selector.get("name")
338
401
  if not selected_name and selector.get("queId") in fields_by_id:
339
402
  selected_name = fields_by_id[selector["queId"]].get("name")
340
- if selected_name and item.get("key") != selected_name:
403
+ # 两侧 strip:模板引用名提取时已 strip(字段名存量带尾随空格,如
404
+ # am4oh08v2401「答:Answer 」),严格相等会把「引用名≠当前字段名」的
405
+ # 存量形态误报为 key 不一致
406
+ if selected_name and str(item.get("key") or "").strip() != str(selected_name).strip():
341
407
  errors.append((f"{input_path}/key", "json_path key must equal the selected field name"))
342
408
 
343
409
  if field_type == "q_linker":
@@ -380,13 +446,16 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
380
446
  )
381
447
  )
382
448
 
383
- producer = name or str(field.get("queId") or field_type)
449
+ producer = str(field.get("name") or "") or str(field.get("queId") or field_type)
384
450
  for index, item in enumerate(binding.get("outputs") or []):
385
451
  if not isinstance(item, dict):
386
452
  continue
387
453
  selector = item.get("targetField")
388
454
  target_path = f"{path}/config/{binding_name}/outputs/{index}/targetField"
389
455
  resolution, selected = resolve_local_selector(selector)
456
+ if resolution == "ambiguous":
457
+ errors.append((target_path, ambiguity_message(selector, f"{binding_name}.outputs[{index}].targetField")))
458
+ continue
390
459
  if resolution == "invalid":
391
460
  errors.append((target_path, "targetField must resolve to exactly one top-level field"))
392
461
  continue