weaver-work-cli 0.1.24 → 0.1.25

package/skills/weaver-e10-builder/references/report/query-condition-api-guide.md

@@ -0,0 +1,890 @@
+# 查询条件 API 写入规范
+
+> **适用场景**：通过 `saveQueryItem` / `saveQueryConfig` API 或脚本添加、修复报表查询条件。
+> **参考报表**：`1304979556231593985`（EBU 经营数据统计）
+> **代码实现**：`本地工作目录` → `ensure_query_conditions()`；执行 `python 本地工作目录`
+> **核心规则**：数据集合选取后，**选择类型未特别指定 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> # 修正为数组短码
+```
+**修复显示方式（CLI 原生，无需手写脚本）：**
+
+```bash
+e10-cli report query fix-echo <reportId> --app-id <appId>   # 长码/空值 → 数组短码，恢复设计器勾选
+e10-cli report query verify <reportId> --app-id <appId> --fix # 体检 Q1~Q10 + 幂等修复
+```
+
+**设计器真实保存形态（基准，从 `saveQueryItem` 实际请求）**
+
+```json
+{
+ "id": "…", "sheetId": "<reportId>", "nameIndex": "0",
+ "text": "销售部门",
+ "displayType": "browser",
+ "browserType": [{ "id": "3332180495306215437", "name": "部门", "type": "department",
+ "module": "hrm", "groupId": "3332180495271315421", "tenantKey": "thfnde9fvr",
+ "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 `save_query_item.js`
+> 在保存时**无条件注入** `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. `save_query_item.js` 内置 `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"]'）
+```
+
+> 来源：前端 bundle 经 CDP `Debugger.getScriptSource` 导出至 `本地工作目录`
+> （`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）判 —— 否则会误报"不匹配"（已修 `save_query_item.js`）。
+> 同一环境里还有近名分类：`部门字段`(…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 项）
+
+> 明细 catalog 见 `date-range-query-reference.md` · 快照 `outputs/join_date_filterparam.json`
+
+设计器手动 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 项快捷按钮（§四）
+
+---
+
+## 六、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` |
+
+代码：`本地工作目录` → `ensure_team_dataset_filter()` / `ensure_contract_dataset_filter()`；执行 `python 本地工作目录`。
+
+---
+
+## 八、验证清单
+
+写入后 `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 步骤入口 |
+| `outputs/join_date_filterparam.json` | filterParam 参考样本 |
+| `本地工作目录` | 生成/修复实现 |