weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/report/query-condition-api-guide.md

@@ -1,939 +1,939 @@
-# 查询条件 API 写入规范
-
-> **适用场景**：通过 `saveQueryItem` / `saveQueryConfig` API 或脚本添加、修复报表查询条件。
-> **金标准报表**：`1304979556231593985`（EBU 经营数据统计）
-> **核心规则**：数据集合选取后，**选择类型未特别指定 SQL 时，一律默认为「条件字段」**。
-
-## ⚡ TL;DR — 显示方式（2026-09-11 定案，务必先读 §2.1）
-
-| 事实 | 结论 |
-|---|---|
-| 条件级 `queryType` 正确落库值 | **JSON 数组字符串** `'["advance"]'`（高级搜索）/ `'["filter"]'`（筛选） |
-| 前端回显判据 | 只看首字符是否 `[`；`'["advance"]'` → 勾选 ✅，`"advancedSearch"` → 不勾 ❌ |
-| **`updateQueryType` 是最大陷阱** | 它把入参 `queryType` **批量写进所有条件**；传长码 = 一键摧毁全表回显（§2.1.3） |
-| 保存后必须自检 | `e10-cli report query check-echo --report-id <id> --app-id <appId>` |
-| 一键修复 | `e10-cli report query fix-echo --report-id <id> --app-id <appId>` |
-
----
-
-## 一、选择类型（设计器 UI ↔ API）
-
-| 设计器「选择类型」 | 顶层 `filterType` | `conditions[]` 内 | 说明 |
-|-------------------|-------------------|-------------------|------|
-| **条件字段**（默认） | `"default"` | **仅** `dataSetId` + `fieldId` + `relation` | 绑定数据集字段，禁止 SQL |
-| **SQL**（显式指定） | `"sql"` | `"filterType": "sql"` + `sql` | 私有化环境才可用 |
-
-**Agent 硬约束**：除非需求明确写「SQL 条件」，否则不得使用 `filterType: "sql"`。
-
-**常见错误**
-
-| 错误写法 | 后果 |
-|----------|------|
-| `conditions[].filterType: "field"` | 设计器「选择类型」无法回显为「条件字段」 |
-| 顶层 `dataSetId` / `name` 有值 | 与设计器 save 形态不一致，回显异常 |
-| `sqlOptions: {selected: ...}` | 条件字段应为 `{}` |
-| `defaultValue: "3"`（非 JSON 数组） | `getQueryItem` 解析失败，整表 500 |
-| **`queryItems` 传数组 `[]`/`[{…}]`** | 服务端 `parseObject` 单对象失败 / NPE → **saveQueryItem 500** |
-| **`queryItems` 为 `{}` 且无 `conditions`** | `getConditions().size()` NPE → **500** |
-| **JSON body 而非 multipart** | 参数绑不上 / 权限校验异常 → 常 500 |
-| 缺 `ebBusinessId` | `wrapEbRightCheck` 编辑权限失败 |
-
----
-
-## 二、条件字段标准形态（saveQueryItem）
-
-设计器 save 后回读的金标准结构：
-
-| 字段 | 条件字段正确值 |
-|------|----------------|
-| 顶层 `dataSetId` | **`null`** |
-| 顶层 `name` | **`null`** |
-| `nameIndex` | **`"0"`** |
-| `filterType` | **`"default"`** |
-| `sqlOptions` | **`{}`** |
-| `conditions[]` | 仅 `dataSetId` + `fieldId` + `relation` |
-| `fieldOptions` | 必传（含 `selected`、`dataSetField`、`relation`）；`getQueryItem` 不持久化，更新时须重带 |
-| `asNameIndex` | **唯一且 > 0**；更新时**必须回传**，否则置 0。`showOrder`（弹窗「排序」）人工配置通常留 **`0`**（= 未设，平台回落按 `asNameIndex` 排）——API 建条件时若自行填 1,2,3… 会在弹窗上留下可见差异（2026-09-14 验证参照报表 5 条全为 0）。事件超链接传查询值用 `{searchfield` + 三位补零 + `}`（如 `asNameIndex=1` → `{searchfield001}`，区间另加 `_start`/`_end`），见 `event-hreflink-guide.md` |
-| **默认值三件套** | **必填**：`defaultValueType`（`default`=常规 / `custom`=自定义）+ `defaultValue`（当前生效值）+ `type1DefaultValue`（常规那份）/ `type2DefaultValue`（自定义那份）；值均为 **JSON 字符串**。**漏写 → 设计器弹窗「默认值类型」= 请选择、默认值区炸开、后续整段行被顶出可视区**（见 §2.1.10） |
-| `fieldId` / `dataSetField` | fieldKey：`{dataSetId}.{sourceId}.{fieldName}` |
-| **`queryType`（显示方式）** | **必填 JSON 数组字符串**，见 §2.1；`'["advance"]'`（高级搜索，默认）或 `'["filter"]'`（筛选），可双选 `'["advance","filter"]'`。**服务端也接受长码字符串 `"advancedSearch"`，但那样设计器 UI 不会勾选** |
-| `showWhere`（遗留） | 设计器一律写 `""`；**勿**用它表达显示方式 |
-| `browserType` / `browserTypeStr` | `displayType=browser` 时必填；富对象优先，落库判据是 `browserTypeStr`（见 §2.1.2） |
-
-```python
-def build_conditions(ds_id, field_id, relation):
-    return [{"dataSetId": ds_id, "fieldId": field_id, "relation": relation}]
-
-def build_field_options(ds_id, field_id, relation, item_id=None):
-    row = {"dataSetField": field_id, "relation": relation, "queryItemValue": "输入值"}
-    if item_id:
-        row["id"] = str(item_id)
-    return {"selected": ds_id, ds_id: [row]}
-```
-
-API：`POST /api/bs/edc/report/saveQueryItem`
-
-| 项 | 正确 | 错误 → 常 500 |
-|----|------|----------------|
-| Content-Type | **`multipart/form-data`** | `application/json` 整包 body |
-| 表单字段 | `reportId` + **`queryItems`** | 缺参、或写成 `queryItem` / `items` |
-| `queryItems` 值 | **单个** QueryField **对象**的 JSON 字符串 | **`[]` / `[{...}]` 数组**（源码 `parseObject` 单对象） |
-| Header | `eteamsid` + `Cookie` + **`ebBusinessId`/`ebbusinessid`=appId** | 缺业务 app，权限包装失败 |
-| Referer | `/sp/edc/report/designer/{reportId}` | 可无，但建议带 |
-
-```http
-POST /api/bs/edc/report/saveQueryItem
-Content-Type: multipart/form-data; boundary=----x
-
-------x
-Content-Disposition: form-data; name="reportId"
-
-{reportId}
-------x
-Content-Disposition: form-data; name="queryItems"
-
-{"dataSetId":null,"name":null,...,"conditions":[{...}],"fieldOptions":{...}}
-------x--
-```
-
-**硬约束（源码 `EdcReportDevDesignServiceImpl.saveQueryItem`）**
-
-1. `JSONObject.parseObject(queryItems, QueryFieldDto.class)` → **禁止**传数组。
-2. 非私有化环境会对 `queryField.getConditions()` 做 `jsonArray.size()`；**`conditions` 为 null**（如 `queryItems="{}"`）→ **NPE → 接口 500**。
-3. 一次请求只保存**一条**条件；多条 → **循环多次** `saveQueryItem`（每条一个对象）。
-4. 更新已有条件：对象内带 `id`（字符串雪花）；新建不带 `id`，服务端生成并自动递增 `asNameIndex`。
-5. `saveQueryConfig` **不能代替** `saveQueryItem`；可先可后，但有高级搜索条件时建议条件级 `queryType: '["advance"]'`（见 §2.1）。
-
-```javascript
-// ✅
-await saveQueryItem({ reportId, queryItems: JSON.stringify(oneItemObject) });
-// ❌
-await saveQueryItem({ reportId, queryItems: JSON.stringify([oneItemObject]) });
-await saveQueryItem({ reportId, queryItems: '[]' });
-await saveQueryItem({ reportId, queryItems: '{}' }); // conditions 缺失 → 500
-```
-
----
-
-### 2.1 显示方式（强制 · 不可不选）
-
-> **✅ 终局定案（2026-09-11 · 以「设计器手工配置的真实条件」为金标准反推）**
->
-> 条件级「显示方式」的正确落库值是 **JSON 数组字符串**：
->
-> | 显示方式 | 正确落库值 |
-> |---|---|
-> | 高级搜索 | `'["advance"]'` |
-> | 筛选 | `'["filter"]'` |
-> | 两者都选 | `'["advance","filter"]'` |
->
-> **服务端对取值不敏感**：`'["advance"]'` / `'["filter"]'` / `'["advance","filter"]'` / `"advancedSearch"` / `"filter"` **全部返回 200 并原样落库**。
-> **但只有 JSON 数组形态能在设计器 UI 正确回显勾选**；长码字符串 `"advancedSearch"` 会导致 **UI 两个都不勾**（旧版文档「写短码 500」的说法是错的，见下方推翻记录）。
-
-#### 2.1.1 前端回显规则（源码级 · `_src/route_DatasetList.js`）
-
-前端**只看首字符是否为 `[`**，据此决定是否 JSON 解析：
-
-```js
-// ① 读取（initCondition）—— 唯一判定逻辑
-t.queryType = (t.queryType?.indexOf("[") > -1)
-    ? JSON.parse(t.queryType || "[]")     // 含 "[" → 解析成数组
-    : t.queryType || [];                  // 不含 → 原样保留（普通字符串）
-```
-
-```js
-// ② 复选项定义（initConditionFormStore）—— 选项 id 是「短码」
-queryType:{ itemType:"CHECKBOX", required:!0,
-  data:[{ id: ze.g.advance, content:"高级搜索" },
-        { id: ze.g.filter,  content:"筛选" }],
-  otherParams:{ minSelected:1 } }
-```
-
-```js
-// ③ 短码枚举（lib.js）
-function(e){ e.filter="filter"; e.advance="advance" }(i||(i={}))
-```
-
-```js
-// ④ 新建条件默认值（仅 fieldKey 为空时）
-this.fieldKey || (i.queryType = ["advance"])     // ← 注意：默认就是「数组」
-```
-
-```js
-// ⑤ 保存 —— 表单值原样写回，不做类型转换
-var l = e.conditionFormStore.getFormDatas();
-r.queryType = l.queryType;
-s.append("queryItems", JSON.stringify(r));
-```
-
-**推论（四条必须记牢）**
-
-1. `CheckboxGroup` 用**严格相等**匹配：表单 value 的每个元素 vs `data[].id`。
-2. 落库 `'["advance"]'` → 解析为 `["advance"]` → 元素 `"advance"` === 选项 id `"advance"` → **勾选 ✅**
-3. 落库 `"advancedSearch"` → 不含 `[` → 保留为字符串 `"advancedSearch"` → 与选项 id 严格不等 → **不勾选 ❌**
-4. **设计器自己写出的就是数组**（见 ④ 默认值、⑥ 接口返回）；长码 `"advancedSearch"` 只可能由**脚本手写**产生 → 它是**错误值**。
-
-#### 2.1.2 验证证据链（2026-09-11，报表 `1313798296523022337`，应用「进销存管理-共享表」）
-
-**A. API 写入实验（`saveQueryItem`，同一条件往返改 4 种值）**
-
-| 写入值 | 返回 | 回读落库 | UI「显示方式」 |
-|---|---|---|---|
-| `'["advance"]'` | **200** | `'["advance"]'` | **高级搜索 ☑ ✅** |
-| `'["filter"]'` | **200** | `'["filter"]'` | 筛选 ☑ ✅ |
-| `'["advance","filter"]'` | **200** | `'["advance","filter"]'` | 双选 ☑ ✅ |
-| `"advancedSearch"`（长码） | **200** | `"advancedSearch"` | **两个都不勾 ❌** |
-
-> ⚠️ 四者**全部 200**，不存在「写短码 → 500」。旧结论 500 的真实成因是**手写 multipart payload 的结构/字段不被服务端封装接受**，与 `queryType` 取值无关。
-
-**B. 三条条件 UI 回显对照（CDP 真实鼠标点击 tag → 读弹窗 checkbox）**
-
-| 条件 | 落库 `queryType` | UI「显示方式」 |
-|---|---|---|
-| 销售部门（**人工手工配置**） | `'["advance"]'` | **高级搜索 ☑** |
-| 销售人员（脚本写长码） | `"advancedSearch"` | **两个都 ☐** |
-| 销售日期（脚本写长码） | `"advancedSearch"` | **两个都 ☐** |
-
-→ 脚本手工写的长码条件**全军覆没**，人工配置的数组条件**正确回显**。把两条长码条件改为 `'["advance"]'` 后，三条**全部回显 ☑ 高级搜索**，闭环验证通过。
-
-**C. 设计器真实 `saveQueryItem` 接口返回（人工点击「确定」）**
-
-```
-Content-Disposition: form-data; name="queryItems"
-
-{"id":"…","sheetId":"…","nameIndex":"0","text":"销售部门","displayType":"browser",
- "showWhere":"","advancedSearchType":"openCondition","queryType":["advance"], … }
-                                                          ^^^^^^^^^^^^^^^^^^
-                                                          数组（短码），非字符串长码
-```
-
-> 设计器上行 payload 里就是 `"queryType":["advance"]`（**数组 + 短码**）—— 这是平台的权威写法。
-
-#### 2.1.3 🔴 真正根因：`updateQueryType` 会**批量覆盖所有条件**（最关键）
-
-> **`POST /api/bs/edc/report/updateQueryType` 不是「只改报表级设置」** —— 它会把入参 `queryType` **全量写进该报表的每一条查询条件**，覆盖刚保存好的数组值。
-> 这是「条件显示方式永远不勾选」的**真正单点根因**，也是历史定位一直抓不到的那个洞。
-
-**验证矩阵**（同一报表连续调用，观察条件级 `queryType`）
-
-| 调用 `updateQueryType(queryType=…)` | 三条条件级 `queryType` 变为 | 设计器回显 |
-|---|---|---|
-| `"advancedSearch"`（长码） | `advancedSearch` ×3 | **全不勾 ❌** |
-| `"advance"`（裸短码） | `advance` ×3 | 不勾 ❌ |
-| `"filter"` | `filter` ×3 | 不勾 ❌ |
-| **`'["advance"]'`（数组短码）** | `'["advance"]'` ×3 | **全勾 ✅** |
-
-**为什么历史定位一直失败**
-
-```text
-旧 CLI 的 save 流程：  saveQueryItem(写 '["advance"]' ✅)  →  updateQueryType("advancedSearch" ❌)
-                                          ↓ 刚写好的数组                 ↓ 立刻被批量打回长码
-                                     设计器打开 → 不勾选
-人工在页面直接配条件：  只走 saveQueryItem，不经过 updateQueryType  →  '["advance"]' 完好 → 正常勾选
-```
-
-于是「人工配的能勾、API 写的不能勾」，长期被误判为「平台前端缺陷，客户端不可修」。**实际是 CLI 自己把值写坏了。**
-
-**硬约束**
-
-1. **`updateQueryType` 的 `queryType` 必须传数组短码**：`'["advance"]'` / `'["filter"]'`，**与条件级同形态**。传长码 = 一键摧毁全表回显。
-2. **保存条件的推荐调用顺序**：`saveQueryItem`（数组） → `updateQueryType`（**同一个数组值**）。
-3. **不要**在保存后用长码 `updateQueryType`「对齐报表级显示形式」—— 它顺带把条件级也改坏。若只需报表级 `advancedSearchType`（如 `openCondition`），仍须把 `queryType` 传成数组形态。
-4. 落库后**必须回读自检**：`e10-cli report query check-echo --report-id <id> --app-id <appId>`。
-
-#### 2.1.4 落库门禁
-
-| 检查 | 接口 | 通过标准 |
-|------|------|----------|
-| **条件级显示方式（落库）** | `POST /api/bs/edc/report/getQueryItemNew`（multipart `reportId` + `query:'{}'`） | 每条 `queryType` 是 **含 `[` 的 JSON 数组字符串**，元素 ∈ `advance` / `filter` |
-| 报表级 + 条件级批量对齐 | `POST /api/bs/edc/report/updateQueryType` | `code=200`，且入参 `queryType` **为数组短码**（§2.1.3） |
-
-**硬约束**
-
-1. **写 `queryType` = JSON 数组字符串**：`'["advance"]'` / `'["filter"]'` / `'["advance","filter"]'`。**不要写长码 `"advancedSearch"`**（可落库但 UI 不回显）。
-2. **写 `showWhere: ""`**（遗留字段，设计器一致行为）。
-3. **回读判据**：`getQueryItemNew` 的 `queryType` **必须以 `[` 开头**。若是 `"advancedSearch"` → **回显必不勾**，需改写为 `'["advance"]'`。
-4. **强制走 CLI**：Agent 禁止手写 multipart 调 `saveQueryItem`；统一 `e10-cli report query save|type|list|check-echo|fix-echo` / `validate query`。
-5. 用户反馈「显示方式没勾选」时：**先 `check-echo` 回读 `queryType`**。若为长码 → **可修复的落库错误**，`fix-echo` 即恢复（**不要再解释为平台缺陷**）；同时定位是否被 `updateQueryType` 长码覆盖过。
-
-#### 2.1.5 报表级 vs 条件级（勿混淆）
-
-| 层面 | 字段 | 正确值 | 存储形态 |
-|---|---|---|---|
-| **条件级**「显示方式」（编辑查询条件弹窗内） | `queryType` | `'["advance"]'` / `'["filter"]'` | **JSON 数组字符串**（§2.1） |
-| **报表级**「高级搜索显示形式」（查询设置弹窗） | `queryType`（入参） | **也须 `'["advance"]'` / `'["filter"]'`** | 会被批量写入所有条件（§2.1.3） |
-
-> 「查询设置」弹窗只有 `高级搜索显示形式 + 默认样式/展开条件` 等报表级开关；条件级的「显示方式 ☑高级搜索 ☑筛选」在**「编辑查询条件」**弹窗里，两者入口不同，但**落库字段同名、同形态、且共享覆盖关系**。
-
-#### 2.1.6 ⚠️ 旧结论推翻记录（避免回退）
-
-| 旧结论（2026-09-10/11 早期） | 现结论（2026-09-11 定案） |
-|---|---|
-| 落库必须写长码 `"advancedSearch"` | ❌ 错。落库必须写数组 `'["advance"]'` |
-| 写短码 `"advance"` → 服务端 500 | ❌ 错。写数组短码 **200 正常落库** |
-| 「UI 不勾选 = 平台缺陷，客户端不可修」 | ❌ 错。**改数组即可修复**，是脚本落库值写错 |
-| `advancedSearch` 前端 0 次出现 → 服务端产物 | ⚠️ 部分成立（前台确实无此串），但它**不是**服务端要求的取值，而是脚本臆造的 |
-| 前端 `edit` 直取长码灌表单 → 死循环 | ❌ 错。`edit` 灌的就是落库值；落库是数组时**正常勾选** |
-| 条件级与报表级是两个独立字段，互不影响 | ❌ 错。`updateQueryType` 用 `queryType` **批量覆盖所有条件**（§2.1.3 真正根因） |
-| `updateQueryType` 只改报表级「高级搜索显示形式」 | ❌ 错。它会把入参写进每条条件 → 长码一键摧毁全表回显 |
-
-**旧结论怎么来的 / 为什么错**：早期用 JS 合成事件点击条件 tag，实际点到了**左侧字段面板**的「显示方式」（那是字段属性，非条件显示方式），读取勾选态得到假信号；且未把「人工配置的条件」作为金标准对照。**修复方式**：改用 **CDP `Input.dispatchMouseEvent` 真实鼠标事件**点条件 tag，读「编辑查询条件」弹窗，并以人工条件为参照。
-
-**真正根因的发现路径**：给 `save` 加「落库后回读自检」时，发现**刚写入的数组被回读成长码** → 隔离实验证明只有 `saveQueryItem` 时数组完好，一旦再调 `updateQueryType` 即被批量覆盖 → 穷举入参证明 `updateQueryType` 是「全表条件 `queryType` 批量写」。**AI 自检回读是抓到它的关键手段**，务必保留。
-
-#### 2.1.7 修复已有错误条件的操作
-
-**首选（CLI 一键）：**
-
-```bash
-e10-cli report query check-echo --report-id <id> --app-id <appId>   # 诊断
-e10-cli report query fix-echo   --report-id <id> --app-id <appId>   # 修正为数组短码
-```
-
-**手动脚本（等价实现，含 `updateQueryType` 数组化）：**
-
-```python
-# 读取 → 把长码条件就地改为数组短码 → 保存 → 再用数组形态对齐报表级(批量)
-import json, copy, sys
-import _eb
-
-APP, RID = "<appId>", "<reportId>"
-DROP = {"browserTypeStr","selectOptionsStr","conditionStr","sqlOptionsStr",
-        "filterParamStr","handleDefaultValue","updateTime"}   # 回显列，服务端不接受
-
-def read():
-    r = _eb.post("/api/bs/edc/report/getQueryItemNew",
-                 data={"reportId": RID, "query": "{}"}, app_id=APP)
-    return ((r.get("data") or {}).get("list")) or []
-
-def save(item):
-    it = {k: v for k, v in item.items() if k not in DROP}
-    return _eb.post("/api/bs/edc/report/saveQueryItem",
-                    data={"reportId": RID, "queryItems": json.dumps(it, ensure_ascii=False)},
-                    app_id=APP)
-
-for q in read():
-    if not str(q.get("queryType") or "").startswith("["):      # 长码/空 → 修正
-        it = copy.deepcopy(q)
-        it["queryType"] = '["filter"]' if q.get("queryType") == "filter" else '["advance"]'
-        print(q["text"], "->", save(it).get("code"))
-
-# ⚠️ 关键：若还要对齐报表级高级搜索显示形式，updateQueryType 的 queryType 必须用数组形态，
-#    否则它会把全部条件重新打回长码（§2.1.3）。
-_eb.post("/api/bs/edc/report/updateQueryType",
-         data={"reportId": RID, "queryType": '["advance"]', "advancedSearchType": "openCondition"},
-         app_id=APP)
-```
-
-**设计器真实保存形态（金标准，从 `saveQueryItem` 接口返回）**
-
-```json
-{
-  "id": "…", "sheetId": "<reportId>", "nameIndex": "0",
-  "text": "销售部门",
-  "displayType": "browser",
-  "browserType": [{ "id": "3332180495306215437", "name": "部门", "type": "department",
-                    "module": "hrm", "groupId": "<groupId>", "tenantKey": "<tenantKey>",
-                    "dataId": "2005096031068185488", "labelId": "52148",
-                    "licenseModule": "hrm", "systemDefault": 1, "ebuliderDataBrowser": false, "disable": 0 }],
-  "browserTypeStr": "[{\"id\":\"HrmDepartmentComInfo\"}]",
-  "showWhere": "",
-  "queryType": ["advance"],
-  "dateType": "ymd",
-  "filterParam": { "optionTile": {}, "isTile": false, "multiple": true, "dataOptions": [],
-                   "enableOption": false, "required": false, "dateSelectDefaultValue": "",
-                   "numberSelectDefaultValue": "", "eBuilderForm": "", "titleField": "" },
-  "defaultValue": "[[],\"\"]", "handleDefaultValue": "[[],\"\"]",
-  "filterType": "default", "fieldOptions": {},
-  "conditions": [{ "dataSetId": "…", "fieldId": "…", "relation": "Equals" }],
-  "asNameIndex": 1, "showOrder": 1
-}
-```
-
----
-
-### 2.1.9 🔴 `advancedSearchType` —— **禁止静默注入**（会改掉报表页查询区的「样式」）
-
-> **事故（2026-09-14）**：在报表 `1314970921403138199` 加 5 条查询条件后，用户质问
-> 「怎么又把查询条件的样式改了，这个之前强调过不能动页面上原有展示格式」。
-> 定位结论：**用户的 payload 里根本没有 `advancedSearchType`**，是 CLI `e10-cli report query save`
-> 在保存时**无条件注入** `advancedSearchType: 'openCondition'`（=「展开条件」）。
-
-**字段语义（源码级）**
-
-| 项 | 结论 |
-|---|---|
-| 实体字段 | `QueryFieldCommon.advancedSearchType`（`@ApiModelProperty("高级搜索类型")`） |
-| 唯一功能读点 | `SheetServiceImpl`：取**第一条**高级搜索条件的 `advancedSearchType`，`=='openCondition'` → `isOpenCondition=true` |
-| 页面效果 | `isOpenCondition=true` → 报表页查询区**展开铺开**（「展开条件」）；否则 → **默认样式**（右上角搜索图标，点击才展开） |
-| 设计器入口 | 报表级「查询设置」弹窗的 **高级搜索显示形式：默认样式 / 展开条件** |
-| 人工条件（金标准） | **该键不存在**（`undefined`），平台不主动写 |
-
-**硬规则**
-
-1. **入参没有该键 → 就别写该键**（保持线上原值）。CLI 只在显式 `--advanced-search-type openCondition` 时才写。
-2. `updateQueryType`（批量对齐 `queryType`）**不得夹带** `advancedSearchType`。
-3. 该字段属于**展示样式**，与「显示方式」（`queryType`：高级搜索/筛选）**是两回事**，不得绑定在一起写。
-4. 用户没说「展开条件」时，任何情况下都不要写它。
-
-**判别与修复**
-
-```bash
-# 判别：条件里 advancedSearchType 非空 = 被注入过
-e10-cli report query list --report-id <id> --app-id <appId>
-
-# 修复（默认 dry-run；--apply 落库；只清该字段，保留 id/顺序/queryType）
-e10-cli report fix query-style --report-id <id> --app-id <appId> [--id <itemId>...] [--apply]
-
-# 附带修复「不带 id 保存 → 变成新增」造成的重复条件行（删除必须显式列 id）
-e10-cli report fix query-style --report-id <id> --app-id <appId> --delete-id <itemId> --apply
-```
-
-> ⚠️ **另一个必须记住的坑**：`saveQueryItem` **必须带 `id` 才是原地更新**；
-> 不带 `id` 会**INSERT 一条新条件**（`asNameIndex` 自增），报表上出现重复条件。
-> 更新存量条件时，payload 一律从线上回读对象派生并**保留 `id`**。
-
----
-
-### 2.1.10 🔴 「默认值三件套」漏写 → 设计器弹窗整段坏掉（2026-09-14 事故）
-
-**用户看到的现象**（"查询条件的样式被改了"）：
-
-| 现象 | 说明 |
-|------|------|
-| 「默认值类型」= **请选择** | 本该是「常规」或「自定义」 |
-| 「默认值」区**同时铺开所有控件变体** | 请输入 / 开始日期-结束日期 / 选择日期时间 / 请选择 / 选择日期 / 选择月份 / 选择年份 … 一屏全来 |
-| 「日期类型 / 显示位置 / 条件必填 / 查询条件」**看不见** | 被上面那一大片顶出可视区（弹窗高度固定），并非真被删除 |
-
-**根因**：弹窗的默认值区由 `defaultValueType` 驱动渲染。不写它 → 前端取不到模式 → 每个变体都渲染一遍。
-
-**数据模型（验证参照报表 `1314938962594906121`，人工配置的权威形态）**
-
-| 键 | 含义 | 参照「年月」取值 | 参照「部门」取值 | 参照「人员/加班/聘用」取值 |
-|----|------|------------------|------------------|----------------------------|
-| `defaultValueType` | 模式：`default`=常规 / `custom`=自定义（前端 label：`55337`=常规、`53999`=自定义） | `custom` | `default` | `default` |
-| `defaultValue` | **当前生效**的值 | `["{yearmonth:-0}",""]` | `[[],""]` | `["",""]` |
-| `type1DefaultValue` | 「常规」模式下保存的值 | `""` | `[[],""]` | `["",""]` |
-| `type2DefaultValue` | 「自定义」模式下保存的值 | `["{yearmonth:-0}",""]` | `""` | `""` |
-| `handleDefaultValue` | 平台解析后的实际值（**服务端自己算并回写**） | `["2026-09",""]` | `[[],""]` | `["",""]` |
-
-> ⚠️ **全部是 JSON 字符串**（`"[[],\""]"` 这种），不是对象/数组本身。
-> ⚠️ 日期占位符（`{yearmonth:-0}` 等）**不用自己解析**：落库时平台会把 `handleDefaultValue` 回写成 `["2026-09",""]`（验证）。
-> 设计器「新建条件」模板本身带 `defaultValueType:"default"` + `defaultValue:["",""]`，所以**人工配的条件永远不会缺** —— 只有用 API 建条件时才会漏。
-
-**修复**
-
-```bash
-# 只补缺失项（默认模式、空默认值 —— 弹窗恢复正常渲染，不改取数范围）
-e10-cli report fix query-default --report-id <id> --app-id <appId> --apply
-
-# 点名某条用「自定义」默认值（如 年月默认当月，与参照报表一致）
-e10-cli report fix query-default --report-id <id> --app-id <appId> \
-  --set '年月=custom:["{yearmonth:-0}",""]' --set '部门=default:[[],""]' --apply
-
-# 顺带把「排序」对齐为设计器模板值 0
-e10-cli report fix query-default --report-id <id> --app-id <appId> --all --show-order 0 --apply
-```
-
-落库后脚本会自动回读校验（`stillMissingDefaultValueType` 必须为空）。
-
----
-
-### 2.1.11 ★ 查询条件合规体检（Q1~Q10 判据总表 · `e10-cli report verify query`）
-
-> 把本章所有坑的**判据**固化成一条只读命令。搭完条件、改完条件、用户投诉后，第一件事就是跑它。
-> **命令**：`e10-cli report verify query <reportId> <appId> [--json] [--fix]`（等价别名 `e10-cli report query verify ...`）
-> 有 FAIL → exit 1；`--fix` 只做幂等安全项（清样式字段 / 补三件套 / 短码化），**绝不新增或删除条件**。
-
-| # | 判据 | 级别 | 不通过时页面上的表现 | 出处 |
-|---|------|------|----------------------|------|
-| Q1 | `queryType` 是 **JSON 数组短码**（以 `[` 开头且可 parse 成数组） | FAIL | 设计器「显示方式」复选框是空的 | §2.1.1 / QUERY-1 |
-| Q2 | `advancedSearchType` **必须为空** | FAIL | 报表页查询区从「默认样式」变成「展开条件」铺开 | §2.1.9 / QUERY-5 |
-| Q3 | `defaultValueType` 有值（`default`\|`custom`） | FAIL | 弹窗「默认值类型」=请选择，默认值区把**所有**控件变体炸开 | §2.1.10 / QUERY-7 |
-| Q4 | `defaultValue` 有值（JSON 字符串） | WARN | 默认值区仍可能铺开 | QUERY-7 |
-| Q5 | `type1DefaultValue`（常规）/ `type2DefaultValue`（自定义）随模式在位 | WARN | 切换模式时值丢失 | QUERY-7 |
-| Q6 | `id` 存在且 `asNameIndex` **唯一且 >0** | FAIL | 重复条件 / 保存变新增 | QUERY-6 |
-| Q7 | `displayType=browser` 时 `browserType` 富对象非空 + `browserTypeStr` 非空 | FAIL | 关联类型为空、条件点不开 | §2.1.2 / QUERY-3 |
-| Q8 | `filterParam.required` / `showType` 在位 | WARN | 「显示位置 / 条件必填」等弹窗后段字段为空 | — |
-| Q9 | `showOrder` 是否为设计器模板值 `0` | INFO | 弹窗「排序」与人工配置有可见差异 | QUERY-7 |
-| Q10 | 报表级 `queryType` **是否混杂**（同时存在多种写法） | WARN | 曾被 `updateQueryType` 批量覆盖过 | §2.1.3 / QUERY-2 |
-
-> **不要拿 `getQueryConfig` 当判据** —— 本环境它恒返回 `data:null`（QUERY-4）。判据一律走 `getQueryItemNew` 回读。
-
----
-
-### 2.1.2 关联类型 `browserType`：必须写「富对象」，不是 `[{id}]` 简写（强制）
-
-> **事故**：同报表查询条件「销售部门」绑定字段 `originFieldType=Department`，但设计器关联类型显示为空/默认**人员**。**定案根因：`browserType` 写成了简写 `[{"id":"HrmDepartmentComInfo"}]`，缺少 `name`/`type` 等字段 → 前端无法解析显示名 → 退回默认「人员」标签页。**
-
-**设计器真实形态（金标准）**：`browserType` 是 **全字段富对象数组**，关键字段 `name`（显示名）、`type`（`department`/`employee`）、`module`、`groupId`、`tenantKey`、`dataId`、`labelId`、`id`。**`browserTypeStr` 才是落库判据**（服务端存 `[{"id":"HrmDepartmentComInfo"}]` 形式的字符串）。
-
-| 字段 `originFieldType` | `displayType` | `browserTypeStr`（落库） | 设计器关联类型 |
-|------------------------|---------------|--------------------------|----------------|
-| `Employee` | `browser` | `[{"id":"HrmEmployeeComInfo"}]` | **人员** |
-| `Department` | `browser` | `[{"id":"HrmDepartmentComInfo"}]` | **部门** |
-| `DepartmentAllPath` | `browser` | `[{"id":"HrmDepartmentAllPathComInfo"}]` | 部门全路径 |
-
-**推荐获取富对象的正确姿势（最稳）**：**不要手拼** `browserType` 富对象；用 `saveQueryItem` 时：
-1. `displayType: "browser"` + `browserTypeStr` 写 `[{"id":"HrmDepartmentComInfo"}]`；
-2. 或在设计器里手动选一次「部门」让前端生成富对象后接口返回复用（本环境已验证：手动选后可正确回显「部门」）。
-
-**硬约束**
-
-1. `displayType: browser` **禁止** `browserTypeStr: "[]"`；必须按字段 `originFieldType` 写入对应 ComInfo id。
-2. 仅写 `[{"id":...}]` 简写**服务端可接受**（`browserTypeStr` 落库正确），但**前端回显可能为空**；若要求 UI 正确显示，需富对象。
-3. `e10-cli report query save` 内置 `applyQueryDisplayType()` 自动补 `browserType`（未显式指定 `displayType` 时）；不匹配时输出 **WARN**。
-4. 回读核对：`browserTypeStr` 不得为 `"[]"`（丢了 → 退回「人员」）。
-5. 跳过自动推导用 `--skip-display-type`（仅在确实要手填时）。
-
----
-
-```javascript
-// 显示方式：条件级落库值 = JSON 数组字符串（前端唯一能回显勾选的形态）
-function resolveQueryType(userHint) {
-  const s = String(userHint || '').toLowerCase();
-  if (/筛选|filter/.test(s) && !/高级搜索|advanced/.test(s)) return '["filter"]';
-  return '["advance"]';   // 默认「高级搜索」· 不可不选
-}
-// 注意：showWhere 一律写 ''（遗留字段）
-//      条件级选项 id 是短码 advance/filter；落库必须是含 "[" 的 JSON 数组字符串，
-//      否则前端首字符判定落空 → 退化为普通字符串 → 严格相等失败 → UI 不勾选（见 §2.1）
-//      报表级 updateQueryType 的 queryType 也须用数组形态（它会批量覆盖所有条件，见 §2.1.3）
-```
-
-### 2.1.8 「显示方式没勾选」诊断卡（对接用户质询时用）
-
-| 用户说法 | 你的回答要点 |
-|---|---|
-| 「页面上显示方式没勾选」 | 先 `getQueryItemNew` 回读 `queryType`：**是否以 `[` 开头**？ |
-| 「回读是 `'["advance"]'` 却仍不勾」 | 极罕见；先强刷设计器页面（CDN/缓存），再核对条件 `id` 是否为最新 |
-| 「回读是 `"advancedSearch"` 长码」 | **这是落库值写错了**，属可修复问题 → 改写为 `'["advance"]'`，重开弹窗即勾选 |
-| 「能修吗？」 | **能修**：把 `queryType` 改为 JSON 数组字符串（§2.1.7 脚本 / `e10-cli report query fix-echo`） |
-| 交付口径 | 「已修正落库值，条件显示方式回显正常」——**不要再解释为平台缺陷** |
-
-**判据一行流**
-
-```text
-queryType 以 "[" 开头  → 数组 → UI 勾选正常 ✅
-queryType 是其它字符串  → 退化 → UI 不勾选  ❌（改写为 '["advance"]'）
-```
-
-> （`route_DatasetList.js` 179879B / `route_ReportDesigner.js` 702877B / `lib.js` 661658B）；
-> UI 回显用 `_q_real2.py`（CDP `Input.dispatchMouseEvent` 真实鼠标点击条件 tag + 读「编辑查询条件」弹窗 checkbox）。
-
-### 2.1.2.1 关联浏览分类元数据接口（⚠️ 富对象唯一正确来源）
-
-> **勿手拼富对象！** 富对象的 13 个字段值全部来自服务端接口，手拼易错（`labelId`/`dataId` 无法猜）。
-> 本接口 2026-09-11 定位、**2026-09-14 修正为 GET `browserBeanSearch`**，为「部门 / 人员 / 岗位 …」全部关联类型的权威数据源。
-
-```http
-GET /api/bcw/relevanceBrowser/browserBeanSearch?searchValue=<中文分类名>
-Header: ebbusinessid: <appId>
-→ data.data[]        每条 = 13 键富对象
-```
-
-> 🔴 **2026-09-14 修正**：旧文档写的 `POST /api/bcw/relevanceBrowser/getBrowserBean` 在**本环境恒返回 `{"code":500,"msg":"接口错误"}`**（前端其实把 `browserBeanSearch` 的响应**本地拦截**了 —— 见 `lib.js` 里 `relationList()` 分支，所以它在页面上看起来"能用"）。
-> 可用的是 **GET `browserBeanSearch`**；`searchValue` 必须用**中文分类名**（拼音检索服务端不支持：`bm` / `ry` 返回 0 条），空串只返回档案/工作流等非 HRM 分类。
-> CLI 已内置此回退：`themes/e10-cli report query save` 的 `fetchBrowserBeanSearch()`；`displayType=browser` 且 `browserType` 仅为 `[{id}]` 简写时**自动升级为富对象**。
-
-**验证取值（租户 `tmxislnm9p` / 应用 1178336857624084480）**
-
-```http
-GET …/browserBeanSearch?searchValue=部门  → 命中 3 条，取 name=部门
-GET …/browserBeanSearch?searchValue=人员  → 命中 3 条，取 name=人员
-```
-
-**「部门」完整富对象（验证取值）**
-
-```json
-{"id":"2005096031068185488","tenantKey":"all_teams","deleteType":0,
- "dataId":"2005096031068185488","licenseModule":"hrm","labelId":"52148",
- "title":"人事： 部门","disable":0,"systemDefault":1,"ebuliderDataBrowser":false,
- "name":"部门","module":"hrm","type":"department","groupId":"8574699142778669114"}
-```
-
-**「人员」完整富对象（验证取值）**
-
-```json
-{"id":"2005096031068185492","tenantKey":"all_teams","deleteType":0,
- "dataId":"2005096031068185492","licenseModule":"hrm","labelId":"29511",
- "title":"人事： 人员","disable":0,"systemDefault":1,"ebuliderDataBrowser":false,
- "name":"人员","module":"hrm","type":"resource","groupId":"8574699142778669114"}
-```
-
-> ⚠️ 两条的 `id` 都是**业务 id**（= `dataId`，部门 …488 / 人员 …492），**不等于** ComInfo 短 id。
-> 因此校验「关联类型对不对」**不能按 id 比**，要按 `name`（人员/部门）或 `type`（resource/department）判 —— 否则会误报"不匹配"（已修 `e10-cli report query save`）。
-> 同一环境里还有近名分类：`部门字段`(…498) / `人员字段`(…502)，按 `name` **精确**取，勿用 `indexOf`。
-
-**落库判据对照**
-
-| 关联类型 | `browserTypeStr`（落库判据） | 富对象 `name` / `type` |
-|---|---|---|
-| 部门 | `[{"id":"HrmDepartmentComInfo"}]` | 部门 / `department` |
-| 人员 | `[{"id":"HrmEmployeeComInfo"}]` | 人员 / `resource` |
-| 部门全路径 | `[{"id":"HrmDepartmentAllPathComInfo"}]` | 部门字段 / `departmentDesc` |
-
-**修复存量条件（最小侵入，已验证 HTTP 200）**
-
-```python
-# 1) 读取
-q = POST /api/bs/edc/report/getQueryItemNew  (multipart: reportId + query:'{}')
-items = q["data"]["list"]                     # ⚠️ 在 data.list，不是 data.queryItems
-# 2) 取富对象
-bean = GET /api/bcw/relevanceBrowser/browserBeanSearch?searchValue=人员  → name=="人员" 那条
-# 3) 替换 + 同步 browserTypeStr + 保存
-item["browserType"] = [bean]
-item["browserTypeStr"] = json.dumps([{"id":"HrmEmployeeComInfo"}], ensure_ascii=False)
-POST /api/bs/edc/report/saveQueryItem  (multipart: reportId + queryItems 单对象JSON)
-```
-
-**UI 验证要点**：打开「编辑查询条件」弹窗，查 `.ui-browser-type-search-input` 的 `value`：
-- `""` + 控件容器带 `is-empty` 类 → 关联类型**丢失**
-- `"人员"` / `"部门"` → **正确回显** ✅
-
-> 验证：修复前「销售人员」`value=""`（`is-empty`）；修复后 `value="人员"` ✅
-
----
-
-## 二点五、saveQueryItem 始终 500 定位（强制）
-
-> **事故**：议题类报表搭建时，改字段/单条/空数组/`queryConfig`/`sheetId` 均 500 → 根因是**调用形态**，不是业务字段内容。
-
-| 检查顺序 | 项 | 通过标准 |
-|----------|----|----------|
-| 1 | Content-Type | `multipart/form-data`，字段名 `reportId`、`queryItems` |
-| 2 | `queryItems` 形态 | **单个对象** JSON；禁止数组、禁止空 `{}` |
-| 3 | `conditions` | **非 null 数组**，至少 1 个 `{dataSetId, fieldId, relation}` |
-| 4 | Header | `ebBusinessId` = 报表所属 **appId**；`eteamsid` + Cookie |
-| 5 | 多条条件 | **多次** POST，每次一条；不要一次塞数组 |
-| 6 | 对照金标准 | 先 `getQueryItem` 拉已有报表一条，改 `text`/`fieldId` 再 save |
-
-**不要**：为排 500 去开浏览器扫页（浪费）；先按上表自检。仍 500 时看响应 `msg` 是否权限/报表不存在，再问用户。
-
-**优先 CLI**（强制）：
-
-```bash
-# 保存条件（自动默认条件级 queryType='["advance"]'，并 updateQueryType）
-e10-cli report query save --report-id <id> --app-id <appId> --item queryItem.json
-e10-cli report query save ... --show-where "筛选"          # 仅用户点名筛选时
-e10-cli report query type --report-id <id> --app-id <appId>  # 只对齐报表级显示方式勾选
-e10-cli report query list --report-id <id> --app-id <appId>
-e10-cli report validate query --map-show-where "高级搜索"
-e10-cli report validate query --validate-show-where --file item.json
-# queryItem.json = 单条对象（禁止数组）；须含非空 conditions；条件级 queryType='["advance"]'
-```
-
-**不卡死（强制）**：`saveQueryItem` / `e10-cli report query save` 按形态自检并重试 **至多 1 次** 仍失败 → **立即提示用户**（可在设计器手动配查询条件）→ **继续**权限/其它布局/交付主表 → 任务收尾再自动补试 1 次。**禁止**在查询条件步骤死循环。见 `failure-cleanup-and-nonblocking-guide.md` §二。
-
-**与布局 500 区分**：`saveReportDevInfo` 的 border `style` 须为**数字**（如 `1`）与查询无关；查询 500 优先查本节。
-
----
-
-| 需求 | displayType | relation | 备注 |
-|------|-------------|----------|------|
-| 文本（包含） | `text` | `Contain` | 勿写 `select` |
-| 文本（等于） | `text` | `Equals` | |
-| **日期区间**（日/时间） | `date` / `date.ymd` | `between` | 见 §3.1 自动匹配 |
-| **年月/年** | `date.ym` / `date` | `between` | 见 §3.1 |
-| 下拉 | `select` | `Equals` | **必须**自动拉选项写入 `selectOptions`（§3.2） |
-| 数字范围 | `number` | 默认 | |
-| 人员浏览按钮 | `browser` | `Equals` | 人员类字段 |
-
-**日期 displayType 与字段 format**
-
-| 数据集字段 format | 查询条件 displayType |
-|-------------------|----------------------|
-| `yyyy-MM-dd`（及带时分秒） | `date.ymd` |
-| `yyyy-MM` | `date.ym` |
-| `yyyy` / 仅「年」 | `date` |
-| 其他日期 | `date` |
-
-首条查询条件可设 `advancedSearchType: "openCondition"`（如集团军默认展开）。
-
----
-
-### 3.1 查询条件类型自动匹配（强制）
-
-> Agent 配置 / 修复查询条件时，**禁止**一律写成 `text`。必须按 **条件显示名 + 数据集字段类型/format** 自行判断。
-
-**判定顺序**（命中即停）：
-
-| 优先级 | 信号（名称或字段元数据） | displayType | relation | 设计器形态 |
-|--------|--------------------------|-------------|----------|------------|
-| 1 | 名称含「年月」；或 format=`yyyy-MM` | `date.ym` | `between` | 年月区间 |
-| 2 | 名称含「年份」「年度」或纯「年」；format=`yyyy` | `date` | `between` | 日期（年） |
-| 3 | 名称含「日期」「时间」「时段」「期间」；或 `fieldType`/`originFieldType` ∈ Date/DateTime/Time/datetime | `date.ymd`（format 非 yyyy-MM 时）或 `date` | **`between`** | **日期区间** |
-| 4 | 人员 / Employee / 浏览按钮字段 | `browser` | `Equals` | 人员 |
-| 5 | **Select / 下拉框 / Check**（`compType`/`type`/`originFieldType` 为 Select）或需求明确下拉 | `select` | `Equals` | 下拉（**§3.2 必拉选项**） |
-| 6 | 其他 | `text` | `Contain`（模糊）或 `Equals` | 文本 |
-
-**硬约束**
-
-1. 日期/时间类 **必须** `relation: "between"`，**禁止** `Equals` + `displayType: text`（事故：签订日期被配成文本等于）。
-2. 判定依据优先：`fieldsAndOriginFields` 的 `fieldType` / `originFieldType` / `config.format`；名称作辅助（如条件叫「签订日期」字段叫「合同签订日期」）。
-3. 写成日期区间时同步带齐 §四：`filterParam.enableOption=true`、21 项 `dataOptions`、`selectOptions=[]`。
-4. **`displayType: select` 时禁止 `selectOptions: []`** — 必须按 §3.2 按匹配字段自动获取选项（事故：供应商等级下拉无选项）。
-5. 回读 `getQueryItem`：核对 `displayType` + `conditions[0].relation` +（下拉时）`selectOptions.length > 0` 且 `selectKey`/`selectValue` 方向正确。
-6. **定点场景**：用户只点一条条件 → 只改该条，禁止重配全部查询（`targeted-fix-guide.md`）。
-
----
-
-### 3.2 下拉查询条件：按匹配字段自动获取选项（强制）
-
-> **事故**：报表「供应商-1」`1312703681350901760`，「供应商等级」已是 `displayType: select`，但 `selectOptions: []` → 预览/高级搜索无选项映射。
-
-当判定为下拉（§3.1 优先级 5）或用户要求下拉时：
-
-1. 从 `conditions[0].fieldId` 解析三段 fieldKey：`{dataSetId}.{sourceId}.{fieldName}`
-   - `fieldName` 在报表内多为 `field_{雪花ID}`（绑定 fieldsKey）
-   - **取选项时** `fieldName` 参数必须用 **裸雪花 ID**（去掉 `field_` 前缀）
-2. 调用：
-
-```
-GET /api/ebuilder/form/ds/options
-  ?sourceType=FORM
-  &objId={sourceId}
-  &fieldName={裸雪花ID}    ← 禁止传 field_xxx（会返回空数组）
-```
-
-`FORM` 无数据时可再试 `sourceType=LOGIC`。也可用 `ds/fields` 里该字段 `config.options`（`name` + `valueKey`/`value`）作为兜底。
-
-3. 映射写入 `selectOptions` / `selectOptionsStr`（**键值方向勿反**）：
-
-| 字段 | 含义 | 示例 |
-|------|------|------|
-| `selectKey` | **选项值 / ID**（过滤用） | `"864407987151323141"` |
-| `selectValue` | **显示名称** | `"准入供应商"` |
-| `id` | 同 `selectKey` | `"864407987151323141"` |
-
-```javascript
-// ds/options → saveQueryItem（事故：曾把名称写进 selectKey、ID 写进 selectValue）
-selectOptions = data
-  .filter(o => String(o.archive ?? '0') !== '1')
-  .map(o => ({
-    selectKey: String(o.id),   // 数值 / 选项 ID
-    selectValue: o.name,       // 名称
-    id: String(o.id),
-  }));
-```
-
-4. `relation` 用 `Equals`；`showWhere` 仍遵守 §2.1。
-5. **禁止**：只设 `displayType: select` 却留下空 `selectOptions`；**禁止**用带 `field_` 前缀调 `/ds/options` 后误判「字段无选项」。
-
-```javascript
-async function fetchSelectOptionsForQuery(sourceId, fieldNameFromKey) {
-  const bare = String(fieldNameFromKey).replace(/^field_/, '');
-  const r = await get('/api/ebuilder/form/ds/options', {
-    sourceType: 'FORM', objId: sourceId, fieldName: bare,
-  });
-  if (!r.data?.length) throw new Error(`select options empty for ${bare}`);
-  return r.data.filter(o => String(o.archive ?? '0') !== '1')
-    .map(o => ({ selectKey: String(o.id), selectValue: o.name, id: String(o.id) }));
-}
-```
-
-```javascript
-function inferQueryDisplay(text, fieldMeta) {
-  const name = `${text||''} ${fieldMeta?.text||''}`;
-  const ft = String(fieldMeta?.fieldType||'').toLowerCase();
-  const oft = String(fieldMeta?.originFieldType||'').toLowerCase();
-  const fmt = String(fieldMeta?.config?.format || fieldMeta?.format || '');
-  if (/年月/.test(name) || fmt === 'yyyy-MM')
-    return { displayType: 'date.ym', relation: 'between' };
-  if (/年份|^年$|年度/.test(name) || fmt === 'yyyy')
-    return { displayType: 'date', relation: 'between' };
-  if (/日期|时间|时段|期间/.test(name) ||
-      ['date','datetime','time','timestamp'].includes(ft) ||
-      ['date','datetime','time'].includes(oft))
-    return { displayType: fmt.startsWith('yyyy-MM-dd') || !fmt ? 'date.ymd' : 'date',
-             relation: 'between' };
-  return { displayType: 'text', relation: 'Contain' };
-}
-```
-
----
-
-## 四、日期区间：快捷选项（21 项）
-
-设计器手动 save 后的**正确形态**（勿用旧版 15 项数字码 + 9 项 selectOptions）：
-
-| 字段 | 正确值 |
-|------|--------|
-| `selectOptions` | **`[]`** |
-| `filterParam.enableOption` | **`true`** |
-| `filterParam.isTile` | **`true`** |
-| `filterParam.dataOptions` | **21 行**，`id` = `selectValue`（camelCase，如 `day3`、`thisMonth`） |
-| `filterParam.optionTile` | **`{}`** |
-| `filterParam.dateSelectDefaultValue` | **`""`（空）** |
-
-**错误做法**：写入 `filterParam.dateSelectDefaultValue: "thisMonth"` 或填满 `optionTile` — 设计器齿轮菜单往往**只剩「自定义」**。
-
-```python
-# 见 apply_ebu_from_xlsx.py → _default_date_filter_param()
-```
-
----
-
-## 五、日期区间：系统参数默认值（设计器「自定义」）
-
-默认值**不是** `dateSelectDefaultValue`，而是顶层：
-
-| 字段 | 说明 |
-|------|------|
-| `defaultValueType` | **`"custom"`** |
-| `defaultValue` | JSON **字符串**，形如 `'["{thismonth}",""]'` |
-
-运行时由 `SystemVariableUtil` + `DynamicParamsBuilder` 解析；`getQueryItem` 回读的 `handleDefaultValue` 为解析后结果。
-
-### 5.1 已验证系统参数
-
-| 场景 | defaultValue | handleDefaultValue 示例 |
-|------|--------------|-------------------------|
-| **本月** | `["{thismonth}",""]` | `["2026-08-01,2026-08-31",""]` |
-| **今天** | `["{date}","{date}"]` | `["2026-08-19","2026-08-19"]` |
-| **本周** | `["{thisweek}",""]` | `["2026-08-17,2026-08-23",""]` |
-| **今年** | `["{thisyear}",""]` | `["2026-01-01,2026-12-31",""]` |
-| **当前用户姓名** | `["{lastname}",""]` | `["张三",""]`（高级搜索文本等于） |
-| **当前用户 ID** | 数据集筛选 **`eq`** + `{userid}` | 人员字段「创建者 = 当前登录人员」 |
-
-**注意**
-
-- `{today}` **无效**（不会被解析，占位符会被清空）；「今天」用 **`{date}`**。
-- `{currmonth}` 无效；「本月」用 **`{thismonth}`**。
-- 区间型参数（本月/本周）写在**数组首项**；今天需起止同一天则写 **`["{date}","{date}"]`**。
-- `defaultValue` 必须是 **JSON 数组字符串**，禁止裸写 `"3"` 等（会导致 `getQueryItem` 500）。
-
-### 5.2 设计器操作对应
-
-1. 默认值类型 → **自定义**
-2. 默认值 → 填 `{thismonth}`、`{date}` 等（设计器存为 JSON 数组）
-3. 日期区间 + **启用选项** ON → 21 项快捷按钮（§四）
-
-### 5.3 跨报表传参：目标条件的默认值（报表跳报表 · 2026-11-03 实测）
-
-来源报表把参数拼在钻取地址上：
-
-```text
-/sp/edc/report/view/<目标报表>?searchfield002=13261367755986572676
-```
-
-目标报表**不会**按参数名自动过滤。要接住它，目标报表的查询条件必须把参数名写进「自定义默认值」：
-
-| 键 | 值 |
-|---|---|
-| `defaultValueType` | `"custom"` |
-| `defaultValue` | `'["{searchfield002}",""]'` |
-| `type2DefaultValue` | 同上；`type1DefaultValue` 置空 |
-
-设计器「默认值」框里显示成 `(searchfield002)` —— **圆括号只是 UI 渲染，落库必须是花括号**。
-
-运行时：
-
-- 请求里带同名字段 → `handleDefaultValue` 变成传入值（如 `["江苏EBU一部",""]`），报表按它过滤；
-- 不带 / 传空 → 占位清空成 `["",""]`，直接打开报表不过滤。
-
-⚠️ 条件保持「常规 / 空」时，URL 参数会被**静默忽略**：页面能打开、不报错、数据一条不少。这是钻取不过滤最常见的原因。
-
-- **参数名以 `{…}` 里的名字为准**，链接的 key 必须与它一致；通常就是条件标识 `searchfield00x`。
-- 日期区间用 `{searchfield001_start}` / `{searchfield001_end}`，URL 参数名同名。
-- 体检：`e10-cli report verify drill <来源报表> --app-id <id>` —— 扫来源链接、读目标条件，缺绑定直接失败并给出修法。
-
----
-
-## 六、EBU 报表示例（三条高级搜索 + 数据集行级筛选）
-
-报表 `1304979556231593985` · 数据集 EBU团队 `1304979556231593994`
-
-| 显示名称 | fieldKey 末段 | displayType | relation | 默认值 | queryType |
-|----------|---------------|-------------|----------|--------|-----------|
-| 集团军 | `field_1299763447342276612` | `text` | `Contain` | 无 | `["advance"]` |
-| 入职时间 | `field_1299763447342276619` | `date.ymd` | `between` | `["{thismonth}",""]` | `["advance"]` |
-| EBU成立时间 | `field_1299763447342276620` | `date.ym` | `between` | `["{date}","{date}"]` | `["advance"]` |
-
-> 三条均为「高级搜索」显示方式 → 条件级 `queryType` 一律 `'["advance"]'`（见 §2.1）。
-> 「高级搜索显示形式」（报表级、`saveQueryConfig` → `{"advancedSearchType":"openCondition"}`）是**报表级**开关，与条件级显示方式共享 `queryType` 覆盖关系（§2.1.3）。
-
----
-
-## 七、数据集筛选（设计器左侧 · 行级权限）
-
-> **完整规范已独立成文**：`dataset-query-filter-guide.md`（func 对照、字段对比、日期 format、AND/OR、EBU 金标准、验证清单）。
-> 本节仅保留与高级搜索的边界说明。
-
-**与高级搜索不同**：设计器左侧数据集右键「筛选条件」走 **`queryInfoSave` / `queryInfoGet`**（`conditionData` + `otherData`），**不是** `saveQueryItem`。
-
-| API | 参数 |
-|-----|------|
-| 保存 | `POST /api/bs/edc/dataset/queryInfoSave` → `datasetId`, `filterData`, `otherData` |
-| 读取 | `GET /api/bs/edc/dataset/queryInfoGet` → `datasetId` |
-
-**快速对照**
-
-| 需求入口 | 读哪份文档 |
-|----------|-----------|
-| 页面 → 查询设置（高级搜索） | 本文 §二–§六 |
-| 左侧数据集 → 筛选条件 | **`dataset-query-filter-guide.md`** |
-| 单元格自定义筛选 / datasetFilter | `cross-dataset-filter-guide.md` |
-
----
-
-## 八、验证清单
-
-写入后 `getQueryItem` 回读：
-
-**形态**
-
-- [ ] **调用**：multipart + `queryItems`=**单对象**（非数组）；`conditions` 非 null
-- [ ] 顶层 `filterType: "default"`；`conditions[]` 无 `filterType`
-- [ ] 顶层 `dataSetId` / `name` 为 `null`；`nameIndex: "0"`；`sqlOptions: {}`
-- [ ] **`queryType` 为 JSON 数组字符串**：`'["advance"]'`（高级搜索）或 `'["filter"]'`（筛选），可双选 `'["advance","filter"]'`（§2.1）；**必须以 `[` 开头**
-- [ ] **回显自检**：落库为长码 `"advancedSearch"` → 设计器「显示方式」**必不勾选**（落库错误，改数组即修复）；不要解释为平台缺陷
-- [ ] `asNameIndex` 唯一且 > 0；与 `showOrder` 一致
-- [ ] `fieldOptions` 与 `conditions` 字段一致
-
-**浏览按钮（人员 / 部门）**
-
-- [ ] `displayType: "browser"` 且 **`browserTypeStr` 非空**（§2.1.2）
-- [ ] 字段 `originFieldType=Employee` → `HrmEmployeeComInfo`
-- [ ] 字段 `originFieldType=Department` → `HrmDepartmentComInfo`
-- [ ] `browserTypeStr` 不得为 `"[]"`（关联类型丢失 → 退回「人员」）
-- [ ] 若要求 UI 正确回显显示名，`browserType` 用富对象（含 `name`/`type`），非 `[{"id"}]` 简写
-
-**文本**
-
-- [ ] `displayType: "text"`（非 `select`）
-
-**下拉**
-
-- [ ] `displayType: "select"` 且 `selectOptions.length > 0`
-- [ ] 选项来自匹配字段的 `/ds/options`（`fieldName` 为裸 ID，见 §3.2）
-- [ ] 每项：`selectKey`=选项 ID（数值）、`selectValue`=显示名称（勿写反）
-
-**日期选项**
-
-- [ ] `enableOption=true`、`isTile=true`、`dataOptions` 21 项、`selectOptions=[]`、`optionTile={}`
-
-**日期默认值**
-
-- [ ] `defaultValueType: "custom"`（有默认值时）
-- [ ] `handleDefaultValue` 非空且符合预期（如本月区间、今天同一天）
-- [ ] **未**依赖 `filterParam.dateSelectDefaultValue`
-
-**工具**
-
-- [ ] 设计器刷新：齿轮菜单 21 项、默认值回显、删一条不影响其他条件
-
----
-
-## 八、相关文档
-
-| 文件 | 用途 |
-|------|------|
-| **`dataset-query-filter-guide.md`** | **左侧数据集筛选**（queryInfoSave 完整规范） |
-| **`cell-transform-guide.md`** | **`browserType` 关联类型预设**（人员/部门 ComInfo id） |
-| **`event-hreflink-guide.md`** | 事件链接传 `{searchfield00x}` / 单元格坐标 |
-| `date-range-query-reference.md` | 21 项 dataOptions catalog |
-| `cross-dataset-filter-guide.md` | datasetFilter / customFilterField |
-| `report-building-guide.md` §6 | 设计器操作步骤 |
-| `report-config-schema.md` §五 | Schema 摘要 |
-| `SKILL.md` §6.3–§6.4 | Agent 步骤入口 |
+# 查询条件 API 写入规范
+
+> **适用场景**：通过 `saveQueryItem` / `saveQueryConfig` API 或脚本添加、修复报表查询条件。
+> **金标准报表**：`1304979556231593985`（EBU 经营数据统计）
+> **核心规则**：数据集合选取后，**选择类型未特别指定 SQL 时，一律默认为「条件字段」**。
+
+## ⚡ TL;DR — 显示方式（2026-09-11 定案，务必先读 §2.1）
+
+| 事实 | 结论 |
+|---|---|
+| 条件级 `queryType` 正确落库值 | **JSON 数组字符串** `'["advance"]'`（高级搜索）/ `'["filter"]'`（筛选） |
+| 前端回显判据 | 只看首字符是否 `[`；`'["advance"]'` → 勾选 ✅，`"advancedSearch"` → 不勾 ❌ |
+| **`updateQueryType` 是最大陷阱** | 它把入参 `queryType` **批量写进所有条件**；传长码 = 一键摧毁全表回显（§2.1.3） |
+| 保存后必须自检 | `e10-cli report query check-echo --report-id <id> --app-id <appId>` |
+| 一键修复 | `e10-cli report query fix-echo --report-id <id> --app-id <appId>` |
+
+---
+
+## 一、选择类型（设计器 UI ↔ API）
+
+| 设计器「选择类型」 | 顶层 `filterType` | `conditions[]` 内 | 说明 |
+|-------------------|-------------------|-------------------|------|
+| **条件字段**（默认） | `"default"` | **仅** `dataSetId` + `fieldId` + `relation` | 绑定数据集字段，禁止 SQL |
+| **SQL**（显式指定） | `"sql"` | `"filterType": "sql"` + `sql` | 私有化环境才可用 |
+
+**Agent 硬约束**：除非需求明确写「SQL 条件」，否则不得使用 `filterType: "sql"`。
+
+**常见错误**
+
+| 错误写法 | 后果 |
+|----------|------|
+| `conditions[].filterType: "field"` | 设计器「选择类型」无法回显为「条件字段」 |
+| 顶层 `dataSetId` / `name` 有值 | 与设计器 save 形态不一致，回显异常 |
+| `sqlOptions: {selected: ...}` | 条件字段应为 `{}` |
+| `defaultValue: "3"`（非 JSON 数组） | `getQueryItem` 解析失败，整表 500 |
+| **`queryItems` 传数组 `[]`/`[{…}]`** | 服务端 `parseObject` 单对象失败 / NPE → **saveQueryItem 500** |
+| **`queryItems` 为 `{}` 且无 `conditions`** | `getConditions().size()` NPE → **500** |
+| **JSON body 而非 multipart** | 参数绑不上 / 权限校验异常 → 常 500 |
+| 缺 `ebBusinessId` | `wrapEbRightCheck` 编辑权限失败 |
+
+---
+
+## 二、条件字段标准形态（saveQueryItem）
+
+设计器 save 后回读的金标准结构：
+
+| 字段 | 条件字段正确值 |
+|------|----------------|
+| 顶层 `dataSetId` | **`null`** |
+| 顶层 `name` | **`null`** |
+| `nameIndex` | **`"0"`** |
+| `filterType` | **`"default"`** |
+| `sqlOptions` | **`{}`** |
+| `conditions[]` | 仅 `dataSetId` + `fieldId` + `relation` |
+| `fieldOptions` | 必传（含 `selected`、`dataSetField`、`relation`）；`getQueryItem` 不持久化，更新时须重带 |
+| `asNameIndex` | **唯一且 > 0**；更新时**必须回传**，否则置 0。`showOrder`（弹窗「排序」）人工配置通常留 **`0`**（= 未设，平台回落按 `asNameIndex` 排）——API 建条件时若自行填 1,2,3… 会在弹窗上留下可见差异（2026-09-14 验证参照报表 5 条全为 0）。事件超链接传查询值用 `{searchfield` + 三位补零 + `}`（如 `asNameIndex=1` → `{searchfield001}`，区间另加 `_start`/`_end`），见 `event-hreflink-guide.md` |
+| **默认值三件套** | **必填**：`defaultValueType`（`default`=常规 / `custom`=自定义）+ `defaultValue`（当前生效值）+ `type1DefaultValue`（常规那份）/ `type2DefaultValue`（自定义那份）；值均为 **JSON 字符串**。**漏写 → 设计器弹窗「默认值类型」= 请选择、默认值区炸开、后续整段行被顶出可视区**（见 §2.1.10） |
+| `fieldId` / `dataSetField` | fieldKey：`{dataSetId}.{sourceId}.{fieldName}` |
+| **`queryType`（显示方式）** | **必填 JSON 数组字符串**，见 §2.1；`'["advance"]'`（高级搜索，默认）或 `'["filter"]'`（筛选），可双选 `'["advance","filter"]'`。**服务端也接受长码字符串 `"advancedSearch"`，但那样设计器 UI 不会勾选** |
+| `showWhere`（遗留） | 设计器一律写 `""`；**勿**用它表达显示方式 |
+| `browserType` / `browserTypeStr` | `displayType=browser` 时必填；富对象优先，落库判据是 `browserTypeStr`（见 §2.1.2） |
+
+```python
+def build_conditions(ds_id, field_id, relation):
+    return [{"dataSetId": ds_id, "fieldId": field_id, "relation": relation}]
+
+def build_field_options(ds_id, field_id, relation, item_id=None):
+    row = {"dataSetField": field_id, "relation": relation, "queryItemValue": "输入值"}
+    if item_id:
+        row["id"] = str(item_id)
+    return {"selected": ds_id, ds_id: [row]}
+```
+
+API：`POST /api/bs/edc/report/saveQueryItem`
+
+| 项 | 正确 | 错误 → 常 500 |
+|----|------|----------------|
+| Content-Type | **`multipart/form-data`** | `application/json` 整包 body |
+| 表单字段 | `reportId` + **`queryItems`** | 缺参、或写成 `queryItem` / `items` |
+| `queryItems` 值 | **单个** QueryField **对象**的 JSON 字符串 | **`[]` / `[{...}]` 数组**（源码 `parseObject` 单对象） |
+| Header | `eteamsid` + `Cookie` + **`ebBusinessId`/`ebbusinessid`=appId** | 缺业务 app，权限包装失败 |
+| Referer | `/sp/edc/report/designer/{reportId}` | 可无，但建议带 |
+
+```http
+POST /api/bs/edc/report/saveQueryItem
+Content-Type: multipart/form-data; boundary=----x
+
+------x
+Content-Disposition: form-data; name="reportId"
+
+{reportId}
+------x
+Content-Disposition: form-data; name="queryItems"
+
+{"dataSetId":null,"name":null,...,"conditions":[{...}],"fieldOptions":{...}}
+------x--
+```
+
+**硬约束（源码 `EdcReportDevDesignServiceImpl.saveQueryItem`）**
+
+1. `JSONObject.parseObject(queryItems, QueryFieldDto.class)` → **禁止**传数组。
+2. 非私有化环境会对 `queryField.getConditions()` 做 `jsonArray.size()`；**`conditions` 为 null**（如 `queryItems="{}"`）→ **NPE → 接口 500**。
+3. 一次请求只保存**一条**条件；多条 → **循环多次** `saveQueryItem`（每条一个对象）。
+4. 更新已有条件：对象内带 `id`（字符串雪花）；新建不带 `id`，服务端生成并自动递增 `asNameIndex`。
+5. `saveQueryConfig` **不能代替** `saveQueryItem`；可先可后，但有高级搜索条件时建议条件级 `queryType: '["advance"]'`（见 §2.1）。
+
+```javascript
+// ✅
+await saveQueryItem({ reportId, queryItems: JSON.stringify(oneItemObject) });
+// ❌
+await saveQueryItem({ reportId, queryItems: JSON.stringify([oneItemObject]) });
+await saveQueryItem({ reportId, queryItems: '[]' });
+await saveQueryItem({ reportId, queryItems: '{}' }); // conditions 缺失 → 500
+```
+
+---
+
+### 2.1 显示方式（强制 · 不可不选）
+
+> **✅ 终局定案（2026-09-11 · 以「设计器手工配置的真实条件」为金标准反推）**
+>
+> 条件级「显示方式」的正确落库值是 **JSON 数组字符串**：
+>
+> | 显示方式 | 正确落库值 |
+> |---|---|
+> | 高级搜索 | `'["advance"]'` |
+> | 筛选 | `'["filter"]'` |
+> | 两者都选 | `'["advance","filter"]'` |
+>
+> **服务端对取值不敏感**：`'["advance"]'` / `'["filter"]'` / `'["advance","filter"]'` / `"advancedSearch"` / `"filter"` **全部返回 200 并原样落库**。
+> **但只有 JSON 数组形态能在设计器 UI 正确回显勾选**；长码字符串 `"advancedSearch"` 会导致 **UI 两个都不勾**（旧版文档「写短码 500」的说法是错的，见下方推翻记录）。
+
+#### 2.1.1 前端回显规则（源码级 · `_src/route_DatasetList.js`）
+
+前端**只看首字符是否为 `[`**，据此决定是否 JSON 解析：
+
+```js
+// ① 读取（initCondition）—— 唯一判定逻辑
+t.queryType = (t.queryType?.indexOf("[") > -1)
+    ? JSON.parse(t.queryType || "[]")     // 含 "[" → 解析成数组
+    : t.queryType || [];                  // 不含 → 原样保留（普通字符串）
+```
+
+```js
+// ② 复选项定义（initConditionFormStore）—— 选项 id 是「短码」
+queryType:{ itemType:"CHECKBOX", required:!0,
+  data:[{ id: ze.g.advance, content:"高级搜索" },
+        { id: ze.g.filter,  content:"筛选" }],
+  otherParams:{ minSelected:1 } }
+```
+
+```js
+// ③ 短码枚举（lib.js）
+function(e){ e.filter="filter"; e.advance="advance" }(i||(i={}))
+```
+
+```js
+// ④ 新建条件默认值（仅 fieldKey 为空时）
+this.fieldKey || (i.queryType = ["advance"])     // ← 注意：默认就是「数组」
+```
+
+```js
+// ⑤ 保存 —— 表单值原样写回，不做类型转换
+var l = e.conditionFormStore.getFormDatas();
+r.queryType = l.queryType;
+s.append("queryItems", JSON.stringify(r));
+```
+
+**推论（四条必须记牢）**
+
+1. `CheckboxGroup` 用**严格相等**匹配：表单 value 的每个元素 vs `data[].id`。
+2. 落库 `'["advance"]'` → 解析为 `["advance"]` → 元素 `"advance"` === 选项 id `"advance"` → **勾选 ✅**
+3. 落库 `"advancedSearch"` → 不含 `[` → 保留为字符串 `"advancedSearch"` → 与选项 id 严格不等 → **不勾选 ❌**
+4. **设计器自己写出的就是数组**（见 ④ 默认值、⑥ 接口返回）；长码 `"advancedSearch"` 只可能由**脚本手写**产生 → 它是**错误值**。
+
+#### 2.1.2 验证证据链（2026-09-11，报表 `1313798296523022337`，应用「进销存管理-共享表」）
+
+**A. API 写入实验（`saveQueryItem`，同一条件往返改 4 种值）**
+
+| 写入值 | 返回 | 回读落库 | UI「显示方式」 |
+|---|---|---|---|
+| `'["advance"]'` | **200** | `'["advance"]'` | **高级搜索 ☑ ✅** |
+| `'["filter"]'` | **200** | `'["filter"]'` | 筛选 ☑ ✅ |
+| `'["advance","filter"]'` | **200** | `'["advance","filter"]'` | 双选 ☑ ✅ |
+| `"advancedSearch"`（长码） | **200** | `"advancedSearch"` | **两个都不勾 ❌** |
+
+> ⚠️ 四者**全部 200**，不存在「写短码 → 500」。旧结论 500 的真实成因是**手写 multipart payload 的结构/字段不被服务端封装接受**，与 `queryType` 取值无关。
+
+**B. 三条条件 UI 回显对照（CDP 真实鼠标点击 tag → 读弹窗 checkbox）**
+
+| 条件 | 落库 `queryType` | UI「显示方式」 |
+|---|---|---|
+| 销售部门（**人工手工配置**） | `'["advance"]'` | **高级搜索 ☑** |
+| 销售人员（脚本写长码） | `"advancedSearch"` | **两个都 ☐** |
+| 销售日期（脚本写长码） | `"advancedSearch"` | **两个都 ☐** |
+
+→ 脚本手工写的长码条件**全军覆没**，人工配置的数组条件**正确回显**。把两条长码条件改为 `'["advance"]'` 后，三条**全部回显 ☑ 高级搜索**，闭环验证通过。
+
+**C. 设计器真实 `saveQueryItem` 接口返回（人工点击「确定」）**
+
+```
+Content-Disposition: form-data; name="queryItems"
+
+{"id":"…","sheetId":"…","nameIndex":"0","text":"销售部门","displayType":"browser",
+ "showWhere":"","advancedSearchType":"openCondition","queryType":["advance"], … }
+                                                          ^^^^^^^^^^^^^^^^^^
+                                                          数组（短码），非字符串长码
+```
+
+> 设计器上行 payload 里就是 `"queryType":["advance"]`（**数组 + 短码**）—— 这是平台的权威写法。
+
+#### 2.1.3 🔴 真正根因：`updateQueryType` 会**批量覆盖所有条件**（最关键）
+
+> **`POST /api/bs/edc/report/updateQueryType` 不是「只改报表级设置」** —— 它会把入参 `queryType` **全量写进该报表的每一条查询条件**，覆盖刚保存好的数组值。
+> 这是「条件显示方式永远不勾选」的**真正单点根因**，也是历史定位一直抓不到的那个洞。
+
+**验证矩阵**（同一报表连续调用，观察条件级 `queryType`）
+
+| 调用 `updateQueryType(queryType=…)` | 三条条件级 `queryType` 变为 | 设计器回显 |
+|---|---|---|
+| `"advancedSearch"`（长码） | `advancedSearch` ×3 | **全不勾 ❌** |
+| `"advance"`（裸短码） | `advance` ×3 | 不勾 ❌ |
+| `"filter"` | `filter` ×3 | 不勾 ❌ |
+| **`'["advance"]'`（数组短码）** | `'["advance"]'` ×3 | **全勾 ✅** |
+
+**为什么历史定位一直失败**
+
+```text
+旧 CLI 的 save 流程：  saveQueryItem(写 '["advance"]' ✅)  →  updateQueryType("advancedSearch" ❌)
+                                          ↓ 刚写好的数组                 ↓ 立刻被批量打回长码
+                                     设计器打开 → 不勾选
+人工在页面直接配条件：  只走 saveQueryItem，不经过 updateQueryType  →  '["advance"]' 完好 → 正常勾选
+```
+
+于是「人工配的能勾、API 写的不能勾」，长期被误判为「平台前端缺陷，客户端不可修」。**实际是 CLI 自己把值写坏了。**
+
+**硬约束**
+
+1. **`updateQueryType` 的 `queryType` 必须传数组短码**：`'["advance"]'` / `'["filter"]'`，**与条件级同形态**。传长码 = 一键摧毁全表回显。
+2. **保存条件的推荐调用顺序**：`saveQueryItem`（数组） → `updateQueryType`（**同一个数组值**）。
+3. **不要**在保存后用长码 `updateQueryType`「对齐报表级显示形式」—— 它顺带把条件级也改坏。若只需报表级 `advancedSearchType`（如 `openCondition`），仍须把 `queryType` 传成数组形态。
+4. 落库后**必须回读自检**：`e10-cli report query check-echo --report-id <id> --app-id <appId>`。
+
+#### 2.1.4 落库门禁
+
+| 检查 | 接口 | 通过标准 |
+|------|------|----------|
+| **条件级显示方式（落库）** | `POST /api/bs/edc/report/getQueryItemNew`（multipart `reportId` + `query:'{}'`） | 每条 `queryType` 是 **含 `[` 的 JSON 数组字符串**，元素 ∈ `advance` / `filter` |
+| 报表级 + 条件级批量对齐 | `POST /api/bs/edc/report/updateQueryType` | `code=200`，且入参 `queryType` **为数组短码**（§2.1.3） |
+
+**硬约束**
+
+1. **写 `queryType` = JSON 数组字符串**：`'["advance"]'` / `'["filter"]'` / `'["advance","filter"]'`。**不要写长码 `"advancedSearch"`**（可落库但 UI 不回显）。
+2. **写 `showWhere: ""`**（遗留字段，设计器一致行为）。
+3. **回读判据**：`getQueryItemNew` 的 `queryType` **必须以 `[` 开头**。若是 `"advancedSearch"` → **回显必不勾**，需改写为 `'["advance"]'`。
+4. **强制走 CLI**：Agent 禁止手写 multipart 调 `saveQueryItem`；统一 `e10-cli report query save|type|list|check-echo|fix-echo` / `validate query`。
+5. 用户反馈「显示方式没勾选」时：**先 `check-echo` 回读 `queryType`**。若为长码 → **可修复的落库错误**，`fix-echo` 即恢复（**不要再解释为平台缺陷**）；同时定位是否被 `updateQueryType` 长码覆盖过。
+
+#### 2.1.5 报表级 vs 条件级（勿混淆）
+
+| 层面 | 字段 | 正确值 | 存储形态 |
+|---|---|---|---|
+| **条件级**「显示方式」（编辑查询条件弹窗内） | `queryType` | `'["advance"]'` / `'["filter"]'` | **JSON 数组字符串**（§2.1） |
+| **报表级**「高级搜索显示形式」（查询设置弹窗） | `queryType`（入参） | **也须 `'["advance"]'` / `'["filter"]'`** | 会被批量写入所有条件（§2.1.3） |
+
+> 「查询设置」弹窗只有 `高级搜索显示形式 + 默认样式/展开条件` 等报表级开关；条件级的「显示方式 ☑高级搜索 ☑筛选」在**「编辑查询条件」**弹窗里，两者入口不同，但**落库字段同名、同形态、且共享覆盖关系**。
+
+#### 2.1.6 ⚠️ 旧结论推翻记录（避免回退）
+
+| 旧结论（2026-09-10/11 早期） | 现结论（2026-09-11 定案） |
+|---|---|
+| 落库必须写长码 `"advancedSearch"` | ❌ 错。落库必须写数组 `'["advance"]'` |
+| 写短码 `"advance"` → 服务端 500 | ❌ 错。写数组短码 **200 正常落库** |
+| 「UI 不勾选 = 平台缺陷，客户端不可修」 | ❌ 错。**改数组即可修复**，是脚本落库值写错 |
+| `advancedSearch` 前端 0 次出现 → 服务端产物 | ⚠️ 部分成立（前台确实无此串），但它**不是**服务端要求的取值，而是脚本臆造的 |
+| 前端 `edit` 直取长码灌表单 → 死循环 | ❌ 错。`edit` 灌的就是落库值；落库是数组时**正常勾选** |
+| 条件级与报表级是两个独立字段，互不影响 | ❌ 错。`updateQueryType` 用 `queryType` **批量覆盖所有条件**（§2.1.3 真正根因） |
+| `updateQueryType` 只改报表级「高级搜索显示形式」 | ❌ 错。它会把入参写进每条条件 → 长码一键摧毁全表回显 |
+
+**旧结论怎么来的 / 为什么错**：早期用 JS 合成事件点击条件 tag，实际点到了**左侧字段面板**的「显示方式」（那是字段属性，非条件显示方式），读取勾选态得到假信号；且未把「人工配置的条件」作为金标准对照。**修复方式**：改用 **CDP `Input.dispatchMouseEvent` 真实鼠标事件**点条件 tag，读「编辑查询条件」弹窗，并以人工条件为参照。
+
+**真正根因的发现路径**：给 `save` 加「落库后回读自检」时，发现**刚写入的数组被回读成长码** → 隔离实验证明只有 `saveQueryItem` 时数组完好，一旦再调 `updateQueryType` 即被批量覆盖 → 穷举入参证明 `updateQueryType` 是「全表条件 `queryType` 批量写」。**AI 自检回读是抓到它的关键手段**，务必保留。
+
+#### 2.1.7 修复已有错误条件的操作
+
+**首选（CLI 一键）：**
+
+```bash
+e10-cli report query check-echo --report-id <id> --app-id <appId>   # 诊断
+e10-cli report query fix-echo   --report-id <id> --app-id <appId>   # 修正为数组短码
+```
+
+**手动脚本（等价实现，含 `updateQueryType` 数组化）：**
+
+```python
+# 读取 → 把长码条件就地改为数组短码 → 保存 → 再用数组形态对齐报表级(批量)
+import json, copy, sys
+import _eb
+
+APP, RID = "<appId>", "<reportId>"
+DROP = {"browserTypeStr","selectOptionsStr","conditionStr","sqlOptionsStr",
+        "filterParamStr","handleDefaultValue","updateTime"}   # 回显列，服务端不接受
+
+def read():
+    r = _eb.post("/api/bs/edc/report/getQueryItemNew",
+                 data={"reportId": RID, "query": "{}"}, app_id=APP)
+    return ((r.get("data") or {}).get("list")) or []
+
+def save(item):
+    it = {k: v for k, v in item.items() if k not in DROP}
+    return _eb.post("/api/bs/edc/report/saveQueryItem",
+                    data={"reportId": RID, "queryItems": json.dumps(it, ensure_ascii=False)},
+                    app_id=APP)
+
+for q in read():
+    if not str(q.get("queryType") or "").startswith("["):      # 长码/空 → 修正
+        it = copy.deepcopy(q)
+        it["queryType"] = '["filter"]' if q.get("queryType") == "filter" else '["advance"]'
+        print(q["text"], "->", save(it).get("code"))
+
+# ⚠️ 关键：若还要对齐报表级高级搜索显示形式，updateQueryType 的 queryType 必须用数组形态，
+#    否则它会把全部条件重新打回长码（§2.1.3）。
+_eb.post("/api/bs/edc/report/updateQueryType",
+         data={"reportId": RID, "queryType": '["advance"]', "advancedSearchType": "openCondition"},
+         app_id=APP)
+```
+
+**设计器真实保存形态（金标准，从 `saveQueryItem` 接口返回）**
+
+```json
+{
+  "id": "…", "sheetId": "<reportId>", "nameIndex": "0",
+  "text": "销售部门",
+  "displayType": "browser",
+  "browserType": [{ "id": "3332180495306215437", "name": "部门", "type": "department",
+                    "module": "hrm", "groupId": "<groupId>", "tenantKey": "<tenantKey>",
+                    "dataId": "2005096031068185488", "labelId": "52148",
+                    "licenseModule": "hrm", "systemDefault": 1, "ebuliderDataBrowser": false, "disable": 0 }],
+  "browserTypeStr": "[{\"id\":\"HrmDepartmentComInfo\"}]",
+  "showWhere": "",
+  "queryType": ["advance"],
+  "dateType": "ymd",
+  "filterParam": { "optionTile": {}, "isTile": false, "multiple": true, "dataOptions": [],
+                   "enableOption": false, "required": false, "dateSelectDefaultValue": "",
+                   "numberSelectDefaultValue": "", "eBuilderForm": "", "titleField": "" },
+  "defaultValue": "[[],\"\"]", "handleDefaultValue": "[[],\"\"]",
+  "filterType": "default", "fieldOptions": {},
+  "conditions": [{ "dataSetId": "…", "fieldId": "…", "relation": "Equals" }],
+  "asNameIndex": 1, "showOrder": 1
+}
+```
+
+---
+
+### 2.1.9 🔴 `advancedSearchType` —— **禁止静默注入**（会改掉报表页查询区的「样式」）
+
+> **事故（2026-09-14）**：在报表 `1314970921403138199` 加 5 条查询条件后，用户质问
+> 「怎么又把查询条件的样式改了，这个之前强调过不能动页面上原有展示格式」。
+> 定位结论：**用户的 payload 里根本没有 `advancedSearchType`**，是 CLI `e10-cli report query save`
+> 在保存时**无条件注入** `advancedSearchType: 'openCondition'`（=「展开条件」）。
+
+**字段语义（源码级）**
+
+| 项 | 结论 |
+|---|---|
+| 实体字段 | `QueryFieldCommon.advancedSearchType`（`@ApiModelProperty("高级搜索类型")`） |
+| 唯一功能读点 | `SheetServiceImpl`：取**第一条**高级搜索条件的 `advancedSearchType`，`=='openCondition'` → `isOpenCondition=true` |
+| 页面效果 | `isOpenCondition=true` → 报表页查询区**展开铺开**（「展开条件」）；否则 → **默认样式**（右上角搜索图标，点击才展开） |
+| 设计器入口 | 报表级「查询设置」弹窗的 **高级搜索显示形式：默认样式 / 展开条件** |
+| 人工条件（金标准） | **该键不存在**（`undefined`），平台不主动写 |
+
+**硬规则**
+
+1. **入参没有该键 → 就别写该键**（保持线上原值）。CLI 只在显式 `--advanced-search-type openCondition` 时才写。
+2. `updateQueryType`（批量对齐 `queryType`）**不得夹带** `advancedSearchType`。
+3. 该字段属于**展示样式**，与「显示方式」（`queryType`：高级搜索/筛选）**是两回事**，不得绑定在一起写。
+4. 用户没说「展开条件」时，任何情况下都不要写它。
+
+**判别与修复**
+
+```bash
+# 判别：条件里 advancedSearchType 非空 = 被注入过
+e10-cli report query list --report-id <id> --app-id <appId>
+
+# 修复（默认 dry-run；--apply 落库；只清该字段，保留 id/顺序/queryType）
+e10-cli report fix query-style --report-id <id> --app-id <appId> [--id <itemId>...] [--apply]
+
+# 附带修复「不带 id 保存 → 变成新增」造成的重复条件行（删除必须显式列 id）
+e10-cli report fix query-style --report-id <id> --app-id <appId> --delete-id <itemId> --apply
+```
+
+> ⚠️ **另一个必须记住的坑**：`saveQueryItem` **必须带 `id` 才是原地更新**；
+> 不带 `id` 会**INSERT 一条新条件**（`asNameIndex` 自增），报表上出现重复条件。
+> 更新存量条件时，payload 一律从线上回读对象派生并**保留 `id`**。
+
+---
+
+### 2.1.10 🔴 「默认值三件套」漏写 → 设计器弹窗整段坏掉（2026-09-14 事故）
+
+**用户看到的现象**（"查询条件的样式被改了"）：
+
+| 现象 | 说明 |
+|------|------|
+| 「默认值类型」= **请选择** | 本该是「常规」或「自定义」 |
+| 「默认值」区**同时铺开所有控件变体** | 请输入 / 开始日期-结束日期 / 选择日期时间 / 请选择 / 选择日期 / 选择月份 / 选择年份 … 一屏全来 |
+| 「日期类型 / 显示位置 / 条件必填 / 查询条件」**看不见** | 被上面那一大片顶出可视区（弹窗高度固定），并非真被删除 |
+
+**根因**：弹窗的默认值区由 `defaultValueType` 驱动渲染。不写它 → 前端取不到模式 → 每个变体都渲染一遍。
+
+**数据模型（验证参照报表 `1314938962594906121`，人工配置的权威形态）**
+
+| 键 | 含义 | 参照「年月」取值 | 参照「部门」取值 | 参照「人员/加班/聘用」取值 |
+|----|------|------------------|------------------|----------------------------|
+| `defaultValueType` | 模式：`default`=常规 / `custom`=自定义（前端 label：`55337`=常规、`53999`=自定义） | `custom` | `default` | `default` |
+| `defaultValue` | **当前生效**的值 | `["{yearmonth:-0}",""]` | `[[],""]` | `["",""]` |
+| `type1DefaultValue` | 「常规」模式下保存的值 | `""` | `[[],""]` | `["",""]` |
+| `type2DefaultValue` | 「自定义」模式下保存的值 | `["{yearmonth:-0}",""]` | `""` | `""` |
+| `handleDefaultValue` | 平台解析后的实际值（**服务端自己算并回写**） | `["2026-09",""]` | `[[],""]` | `["",""]` |
+
+> ⚠️ **全部是 JSON 字符串**（`"[[],\""]"` 这种），不是对象/数组本身。
+> ⚠️ 日期占位符（`{yearmonth:-0}` 等）**不用自己解析**：落库时平台会把 `handleDefaultValue` 回写成 `["2026-09",""]`（验证）。
+> 设计器「新建条件」模板本身带 `defaultValueType:"default"` + `defaultValue:["",""]`，所以**人工配的条件永远不会缺** —— 只有用 API 建条件时才会漏。
+
+**修复**
+
+```bash
+# 只补缺失项（默认模式、空默认值 —— 弹窗恢复正常渲染，不改取数范围）
+e10-cli report fix query-default --report-id <id> --app-id <appId> --apply
+
+# 点名某条用「自定义」默认值（如 年月默认当月，与参照报表一致）
+e10-cli report fix query-default --report-id <id> --app-id <appId> \
+  --set '年月=custom:["{yearmonth:-0}",""]' --set '部门=default:[[],""]' --apply
+
+# 顺带把「排序」对齐为设计器模板值 0
+e10-cli report fix query-default --report-id <id> --app-id <appId> --all --show-order 0 --apply
+```
+
+落库后脚本会自动回读校验（`stillMissingDefaultValueType` 必须为空）。
+
+---
+
+### 2.1.11 ★ 查询条件合规体检（Q1~Q10 判据总表 · `e10-cli report verify query`）
+
+> 把本章所有坑的**判据**固化成一条只读命令。搭完条件、改完条件、用户投诉后，第一件事就是跑它。
+> **命令**：`e10-cli report verify query <reportId> <appId> [--json] [--fix]`（等价别名 `e10-cli report query verify ...`）
+> 有 FAIL → exit 1；`--fix` 只做幂等安全项（清样式字段 / 补三件套 / 短码化），**绝不新增或删除条件**。
+
+| # | 判据 | 级别 | 不通过时页面上的表现 | 出处 |
+|---|------|------|----------------------|------|
+| Q1 | `queryType` 是 **JSON 数组短码**（以 `[` 开头且可 parse 成数组） | FAIL | 设计器「显示方式」复选框是空的 | §2.1.1 / QUERY-1 |
+| Q2 | `advancedSearchType` **必须为空** | FAIL | 报表页查询区从「默认样式」变成「展开条件」铺开 | §2.1.9 / QUERY-5 |
+| Q3 | `defaultValueType` 有值（`default`\|`custom`） | FAIL | 弹窗「默认值类型」=请选择，默认值区把**所有**控件变体炸开 | §2.1.10 / QUERY-7 |
+| Q4 | `defaultValue` 有值（JSON 字符串） | WARN | 默认值区仍可能铺开 | QUERY-7 |
+| Q5 | `type1DefaultValue`（常规）/ `type2DefaultValue`（自定义）随模式在位 | WARN | 切换模式时值丢失 | QUERY-7 |
+| Q6 | `id` 存在且 `asNameIndex` **唯一且 >0** | FAIL | 重复条件 / 保存变新增 | QUERY-6 |
+| Q7 | `displayType=browser` 时 `browserType` 富对象非空 + `browserTypeStr` 非空 | FAIL | 关联类型为空、条件点不开 | §2.1.2 / QUERY-3 |
+| Q8 | `filterParam.required` / `showType` 在位 | WARN | 「显示位置 / 条件必填」等弹窗后段字段为空 | — |
+| Q9 | `showOrder` 是否为设计器模板值 `0` | INFO | 弹窗「排序」与人工配置有可见差异 | QUERY-7 |
+| Q10 | 报表级 `queryType` **是否混杂**（同时存在多种写法） | WARN | 曾被 `updateQueryType` 批量覆盖过 | §2.1.3 / QUERY-2 |
+
+> **不要拿 `getQueryConfig` 当判据** —— 本环境它恒返回 `data:null`（QUERY-4）。判据一律走 `getQueryItemNew` 回读。
+
+---
+
+### 2.1.2 关联类型 `browserType`：必须写「富对象」，不是 `[{id}]` 简写（强制）
+
+> **事故**：同报表查询条件「销售部门」绑定字段 `originFieldType=Department`，但设计器关联类型显示为空/默认**人员**。**定案根因：`browserType` 写成了简写 `[{"id":"HrmDepartmentComInfo"}]`，缺少 `name`/`type` 等字段 → 前端无法解析显示名 → 退回默认「人员」标签页。**
+
+**设计器真实形态（金标准）**：`browserType` 是 **全字段富对象数组**，关键字段 `name`（显示名）、`type`（`department`/`employee`）、`module`、`groupId`、`tenantKey`、`dataId`、`labelId`、`id`。**`browserTypeStr` 才是落库判据**（服务端存 `[{"id":"HrmDepartmentComInfo"}]` 形式的字符串）。
+
+| 字段 `originFieldType` | `displayType` | `browserTypeStr`（落库） | 设计器关联类型 |
+|------------------------|---------------|--------------------------|----------------|
+| `Employee` | `browser` | `[{"id":"HrmEmployeeComInfo"}]` | **人员** |
+| `Department` | `browser` | `[{"id":"HrmDepartmentComInfo"}]` | **部门** |
+| `DepartmentAllPath` | `browser` | `[{"id":"HrmDepartmentAllPathComInfo"}]` | 部门全路径 |
+
+**推荐获取富对象的正确姿势（最稳）**：**不要手拼** `browserType` 富对象；用 `saveQueryItem` 时：
+1. `displayType: "browser"` + `browserTypeStr` 写 `[{"id":"HrmDepartmentComInfo"}]`；
+2. 或在设计器里手动选一次「部门」让前端生成富对象后接口返回复用（本环境已验证：手动选后可正确回显「部门」）。
+
+**硬约束**
+
+1. `displayType: browser` **禁止** `browserTypeStr: "[]"`；必须按字段 `originFieldType` 写入对应 ComInfo id。
+2. 仅写 `[{"id":...}]` 简写**服务端可接受**（`browserTypeStr` 落库正确），但**前端回显可能为空**；若要求 UI 正确显示，需富对象。
+3. `e10-cli report query save` 内置 `applyQueryDisplayType()` 自动补 `browserType`（未显式指定 `displayType` 时）；不匹配时输出 **WARN**。
+4. 回读核对：`browserTypeStr` 不得为 `"[]"`（丢了 → 退回「人员」）。
+5. 跳过自动推导用 `--skip-display-type`（仅在确实要手填时）。
+
+---
+
+```javascript
+// 显示方式：条件级落库值 = JSON 数组字符串（前端唯一能回显勾选的形态）
+function resolveQueryType(userHint) {
+  const s = String(userHint || '').toLowerCase();
+  if (/筛选|filter/.test(s) && !/高级搜索|advanced/.test(s)) return '["filter"]';
+  return '["advance"]';   // 默认「高级搜索」· 不可不选
+}
+// 注意：showWhere 一律写 ''（遗留字段）
+//      条件级选项 id 是短码 advance/filter；落库必须是含 "[" 的 JSON 数组字符串，
+//      否则前端首字符判定落空 → 退化为普通字符串 → 严格相等失败 → UI 不勾选（见 §2.1）
+//      报表级 updateQueryType 的 queryType 也须用数组形态（它会批量覆盖所有条件，见 §2.1.3）
+```
+
+### 2.1.8 「显示方式没勾选」诊断卡（对接用户质询时用）
+
+| 用户说法 | 你的回答要点 |
+|---|---|
+| 「页面上显示方式没勾选」 | 先 `getQueryItemNew` 回读 `queryType`：**是否以 `[` 开头**？ |
+| 「回读是 `'["advance"]'` 却仍不勾」 | 极罕见；先强刷设计器页面（CDN/缓存），再核对条件 `id` 是否为最新 |
+| 「回读是 `"advancedSearch"` 长码」 | **这是落库值写错了**，属可修复问题 → 改写为 `'["advance"]'`，重开弹窗即勾选 |
+| 「能修吗？」 | **能修**：把 `queryType` 改为 JSON 数组字符串（§2.1.7 脚本 / `e10-cli report query fix-echo`） |
+| 交付口径 | 「已修正落库值，条件显示方式回显正常」——**不要再解释为平台缺陷** |
+
+**判据一行流**
+
+```text
+queryType 以 "[" 开头  → 数组 → UI 勾选正常 ✅
+queryType 是其它字符串  → 退化 → UI 不勾选  ❌（改写为 '["advance"]'）
+```
+
+> （`route_DatasetList.js` 179879B / `route_ReportDesigner.js` 702877B / `lib.js` 661658B）；
+> UI 回显用 `_q_real2.py`（CDP `Input.dispatchMouseEvent` 真实鼠标点击条件 tag + 读「编辑查询条件」弹窗 checkbox）。
+
+### 2.1.2.1 关联浏览分类元数据接口（⚠️ 富对象唯一正确来源）
+
+> **勿手拼富对象！** 富对象的 13 个字段值全部来自服务端接口，手拼易错（`labelId`/`dataId` 无法猜）。
+> 本接口 2026-09-11 定位、**2026-09-14 修正为 GET `browserBeanSearch`**，为「部门 / 人员 / 岗位 …」全部关联类型的权威数据源。
+
+```http
+GET /api/bcw/relevanceBrowser/browserBeanSearch?searchValue=<中文分类名>
+Header: ebbusinessid: <appId>
+→ data.data[]        每条 = 13 键富对象
+```
+
+> 🔴 **2026-09-14 修正**：旧文档写的 `POST /api/bcw/relevanceBrowser/getBrowserBean` 在**本环境恒返回 `{"code":500,"msg":"接口错误"}`**（前端其实把 `browserBeanSearch` 的响应**本地拦截**了 —— 见 `lib.js` 里 `relationList()` 分支，所以它在页面上看起来"能用"）。
+> 可用的是 **GET `browserBeanSearch`**；`searchValue` 必须用**中文分类名**（拼音检索服务端不支持：`bm` / `ry` 返回 0 条），空串只返回档案/工作流等非 HRM 分类。
+> CLI 已内置此回退：`themes/e10-cli report query save` 的 `fetchBrowserBeanSearch()`；`displayType=browser` 且 `browserType` 仅为 `[{id}]` 简写时**自动升级为富对象**。
+
+**验证取值（租户 `tmxislnm9p` / 应用 1178336857624084480）**
+
+```http
+GET …/browserBeanSearch?searchValue=部门  → 命中 3 条，取 name=部门
+GET …/browserBeanSearch?searchValue=人员  → 命中 3 条，取 name=人员
+```
+
+**「部门」完整富对象（验证取值）**
+
+```json
+{"id":"2005096031068185488","tenantKey":"all_teams","deleteType":0,
+ "dataId":"2005096031068185488","licenseModule":"hrm","labelId":"52148",
+ "title":"人事： 部门","disable":0,"systemDefault":1,"ebuliderDataBrowser":false,
+ "name":"部门","module":"hrm","type":"department","groupId":"8574699142778669114"}
+```
+
+**「人员」完整富对象（验证取值）**
+
+```json
+{"id":"2005096031068185492","tenantKey":"all_teams","deleteType":0,
+ "dataId":"2005096031068185492","licenseModule":"hrm","labelId":"29511",
+ "title":"人事： 人员","disable":0,"systemDefault":1,"ebuliderDataBrowser":false,
+ "name":"人员","module":"hrm","type":"resource","groupId":"8574699142778669114"}
+```
+
+> ⚠️ 两条的 `id` 都是**业务 id**（= `dataId`，部门 …488 / 人员 …492），**不等于** ComInfo 短 id。
+> 因此校验「关联类型对不对」**不能按 id 比**，要按 `name`（人员/部门）或 `type`（resource/department）判 —— 否则会误报"不匹配"（已修 `e10-cli report query save`）。
+> 同一环境里还有近名分类：`部门字段`(…498) / `人员字段`(…502)，按 `name` **精确**取，勿用 `indexOf`。
+
+**落库判据对照**
+
+| 关联类型 | `browserTypeStr`（落库判据） | 富对象 `name` / `type` |
+|---|---|---|
+| 部门 | `[{"id":"HrmDepartmentComInfo"}]` | 部门 / `department` |
+| 人员 | `[{"id":"HrmEmployeeComInfo"}]` | 人员 / `resource` |
+| 部门全路径 | `[{"id":"HrmDepartmentAllPathComInfo"}]` | 部门字段 / `departmentDesc` |
+
+**修复存量条件（最小侵入，已验证 HTTP 200）**
+
+```python
+# 1) 读取
+q = POST /api/bs/edc/report/getQueryItemNew  (multipart: reportId + query:'{}')
+items = q["data"]["list"]                     # ⚠️ 在 data.list，不是 data.queryItems
+# 2) 取富对象
+bean = GET /api/bcw/relevanceBrowser/browserBeanSearch?searchValue=人员  → name=="人员" 那条
+# 3) 替换 + 同步 browserTypeStr + 保存
+item["browserType"] = [bean]
+item["browserTypeStr"] = json.dumps([{"id":"HrmEmployeeComInfo"}], ensure_ascii=False)
+POST /api/bs/edc/report/saveQueryItem  (multipart: reportId + queryItems 单对象JSON)
+```
+
+**UI 验证要点**：打开「编辑查询条件」弹窗，查 `.ui-browser-type-search-input` 的 `value`：
+- `""` + 控件容器带 `is-empty` 类 → 关联类型**丢失**
+- `"人员"` / `"部门"` → **正确回显** ✅
+
+> 验证：修复前「销售人员」`value=""`（`is-empty`）；修复后 `value="人员"` ✅
+
+---
+
+## 二点五、saveQueryItem 始终 500 定位（强制）
+
+> **事故**：议题类报表搭建时，改字段/单条/空数组/`queryConfig`/`sheetId` 均 500 → 根因是**调用形态**，不是业务字段内容。
+
+| 检查顺序 | 项 | 通过标准 |
+|----------|----|----------|
+| 1 | Content-Type | `multipart/form-data`，字段名 `reportId`、`queryItems` |
+| 2 | `queryItems` 形态 | **单个对象** JSON；禁止数组、禁止空 `{}` |
+| 3 | `conditions` | **非 null 数组**，至少 1 个 `{dataSetId, fieldId, relation}` |
+| 4 | Header | `ebBusinessId` = 报表所属 **appId**；`eteamsid` + Cookie |
+| 5 | 多条条件 | **多次** POST，每次一条；不要一次塞数组 |
+| 6 | 对照金标准 | 先 `getQueryItem` 拉已有报表一条，改 `text`/`fieldId` 再 save |
+
+**不要**：为排 500 去开浏览器扫页（浪费）；先按上表自检。仍 500 时看响应 `msg` 是否权限/报表不存在，再问用户。
+
+**优先 CLI**（强制）：
+
+```bash
+# 保存条件（自动默认条件级 queryType='["advance"]'，并 updateQueryType）
+e10-cli report query save --report-id <id> --app-id <appId> --item queryItem.json
+e10-cli report query save ... --show-where "筛选"          # 仅用户点名筛选时
+e10-cli report query type --report-id <id> --app-id <appId>  # 只对齐报表级显示方式勾选
+e10-cli report query list --report-id <id> --app-id <appId>
+e10-cli report validate query --map-show-where "高级搜索"
+e10-cli report validate query --validate-show-where --file item.json
+# queryItem.json = 单条对象（禁止数组）；须含非空 conditions；条件级 queryType='["advance"]'
+```
+
+**不卡死（强制）**：`saveQueryItem` / `e10-cli report query save` 按形态自检并重试 **至多 1 次** 仍失败 → **立即提示用户**（可在设计器手动配查询条件）→ **继续**权限/其它布局/交付主表 → 任务收尾再自动补试 1 次。**禁止**在查询条件步骤死循环。见 `failure-cleanup-and-nonblocking-guide.md` §二。
+
+**与布局 500 区分**：`saveReportDevInfo` 的 border `style` 须为**数字**（如 `1`）与查询无关；查询 500 优先查本节。
+
+---
+
+| 需求 | displayType | relation | 备注 |
+|------|-------------|----------|------|
+| 文本（包含） | `text` | `Contain` | 勿写 `select` |
+| 文本（等于） | `text` | `Equals` | |
+| **日期区间**（日/时间） | `date` / `date.ymd` | `between` | 见 §3.1 自动匹配 |
+| **年月/年** | `date.ym` / `date` | `between` | 见 §3.1 |
+| 下拉 | `select` | `Equals` | **必须**自动拉选项写入 `selectOptions`（§3.2） |
+| 数字范围 | `number` | 默认 | |
+| 人员浏览按钮 | `browser` | `Equals` | 人员类字段 |
+
+**日期 displayType 与字段 format**
+
+| 数据集字段 format | 查询条件 displayType |
+|-------------------|----------------------|
+| `yyyy-MM-dd`（及带时分秒） | `date.ymd` |
+| `yyyy-MM` | `date.ym` |
+| `yyyy` / 仅「年」 | `date` |
+| 其他日期 | `date` |
+
+首条查询条件可设 `advancedSearchType: "openCondition"`（如集团军默认展开）。
+
+---
+
+### 3.1 查询条件类型自动匹配（强制）
+
+> Agent 配置 / 修复查询条件时，**禁止**一律写成 `text`。必须按 **条件显示名 + 数据集字段类型/format** 自行判断。
+
+**判定顺序**（命中即停）：
+
+| 优先级 | 信号（名称或字段元数据） | displayType | relation | 设计器形态 |
+|--------|--------------------------|-------------|----------|------------|
+| 1 | 名称含「年月」；或 format=`yyyy-MM` | `date.ym` | `between` | 年月区间 |
+| 2 | 名称含「年份」「年度」或纯「年」；format=`yyyy` | `date` | `between` | 日期（年） |
+| 3 | 名称含「日期」「时间」「时段」「期间」；或 `fieldType`/`originFieldType` ∈ Date/DateTime/Time/datetime | `date.ymd`（format 非 yyyy-MM 时）或 `date` | **`between`** | **日期区间** |
+| 4 | 人员 / Employee / 浏览按钮字段 | `browser` | `Equals` | 人员 |
+| 5 | **Select / 下拉框 / Check**（`compType`/`type`/`originFieldType` 为 Select）或需求明确下拉 | `select` | `Equals` | 下拉（**§3.2 必拉选项**） |
+| 6 | 其他 | `text` | `Contain`（模糊）或 `Equals` | 文本 |
+
+**硬约束**
+
+1. 日期/时间类 **必须** `relation: "between"`，**禁止** `Equals` + `displayType: text`（事故：签订日期被配成文本等于）。
+2. 判定依据优先：`fieldsAndOriginFields` 的 `fieldType` / `originFieldType` / `config.format`；名称作辅助（如条件叫「签订日期」字段叫「合同签订日期」）。
+3. 写成日期区间时同步带齐 §四：`filterParam.enableOption=true`、21 项 `dataOptions`、`selectOptions=[]`。
+4. **`displayType: select` 时禁止 `selectOptions: []`** — 必须按 §3.2 按匹配字段自动获取选项（事故：供应商等级下拉无选项）。
+5. 回读 `getQueryItem`：核对 `displayType` + `conditions[0].relation` +（下拉时）`selectOptions.length > 0` 且 `selectKey`/`selectValue` 方向正确。
+6. **定点场景**：用户只点一条条件 → 只改该条，禁止重配全部查询（`targeted-fix-guide.md`）。
+
+---
+
+### 3.2 下拉查询条件：按匹配字段自动获取选项（强制）
+
+> **事故**：报表「供应商-1」`1312703681350901760`，「供应商等级」已是 `displayType: select`，但 `selectOptions: []` → 预览/高级搜索无选项映射。
+
+当判定为下拉（§3.1 优先级 5）或用户要求下拉时：
+
+1. 从 `conditions[0].fieldId` 解析三段 fieldKey：`{dataSetId}.{sourceId}.{fieldName}`
+   - `fieldName` 在报表内多为 `field_{雪花ID}`（绑定 fieldsKey）
+   - **取选项时** `fieldName` 参数必须用 **裸雪花 ID**（去掉 `field_` 前缀）
+2. 调用：
+
+```
+GET /api/ebuilder/form/ds/options
+  ?sourceType=FORM
+  &objId={sourceId}
+  &fieldName={裸雪花ID}    ← 禁止传 field_xxx（会返回空数组）
+```
+
+`FORM` 无数据时可再试 `sourceType=LOGIC`。也可用 `ds/fields` 里该字段 `config.options`（`name` + `valueKey`/`value`）作为兜底。
+
+3. 映射写入 `selectOptions` / `selectOptionsStr`（**键值方向勿反**）：
+
+| 字段 | 含义 | 示例 |
+|------|------|------|
+| `selectKey` | **选项值 / ID**（过滤用） | `"864407987151323141"` |
+| `selectValue` | **显示名称** | `"准入供应商"` |
+| `id` | 同 `selectKey` | `"864407987151323141"` |
+
+```javascript
+// ds/options → saveQueryItem（事故：曾把名称写进 selectKey、ID 写进 selectValue）
+selectOptions = data
+  .filter(o => String(o.archive ?? '0') !== '1')
+  .map(o => ({
+    selectKey: String(o.id),   // 数值 / 选项 ID
+    selectValue: o.name,       // 名称
+    id: String(o.id),
+  }));
+```
+
+4. `relation` 用 `Equals`；`showWhere` 仍遵守 §2.1。
+5. **禁止**：只设 `displayType: select` 却留下空 `selectOptions`；**禁止**用带 `field_` 前缀调 `/ds/options` 后误判「字段无选项」。
+
+```javascript
+async function fetchSelectOptionsForQuery(sourceId, fieldNameFromKey) {
+  const bare = String(fieldNameFromKey).replace(/^field_/, '');
+  const r = await get('/api/ebuilder/form/ds/options', {
+    sourceType: 'FORM', objId: sourceId, fieldName: bare,
+  });
+  if (!r.data?.length) throw new Error(`select options empty for ${bare}`);
+  return r.data.filter(o => String(o.archive ?? '0') !== '1')
+    .map(o => ({ selectKey: String(o.id), selectValue: o.name, id: String(o.id) }));
+}
+```
+
+```javascript
+function inferQueryDisplay(text, fieldMeta) {
+  const name = `${text||''} ${fieldMeta?.text||''}`;
+  const ft = String(fieldMeta?.fieldType||'').toLowerCase();
+  const oft = String(fieldMeta?.originFieldType||'').toLowerCase();
+  const fmt = String(fieldMeta?.config?.format || fieldMeta?.format || '');
+  if (/年月/.test(name) || fmt === 'yyyy-MM')
+    return { displayType: 'date.ym', relation: 'between' };
+  if (/年份|^年$|年度/.test(name) || fmt === 'yyyy')
+    return { displayType: 'date', relation: 'between' };
+  if (/日期|时间|时段|期间/.test(name) ||
+      ['date','datetime','time','timestamp'].includes(ft) ||
+      ['date','datetime','time'].includes(oft))
+    return { displayType: fmt.startsWith('yyyy-MM-dd') || !fmt ? 'date.ymd' : 'date',
+             relation: 'between' };
+  return { displayType: 'text', relation: 'Contain' };
+}
+```
+
+---
+
+## 四、日期区间：快捷选项（21 项）
+
+设计器手动 save 后的**正确形态**（勿用旧版 15 项数字码 + 9 项 selectOptions）：
+
+| 字段 | 正确值 |
+|------|--------|
+| `selectOptions` | **`[]`** |
+| `filterParam.enableOption` | **`true`** |
+| `filterParam.isTile` | **`true`** |
+| `filterParam.dataOptions` | **21 行**，`id` = `selectValue`（camelCase，如 `day3`、`thisMonth`） |
+| `filterParam.optionTile` | **`{}`** |
+| `filterParam.dateSelectDefaultValue` | **`""`（空）** |
+
+**错误做法**：写入 `filterParam.dateSelectDefaultValue: "thisMonth"` 或填满 `optionTile` — 设计器齿轮菜单往往**只剩「自定义」**。
+
+```python
+# 见 apply_ebu_from_xlsx.py → _default_date_filter_param()
+```
+
+---
+
+## 五、日期区间：系统参数默认值（设计器「自定义」）
+
+默认值**不是** `dateSelectDefaultValue`，而是顶层：
+
+| 字段 | 说明 |
+|------|------|
+| `defaultValueType` | **`"custom"`** |
+| `defaultValue` | JSON **字符串**，形如 `'["{thismonth}",""]'` |
+
+运行时由 `SystemVariableUtil` + `DynamicParamsBuilder` 解析；`getQueryItem` 回读的 `handleDefaultValue` 为解析后结果。
+
+### 5.1 已验证系统参数
+
+| 场景 | defaultValue | handleDefaultValue 示例 |
+|------|--------------|-------------------------|
+| **本月** | `["{thismonth}",""]` | `["2026-08-01,2026-08-31",""]` |
+| **今天** | `["{date}","{date}"]` | `["2026-08-19","2026-08-19"]` |
+| **本周** | `["{thisweek}",""]` | `["2026-08-17,2026-08-23",""]` |
+| **今年** | `["{thisyear}",""]` | `["2026-01-01,2026-12-31",""]` |
+| **当前用户姓名** | `["{lastname}",""]` | `["张三",""]`（高级搜索文本等于） |
+| **当前用户 ID** | 数据集筛选 **`eq`** + `{userid}` | 人员字段「创建者 = 当前登录人员」 |
+
+**注意**
+
+- `{today}` **无效**（不会被解析，占位符会被清空）；「今天」用 **`{date}`**。
+- `{currmonth}` 无效；「本月」用 **`{thismonth}`**。
+- 区间型参数（本月/本周）写在**数组首项**；今天需起止同一天则写 **`["{date}","{date}"]`**。
+- `defaultValue` 必须是 **JSON 数组字符串**，禁止裸写 `"3"` 等（会导致 `getQueryItem` 500）。
+
+### 5.2 设计器操作对应
+
+1. 默认值类型 → **自定义**
+2. 默认值 → 填 `{thismonth}`、`{date}` 等（设计器存为 JSON 数组）
+3. 日期区间 + **启用选项** ON → 21 项快捷按钮（§四）
+
+### 5.3 跨报表传参：目标条件的默认值（报表跳报表 · 2026-11-03 实测）
+
+来源报表把参数拼在钻取地址上：
+
+```text
+/sp/edc/report/view/<目标报表>?searchfield002=13261367755986572676
+```
+
+目标报表**不会**按参数名自动过滤。要接住它，目标报表的查询条件必须把参数名写进「自定义默认值」：
+
+| 键 | 值 |
+|---|---|
+| `defaultValueType` | `"custom"` |
+| `defaultValue` | `'["{searchfield002}",""]'` |
+| `type2DefaultValue` | 同上；`type1DefaultValue` 置空 |
+
+设计器「默认值」框里显示成 `(searchfield002)` —— **圆括号只是 UI 渲染，落库必须是花括号**。
+
+运行时：
+
+- 请求里带同名字段 → `handleDefaultValue` 变成传入值（如 `["江苏EBU一部",""]`），报表按它过滤；
+- 不带 / 传空 → 占位清空成 `["",""]`，直接打开报表不过滤。
+
+⚠️ 条件保持「常规 / 空」时，URL 参数会被**静默忽略**：页面能打开、不报错、数据一条不少。这是钻取不过滤最常见的原因。
+
+- **参数名以 `{…}` 里的名字为准**，链接的 key 必须与它一致；通常就是条件标识 `searchfield00x`。
+- 日期区间用 `{searchfield001_start}` / `{searchfield001_end}`，URL 参数名同名。
+- 体检：`e10-cli report verify drill <来源报表> --app-id <id>` —— 扫来源链接、读目标条件，缺绑定直接失败并给出修法。
+
+---
+
+## 六、EBU 报表示例（三条高级搜索 + 数据集行级筛选）
+
+报表 `1304979556231593985` · 数据集 EBU团队 `1304979556231593994`
+
+| 显示名称 | fieldKey 末段 | displayType | relation | 默认值 | queryType |
+|----------|---------------|-------------|----------|--------|-----------|
+| 集团军 | `field_1299763447342276612` | `text` | `Contain` | 无 | `["advance"]` |
+| 入职时间 | `field_1299763447342276619` | `date.ymd` | `between` | `["{thismonth}",""]` | `["advance"]` |
+| EBU成立时间 | `field_1299763447342276620` | `date.ym` | `between` | `["{date}","{date}"]` | `["advance"]` |
+
+> 三条均为「高级搜索」显示方式 → 条件级 `queryType` 一律 `'["advance"]'`（见 §2.1）。
+> 「高级搜索显示形式」（报表级、`saveQueryConfig` → `{"advancedSearchType":"openCondition"}`）是**报表级**开关，与条件级显示方式共享 `queryType` 覆盖关系（§2.1.3）。
+
+---
+
+## 七、数据集筛选（设计器左侧 · 行级权限）
+
+> **完整规范已独立成文**：`dataset-query-filter-guide.md`（func 对照、字段对比、日期 format、AND/OR、EBU 金标准、验证清单）。
+> 本节仅保留与高级搜索的边界说明。
+
+**与高级搜索不同**：设计器左侧数据集右键「筛选条件」走 **`queryInfoSave` / `queryInfoGet`**（`conditionData` + `otherData`），**不是** `saveQueryItem`。
+
+| API | 参数 |
+|-----|------|
+| 保存 | `POST /api/bs/edc/dataset/queryInfoSave` → `datasetId`, `filterData`, `otherData` |
+| 读取 | `GET /api/bs/edc/dataset/queryInfoGet` → `datasetId` |
+
+**快速对照**
+
+| 需求入口 | 读哪份文档 |
+|----------|-----------|
+| 页面 → 查询设置（高级搜索） | 本文 §二–§六 |
+| 左侧数据集 → 筛选条件 | **`dataset-query-filter-guide.md`** |
+| 单元格自定义筛选 / datasetFilter | `cross-dataset-filter-guide.md` |
+
+---
+
+## 八、验证清单
+
+写入后 `getQueryItem` 回读：
+
+**形态**
+
+- [ ] **调用**：multipart + `queryItems`=**单对象**（非数组）；`conditions` 非 null
+- [ ] 顶层 `filterType: "default"`；`conditions[]` 无 `filterType`
+- [ ] 顶层 `dataSetId` / `name` 为 `null`；`nameIndex: "0"`；`sqlOptions: {}`
+- [ ] **`queryType` 为 JSON 数组字符串**：`'["advance"]'`（高级搜索）或 `'["filter"]'`（筛选），可双选 `'["advance","filter"]'`（§2.1）；**必须以 `[` 开头**
+- [ ] **回显自检**：落库为长码 `"advancedSearch"` → 设计器「显示方式」**必不勾选**（落库错误，改数组即修复）；不要解释为平台缺陷
+- [ ] `asNameIndex` 唯一且 > 0；与 `showOrder` 一致
+- [ ] `fieldOptions` 与 `conditions` 字段一致
+
+**浏览按钮（人员 / 部门）**
+
+- [ ] `displayType: "browser"` 且 **`browserTypeStr` 非空**（§2.1.2）
+- [ ] 字段 `originFieldType=Employee` → `HrmEmployeeComInfo`
+- [ ] 字段 `originFieldType=Department` → `HrmDepartmentComInfo`
+- [ ] `browserTypeStr` 不得为 `"[]"`（关联类型丢失 → 退回「人员」）
+- [ ] 若要求 UI 正确回显显示名，`browserType` 用富对象（含 `name`/`type`），非 `[{"id"}]` 简写
+
+**文本**
+
+- [ ] `displayType: "text"`（非 `select`）
+
+**下拉**
+
+- [ ] `displayType: "select"` 且 `selectOptions.length > 0`
+- [ ] 选项来自匹配字段的 `/ds/options`（`fieldName` 为裸 ID，见 §3.2）
+- [ ] 每项：`selectKey`=选项 ID（数值）、`selectValue`=显示名称（勿写反）
+
+**日期选项**
+
+- [ ] `enableOption=true`、`isTile=true`、`dataOptions` 21 项、`selectOptions=[]`、`optionTile={}`
+
+**日期默认值**
+
+- [ ] `defaultValueType: "custom"`（有默认值时）
+- [ ] `handleDefaultValue` 非空且符合预期（如本月区间、今天同一天）
+- [ ] **未**依赖 `filterParam.dateSelectDefaultValue`
+
+**工具**
+
+- [ ] 设计器刷新：齿轮菜单 21 项、默认值回显、删一条不影响其他条件
+
+---
+
+## 八、相关文档
+
+| 文件 | 用途 |
+|------|------|
+| **`dataset-query-filter-guide.md`** | **左侧数据集筛选**（queryInfoSave 完整规范） |
+| **`cell-transform-guide.md`** | **`browserType` 关联类型预设**（人员/部门 ComInfo id） |
+| **`event-hreflink-guide.md`** | 事件链接传 `{searchfield00x}` / 单元格坐标 |
+| `date-range-query-reference.md` | 21 项 dataOptions catalog |
+| `cross-dataset-filter-guide.md` | datasetFilter / customFilterField |
+| `report-building-guide.md` §6 | 设计器操作步骤 |
+| `report-config-schema.md` §五 | Schema 摘要 |
+| `SKILL.md` §6.3–§6.4 | Agent 步骤入口 |