weaver-e10-builder 1.6.14 → 1.6.16

package/skill-docs/references/report/drilldown-report-guide.md

@@ -1,75 +1,75 @@
-# 数据钻取类报表 · 指南（SKILL A0.14 · 场景 D）
-
-> 形态：**列表报表 + 行级钻取**（官方 demo「订单信息列表」类）：
-> ① **多维度钻取** —— 点击订单号钻取订单明细 / 物流信息（跳其他报表并按当前行值过滤）；
-> ② **列排序** —— 点击订购日期按升/降序查看；
-> ③ **行级导出/打印明细** —— 每行「导出」链接（详见 §三能力边界）。
-> 固化：2026-10-29 · 落地点 = `build spec` 的 `columns[].link` / `columns[].sort`（通用建表器内置，禁止临时脚本）。
-
-## 一、能力 → 落库键映射
-
-| 需求 | 落库键 | 语法 | 规则来源 |
-|---|---|---|---|
-| 钻取链接 | `style.cellType.pcHreflink` + `openType` | 见 §二 | `event-hreflink-guide.md` §二/§三 |
-| 列排序 | Field 格 `style.cellType.orderType` = `asc`/`desc` | `columns[].sort` | 预览点击排序表现**以设计器确认为准** |
-| 跳同表其他 Sheet | 同上（pcHreflink + `sheetIndex=N-1`） | `columns[].cellType:"jump"` + `jumpSheet:N` | 场景 C（branch-scene-guide.md） |
-
-## 二、columns[].link 声明（build spec spec.json）
-
-```json
-"columns": [
-  { "title": "订单号", "field": "订单号", "width": 100,
-    "link": { "type": "report", "reportId": "<明细报表id>", "params": { "ddhh": "SELF" }, "openType": "blank" } },
-  { "title": "订购日期", "field": "订购日期", "width": 120, "sort": "asc" },
-  { "title": "客户名称", "field": "客户名称", "width": 140 },
-  { "title": "导出明细", "cellType": "jump", "href": "<custom 或见 §三>", "width": 90 }
-]
-```
-
-| type | 生成的 URL | 传参方式 |
-|---|---|---|
-| `report` | `/sp/edc/report/view/<reportId>` | 查询串 `参数名=坐标`（无花括号）；参数名须与**目标报表查询条件标识**对应 |
-| `list` | `/sp/ebdfpage/list/<formId>` | 同上 |
-| `card` | `/sp/ebdfpage/card/0/<formId>` | **路径占位** `{坐标}`（带花括号，§3.2），第一个参数进路径、其余进查询串 |
-| `custom` | 原样 `url`（可预置 `{坐标}` 占位） | params 仍拼查询串 |
-
-- `params` 值：`"SELF"` = 当前格；或**列标题** → 该列数据格坐标（自动转 Excel 引用，如 `D3`）。
-- `openType`：`blank`（默认弹出页）/ `self` / `jsscript`，禁止自造别名。
-- 参数名**避免** `id`/`name` 等系统关键字；`?`/`&` 必须 ASCII（禁全角 `？`）。
-
-**★ 逆引用硬门禁（A0.11）**：列表数据带左父格链（引用列 ≤ 链接列）。引用右侧列 → 构建**直接抛错不落库**
-（静默失效无报错，历史血案）。要传行内任意列 → 把链接列放**最右**（demo 的「导出明细」列即最右）。
-
-### 接收端：目标报表的查询条件（强制 · 2026-11-03 实测）
-
-链接参数**不会**自动过滤目标报表。目标报表里必须有对应条件，且默认值写成「自定义 + `{参数名}`」：
-
-| 键 | 值 |
-|---|---|
-| `defaultValueType` | `"custom"` |
-| `defaultValue` / `type2DefaultValue` | `'["{searchfield002}",""]'` |
-
-- URL 的参数名 = `{…}` 里的名字（通常与条件标识 `searchfield00x` 相同）。
-- 设计器「默认值」框显示为 `(searchfield002)`，圆括号只是 UI 渲染，落库是花括号。
-- 保持「常规 / 空」→ 参数被**静默忽略**：页面能打开、不报错、数据一条不少。
-- 不带参数打开目标报表时，占位会被清空，不会残留字面量。
-- 落地后跑 `e10-cli report verify drill <来源报表> --app-id <id>` 验收；缺绑定会失败并给出修法。
-
-## 三、能力边界（如实告知用户）
-
-| 效果 | 结论 |
-|---|---|
-| 每行「导出」**不预览直接导出**该行明细 | **无已验证 API**。已固化替代：导出列 = Const 链接钻取到明细报表（预览态）。真·直接导出/打印须在设计器或预览页验证官方事件（`openType:"jsscript"` 路线），验证通过后再固化进 CLI |
-| 点击列头升降序切换 | `orderType` 落库即生效配置；预览是否可点击切换以平台版本验证为准 |
-| 无限层次钻取（订单→明细→产品） | 逐层建报表、每层 `link.type:"report"` 指向下一层即可，机制相同无层数限制 |
-
-## 四、搭建提示语句（用户照此提需求）
-
-> 搭一张数据钻取列表报表（appId <appId>，数据源 <表名/sourceId>）：
-> 列：订单号/订购日期/客户名称/…（列级 `sort` 按需升序）；点击订单号钻取到明细报表 <reportId> 并按订单号过滤
-> （`link.type:"report"`，参数名=目标报表查询条件标识）；末列「导出明细」钻取到 <明细报表/单据卡片>；
-> 无限层次（订单→明细→产品）逐层建表互联。用 `e10-cli report build spec` 一次落库，回读验收 pcHreflink/orderType。
-
-**验证**：回读 `dump cells` 或 `getReportDevInfo`，核对 `pcHreflink`（占位/坐标/ASCII ?）与 `orderType`；
-渲染验证占位已替换为真实值（event-hreflink-guide §3.0，配置层正常 ≠ 运行时穿透）；
-接收端跑 `e10-cli report verify drill <来源报表> --app-id <id>`，确认每个 URL 参数都被目标条件的自定义默认值接住。
+# 数据钻取类报表 · 指南（SKILL A0.14 · 场景 D）
+
+> 形态：**列表报表 + 行级钻取**（官方 demo「订单信息列表」类）：
+> ① **多维度钻取** —— 点击订单号钻取订单明细 / 物流信息（跳其他报表并按当前行值过滤）；
+> ② **列排序** —— 点击订购日期按升/降序查看；
+> ③ **行级导出/打印明细** —— 每行「导出」链接（详见 §三能力边界）。
+> 固化：2026-10-29 · 落地点 = `build spec` 的 `columns[].link` / `columns[].sort`（通用建表器内置，禁止临时脚本）。
+
+## 一、能力 → 落库键映射
+
+| 需求 | 落库键 | 语法 | 规则来源 |
+|---|---|---|---|
+| 钻取链接 | `style.cellType.pcHreflink` + `openType` | 见 §二 | `event-hreflink-guide.md` §二/§三 |
+| 列排序 | Field 格 `style.cellType.orderType` = `asc`/`desc` | `columns[].sort` | 预览点击排序表现**以设计器确认为准** |
+| 跳同表其他 Sheet | 同上（pcHreflink + `sheetIndex=N-1`） | `columns[].cellType:"jump"` + `jumpSheet:N` | 场景 C（branch-scene-guide.md） |
+
+## 二、columns[].link 声明（build spec spec.json）
+
+```json
+"columns": [
+  { "title": "订单号", "field": "订单号", "width": 100,
+    "link": { "type": "report", "reportId": "<明细报表id>", "params": { "ddhh": "SELF" }, "openType": "blank" } },
+  { "title": "订购日期", "field": "订购日期", "width": 120, "sort": "asc" },
+  { "title": "客户名称", "field": "客户名称", "width": 140 },
+  { "title": "导出明细", "cellType": "jump", "href": "<custom 或见 §三>", "width": 90 }
+]
+```
+
+| type | 生成的 URL | 传参方式 |
+|---|---|---|
+| `report` | `/sp/edc/report/view/<reportId>` | 查询串 `参数名=坐标`（无花括号）；参数名须与**目标报表查询条件标识**对应 |
+| `list` | `/sp/ebdfpage/list/<formId>` | 同上 |
+| `card` | `/sp/ebdfpage/card/0/<formId>` | **路径占位** `{坐标}`（带花括号，§3.2），第一个参数进路径、其余进查询串 |
+| `custom` | 原样 `url`（可预置 `{坐标}` 占位） | params 仍拼查询串 |
+
+- `params` 值：`"SELF"` = 当前格；或**列标题** → 该列数据格坐标（自动转 Excel 引用，如 `D3`）。
+- `openType`：`blank`（默认弹出页）/ `self` / `jsscript`，禁止自造别名。
+- 参数名**避免** `id`/`name` 等系统关键字；`?`/`&` 必须 ASCII（禁全角 `？`）。
+
+**★ 逆引用硬门禁（A0.11）**：列表数据带左父格链（引用列 ≤ 链接列）。引用右侧列 → 构建**直接抛错不落库**
+（静默失效无报错，历史血案）。要传行内任意列 → 把链接列放**最右**（demo 的「导出明细」列即最右）。
+
+### 接收端：目标报表的查询条件（强制 · 2026-11-03 实测）
+
+链接参数**不会**自动过滤目标报表。目标报表里必须有对应条件，且默认值写成「自定义 + `{参数名}`」：
+
+| 键 | 值 |
+|---|---|
+| `defaultValueType` | `"custom"` |
+| `defaultValue` / `type2DefaultValue` | `'["{searchfield002}",""]'` |
+
+- URL 的参数名 = `{…}` 里的名字（通常与条件标识 `searchfield00x` 相同）。
+- 设计器「默认值」框显示为 `(searchfield002)`，圆括号只是 UI 渲染，落库是花括号。
+- 保持「常规 / 空」→ 参数被**静默忽略**：页面能打开、不报错、数据一条不少。
+- 不带参数打开目标报表时，占位会被清空，不会残留字面量。
+- 落地后跑 `e10-cli report verify drill <来源报表> --app-id <id>` 验收；缺绑定会失败并给出修法。
+
+## 三、能力边界（如实告知用户）
+
+| 效果 | 结论 |
+|---|---|
+| 每行「导出」**不预览直接导出**该行明细 | **无已验证 API**。已固化替代：导出列 = Const 链接钻取到明细报表（预览态）。真·直接导出/打印须在设计器或预览页验证官方事件（`openType:"jsscript"` 路线），验证通过后再固化进 CLI |
+| 点击列头升降序切换 | `orderType` 落库即生效配置；预览是否可点击切换以平台版本验证为准 |
+| 无限层次钻取（订单→明细→产品） | 逐层建报表、每层 `link.type:"report"` 指向下一层即可，机制相同无层数限制 |
+
+## 四、搭建提示语句（用户照此提需求）
+
+> 搭一张数据钻取列表报表（appId <appId>，数据源 <表名/sourceId>）：
+> 列：订单号/订购日期/客户名称/…（列级 `sort` 按需升序）；点击订单号钻取到明细报表 <reportId> 并按订单号过滤
+> （`link.type:"report"`，参数名=目标报表查询条件标识）；末列「导出明细」钻取到 <明细报表/单据卡片>；
+> 无限层次（订单→明细→产品）逐层建表互联。用 `e10-cli report build spec` 一次落库，回读验收 pcHreflink/orderType。
+
+**验证**：回读 `dump cells` 或 `getReportDevInfo`，核对 `pcHreflink`（占位/坐标/ASCII ?）与 `orderType`；
+渲染验证占位已替换为真实值（event-hreflink-guide §3.0，配置层正常 ≠ 运行时穿透）；
+接收端跑 `e10-cli report verify drill <来源报表> --app-id <id>`，确认每个 URL 参数都被目标条件的自定义默认值接住。

package/skill-docs/references/report/event-hreflink-guide.md

@@ -1,222 +1,222 @@
-# 报表事件 · 超链接传参（强制）
-
-> **UI**：设计器右侧 **事件** Tab — PC链接地址 / H5链接地址 / 打开方式
-> **帮助手册依据**：知识库 §5.3「查询条件传参」、§6.6「跳转数据列表页」；搭建指南「事件」Tab
-> **源码**：`HreflinkTrans` · `SpreadUtil.getFormulaParams` · `DynamicParamsBuilder` · `HreflinkCellType`
-> **CLI**：`e10-cli report validate href --file cell.json` / `--map "弹出页"`
-
----
-
-## 〇、能力与落库键
-
-| UI | 落库字段 | 说明 |
-|----|----------|------|
-| PC链接地址 | **`pcHreflink`** | 分析页 PC 点击跳转；运行时别名 `hreflink` |
-| H5链接地址 | **`h5Hreflink`** | 移动端优先；运行时别名 `mbhreflink`；有值且移动端时覆盖 PC 链接 |
-| 打开方式 | **`openType`** | 见 §二 |
-
-须写入 **`fields[]` + workbook `style.cellType`**（Const/Field 均可配事件；超链接占位 Const 另遵守父格规则）。
-
----
-
-## 一、帮助手册规则（产品语义）
-
-摘自报表功能说明 / 知识库（Agent 须按此话术与用户对齐）：
-
-1. **事件动作可传递单元格值**（当前格及其父格值；**父格的父格也支持**）。
-2. **可传递查询条件值**（查询条件标识形如 `{searchfield001}`）。
-3. **跳转列表示例**：在链接中拼接单元格坐标参数，如
-   `/sp/ebdfpage/list/xxx?ry=B5&kssj=E3`
-   （`B5`/`E3` 表示取该格展开后的实际值）。
-4. 打开方式 UI：**弹出页 / 当前页 / 执行js代码**。
-
----
-
-## 二、打开方式 `openType`
-
-| UI（事件面板） | 落库值 | 运行时 |
-|----------------|--------|--------|
-| **弹出页** | **`blank`**（默认；空则归一为 blank） | 新窗口/弹层 |
-| **当前页** | **`self`** | 当前页跳转 |
-| **执行js代码** | **`jsscript`** | 将链接内容当 JS 执行 |
-
-禁止自造 `popup` / `window` 等别名。
-
-**链接字符**：`?` / `&` 必须是 **ASCII**（`?`=U+003F）。禁止中文全角 `？`（U+FF1F），否则预览点击无反应（事故：E7 全角 vs F7 半角）。
-
-```bash
-e10-cli report validate href --map "弹出页"
-e10-cli report validate href --map "执行js代码"
-e10-cli report validate href --file cell.json --fix   # 全角？→ASCII ?
-```
-
----
-
-## 三、传「单元格值」语法（帮助手册 · 强制）
-
-> **范围**：仅当前格 + 设置链接字段的**左/上父格**（父格的父格也支持）。超出父格链的坐标**不能**取值。
-
-### 3.0 ★★ 逆引用会「静默失效」（A0.11 · 2026-09-15 血案）
-
-> 供应商绩效看板 `1315297716934582273`：A3 写 `pcHreflink="…/{M3}"`，而 **M3 是 A3 的子格**（M3 左父格 = A3）。
-> 配置回读正常、设计器正常、预览不报错 —— 渲染后 `{M3}` **原样保留从未替换**，穿透 100% 失效。
-
-| 引用目标 | 结果 |
-|---|---|
-| 当前格 / 左父格 / 上父格（含父格的父格） | ✅ 运行时替换为展开后的真实值 |
-| **子格 / 旁系格**（如 A3 引 `{M3}`，而 M3 左父格=A3） | ❌ **静默失效**：占位符原样输出，无任何报错 |
-| `$datasetId.fieldName$`（同行数据集字段） | ❌ 本环境超链接中**验证不生效**（原样保留） |
-
-**唯一验证方法（不看配置层、不看设计器）**：渲染后读 `cell.style.cellType.hreflink`（`BlankHerflinkCellType`），
-确认占位已变成**真实值**：
-
-```
-期望  /sp/ebdfpage/card/0/864399547574140928/866754615609884673
-而非  /sp/ebdfpage/card/0/864399547574140928/{M3}
-```
-
-**修法（最小改动）**：让**承载目标值的格**成为链接格的**父格**：
-
-```bash
-# A3 需要引用 M3 的 id → 把 M3 变成 A3 的左父格（M3 设为根格避免环）
-e10-cli report fix table-name --report-id <id> \
-  --set-parent "2,0=2,12" --set-parent "2,12=-1,-1" \
-  --set-json '2,0:pcHreflink:"…/{M3}"' --apply
-```
-
-**标准形态**（参考实现 `_ref_m4_full.json`）：链接格在**右**、承 id 列在**左** ——
-`M4`（Const「点击查看」）的 `leftX/leftY = L4`，`pcHreflink="…/{L4}"`，引的正是自己的左父格。
-想「点击**某字段列**」穿透，就让承 id 的**隐藏列位于该字段列左侧**。
-
-> ⚠️ **禁止**为了「父格方向顺眼」而重排列（违反 A0.8 + 用户「不顺手改其他」偏好）；确需重排属**结构性变更**，须先获用户同意。
-
-### 3.1 查询串传参（台账过滤 / 外链最常用）
-
-格式：`参数名=字段坐标`（坐标**不加** `{}`）。
-
-| 规则 | 说明 |
-|------|------|
-| 链接**已有** `?` | 用 `&` 拼接：`...&aa=D4&bb=C4` |
-| 链接**没有** `?` | 第一个参数用 `?`：`...?aa=D4&bb=C4` |
-| 多值 | 多个 `&参数名=坐标` |
-| 参数名 | **避免**系统关键字：`id`、`name` 等 |
-| 父格链 | 左父格为默认时，E4→D4→C4，故 E4 链接可传 E4/D4/C4 |
-
-```text
-# 示例1（已有 ?）
-https://weapp.xxx.cn/sp/ebdfpage/list/1092...?id=1123...&aa=D4&bb=C4
-
-# 示例2（无业务 ? 时，第一个单元格参用 ?）
-https://weapp.xxx.cn/sp/ebdfpage/list/1092...?aa=D3&bb=C4
-
-# 百度等外链（勿用 id/name 作参数名）
-https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}
-```
-
-运行时将 `D4`/`C4` 替换为对应单元格展开后的**实际值**。
-
-### 3.2 路径占位（表单布局 card 等）
-
-布局地址里的 `$dataid$` 等改为 **`{坐标}`**（**带花括号**）：
-
-```text
-/sp/ebdfpage/card/0/1123053786772799489/{C4}
-```
-
-### 3.3 其它写法（次要）
-
-| 写法 | 说明 |
-|------|------|
-| **`{L4}` / `{A1}`** | 路径或需花括号的场景 |
-| **`$datasetId.fieldName$`** | 同行数据集字段（引擎支持；**手册主推仍是坐标传参**） |
-
-**超链接 Const 父格（强制）**：若链接依赖坐标数据格且该格是 Const 占位：
-
-- **左父格**须指向提供该值的数据格，**禁止**默认 / `(0,0)`
-- **上父格**通常 `-1`
-
-普通 **Field** 纵向列表、左父格默认时：可按 §3.1 传当前格及左侧父格链坐标（如 E4 传 D4、C4）。
-
-详见 `report-self-check-guide.md` §2.2。
-
----
-
-## 四、传「查询条件值」语法
-
-查询条件在高级搜索中的标识：
-
-| 标识 | 含义 |
-|------|------|
-| `{searchfield001}` | `asNameIndex=1` → `searchfield` + 三位补零 |
-| `{searchfield002}` | `asNameIndex=2` |
-| `{searchfield001_start}` / `{searchfield001_end}` | 日期区间起止 |
-
-规则：
-
-1. `asNameIndex` 与 `showOrder` 一致且唯一 >0（见 `query-condition-api-guide.md`）。
-2. 链接中写 `{searchfield00x}`，预览时替换为用户当前查询值。
-3. 也可在表头 Const 的 `cellText` 中引用同一标识显示查询值。
-4. 系统参数（如 `{userid}`、`{date}`、`{year}`）亦可出现在链接中（`DynamicParamsBuilder`）。
-5. **报表跳报表时，接收端要配条件**：目标报表的查询条件必须用「自定义」默认值 `'["{searchfield00x}",""]'` 声明同名参数，否则 URL 参数被静默忽略（页面正常、数据不过滤）。参数名以 `{…}` 里为准，链接 key 必须与之一致。详见 `query-condition-api-guide.md` §5.3，落地后用 `report verify drill` 验收。
-
-示例：
-
-```text
-/sp/ebdfpage/list/864399547574140928?creator={searchfield001}&dept=B5
-```
-
-> 查询条件用 `{searchfield00x}`；单元格在查询串里用 **无花括号** 坐标（`dept=B5`）。
-
----
-
-## 五、完整写入示例
-
-```json
-{
-  "cellType": "Field",
-  "name": "3506271460832878820",
-  "text": "资产名称",
-  "pcHreflink": "https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}",
-  "h5Hreflink": "",
-  "openType": "blank"
-}
-```
-
-路径型示例（Const/Field 均可）：
-
-```json
-{
-  "cellType": "Const",
-  "cellText": "点击查看",
-  "pcHreflink": "/sp/ebdfpage/card/0/1123053786772799489/{C4}",
-  "openType": "blank",
-  "leftX": 3,
-  "leftY": 2,
-  "topX": -1,
-  "topY": -1
-}
-```
-
----
-
-## 六、Agent 检查清单
-
-- [ ] `openType` ∈ `blank|self|jsscript`，UI 文案已映射
-- [ ] 传单元格：查询串用 `参数名=坐标`（无 `{}`）；路径用 `{坐标}`；仅当前格+父格链
-- [ ] ★ **逆引用自检**：每个占位坐标都落在「该格自身 + 左/上父格链」内（引子格/旁系格 = 静默失效）
-- [ ] ★ **渲染验证**：渲染后读 `cellType.hreflink`，确认占位已替换为**真实值**（配置层看不出问题）
-- [ ] 传查询条件：`{searchfield00x}`，asNameIndex 已对齐
-- [ ] ★ 报表跳报表：目标条件的自定义默认值已声明 `{参数名}`（`report verify drill` 通过）
-- [ ] 参数名避免 `id`/`name` 等系统关键字
-- [ ] PC/H5 分端：移动需要时填 `h5Hreflink`
-- [ ] 双写 fields + workbook；`safe_report_save` / fieldToCell 不丢链接键
-
----
-
-## 关联
-
-- `report-help-guide.md` §事件（摘要）
-- `report-knowledge-base.md` §5.3 / §6.6
-- `query-condition-api-guide.md` — asNameIndex / searchfield
-- `report-self-check-guide.md` — 超链接父格
-- `report-designer-feature-map.md` §7.2
+# 报表事件 · 超链接传参（强制）
+
+> **UI**：设计器右侧 **事件** Tab — PC链接地址 / H5链接地址 / 打开方式
+> **帮助手册依据**：知识库 §5.3「查询条件传参」、§6.6「跳转数据列表页」；搭建指南「事件」Tab
+> **源码**：`HreflinkTrans` · `SpreadUtil.getFormulaParams` · `DynamicParamsBuilder` · `HreflinkCellType`
+> **CLI**：`e10-cli report validate href --file cell.json` / `--map "弹出页"`
+
+---
+
+## 〇、能力与落库键
+
+| UI | 落库字段 | 说明 |
+|----|----------|------|
+| PC链接地址 | **`pcHreflink`** | 分析页 PC 点击跳转；运行时别名 `hreflink` |
+| H5链接地址 | **`h5Hreflink`** | 移动端优先；运行时别名 `mbhreflink`；有值且移动端时覆盖 PC 链接 |
+| 打开方式 | **`openType`** | 见 §二 |
+
+须写入 **`fields[]` + workbook `style.cellType`**（Const/Field 均可配事件；超链接占位 Const 另遵守父格规则）。
+
+---
+
+## 一、帮助手册规则（产品语义）
+
+摘自报表功能说明 / 知识库（Agent 须按此话术与用户对齐）：
+
+1. **事件动作可传递单元格值**（当前格及其父格值；**父格的父格也支持**）。
+2. **可传递查询条件值**（查询条件标识形如 `{searchfield001}`）。
+3. **跳转列表示例**：在链接中拼接单元格坐标参数，如
+   `/sp/ebdfpage/list/xxx?ry=B5&kssj=E3`
+   （`B5`/`E3` 表示取该格展开后的实际值）。
+4. 打开方式 UI：**弹出页 / 当前页 / 执行js代码**。
+
+---
+
+## 二、打开方式 `openType`
+
+| UI（事件面板） | 落库值 | 运行时 |
+|----------------|--------|--------|
+| **弹出页** | **`blank`**（默认；空则归一为 blank） | 新窗口/弹层 |
+| **当前页** | **`self`** | 当前页跳转 |
+| **执行js代码** | **`jsscript`** | 将链接内容当 JS 执行 |
+
+禁止自造 `popup` / `window` 等别名。
+
+**链接字符**：`?` / `&` 必须是 **ASCII**（`?`=U+003F）。禁止中文全角 `？`（U+FF1F），否则预览点击无反应（事故：E7 全角 vs F7 半角）。
+
+```bash
+e10-cli report validate href --map "弹出页"
+e10-cli report validate href --map "执行js代码"
+e10-cli report validate href --file cell.json --fix   # 全角？→ASCII ?
+```
+
+---
+
+## 三、传「单元格值」语法（帮助手册 · 强制）
+
+> **范围**：仅当前格 + 设置链接字段的**左/上父格**（父格的父格也支持）。超出父格链的坐标**不能**取值。
+
+### 3.0 ★★ 逆引用会「静默失效」（A0.11 · 2026-09-15 血案）
+
+> 供应商绩效看板 `1315297716934582273`：A3 写 `pcHreflink="…/{M3}"`，而 **M3 是 A3 的子格**（M3 左父格 = A3）。
+> 配置回读正常、设计器正常、预览不报错 —— 渲染后 `{M3}` **原样保留从未替换**，穿透 100% 失效。
+
+| 引用目标 | 结果 |
+|---|---|
+| 当前格 / 左父格 / 上父格（含父格的父格） | ✅ 运行时替换为展开后的真实值 |
+| **子格 / 旁系格**（如 A3 引 `{M3}`，而 M3 左父格=A3） | ❌ **静默失效**：占位符原样输出，无任何报错 |
+| `$datasetId.fieldName$`（同行数据集字段） | ❌ 本环境超链接中**验证不生效**（原样保留） |
+
+**唯一验证方法（不看配置层、不看设计器）**：渲染后读 `cell.style.cellType.hreflink`（`BlankHerflinkCellType`），
+确认占位已变成**真实值**：
+
+```
+期望  /sp/ebdfpage/card/0/864399547574140928/866754615609884673
+而非  /sp/ebdfpage/card/0/864399547574140928/{M3}
+```
+
+**修法（最小改动）**：让**承载目标值的格**成为链接格的**父格**：
+
+```bash
+# A3 需要引用 M3 的 id → 把 M3 变成 A3 的左父格（M3 设为根格避免环）
+e10-cli report fix table-name --report-id <id> \
+  --set-parent "2,0=2,12" --set-parent "2,12=-1,-1" \
+  --set-json '2,0:pcHreflink:"…/{M3}"' --apply
+```
+
+**标准形态**（参考实现 `_ref_m4_full.json`）：链接格在**右**、承 id 列在**左** ——
+`M4`（Const「点击查看」）的 `leftX/leftY = L4`，`pcHreflink="…/{L4}"`，引的正是自己的左父格。
+想「点击**某字段列**」穿透，就让承 id 的**隐藏列位于该字段列左侧**。
+
+> ⚠️ **禁止**为了「父格方向顺眼」而重排列（违反 A0.8 + 用户「不顺手改其他」偏好）；确需重排属**结构性变更**，须先获用户同意。
+
+### 3.1 查询串传参（台账过滤 / 外链最常用）
+
+格式：`参数名=字段坐标`（坐标**不加** `{}`）。
+
+| 规则 | 说明 |
+|------|------|
+| 链接**已有** `?` | 用 `&` 拼接：`...&aa=D4&bb=C4` |
+| 链接**没有** `?` | 第一个参数用 `?`：`...?aa=D4&bb=C4` |
+| 多值 | 多个 `&参数名=坐标` |
+| 参数名 | **避免**系统关键字：`id`、`name` 等 |
+| 父格链 | 左父格为默认时，E4→D4→C4，故 E4 链接可传 E4/D4/C4 |
+
+```text
+# 示例1（已有 ?）
+https://weapp.xxx.cn/sp/ebdfpage/list/1092...?id=1123...&aa=D4&bb=C4
+
+# 示例2（无业务 ? 时，第一个单元格参用 ?）
+https://weapp.xxx.cn/sp/ebdfpage/list/1092...?aa=D3&bb=C4
+
+# 百度等外链（勿用 id/name 作参数名）
+https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}
+```
+
+运行时将 `D4`/`C4` 替换为对应单元格展开后的**实际值**。
+
+### 3.2 路径占位（表单布局 card 等）
+
+布局地址里的 `$dataid$` 等改为 **`{坐标}`**（**带花括号**）：
+
+```text
+/sp/ebdfpage/card/0/1123053786772799489/{C4}
+```
+
+### 3.3 其它写法（次要）
+
+| 写法 | 说明 |
+|------|------|
+| **`{L4}` / `{A1}`** | 路径或需花括号的场景 |
+| **`$datasetId.fieldName$`** | 同行数据集字段（引擎支持；**手册主推仍是坐标传参**） |
+
+**超链接 Const 父格（强制）**：若链接依赖坐标数据格且该格是 Const 占位：
+
+- **左父格**须指向提供该值的数据格，**禁止**默认 / `(0,0)`
+- **上父格**通常 `-1`
+
+普通 **Field** 纵向列表、左父格默认时：可按 §3.1 传当前格及左侧父格链坐标（如 E4 传 D4、C4）。
+
+详见 `report-self-check-guide.md` §2.2。
+
+---
+
+## 四、传「查询条件值」语法
+
+查询条件在高级搜索中的标识：
+
+| 标识 | 含义 |
+|------|------|
+| `{searchfield001}` | `asNameIndex=1` → `searchfield` + 三位补零 |
+| `{searchfield002}` | `asNameIndex=2` |
+| `{searchfield001_start}` / `{searchfield001_end}` | 日期区间起止 |
+
+规则：
+
+1. `asNameIndex` 与 `showOrder` 一致且唯一 >0（见 `query-condition-api-guide.md`）。
+2. 链接中写 `{searchfield00x}`，预览时替换为用户当前查询值。
+3. 也可在表头 Const 的 `cellText` 中引用同一标识显示查询值。
+4. 系统参数（如 `{userid}`、`{date}`、`{year}`）亦可出现在链接中（`DynamicParamsBuilder`）。
+5. **报表跳报表时，接收端要配条件**：目标报表的查询条件必须用「自定义」默认值 `'["{searchfield00x}",""]'` 声明同名参数，否则 URL 参数被静默忽略（页面正常、数据不过滤）。参数名以 `{…}` 里为准，链接 key 必须与之一致。详见 `query-condition-api-guide.md` §5.3，落地后用 `report verify drill` 验收。
+
+示例：
+
+```text
+/sp/ebdfpage/list/864399547574140928?creator={searchfield001}&dept=B5
+```
+
+> 查询条件用 `{searchfield00x}`；单元格在查询串里用 **无花括号** 坐标（`dept=B5`）。
+
+---
+
+## 五、完整写入示例
+
+```json
+{
+  "cellType": "Field",
+  "name": "3506271460832878820",
+  "text": "资产名称",
+  "pcHreflink": "https://www.baidu.com/s?zclb=D7&zcmc=E7&cx={searchfield001}",
+  "h5Hreflink": "",
+  "openType": "blank"
+}
+```
+
+路径型示例（Const/Field 均可）：
+
+```json
+{
+  "cellType": "Const",
+  "cellText": "点击查看",
+  "pcHreflink": "/sp/ebdfpage/card/0/1123053786772799489/{C4}",
+  "openType": "blank",
+  "leftX": 3,
+  "leftY": 2,
+  "topX": -1,
+  "topY": -1
+}
+```
+
+---
+
+## 六、Agent 检查清单
+
+- [ ] `openType` ∈ `blank|self|jsscript`，UI 文案已映射
+- [ ] 传单元格：查询串用 `参数名=坐标`（无 `{}`）；路径用 `{坐标}`；仅当前格+父格链
+- [ ] ★ **逆引用自检**：每个占位坐标都落在「该格自身 + 左/上父格链」内（引子格/旁系格 = 静默失效）
+- [ ] ★ **渲染验证**：渲染后读 `cellType.hreflink`，确认占位已替换为**真实值**（配置层看不出问题）
+- [ ] 传查询条件：`{searchfield00x}`，asNameIndex 已对齐
+- [ ] ★ 报表跳报表：目标条件的自定义默认值已声明 `{参数名}`（`report verify drill` 通过）
+- [ ] 参数名避免 `id`/`name` 等系统关键字
+- [ ] PC/H5 分端：移动需要时填 `h5Hreflink`
+- [ ] 双写 fields + workbook；`safe_report_save` / fieldToCell 不丢链接键
+
+---
+
+## 关联
+
+- `report-help-guide.md` §事件（摘要）
+- `report-knowledge-base.md` §5.3 / §6.6
+- `query-condition-api-guide.md` — asNameIndex / searchfield
+- `report-self-check-guide.md` — 超链接父格
+- `report-designer-feature-map.md` §7.2