weaver-e10-builder 1.6.10 → 1.6.12

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

@@ -1,8 +1,7 @@
 # 查询条件 API 写入规范
 
 > **适用场景**：通过 `saveQueryItem` / `saveQueryConfig` API 或脚本添加、修复报表查询条件。
-> **参考报表**：`1304979556231593985`（EBU 经营数据统计）
-> **代码实现**：`本地工作目录` → `ensure_query_conditions()`；执行 `python 本地工作目录`
+> **金标准报表**：`1304979556231593985`（EBU 经营数据统计）
 > **核心规则**：数据集合选取后，**选择类型未特别指定 SQL 时，一律默认为「条件字段」**。
 
 ## ⚡ TL;DR — 显示方式（2026-09-11 定案，务必先读 §2.1）
@@ -43,7 +42,7 @@
 
 ## 二、条件字段标准形态（saveQueryItem）
 
-设计器 save 后回读的基准结构：
+设计器 save 后回读的金标准结构：
 
 | 字段 | 条件字段正确值 |
 |------|----------------|
@@ -54,7 +53,7 @@
 | `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` |
+| `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 不会勾选** |
@@ -63,13 +62,13 @@
 
 ```python
 def build_conditions(ds_id, field_id, relation):
- return [{"dataSetId": ds_id, "fieldId": field_id, "relation": 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]}
+    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`
@@ -118,7 +117,7 @@ await saveQueryItem({ reportId, queryItems: '{}' }); // conditions 缺失 → 50
 
 ### 2.1 显示方式（强制 · 不可不选）
 
-> **✅ 终局定案（2026-09-11 · 以「设计器手工配置的真实条件」为基准反推）**
+> **✅ 终局定案（2026-09-11 · 以「设计器手工配置的真实条件」为金标准反推）**
 >
 > 条件级「显示方式」的正确落库值是 **JSON 数组字符串**：
 >
@@ -138,16 +137,16 @@ await saveQueryItem({ reportId, queryItems: '{}' }); // conditions 缺失 → 50
 ```js
 // ① 读取（initCondition）—— 唯一判定逻辑
 t.queryType = (t.queryType?.indexOf("[") > -1)
- ? JSON.parse(t.queryType || "[]") // 含 "[" → 解析成数组
- : t.queryType || []; // 不含 → 原样保留（普通字符串）
+    ? 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 } }
+  data:[{ id: ze.g.advance, content:"高级搜索" },
+        { id: ze.g.filter,  content:"筛选" }],
+  otherParams:{ minSelected:1 } }
 ```
 
 ```js
@@ -157,7 +156,7 @@ function(e){ e.filter="filter"; e.advance="advance" }(i||(i={}))
 
 ```js
 // ④ 新建条件默认值（仅 fieldKey 为空时）
-this.fieldKey || (i.queryType = ["advance"]) // ← 注意：默认就是「数组」
+this.fieldKey || (i.queryType = ["advance"])     // ← 注意：默认就是「数组」
 ```
 
 ```js
@@ -172,9 +171,9 @@ s.append("queryItems", JSON.stringify(r));
 1. `CheckboxGroup` 用**严格相等**匹配：表单 value 的每个元素 vs `data[].id`。
 2. 落库 `'["advance"]'` → 解析为 `["advance"]` → 元素 `"advance"` === 选项 id `"advance"` → **勾选 ✅**
 3. 落库 `"advancedSearch"` → 不含 `[` → 保留为字符串 `"advancedSearch"` → 与选项 id 严格不等 → **不勾选 ❌**
-4. **设计器自己写出的就是数组**（见 ④ 默认值、⑥ 实际请求）；长码 `"advancedSearch"` 只可能由**脚本手写**产生 → 它是**错误值**。
+4. **设计器自己写出的就是数组**（见 ④ 默认值、⑥ 接口返回）；长码 `"advancedSearch"` 只可能由**脚本手写**产生 → 它是**错误值**。
 
-#### 2.1.2 证据链（2026-09-11，报表 `1313798296523022337`，应用「进销存管理-共享表」）
+#### 2.1.2 验证证据链（2026-09-11，报表 `1313798296523022337`，应用「进销存管理-共享表」）
 
 **A. API 写入实验（`saveQueryItem`，同一条件往返改 4 种值）**
 
@@ -197,15 +196,15 @@ s.append("queryItems", JSON.stringify(r));
 
 → 脚本手工写的长码条件**全军覆没**，人工配置的数组条件**正确回显**。把两条长码条件改为 `'["advance"]'` 后，三条**全部回显 ☑ 高级搜索**，闭环验证通过。
 
-**C. 设计器真实 `saveQueryItem` 实际请求（人工点击「确定」）**
+**C. 设计器真实 `saveQueryItem` 接口返回（人工点击「确定」）**
 
 ```
 Content-Disposition: form-data; name="queryItems"
 
 {"id":"…","sheetId":"…","nameIndex":"0","text":"销售部门","displayType":"browser",
  "showWhere":"","advancedSearchType":"openCondition","queryType":["advance"], … }
- ^^^^^^^^^^^^^^^^^^
- 数组（短码），非字符串长码
+                                                          ^^^^^^^^^^^^^^^^^^
+                                                          数组（短码），非字符串长码
 ```
 
 > 设计器上行 payload 里就是 `"queryType":["advance"]`（**数组 + 短码**）—— 这是平台的权威写法。
@@ -215,7 +214,7 @@ Content-Disposition: form-data; name="queryItems"
 > **`POST /api/bs/edc/report/updateQueryType` 不是「只改报表级设置」** —— 它会把入参 `queryType` **全量写进该报表的每一条查询条件**，覆盖刚保存好的数组值。
 > 这是「条件显示方式永远不勾选」的**真正单点根因**，也是历史定位一直抓不到的那个洞。
 
-** 矩阵**（同一报表连续调用，观察条件级 `queryType`）
+**验证矩阵**（同一报表连续调用，观察条件级 `queryType`）
 
 | 调用 `updateQueryType(queryType=…)` | 三条条件级 `queryType` 变为 | 设计器回显 |
 |---|---|---|
@@ -227,10 +226,10 @@ Content-Disposition: form-data; name="queryItems"
 **为什么历史定位一直失败**
 
 ```text
-旧 CLI 的 save 流程： saveQueryItem(写 '["advance"]' ✅) → updateQueryType("advancedSearch" ❌)
- ↓ 刚写好的数组 ↓ 立刻被批量打回长码
- 设计器打开 → 不勾选
-人工在页面直接配条件： 只走 saveQueryItem，不经过 updateQueryType → '["advance"]' 完好 → 正常勾选
+旧 CLI 的 save 流程：  saveQueryItem(写 '["advance"]' ✅)  →  updateQueryType("advancedSearch" ❌)
+                                          ↓ 刚写好的数组                 ↓ 立刻被批量打回长码
+                                     设计器打开 → 不勾选
+人工在页面直接配条件：  只走 saveQueryItem，不经过 updateQueryType  →  '["advance"]' 完好 → 正常勾选
 ```
 
 于是「人工配的能勾、API 写的不能勾」，长期被误判为「平台前端缺陷，客户端不可修」。**实际是 CLI 自己把值写坏了。**
@@ -278,7 +277,7 @@ Content-Disposition: form-data; name="queryItems"
 | 条件级与报表级是两个独立字段，互不影响 | ❌ 错。`updateQueryType` 用 `queryType` **批量覆盖所有条件**（§2.1.3 真正根因） |
 | `updateQueryType` 只改报表级「高级搜索显示形式」 | ❌ 错。它会把入参写进每条条件 → 长码一键摧毁全表回显 |
 
-**旧结论怎么来的 / 为什么错**：早期用 JS 合成事件点击条件 tag，实际点到了**左侧字段面板**的「显示方式」（那是字段属性，非条件显示方式），读取勾选态得到假信号；且未把「人工配置的条件」作为基准对照。**修复方式**：改用 **CDP `Input.dispatchMouseEvent` 真实鼠标事件**点条件 tag，读「编辑查询条件」弹窗，并以人工条件为参照。
+**旧结论怎么来的 / 为什么错**：早期用 JS 合成事件点击条件 tag，实际点到了**左侧字段面板**的「显示方式」（那是字段属性，非条件显示方式），读取勾选态得到假信号；且未把「人工配置的条件」作为金标准对照。**修复方式**：改用 **CDP `Input.dispatchMouseEvent` 真实鼠标事件**点条件 tag，读「编辑查询条件」弹窗，并以人工条件为参照。
 
 **真正根因的发现路径**：给 `save` 加「落库后回读自检」时，发现**刚写入的数组被回读成长码** → 隔离实验证明只有 `saveQueryItem` 时数组完好，一旦再调 `updateQueryType` 即被批量覆盖 → 穷举入参证明 `updateQueryType` 是「全表条件 `queryType` 批量写」。**AI 自检回读是抓到它的关键手段**，务必保留。
 
@@ -287,38 +286,67 @@ Content-Disposition: form-data; name="queryItems"
 **首选（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> # 修正为数组短码
+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 + 幂等修复
+**手动脚本（等价实现，含 `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` 实际请求）**
+**设计器真实保存形态（金标准，从 `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
+  "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
 }
 ```
 
@@ -328,7 +356,7 @@ e10-cli report query verify <reportId> --app-id <appId> --fix # 体检 Q1~Q10 +
 
 > **事故（2026-09-14）**：在报表 `1314970921403138199` 加 5 条查询条件后，用户质问
 > 「怎么又把查询条件的样式改了，这个之前强调过不能动页面上原有展示格式」。
-> 定位结论：**用户的 payload 里根本没有 `advancedSearchType`**，是 CLI `save_query_item.js`
+> 定位结论：**用户的 payload 里根本没有 `advancedSearchType`**，是 CLI `e10-cli report query save`
 > 在保存时**无条件注入** `advancedSearchType: 'openCondition'`（=「展开条件」）。
 
 **字段语义（源码级）**
@@ -339,7 +367,7 @@ e10-cli report query verify <reportId> --app-id <appId> --fix # 体检 Q1~Q10 +
 | 唯一功能读点 | `SheetServiceImpl`：取**第一条**高级搜索条件的 `advancedSearchType`，`=='openCondition'` → `isOpenCondition=true` |
 | 页面效果 | `isOpenCondition=true` → 报表页查询区**展开铺开**（「展开条件」）；否则 → **默认样式**（右上角搜索图标，点击才展开） |
 | 设计器入口 | 报表级「查询设置」弹窗的 **高级搜索显示形式：默认样式 / 展开条件** |
-| 人工条件（基准） | **该键不存在**（`undefined`），平台不主动写 |
+| 人工条件（金标准） | **该键不存在**（`undefined`），平台不主动写 |
 
 **硬规则**
 
@@ -379,7 +407,7 @@ e10-cli report fix query-style --report-id <id> --app-id <appId> --delete-id <it
 
 **根因**：弹窗的默认值区由 `defaultValueType` 驱动渲染。不写它 → 前端取不到模式 → 每个变体都渲染一遍。
 
-**数据模型（ 参照报表 `1314938962594906121`，人工配置的权威形态）**
+**数据模型（验证参照报表 `1314938962594906121`，人工配置的权威形态）**
 
 | 键 | 含义 | 参照「年月」取值 | 参照「部门」取值 | 参照「人员/加班/聘用」取值 |
 |----|------|------------------|------------------|----------------------------|
@@ -390,7 +418,7 @@ e10-cli report fix query-style --report-id <id> --app-id <appId> --delete-id <it
 | `handleDefaultValue` | 平台解析后的实际值（**服务端自己算并回写**） | `["2026-09",""]` | `[[],""]` | `["",""]` |
 
 > ⚠️ **全部是 JSON 字符串**（`"[[],\""]"` 这种），不是对象/数组本身。
-> ⚠️ 日期占位符（`{yearmonth:-0}` 等）**不用自己解析**：落库时平台会把 `handleDefaultValue` 回写成 `["2026-09",""]`。
+> ⚠️ 日期占位符（`{yearmonth:-0}` 等）**不用自己解析**：落库时平台会把 `handleDefaultValue` 回写成 `["2026-09",""]`（验证）。
 > 设计器「新建条件」模板本身带 `defaultValueType:"default"` + `defaultValue:["",""]`，所以**人工配的条件永远不会缺** —— 只有用 API 建条件时才会漏。
 
 **修复**
@@ -401,7 +429,7 @@ 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
+  --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
@@ -438,7 +466,7 @@ e10-cli report fix query-default --report-id <id> --app-id <appId> --all --show-
 
 > **事故**：同报表查询条件「销售部门」绑定字段 `originFieldType=Department`，但设计器关联类型显示为空/默认**人员**。**定案根因：`browserType` 写成了简写 `[{"id":"HrmDepartmentComInfo"}]`，缺少 `name`/`type` 等字段 → 前端无法解析显示名 → 退回默认「人员」标签页。**
 
-**设计器真实形态（基准）**：`browserType` 是 **全字段富对象数组**，关键字段 `name`（显示名）、`type`（`department`/`employee`）、`module`、`groupId`、`tenantKey`、`dataId`、`labelId`、`id`。**`browserTypeStr` 才是落库判据**（服务端存 `[{"id":"HrmDepartmentComInfo"}]` 形式的字符串）。
+**设计器真实形态（金标准）**：`browserType` 是 **全字段富对象数组**，关键字段 `name`（显示名）、`type`（`department`/`employee`）、`module`、`groupId`、`tenantKey`、`dataId`、`labelId`、`id`。**`browserTypeStr` 才是落库判据**（服务端存 `[{"id":"HrmDepartmentComInfo"}]` 形式的字符串）。
 
 | 字段 `originFieldType` | `displayType` | `browserTypeStr`（落库） | 设计器关联类型 |
 |------------------------|---------------|--------------------------|----------------|
@@ -448,13 +476,13 @@ e10-cli report fix query-default --report-id <id> --app-id <appId> --all --show-
 
 **推荐获取富对象的正确姿势（最稳）**：**不要手拼** `browserType` 富对象；用 `saveQueryItem` 时：
 1. `displayType: "browser"` + `browserTypeStr` 写 `[{"id":"HrmDepartmentComInfo"}]`；
-2. 或在设计器里手动选一次「部门」让前端生成富对象后实际请求复用（本环境已验证：手动选后可正确回显「部门」）。
+2. 或在设计器里手动选一次「部门」让前端生成富对象后接口返回复用（本环境已验证：手动选后可正确回显「部门」）。
 
 **硬约束**
 
 1. `displayType: browser` **禁止** `browserTypeStr: "[]"`；必须按字段 `originFieldType` 写入对应 ComInfo id。
 2. 仅写 `[{"id":...}]` 简写**服务端可接受**（`browserTypeStr` 落库正确），但**前端回显可能为空**；若要求 UI 正确显示，需富对象。
-3. `save_query_item.js` 内置 `applyQueryDisplayType()` 自动补 `browserType`（未显式指定 `displayType` 时）；不匹配时输出 **WARN**。
+3. `e10-cli report query save` 内置 `applyQueryDisplayType()` 自动补 `browserType`（未显式指定 `displayType` 时）；不匹配时输出 **WARN**。
 4. 回读核对：`browserTypeStr` 不得为 `"[]"`（丢了 → 退回「人员」）。
 5. 跳过自动推导用 `--skip-display-type`（仅在确实要手填时）。
 
@@ -463,14 +491,14 @@ e10-cli report fix query-default --report-id <id> --app-id <appId> --all --show-
 ```javascript
 // 显示方式：条件级落库值 = JSON 数组字符串（前端唯一能回显勾选的形态）
 function resolveQueryType(userHint) {
- const s = String(userHint || '').toLowerCase();
- if (/筛选|filter/.test(s) && !/高级搜索|advanced/.test(s)) return '["filter"]';
- return '["advance"]'; // 默认「高级搜索」· 不可不选
+  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）
+//      条件级选项 id 是短码 advance/filter；落库必须是含 "[" 的 JSON 数组字符串，
+//      否则前端首字符判定落空 → 退化为普通字符串 → 严格相等失败 → UI 不勾选（见 §2.1）
+//      报表级 updateQueryType 的 queryType 也须用数组形态（它会批量覆盖所有条件，见 §2.1.3）
 ```
 
 ### 2.1.8 「显示方式没勾选」诊断卡（对接用户质询时用）
@@ -486,11 +514,10 @@ function resolveQueryType(userHint) {
 **判据一行流**
 
 ```text
-queryType 以 "[" 开头 → 数组 → UI 勾选正常 ✅
-queryType 是其它字符串 → 退化 → UI 不勾选 ❌（改写为 '["advance"]'）
+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）。
 
@@ -502,21 +529,21 @@ queryType 是其它字符串 → 退化 → UI 不勾选 ❌（改写为 '["adva
 ```http
 GET /api/bcw/relevanceBrowser/browserBeanSearch?searchValue=<中文分类名>
 Header: ebbusinessid: <appId>
-→ data.data[] 每条 = 13 键富对象
+→ 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）**
+**验证取值（租户 `tmxislnm9p` / 应用 1178336857624084480）**
 
 ```http
-GET …/browserBeanSearch?searchValue=部门 → 命中 3 条，取 name=部门
-GET …/browserBeanSearch?searchValue=人员 → 命中 3 条，取 name=人员
+GET …/browserBeanSearch?searchValue=部门  → 命中 3 条，取 name=部门
+GET …/browserBeanSearch?searchValue=人员  → 命中 3 条，取 name=人员
 ```
 
-**「部门」完整富对象（ 取值）**
+**「部门」完整富对象（验证取值）**
 
 ```json
 {"id":"2005096031068185488","tenantKey":"all_teams","deleteType":0,
@@ -525,7 +552,7 @@ GET …/browserBeanSearch?searchValue=人员 → 命中 3 条，取 name=人员
  "name":"部门","module":"hrm","type":"department","groupId":"8574699142778669114"}
 ```
 
-**「人员」完整富对象（ 取值）**
+**「人员」完整富对象（验证取值）**
 
 ```json
 {"id":"2005096031068185492","tenantKey":"all_teams","deleteType":0,
@@ -535,7 +562,7 @@ GET …/browserBeanSearch?searchValue=人员 → 命中 3 条，取 name=人员
 ```
 
 > ⚠️ 两条的 `id` 都是**业务 id**（= `dataId`，部门 …488 / 人员 …492），**不等于** ComInfo 短 id。
-> 因此校验「关联类型对不对」**不能按 id 比**，要按 `name`（人员/部门）或 `type`（resource/department）判 —— 否则会误报"不匹配"（已修 `save_query_item.js`）。
+> 因此校验「关联类型对不对」**不能按 id 比**，要按 `name`（人员/部门）或 `type`（resource/department）判 —— 否则会误报"不匹配"（已修 `e10-cli report query save`）。
 > 同一环境里还有近名分类：`部门字段`(…498) / `人员字段`(…502)，按 `name` **精确**取，勿用 `indexOf`。
 
 **落库判据对照**
@@ -546,25 +573,25 @@ GET …/browserBeanSearch?searchValue=人员 → 命中 3 条，取 name=人员
 | 人员 | `[{"id":"HrmEmployeeComInfo"}]` | 人员 / `resource` |
 | 部门全路径 | `[{"id":"HrmDepartmentAllPathComInfo"}]` | 部门字段 / `departmentDesc` |
 
-**修复存量条件（最小侵入，已 HTTP 200）**
+**修复存量条件（最小侵入，已验证 HTTP 200）**
 
 ```python
 # 1) 读取
-q = POST /api/bs/edc/report/getQueryItemNew (multipart: reportId + query:'{}')
-items = q["data"]["list"] # ⚠️ 在 data.list，不是 data.queryItems
+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=="人员" 那条
+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)
+POST /api/bs/edc/report/saveQueryItem  (multipart: reportId + queryItems 单对象JSON)
 ```
 
 **UI 验证要点**：打开「编辑查询条件」弹窗，查 `.ui-browser-type-search-input` 的 `value`：
 - `""` + 控件容器带 `is-empty` 类 → 关联类型**丢失**
 - `"人员"` / `"部门"` → **正确回显** ✅
 
-> 修复前「销售人员」`value=""`（`is-empty`）；修复后 `value="人员"` ✅
+> 验证：修复前「销售人员」`value=""`（`is-empty`）；修复后 `value="人员"` ✅
 
 ---
 
@@ -579,7 +606,7 @@ POST /api/bs/edc/report/saveQueryItem (multipart: reportId + queryItems 单对
 | 3 | `conditions` | **非 null 数组**，至少 1 个 `{dataSetId, fieldId, relation}` |
 | 4 | Header | `ebBusinessId` = 报表所属 **appId**；`eteamsid` + Cookie |
 | 5 | 多条条件 | **多次** POST，每次一条；不要一次塞数组 |
-| 6 | 对照基准 | 先 `getQueryItem` 拉已有报表一条，改 `text`/`fieldId` 再 save |
+| 6 | 对照金标准 | 先 `getQueryItem` 拉已有报表一条，改 `text`/`fieldId` 再 save |
 
 **不要**：为排 500 去开浏览器扫页（浪费）；先按上表自检。仍 500 时看响应 `msg` 是否权限/报表不存在，再问用户。
 
@@ -588,8 +615,8 @@ POST /api/bs/edc/report/saveQueryItem (multipart: reportId + queryItems 单对
 ```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 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
@@ -658,15 +685,15 @@ e10-cli report validate query --validate-show-where --file item.json
 当判定为下拉（§3.1 优先级 5）或用户要求下拉时：
 
 1. 从 `conditions[0].fieldId` 解析三段 fieldKey：`{dataSetId}.{sourceId}.{fieldName}`
- - `fieldName` 在报表内多为 `field_{雪花ID}`（绑定 fieldsKey）
- - **取选项时** `fieldName` 参数必须用 **裸雪花 ID**（去掉 `field_` 前缀）
+   - `fieldName` 在报表内多为 `field_{雪花ID}`（绑定 fieldsKey）
+   - **取选项时** `fieldName` 参数必须用 **裸雪花 ID**（去掉 `field_` 前缀）
 2. 调用：
 
 ```
 GET /api/ebuilder/form/ds/options
- ?sourceType=FORM
- &objId={sourceId}
- &fieldName={裸雪花ID} ← 禁止传 field_xxx（会返回空数组）
+  ?sourceType=FORM
+  &objId={sourceId}
+  &fieldName={裸雪花ID}    ← 禁止传 field_xxx（会返回空数组）
 ```
 
 `FORM` 无数据时可再试 `sourceType=LOGIC`。也可用 `ds/fields` 里该字段 `config.options`（`name` + `valueKey`/`value`）作为兜底。
@@ -682,12 +709,12 @@ GET /api/ebuilder/form/ds/options
 ```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),
- }));
+  .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。
@@ -695,32 +722,32 @@ selectOptions = data
 
 ```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) }));
+  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' };
+  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' };
 }
 ```
 
@@ -728,8 +755,6 @@ function inferQueryDisplay(text, fieldMeta) {
 
 ## 四、日期区间：快捷选项（21 项）
 
-> 明细 catalog 见 `date-range-query-reference.md` · 快照 `outputs/join_date_filterparam.json`
-
 设计器手动 save 后的**正确形态**（勿用旧版 15 项数字码 + 9 项 selectOptions）：
 
 | 字段 | 正确值 |
@@ -784,6 +809,35 @@ function inferQueryDisplay(text, fieldMeta) {
 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 报表示例（三条高级搜索 + 数据集行级筛选）
@@ -803,7 +857,7 @@ function inferQueryDisplay(text, fieldMeta) {
 
 ## 七、数据集筛选（设计器左侧 · 行级权限）
 
-> **完整规范已独立成文**：`dataset-query-filter-guide.md`（func 对照、字段对比、日期 format、AND/OR、EBU 参考样本、验证清单）。
+> **完整规范已独立成文**：`dataset-query-filter-guide.md`（func 对照、字段对比、日期 format、AND/OR、EBU 金标准、验证清单）。
 > 本节仅保留与高级搜索的边界说明。
 
 **与高级搜索不同**：设计器左侧数据集右键「筛选条件」走 **`queryInfoSave` / `queryInfoGet`**（`conditionData` + `otherData`），**不是** `saveQueryItem`。
@@ -821,8 +875,6 @@ function inferQueryDisplay(text, fieldMeta) {
 | 左侧数据集 → 筛选条件 | **`dataset-query-filter-guide.md`** |
 | 单元格自定义筛选 / datasetFilter | `cross-dataset-filter-guide.md` |
 
-代码：`本地工作目录` → `ensure_team_dataset_filter()` / `ensure_contract_dataset_filter()`；执行 `python 本地工作目录`。
-
 ---
 
 ## 八、验证清单
@@ -869,7 +921,6 @@ function inferQueryDisplay(text, fieldMeta) {
 
 **工具**
 
-- [ ] `本地工作目录` 导出快照对比
 - [ ] 设计器刷新：齿轮菜单 21 项、默认值回显、删一条不影响其他条件
 
 ---
@@ -886,5 +937,3 @@ function inferQueryDisplay(text, fieldMeta) {
 | `report-building-guide.md` §6 | 设计器操作步骤 |
 | `report-config-schema.md` §五 | Schema 摘要 |
 | `SKILL.md` §6.3–§6.4 | Agent 步骤入口 |
-| `outputs/join_date_filterparam.json` | filterParam 参考样本 |
-| `本地工作目录` | 生成/修复实现 |