weaver-e10-builder 1.6.16 → 1.7.1

package/skill-docs/references/report/cell-transform-guide.md

@@ -1,147 +1,161 @@
-# 单元格「转换」面板（强制）
-
-> **UI**：设计器右侧 **单元格 → 转换**（选中 Field 格时）
-> **源码**：`AnalysisFieldCellType` · `Trans.getTransInstance` · 设计器 `route_ReportDesigner`
-> **CLI**：`e10-cli report validate transform --map "人员"` / `--file cell.json`
-> **落库**：须同时写入 `fields[]` 与 workbook `style.cellType`（`fieldToCell` 已透传）
-
----
-
-## 〇、结论（扫描结果）
-
-| UI 能力 | 落库键 | Skill 此前 | 现状 |
-|---------|--------|------------|------|
-| 字段转换（人员/部门/…） | `transType` + `browserType` / `transSelectOptions` | 帮助文案不全；`report-data-model` 枚举**错误** | **本文 + validate + fieldToCell** |
-| HTML转换 | **`isHtml`** `"0"|"1"`（不是 transType） | 未正确文档化 | ✅ |
-| 前缀/后缀 | **`prefixAndSuffix`** `["前","后"]` | 仅一笔带过 | ✅ |
-| 条码 | **`qrcodeType`** `no|barcode|qrcode`（± `qrcodelink`） | 误写成 FieldType | ✅ |
-| 隐藏内容 | **`hiddenContext`** `"0"|"1"`（拼写 Context） | 易与显示方式混淆 | ✅ |
-| 文字方向 | **`textDirection`** 枚举 | 知识库有枚举、无面板映射 | ✅ |
-
-**禁止**再用 `person` / `department` / `image` / `html` / `barcode` 当作单一 `transType`。
-
----
-
-## 一、字段转换 `transType`
-
-### 1.1 UI → 落库（设计器当前）
-
-| UI 文案 | `transType` | 附加字段 |
-|---------|-------------|---------|
-| 无 | `default` | — |
-| **人员** | **`browser`** | `browserType:[{id:"HrmEmployeeComInfo"}]` |
-| **部门** | **`browser`** | `browserType:[{id:"HrmDepartmentComInfo"}]` |
-| **部门全路径** | **`browser`** | `browserType:[{id:"HrmDepartmentAllPathComInfo"}]` |
-| Checkbox | `checkbox` | — |
-| 选择框 | `select` | `transSelectOptions:[{selectValue,selectName},…]` |
-| 颜色选择框 | `colorSelect` | `transSelectOptions`（`selectName` 常为颜色值） |
-| 分值图标 | `scoreIcon` | `transSelectOptions:[{id:"scoreIconId",selectValue:"1",selectName:"<最大分>"}]` |
-| 斜线文字 | `slashWord` | `transSelectOptions:[{id:"slashWordId",selectValue:"slashWord",selectName:"TopLeftDownRight"|"DownLeftTopRight"}]`；文案最多 3 段，半角 `;` 分隔 |
-| 关联类型 | `browser` | 弹窗写入 `browserType`（如 `{module,type}` / ComInfo id，**以接口返回为准**） |
-| 图片 | `picture` | — |
-
-> Java 仍兼容遗留 `hrm` / `dept` / `subcom` / `fill`，**新写禁止**用遗留值；人员/部门一律走 `browser`+ComInfo。
-
-### 1.2 双写示例（人员）
-
-```json
-{
-  "transType": "browser",
-  "browserType": [{ "id": "HrmEmployeeComInfo" }],
-  "isHtml": "0",
-  "qrcodeType": "no",
-  "prefixAndSuffix": ["", ""],
-  "hiddenContext": "0",
-  "textDirection": "FromLeftToRight"
-}
-```
-
-`fields[].browserType` / `transSelectOptions` / `prefixAndSuffix` 在 DB 侧常为 **JSON 字符串**；workbook `cellType` 侧为数组。
-
----
-
-## 二、HTML转换 · `isHtml`
-
-| UI | 值 |
-|----|-----|
-| 否 | `"0"` |
-| 是 | `"1"` |
-
-为 `"1"` 时运行时按 HTML 处理/剥离（见 `AnalysisParams`）。**不是** `transType=html`。
-
----
-
-## 三、前缀 / 后缀 · `prefixAndSuffix`
-
-```json
-"prefixAndSuffix": ["前缀文本", "后缀文本"]
-```
-
-默认 `["",""]`。重建 workbook 时禁止丢掉该键。
-
----
-
-## 四、条码 · `qrcodeType`
-
-| UI | 值 |
-|----|-----|
-| 无 | `no` |
-| 条码 | `barcode` |
-| 二维码 | `qrcode` |
-
-二维码可选：`qrcodelink` = `"1"` / `"0"`（是否包含移动端地址）。**不是** `transType`。
-
----
-
-## 五、隐藏内容 · `hiddenContext`
-
-| UI | 值 |
-|----|-----|
-| 否 | `"0"` |
-| 是 | `"1"` |
-
-键名是 **`hiddenContext`**（Context，不是 Content）。与「显示方式」`displayType` **无关**。
-
----
-
-## 六、文字方向 · `textDirection`
-
-| UI | 值 |
-|----|-----|
-| 从左向右 | `FromLeftToRight`（默认） |
-| 从右向左 | `FromRightToLeft` |
-| 竖排 | `VerticalArrangement` |
-| 顺时针旋转 90° | `CW` |
-| 逆时针旋转 90° | `CCW` |
-
----
-
-## 七、Agent / CLI
-
-```bash
-e10-cli report validate transform --map "人员"
-e10-cli report validate transform --map "部门全路径"
-e10-cli report validate transform --map "二维码"
-e10-cli report validate transform --file cell-transform.json
-e10-cli report validate transform --list
-```
-
-定点改转换时：改 `fields[]` 对应键 → `safe_report_save` / `fieldToCell` 透传到 workbook → 回读核对。
-
----
-
-## 八、禁令
-
-- 禁止 `transType=person|department|image|html|barcode|hidden`
-- 禁止人员/部门只写 `transType=hrm|dept`（遗留）
-- 禁止重建 workbook 时丢掉转换键
-- 禁止把「隐藏内容」当成「显示方式=不显示」
-
----
-
-## 关联
-
-- `cell-config-echo-guide.md` — 数字格式 / 日期分组 / 字体
-- `report-designer-feature-map.md` — 右侧面板总览
-- `report-data-model.md` §八 — 已废弃错误表，以本文为准
-- `` — `fieldToCell` 透传
+# 单元格「转换」面板（强制）
+
+> **UI**：设计器右侧 **单元格 → 转换**（选中 Field 格时）
+> **源码**：`AnalysisFieldCellType` · `Trans.getTransInstance` · 设计器 `route_ReportDesigner`
+> **CLI**：`e10-cli report cell-transform set/show/list/clear …`（写入 + 回读）；纯校验用 `e10-cli report validate transform`
+> **落库**：须同时写入 `fields[]` 与 workbook `style.cellType`（`fieldToCell` 已透传）
+
+---
+
+## 〇、结论（扫描结果）
+
+| UI 能力 | 落库键 | Skill 此前 | 现状 |
+|---------|--------|------------|------|
+| 字段转换（人员/部门/…） | `transType` + `browserType` / `transSelectOptions` | 帮助文案不全；`report-data-model` 枚举**错误** | **本文 + validate + fieldToCell** |
+| HTML转换 | **`isHtml`** `"0"|"1"`（不是 transType） | 未正确文档化 | ✅ |
+| 前缀/后缀 | **`prefixAndSuffix`** `["前","后"]` | 仅一笔带过 | ✅ |
+| 条码 | **`qrcodeType`** `no|barcode|qrcode`（± `qrcodelink`） | 误写成 FieldType | ✅ |
+| 隐藏内容 | **`hiddenContext`** `"0"|"1"`（拼写 Context） | 易与显示方式混淆 | ✅ |
+| 文字方向 | **`textDirection`** 枚举 | 知识库有枚举、无面板映射 | ✅ |
+
+**禁止**再用 `person` / `department` / `image` / `html` / `barcode` 当作单一 `transType`。
+
+---
+
+## 一、字段转换 `transType`
+
+### 1.1 UI → 落库（设计器当前）
+
+| UI 文案 | `transType` | 附加字段 |
+|---------|-------------|---------|
+| 无 | `default` | — |
+| **人员** | **`browser`** | `browserType:[{id:"HrmEmployeeComInfo"}]` |
+| **部门** | **`browser`** | `browserType:[{id:"HrmDepartmentComInfo"}]` |
+| **部门全路径** | **`browser`** | `browserType:[{id:"HrmDepartmentAllPathComInfo"}]` |
+| Checkbox | `checkbox` | — |
+| 选择框 | `select` | `transSelectOptions:[{selectValue,selectName},…]` |
+| 颜色选择框 | `colorSelect` | `transSelectOptions`（`selectName` 常为颜色值） |
+| 分值图标 | `scoreIcon` | `transSelectOptions:[{id:"scoreIconId",selectValue:"1",selectName:"<最大分>"}]` |
+| 斜线文字 | `slashWord` | `transSelectOptions:[{id:"slashWordId",selectValue:"slashWord",selectName:"TopLeftDownRight"|"DownLeftTopRight"}]`；文案最多 3 段，半角 `;` 分隔 |
+| 关联类型 | `browser` | 弹窗写入 `browserType`（如 `{module,type}` / ComInfo id，**以接口返回为准**） |
+| 图片 | `picture` | — |
+
+> Java 仍兼容遗留 `hrm` / `dept` / `subcom` / `fill`，**新写禁止**用遗留值；人员/部门一律走 `browser`+ComInfo。
+
+### 1.2 双写示例（人员）
+
+```json
+{
+  "transType": "browser",
+  "browserType": [{ "id": "HrmEmployeeComInfo" }],
+  "isHtml": "0",
+  "qrcodeType": "no",
+  "prefixAndSuffix": ["", ""],
+  "hiddenContext": "0",
+  "textDirection": "FromLeftToRight"
+}
+```
+
+`fields[].browserType` / `transSelectOptions` / `prefixAndSuffix` 在 DB 侧常为 **JSON 字符串**；workbook `cellType` 侧为数组。
+
+---
+
+## 二、HTML转换 · `isHtml`
+
+| UI | 值 |
+|----|-----|
+| 否 | `"0"` |
+| 是 | `"1"` |
+
+为 `"1"` 时运行时按 HTML 处理/剥离（见 `AnalysisParams`）。**不是** `transType=html`。
+
+---
+
+## 三、前缀 / 后缀 · `prefixAndSuffix`
+
+```json
+"prefixAndSuffix": ["前缀文本", "后缀文本"]
+```
+
+默认 `["",""]`。重建 workbook 时禁止丢掉该键。
+
+---
+
+## 四、条码 · `qrcodeType`
+
+| UI | 值 |
+|----|-----|
+| 无 | `no` |
+| 条码 | `barcode` |
+| 二维码 | `qrcode` |
+
+二维码可选：`qrcodelink` = `"1"` / `"0"`（是否包含移动端地址）。**不是** `transType`。
+
+---
+
+## 五、隐藏内容 · `hiddenContext`
+
+| UI | 值 |
+|----|-----|
+| 否 | `"0"` |
+| 是 | `"1"` |
+
+键名是 **`hiddenContext`**（Context，不是 Content）。与「显示方式」`displayType` **无关**。
+
+---
+
+## 六、文字方向 · `textDirection`
+
+| UI | 值 |
+|----|-----|
+| 从左向右 | `FromLeftToRight`（默认） |
+| 从右向左 | `FromRightToLeft` |
+| 竖排 | `VerticalArrangement` |
+| 顺时针旋转 90° | `CW` |
+| 逆时针旋转 90° | `CCW` |
+
+---
+
+## 七、Agent / CLI
+
+```bash
+# 校验（不落库）
+e10-cli report validate transform --map "人员"
+e10-cli report validate transform --file cell-transform.json
+e10-cli report validate transform --list
+
+# 写入 + 回读（report cell transform 是等价别名）
+e10-cli report cell-transform show <reportId> --app-id <id> --cell 1,0
+e10-cli report cell-transform list <reportId> --app-id <id>
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 --map "人员"
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 \
+  --trans browser --browser HrmEmployeeComInfo --prefix "[" --suffix "]"
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 \
+  --html on --qrcode barcode --hidden off --direction 竖排
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 --file cell-transform.json
+e10-cli report cell-transform clear <reportId> --app-id <id> --cell 1,0
+```
+
+`--html` / `--hidden` 接受 `on|off`、`1|0`、`是|否`。只改点名的键，其余保持原值；
+显式切 `transType` 时会清掉不再适配的 `browserType` / `transSelectOptions`。保存后回读
+`fields[]` 逐键比对，不一致直接报错。
+
+定点改转换时：改 `fields[]` 对应键 → `safe_report_save` / `fieldToCell` 透传到 workbook → 回读核对。
+
+---
+
+## 八、禁令
+
+- 禁止 `transType=person|department|image|html|barcode|hidden`
+- 禁止人员/部门只写 `transType=hrm|dept`（遗留）
+- 禁止重建 workbook 时丢掉转换键
+- 禁止把「隐藏内容」当成「显示方式=不显示」
+
+---
+
+## 关联
+
+- `cell-config-echo-guide.md` — 数字格式 / 日期分组 / 字体
+- `report-designer-feature-map.md` — 右侧面板总览
+- `report-data-model.md` §八 — 已废弃错误表，以本文为准
+- `` — `fieldToCell` 透传

package/skill-docs/references/report/code-block-guide.md

@@ -0,0 +1,54 @@
+# 报表「代码块」（设计器 开始 → 代码块）
+
+> **UI**：报表设计器 → 开始 → 代码块（自定义 JS/HTML 片段，**按 sheet 存储**）
+> **CLI**：`e10-cli report code-block get|set|clear <reportId> --app-id <id> [--sheet-id <id>|--sheet-index <n>]`
+> **别名**：`report code block …` 与上面等价
+
+---
+
+## 一、接口与落库
+
+| 动作 | 方法 | 路径 | 参数 |
+|------|------|------|------|
+| 读 | GET | `/api/bs/edc/report/queryCustomCodeById` | `sheetId` |
+| 写 | POST | `/api/bs/edc/report/saveCustomCode` | form：`cusCode` + `sheetId` |
+
+- 请求头 `ebbusinessid` = 应用 ID（`report code-block` 的 `--app-id` 已带）。
+- `cusCode` = **代码文本的 UTF-8 base64**，等价前端：
+  ```js
+  btoa(unescape(encodeURIComponent(code)))
+  ```
+- `sheetId` 取 `getReportDevInfo.sheetProps[].sheetId`（**不是** `sheetProps[].id`）。
+- 保存接口回 200 不代表内容已落库：CLI 写完会回读比对，不一致直接报错。
+- 设计器新建代码块时的默认模板：
+  ```html
+  <script type="text/javascript">
+  /*
+  * 请在下面编写JS代码
+  */
+
+  </script>
+  ```
+
+## 二、命令
+
+```bash
+# 读（默认第一张 sheet）
+e10-cli report code-block get <reportId> --app-id <appId>
+e10-cli report code-block get <reportId> --app-id <appId> --sheet-index 1
+e10-cli report code-block get <reportId> --app-id <appId> --out code.js
+
+# 写（--code / --file / --template 三选一；含中文或换行建议用 --file）
+e10-cli report code-block set <reportId> --app-id <appId> --file code.js
+e10-cli report code-block set <reportId> --app-id <appId> --code '<script>console.log(1)</script>'
+e10-cli report code-block set <reportId> --app-id <appId> --template
+
+# 清空（保存空文本并回读确认；设计器再次打开会显示默认模板）
+e10-cli report code-block clear <reportId> --app-id <appId>
+```
+
+## 三、注意
+
+- 代码块按 sheet 独立：多 sheet 报表必须用 `--sheet-index` / `--sheet-id` 选对页。
+- 代码在预览/运行页执行，写入前确认脚本来源与用途；CLI 不做 JS 语义校验。
+- 不要把代码块和「单元格事件 → 执行 js 代码」（`cell-event`）混淆：前者按 sheet 一段，后者挂在单个单元格上。

package/skill-docs/references/report/column-split-report-guide.md

@@ -1,96 +1,96 @@
-# 分栏报表四案例 · 场景 J（SKILL A0.19）
-
-> 案例一「行分栏」：各分公司员工劳动关系详表——纵向扩展明细横向分 2 栏，标题行复制。
-> 案例二「列分栏」：股票行情——横向扩展记录纵向分块（1-8 / 9-16 / 17-24），表头列复制。
-> 案例三「卡片分栏」：条码卡 3 栏平铺（卡片版式 + 条码格）。
-> 案例四「行分栏汇总统计」：多级行维度（集团→公司→厂）+ 合计行 + 红色百分比预警 + 横向分栏。
-
----
-
-## 一、核心结论：分栏是渲染级配置，不是多带构造
-
-分栏入口 = 设计器「**页面 → 报表展示 → 分栏**」（help-guide §8.5：按行/列数分栏 / 按栏数分栏；
-模式：垂直 / 水平 / 卡片；复制标题或表头）。**设计 workbook 保持单数据带**，引擎按配置复制标题
-并重排实例 —— 与预聚合 / 分页同属 sheetConfig 级开关（knowledge-base §4.7）。
-
-**落库通道（已固化）**：
-- `build spec`：`layout.sheetConfig: { ... }` → 并入 `sheet.tag.sheetConfig`（A0.19 起，与 dataPreAgg 同通道）
-- `card spec`：`spec.sheetConfig` 原本就透传
-
-⚠️ **分栏 sheetConfig 具体键名待确认**（类比 dataPreAgg 当年也是验证出来的）。
-**验证捕获法**：设计器建一张分栏报表 → `getReportDevInfo` → 看 `sheetProps[0].sheetConfig`
-（JSON 字符串）里的分栏键 → 回填本指南后即可在 spec 里写死。
-示例占位（**未验证**，仅示意形状）：`{"splitConfig":{"mode":"row","count":20}}`。
-
-## 二、四案例解析
-
-### J-1 行分栏（案例一 · 纵向扩展数据横向分栏）
-
-| 特性 | 设计 |
-|---|---|
-| 左维度「分公司名称」纵跨整栏 | 分公司 Field `Vertical+Group`、isActiveParent；明细左父格链到它 |
-| 明细带（序号/姓名/劳动关系/学历） | 序号=`cellType:"seq"`；其余普通 Field 左父格链式 |
-| 每栏复制标题行 | 分栏配置「复制标题行」= 表头 Const 行（引擎自动复制） |
-| 分栏触发 | 按行数（每 N 行一栏）或按栏数 |
-
-spec 骨架：普通分组明细表 `build spec` + `layout.sheetConfig`（分栏键）。
-
-### J-2 列分栏（案例二 · 横向扩展数据纵向分块）
-
-| 特性 | 设计 |
-|---|---|
-| 字段为行标签（日期/成交量/…） | 字段名列 = 各 Field 竖排（不扩展），左父格链 |
-| 记录横向扩展（序号 1-8） | 序号/日期行 = `Horizontal` 扩展格（日期 Group 或记录序），isActiveParent |
-| 分块（1-8 / 9-16 / …） | 分栏配置「按列数」+「复制表头列」（序号+标签列） |
-| 顶层标题合并 | 「某公司2~4月份股票行情」Const 跨全宽 |
-
-直构坐标模板（rebuild 路径）：标签列 A（6 个 Field 竖排），B 列横向扩展锚点；分栏键在 sheetConfig。
-
-### J-3 卡片分栏（案例三 · 卡片版式 3 栏平铺 + 条码）
-
-| 特性 | 设计 |
-|---|---|
-| 一条记录=一张卡片（姓名/编号ID/职务/出生日期/地址/邮编/联系方式） | **`card build` 通道**（cells 网格 label/value，同段落机制） |
-| 3 栏平铺、行间复制 | 分栏模式=**卡片**（栏数 N + 复制单元=整体扩展单元首尾单元格，knowledge-base §4.7-5） |
-| 编号ID 条码 | ✅ A0.19 起 card spec 单元格支持 **`qrcode`/`qrlink`** 透传（`qrcodeType/qrcodelink`）；**条码枚举值待验证**（设计器 条码下拉：无/条码/二维码，具体字符串回填） |
-| 姓名+条码图片位 | 姓名 Field；图片格=字段转换（图片 transType，见 cell-transform-guide）或 Const 占位 |
-
-### J-4 行分栏汇总统计（案例四 · 多级行维度 + 合计 + 预警 + 分栏）
-
-| 特性 | 设计 |
-|---|---|
-| 三级行维度（集团→公司→厂） | 场景 H 多级行维度：子级左父格→上级格（rebuild 直构） |
-| 各级「合计」行 | Formula 左父格=该级维度格（crosstab §4.2 ★禁默认链） |
-| 值列组（全年计划/10月/累计/完成年计划比…） | 普通 Field + 完成率 Formula；红色百分比=conditionRule（超标红字） |
-| 横向分栏 | 同 J-1 分栏配置；多级左维度树整棵随栏复制（引擎行为，已验证） |
-
-## 三、搭建提示语句
-
-**J-1 行分栏**：
-> 按行分栏格式搭一张员工劳动关系详表：列「分公司名称/序号/员工姓名/劳动关系/学历」，
-> 分公司 Field 纵向分组扩展、明细跟随，序号用系统序号；数据源 `<sid>`（appId `<appId>`）；
-> 横向分栏每栏 N 行、复制标题行；用 `build spec` 落库 + `layout.sheetConfig` 写分栏配置
-> （键名以设计器确认回填为准），落库后回读验收父格链。
-
-**J-2 列分栏**：
-> 按列分栏格式搭一张股票行情表：左侧标签列（日期/成交量/开盘/盘高/盘低/收盘）竖排，
-> 记录横向扩展（序号行）；纵向分块每块 N 列、复制表头列；数据源 `<sid>`（appId `<appId>`）；
-> 走 rebuild 直构（横向扩展 + 分栏 sheetConfig），回读验收扩展格与分栏配置。
-
-**J-3 卡片分栏条码**：
-> 按卡片分栏格式搭一张员工条码卡：卡片内 姓名+条码（编号ID 字段，qrcode 透传）+
-> 职务/出生日期/地址/邮编/联系方式 label-value 网格；数据源 `<sid>`（appId `<appId>`）；
-> 用 `card build` 出版式，`spec.sheetConfig` 写卡片分栏（栏数 3，复制单元首尾）；
-> 条码枚举值与分栏键名以设计器确认回填为准，回读验收 qrcodeType 与锚点。
-
-**J-4 行分栏汇总统计**：
-> 按行分栏汇总格式搭一张生产产量完成情况表：行维度三级「集团→公司→厂」逐级缩进、
-> 各级合计行、值列组（计划/实际/完成比），完成率超 100% 红字；
-> 数据源 `<sid>`（appId `<appId>`）；rebuild 直构（多级行维度+合计行）+
-> `layout.sheetConfig` 横向分栏；回读验收合计行左父格与条件色。
-
-## 四、能力边界（如实）
-
-1. 分栏 sheetConfig 键名、条码 qrcodeType 枚举字符串 = **待确认**（通道已通，值待回填）。
-2. 分栏后跨栏的父格/合并表现（尤其多级行维度整棵复制）= 引擎渲染行为，设计器已验证。
-3. J-2/J-4 的多级结构超出 build spec 表达力 → rebuild 直构；J-1/J-3 单源可走 build spec / card build。
+# 分栏报表四案例 · 场景 J（SKILL A0.19）
+
+> 案例一「行分栏」：各分公司员工劳动关系详表——纵向扩展明细横向分 2 栏，标题行复制。
+> 案例二「列分栏」：股票行情——横向扩展记录纵向分块（1-8 / 9-16 / 17-24），表头列复制。
+> 案例三「卡片分栏」：条码卡 3 栏平铺（卡片版式 + 条码格）。
+> 案例四「行分栏汇总统计」：多级行维度（集团→公司→厂）+ 合计行 + 红色百分比预警 + 横向分栏。
+
+---
+
+## 一、核心结论：分栏是渲染级配置，不是多带构造
+
+分栏入口 = 设计器「**页面 → 报表展示 → 分栏**」（help-guide §8.5：按行/列数分栏 / 按栏数分栏；
+模式：垂直 / 水平 / 卡片；复制标题或表头）。**设计 workbook 保持单数据带**，引擎按配置复制标题
+并重排实例 —— 与预聚合 / 分页同属 sheetConfig 级开关（knowledge-base §4.7）。
+
+**落库通道（已固化）**：
+- `build spec`：`layout.sheetConfig: { ... }` → 并入 `sheet.tag.sheetConfig`（A0.19 起，与 dataPreAgg 同通道）
+- `card spec`：`spec.sheetConfig` 原本就透传
+
+⚠️ **分栏 sheetConfig 具体键名待确认**（类比 dataPreAgg 当年也是验证出来的）。
+**验证捕获法**：设计器建一张分栏报表 → `getReportDevInfo` → 看 `sheetProps[0].sheetConfig`
+（JSON 字符串）里的分栏键 → 回填本指南后即可在 spec 里写死。
+示例占位（**未验证**，仅示意形状）：`{"splitConfig":{"mode":"row","count":20}}`。
+
+## 二、四案例解析
+
+### J-1 行分栏（案例一 · 纵向扩展数据横向分栏）
+
+| 特性 | 设计 |
+|---|---|
+| 左维度「分公司名称」纵跨整栏 | 分公司 Field `Vertical+Group`、isActiveParent；明细左父格链到它 |
+| 明细带（序号/姓名/劳动关系/学历） | 序号=`cellType:"seq"`；其余普通 Field 左父格链式 |
+| 每栏复制标题行 | 分栏配置「复制标题行」= 表头 Const 行（引擎自动复制） |
+| 分栏触发 | 按行数（每 N 行一栏）或按栏数 |
+
+spec 骨架：普通分组明细表 `build spec` + `layout.sheetConfig`（分栏键）。
+
+### J-2 列分栏（案例二 · 横向扩展数据纵向分块）
+
+| 特性 | 设计 |
+|---|---|
+| 字段为行标签（日期/成交量/…） | 字段名列 = 各 Field 竖排（不扩展），左父格链 |
+| 记录横向扩展（序号 1-8） | 序号/日期行 = `Horizontal` 扩展格（日期 Group 或记录序），isActiveParent |
+| 分块（1-8 / 9-16 / …） | 分栏配置「按列数」+「复制表头列」（序号+标签列） |
+| 顶层标题合并 | 「某公司2~4月份股票行情」Const 跨全宽 |
+
+直构坐标模板（rebuild 路径）：标签列 A（6 个 Field 竖排），B 列横向扩展锚点；分栏键在 sheetConfig。
+
+### J-3 卡片分栏（案例三 · 卡片版式 3 栏平铺 + 条码）
+
+| 特性 | 设计 |
+|---|---|
+| 一条记录=一张卡片（姓名/编号ID/职务/出生日期/地址/邮编/联系方式） | **`card build` 通道**（cells 网格 label/value，同段落机制） |
+| 3 栏平铺、行间复制 | 分栏模式=**卡片**（栏数 N + 复制单元=整体扩展单元首尾单元格，knowledge-base §4.7-5） |
+| 编号ID 条码 | ✅ A0.19 起 card spec 单元格支持 **`qrcode`/`qrlink`** 透传（`qrcodeType/qrcodelink`）；**条码枚举值待验证**（设计器 条码下拉：无/条码/二维码，具体字符串回填） |
+| 姓名+条码图片位 | 姓名 Field；图片格=字段转换（图片 transType，见 cell-transform-guide）或 Const 占位 |
+
+### J-4 行分栏汇总统计（案例四 · 多级行维度 + 合计 + 预警 + 分栏）
+
+| 特性 | 设计 |
+|---|---|
+| 三级行维度（集团→公司→厂） | 场景 H 多级行维度：子级左父格→上级格（rebuild 直构） |
+| 各级「合计」行 | Formula 左父格=该级维度格（crosstab §4.2 ★禁默认链） |
+| 值列组（全年计划/10月/累计/完成年计划比…） | 普通 Field + 完成率 Formula；红色百分比=conditionRule（超标红字） |
+| 横向分栏 | 同 J-1 分栏配置；多级左维度树整棵随栏复制（引擎行为，已验证） |
+
+## 三、搭建提示语句
+
+**J-1 行分栏**：
+> 按行分栏格式搭一张员工劳动关系详表：列「分公司名称/序号/员工姓名/劳动关系/学历」，
+> 分公司 Field 纵向分组扩展、明细跟随，序号用系统序号；数据源 `<sid>`（appId `<appId>`）；
+> 横向分栏每栏 N 行、复制标题行；用 `build spec` 落库 + `layout.sheetConfig` 写分栏配置
+> （键名以设计器确认回填为准），落库后回读验收父格链。
+
+**J-2 列分栏**：
+> 按列分栏格式搭一张股票行情表：左侧标签列（日期/成交量/开盘/盘高/盘低/收盘）竖排，
+> 记录横向扩展（序号行）；纵向分块每块 N 列、复制表头列；数据源 `<sid>`（appId `<appId>`）；
+> 走 rebuild 直构（横向扩展 + 分栏 sheetConfig），回读验收扩展格与分栏配置。
+
+**J-3 卡片分栏条码**：
+> 按卡片分栏格式搭一张员工条码卡：卡片内 姓名+条码（编号ID 字段，qrcode 透传）+
+> 职务/出生日期/地址/邮编/联系方式 label-value 网格；数据源 `<sid>`（appId `<appId>`）；
+> 用 `card build` 出版式，`spec.sheetConfig` 写卡片分栏（栏数 3，复制单元首尾）；
+> 条码枚举值与分栏键名以设计器确认回填为准，回读验收 qrcodeType 与锚点。
+
+**J-4 行分栏汇总统计**：
+> 按行分栏汇总格式搭一张生产产量完成情况表：行维度三级「集团→公司→厂」逐级缩进、
+> 各级合计行、值列组（计划/实际/完成比），完成率超 100% 红字；
+> 数据源 `<sid>`（appId `<appId>`）；rebuild 直构（多级行维度+合计行）+
+> `layout.sheetConfig` 横向分栏；回读验收合计行左父格与条件色。
+
+## 四、能力边界（如实）
+
+1. 分栏 sheetConfig 键名、条码 qrcodeType 枚举字符串 = **待确认**（通道已通，值待回填）。
+2. 分栏后跨栏的父格/合并表现（尤其多级行维度整棵复制）= 引擎渲染行为，设计器已验证。
+3. J-2/J-4 的多级结构超出 build spec 表达力 → rebuild 直构；J-1/J-3 单源可走 build spec / card build。