weaver-e10-builder 1.6.10 → 1.6.11

package/skill-docs/references/report/branch-scene-guide.md

@@ -0,0 +1,293 @@
+# 分支场景规则 —— 同 sheet 多报表 / 自增序号 / 单元格跳转 Sheet（SKILL A0.13）
+
+> **优先级**：本节规则**优先级高于原有报表规则**，但**仅在识别命中时启用**。
+> **不满足识别条件的普通报表需求 → 完全沿用原有全部报表逻辑**，不执行任何特殊配置。
+>
+> **CLI**：`e10-cli report scene rules | detect | check | apply`
+> **脚本**：`e10-cli report scene` · 规则常量 `SCENE_RULES`（与 SKILL A0.13 同源）
+> **声明式**：`build spec` 的 spec 支持 `columns[].cellType:"seq"｜"jump"`、
+> `scene.publicParent + scene.anchorCells`、`scene.jumpCells`
+
+---
+
+## 一、识别纪律（**不依赖关键词**）
+
+> ⚠ **禁止**用「多报表」「序号」「自增」这类**业务关键词**去猜场景 —— 那正是本规则要避免的做法。
+> 判定**只看内容结构**：`e10-cli report scene detect --req <需求文件>`。
+
+支持的输入：`.json`（spec / `cells[]` / `blocks[]`）、`.md` / `.txt` / `.csv`（文本网格）。
+`.xlsx` 需先另存为 `.csv` / `.md`（本工具不直接解析二进制表格）。
+
+「数据源字段单元格」的结构特征（任一命中即为字段单元格）：
+
+| 形态 | 示例 |
+|------|------|
+| 三段式 `fieldKey` | `1324295304156717057.1162255789527552000.sort` |
+| 结构化键值 | `字段：学院号` / `fieldKey: …` |
+| 表格「字段」列 | 表头含 `字段` / `字段名` / `field` 列，该列有值 |
+
+**分组规则**：连续的字段行归为一个**数据区**；空行 / 标题行 / 段落行 = **硬边界**（分隔符行 `|---|` 不断组）。
+
+```jsonc
+// 输出（--json）
+{
+  "scenes": ["A", "C"],                 // 命中场景（可同时 A+B / A+C / B+C / A+B+C）
+  "scene": "A+C",
+  "evidence": {
+    "dataAreas": 2,                     // ★ 场景 A 判据：数据区数量
+    "fieldRows": [7, 8, 9, 15, 16],
+    "seqMarked": ["【自增序号单元格】"],   // ★ 场景 B 判据：标注
+    "jumpMarked": ["sheet2: 点击跳转sheet2"], // ★ 场景 C 判据：动作描述
+    "criteria": { "A": ["…"], "B": [], "C": ["识别到「点击跳转 sheetN」描述 1 处"] }
+  },
+  "action": "enable_scene_rules",       // 未命中时 = "keep_default_rules"
+  "rules": { "A": { "mandatory": ["…"] } }
+}
+```
+
+**退出码**：detect 恒 0（识别结果本身不是错误）；`check` 不合规 = **3**。
+
+### 1.1 识别边界说明（防过度触发 · 必须遵守）
+
+| # | 边界 | 说明 |
+|---|------|------|
+| ① | **多报表只认「多组独立数据源字段」** | 仅当**同一个 sheet 内出现多组独立数据源字段（多行数据源）**才判定为多报表场景；**单报表单数据源 sheet，不新增公共父格**。 |
+| ② | **公共父格只做归集，不改内部** | 公共父格**只**用于当前 sheet 内多个报表的**父格归集**，**不修改单报表内部原有单元格的左父格关系**。 |
+| ③ | **`{seq}` 只认显式标注** | 只有需求里**明确标注**「自增序号单元格」才启用 `{seq}`；**普通序号 / 手工编号不触发**此规则。 |
+| ④ | **跳转只认「点击跳转」描述** | 跳转 Sheet **仅当**需求描述包含「点击跳转sheetX / 点击可跳转到sheetX」这类描述才触发跳转事件；URL 参数严格遵循 `sheetIndex` **从 0 开始计数**。 |
+
+---
+
+## 二、场景 A · 同 sheet 多报表（公共父格）
+
+### 2.1 识别条件
+
+**同一个 sheet 页存在多行数据源字段单元格** → 判定为「同页面上下放置多个独立报表」。
+
+### 2.2 强制配置（命中后必做）
+
+> **细化指南**：`expansion-block-parent-config-guide.md`（三类单元格口径 / 泛化禁令 / 合计·总计行 / 扩展带公式格）。
+> 凡同 sheet 存在「**主区 + 多个独立扩展块（统计块）**」时，按**三类单元格口径**处理：
+
+| 类 | 单元格 | 配置 |
+|---|--------|------|
+| ① **公共父格** | Sheet **左上角** `Const`（自定义文本，如「统计区」） | `left=(-1,-1)` + **`isActiveParent=true`** |
+| ② **入口格 + 标题/表头行整行 Const** | 每带**入口格**（数据带第一格、合计带第一格 = 纵向扩展根）；每块**标题行 / 表头行整行 Const** | 左父格**统一绑定**公共父格 |
+| ③ **数据格** | 入口格**右侧**的普通 Field 格 | **保持默认链**（同行前一列），**不动** |
+
+> ⚠ **泛化禁令**：**不得**把公共父格配置**泛化**到「入口格以右的数据格」—— 数据跟随入口格扩展，
+> **父格链**与**公共父格**是**两层机制**。
+
+**合计行 / 总计行**：**合计行（按维度合计，如按学年/按部门）** 该行**整行所有格**（标签 + Field + Formula）左父格**统一 = 维度字段所在格**；
+**总计行**保持**独立链**（挂自己行标签），公式**引用合计行**，不跟随维度扩展。
+
+### 2.3 配置形态
+
+```jsonc
+// 公共父格（落库形态）
+{ "x": 0, "y": 0, "cellType": "Const", "cellText": "报表区",
+  "leftX": -1, "leftY": -1, "expandType": "NoExpand",
+  "isActiveParent": true, "displayType": "Group" }
+
+// 各独立报表的行维入口格（=「扩展父格」）
+{ "x": 1, "y": 1, "cellType": "Field", "name": "zxmc", "text": "中心名称",
+  "expandType": "Vertical", "leftX": 0, "leftY": 0 }   // ← 绑到公共父格
+```
+
+> 公共父格若**已占用**该坐标 → **复用**它并置 `isActiveParent=true`（不新建）。
+
+### 2.4 判据纪律（★ 防交叉表误报）
+
+**一个交叉表**的「列维表头」是 `Horizontal` 扩展、「行维入口」是 `Vertical` 扩展 ——
+二者同属**同一个矩阵**，**不是**两个独立报表。
+
+| 判据 | 规则 |
+|------|------|
+| 只认**纵向入口** | `Vertical` 且「是根（`left=-1,-1`）**或**已绑公共父格」（`entryLikeCells()`）—— 幂等：绑过公共父格的入口格重复 check 不漏判 |
+| 且必须**分布在不同行** | 行号去重后 ≥2（`looksMultiReport()`）→ 才是「上下多个独立报表」 |
+| 纵向入口 ≤1 或全在同一行 | **不适用**场景 A，检查直接 PASS |
+
+**反例（会误报的情形）**：chl测试1010 这类行列交叉表 —— 列头 `(0,3) 年级` 是 `Horizontal`、
+行头 `(1,1) 学院名称` 是 `Vertical`，粗按「扩展根≥2」会误判成多报表。**按上述判据即正确排除。**
+
+### 2.5 正例 / 反例
+
+```text
+✅ 正例：上下两个独立报表
+   A1「中心名称」  Vertical  left=(-1,-1)  ┐
+   A5「专业名称」  Vertical  left=(-1,-1)  ┘ 两个纵向根、行号不同 → 场景 A
+   → 修法：(0,0) 建公共父格，A1/A5 的 leftX/leftY 都改成 0,0
+
+❌ 反例：单块交叉表（不适用场景 A）
+   D1「年级」      Horizontal left=(-1,-1)
+   B2「学院名称」  Vertical   left=(-1,-1)
+   → 只有 1 个纵向根 → 场景 A **不适用**，勿加公共父格
+```
+
+---
+
+## 三、场景 B · 自增序号（系统 `{seq}`）
+
+### 3.1 识别条件
+
+需求文件单元格标注 **【自增序号单元格】**（也接受 `[自增序号单元格]`）。
+
+> ⚠ 边界③：**普通序号 / 手工编号不触发**本规则。
+
+### 3.2 强制配置
+
+| # | 配置 | 说明 |
+|---|------|------|
+| ① | 统一使用系统标准序号字段 **`{seq}`** | `cellType='SequenceNumber'`，`cellText='{seq}'` |
+| ② | **纵向扩展** | `expandType='Vertical'` |
+| ③ | **禁止**用自定义公式生成序号 | 不得写 `=ROW()-2` / `=SUBTOTAL(...)` 之类 |
+
+### 3.3 配置形态
+
+```jsonc
+{ "cellType": "SequenceNumber", "typeName": "SequenceNumberCellType",
+  "cellText": "{seq}", "expandType": "Vertical", "displayType": "Group",
+  "leftX": 1, "leftY": 1 }        // 左父格 = 所在块的入口格，随块纵向扩展
+```
+
+> **反例**：`{"cellType":"Formula","cellText":"ROW()-2"}` —— 导出/分页后错位、跨块串号，**禁止**。
+
+---
+
+## 四、场景 C · 单元格跳转 Sheet 页
+
+### 4.1 识别条件
+
+需求描述包含「**点击跳转sheetX** / **点击可跳转到sheetX**」这类描述
+（正则 `/(?:点击|单击|点按)\s*(?:可|即|能)?\s*跳转\s*(?:到|至)?\s*sheet\s*(?:页)?\s*([0-9]+)/i`）。
+
+> ⚠ 边界④：**仅**这类「点击跳转」描述才触发；`sheetIndex` **严格从 0 开始计数**。
+
+### 4.2 强制配置（命中后必做）
+
+| # | 配置 | 说明 |
+|---|------|------|
+| ① | 在**当前单元格**添加**点击跳转事件** | 落 `pcHreflink`（PC 端）；移动端另配 `h5Hreflink`（别名 `mbhreflink`） |
+| ② | 基础地址取**当前报表预览页 URL** | `/sp/edc/report/view/<reportId>` |
+| ③ | URL 参数 **`sheetIndex=<N-1>`** | sheet1→`0`，sheet2→`1`，sheetN→`N-1`（**严格从 0 起**） |
+| ④ | **打开方式**默认「**弹出页**」 | `openType="blank"`（与设计器右侧配置一致） |
+
+### 4.3 链接形态
+
+```text
+报表预览页：/sp/edc/report/view/1325388137101516800
+转到 sheet2 的完整链接：/sp/edc/report/view/1325388137101516800?sheetIndex=1
+```
+
+```jsonc
+// 落库形态（fields[] + workbook style.cellType）
+{ "x": 2, "y": 1, "cellType": "Const", "cellText": "查看明细",
+  "pcHreflink": "/sp/edc/report/view/1325388137101516800?sheetIndex=1",
+  "h5Hreflink": "", "openType": "blank" }
+```
+
+> **映射表（sheet 序号 → sheetIndex）**：`sheet1→0` · `sheet2→1` · `sheet3→2` … `sheetN→N-1`。
+> 链接字符 `?` / `&` 必须是 **ASCII**（禁用全角 `？`），见 `event-hreflink-guide.md` §二。
+
+### 4.4 反例 / 常见错
+
+| 错法 | 后果 |
+|------|------|
+| `sheet2 → sheetIndex=2`（off-by-one） | 跳到 sheet3，或越界无效 |
+| 基础地址非 `/sp/edc/report/view/…` | 跳到无关页面 |
+| `openType="popup"` / `"window"` | 非法值，平台不认（只认 `blank`/`self`/`jsscript`） |
+| 链接用了全角 `？` / `&` | 预览点击**无反应** |
+
+---
+
+## 五、CLI
+
+```bash
+# 识别（恒 exit 0）
+e10-cli report scene rules
+e10-cli report scene detect --req <需求文件> [--json]
+
+# 体检（只读；exit 3 = 不合规）
+e10-cli report scene check --report-id <rid> --app-id <appId> [--scene A|B|C] \
+  [--seq-cells "x,y;x,y"] [--jump-cells "x,y=N"] [--open-type blank] [--json]
+# 离线定位：--dev-file <getReportDevInfo 的 data JSON>
+
+# 定点修复（默认 dry-run，打印逐格差集；--apply 才落库）
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene A \
+  [--at 0,0] [--text "报表区"] [--anchor "1,1;5,1"] [--apply]
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene B \
+  --seq-cells "1,0" [--apply]
+e10-cli report scene apply --report-id <rid> --app-id <appId> --scene C \
+  --jump-cells "2,1=2" [--base /sp/edc/report/view/<rid>] [--open-type blank] [--apply]
+```
+
+**落库通道保障**：`scene apply` 一律走 `buildWorkbookFromFields`（**A0.8 定点补丁**，禁止整表重建）
++ `saveReportDevInfoAuto`（**BUILD-39** 载荷自适应）+ `assertNoStaleDatasetIds`（**BUILD-42** 数据集 id 硬门禁），
+`--apply` 后**自动回读校验**（场景 A：公共父格 `isActiveParent` + 锚点是否都绑上；场景 B：序号格 `SequenceNumber`+`Vertical`；
+场景 C：跳转格 `pcHreflink` 含 `/sp/edc/report/view/` 且 `sheetIndex` = N-1、`openType` 正确）。
+校验不过 → exit 2 且提示复查。
+
+`--jump-cells` 语法：`"x,y=N"`，多个用 `;` 分隔（如 `"2,1=2;5,1=3"`）；**N = 目标 sheet 序号，从 1 起**。
+
+---
+
+## 六、声明式（`build spec` 的 spec 字段）
+
+```jsonc
+{
+  "appId": "…", "name": "预算执行(多报表同页)", "form": "…",
+  "columns": [
+    { "title": "序号", "cellType": "seq" },                      // ★ 场景 B：系统序号 {seq}
+    { "title": "查看明细", "cellType": "jump", "jumpSheet": 2 },  // ★ 场景 C：跳转 sheet2
+    { "title": "中心名称", "field": "中心名称" }
+  ],
+  "scene": {                                                      // ★ 场景 A + C
+    "publicParent": { "x": 0, "y": 0, "text": "报表区" },
+    "anchorCells": ["1,1", "5,1"],                                // 各独立报表的扩展父格坐标
+    "jumpCells": [ { "cell": "2,1", "sheet": 2 }, "5,1=3" ],      // 落库期给指定格写跳转链接
+    "base": "/sp/edc/report/view/<rid>",                          // 可选；缺省用搭建期 reportId 自动拼
+    "openType": "blank"                                           // 可选；默认「弹出页」
+  }
+}
+```
+
+- `columns[].cellType:"seq"` → 生成 `SequenceNumber` **纵向**格；该列**不参与字段绑定匹配**（不会因无字段而 exit 4）。
+- `columns[].cellType:"jump" + jumpSheet:N` → 生成 Const 文本 + 跳转链接；同样**不参与字段绑定匹配**。
+- `scene.publicParent` → 落库前在指定坐标插入（或复用）公共父格并置 `isActiveParent`；
+  `scene.anchorCells` 列出的入口格左父格统一改到该坐标；**未列出的格一律不动**。
+- `scene.jumpCells` → 落库前给每个 `{cell,sheet}`（或 `"x,y=N"`）写 `pcHreflink = <base>?sheetIndex=<N-1>` + `openType`。
+- 不写 `scene` 段（或只写空对象）→ **完全不介入**（`applySceneDecl` 返回 null），原单块路径零影响。
+
+> **多块内容**：`build spec` 当前为**单块模型**。多块（上下多个报表）内容可分别构建 /
+> 在其上继续铺块后，统一用 `scene apply --scene A` 做「建公共父格 + 重绑入口格」这一步。
+
+---
+
+## 七、自检清单（交付前必过）
+
+- [ ] 是否先跑了 `scene detect`？**不命中就不加任何特殊配置**（不要「顺手也加上」）。
+- [ ] 场景 A 的公共父格是否在 **Sheet 左上角**、`isActiveParent=true`、有自定义文本？
+- [ ] 场景 A 是否**只**改了「各独立报表的扩展父格」的左父格，其余格父格**未动**？（边界②）
+- [ ] 是否确认这些纵向根**分布在不同行**（而非交叉表的列维/行维）？单报表单数据源**未**加公共父格？（边界①）
+- [ ] 场景 B 的序号格是否 `SequenceNumber` + `Vertical` + `{seq}`，且**没有**残留公式？**普通序号未被误改**？（边界③）
+- [ ] 场景 C 的跳转链接基础地址是否 `/sp/edc/report/view/<reportId>`、`sheetIndex` = **N-1（从 0 起）**、`openType=blank`？（边界④）
+- [ ] 跳转链接是否用了 **ASCII** `?` / `&`（非全角）？
+- [ ] `scene check` 是否 **PASS**（exit 0）？`check-ids` 是否同步合规（BUILD-42）？
+
+---
+
+## 八、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `SKILL.md` A0.13 / 执行优先级 0.46 | 硬规则正文 |
+| `expansion-block-parent-config-guide.md` | ★ 场景 A **细化**：三类单元格口径 / 泛化禁令 / 合计·总计行 / 扩展带公式格（BUILD-46/47/48） |
+| `pitfalls BUILD-43` | 多报表未绑公共父格（各块扩展互串） |
+| `pitfalls BUILD-44` | 序号用自定义公式生成（导出/分页错位） |
+| `pitfalls BUILD-45` | 跳转 Sheet 的 `sheetIndex` 错位 / 基础地址非预览页 / 打开方式非法 |
+| `pitfalls BUILD-48` | 公共父格泛化到数据格 / 合计行·总计行父格错配 |
+| `event-hreflink-guide.md` | 超链接落库键 `pcHreflink`/`h5Hreflink`/`openType`、ASCII `?`/`&`、父格链传参 |
+| `datasource-selection-and-parent-filter-guide.md` §2.0 | 既有父格链铁律（A0.7），本规则**不替代**它 |
+| `formula-cell-api-guide.md` | Formula 格 API（场景 B 明令**不用**公式生号） |
+| `report-requirement-analysis-template.md` §〇 | 需求分析阶段的场景识别章节 |
+| `crosstab-raw-workbook-guide.md` §六 | 数据集 id 隔离（BUILD-42） |

package/skill-docs/references/report/build-resilience-guide.md

@@ -0,0 +1,99 @@
+# Agent 执行韧性（空壳清理 · 失败不卡死）（强制）
+
+> **适用**：API/脚本搭建或改报表全程。
+> **目标**：失败不留垃圾空壳；单点报错不拖死整单，先交可用结果、再提示用户、最后可后台补救。
+
+---
+
+## 一、失败 / 终止必须清理空壳报表（强制）
+
+### 1.1 什么叫「空壳 / 无用报表」
+
+满足**任一**即视为应删的空壳：
+
+| 情形 | 说明 |
+|------|------|
+| 仅 `baseInfo` 建壳，**从未**成功 `saveReportDevInfo`（无 Field / 设计区空） | 临时名 `__build_*` / `__probe_*` / `__bench_*` |
+| 布局保存失败 / 脚本异常退出 / 用户中止，留下未改目标名或不可用壳 | 列表里出现但点开空白或全 Const |
+| 探测用临时报表（找表、压测） | 用完即删，禁止留在应用报表列表 |
+
+**不要删**：已成功落库且已向用户交付设计器地址的正式报表（如「测试BBB报表-chl」「议题A」）。
+
+### 1.2 何时必须删除
+
+- 命令 / 脚本 **抛错退出**
+- Agent **中止**当前建表任务（含用户叫停）
+- 同一任务内 **重建**前：旧失败 `reportId` 先 `deleteReport`
+- `finally` / 收尾逻辑：扫描本会话创建的临时壳并清理
+
+```
+POST/GET /api/bs/edc/report/deleteReport?id={reportId}
+（或 multipart ids=；进回收站即可，见 report-lifecycle-api-guide.md §删除）
+```
+
+Header 须带 `ebBusinessId`=appId。可批量：`id=id1,id2`。
+
+### 1.3 实现纪律
+
+1. 建壳成功后立刻记下 `reportId`（变量 / 日志）；**禁止**只记名字。
+2. 成功改名并交付前，临时名壳仍算「进行中」；**失败路径必须 delete**。
+3. 向用户说明：「已删除失败产生的空报表 xxx」，避免列表残留。
+4. 禁止留下多个 `__build_*` 占列表。
+
+---
+
+## 二、单点失败不卡死（强制 · 失败前进）
+
+### 2.1 步骤分级
+
+| 级别 | 步骤例 | 失败策略 |
+|------|--------|----------|
+| **阻断** | 登录、找 app/表（预算内）、建壳、绑数据集、**布局 saveReportDevInfo** | 修 1 次或删壳重建 1 次；仍失败 → **提示用户**并停止交付假链接；清理空壳 |
+| **可降级** | `saveQueryItem`、`saveQueryConfig`、数据集筛选、权限、快照；**用户点名的** verify/HTML | **最多重试 1 次** → **提示用户** → **结束**（禁无限轮） |
+
+### 2.2 禁止卡死
+
+- 同一 API / 同一报错 **连续尝试 > 2 次**（含重试）仍失败 → **必须停手**，向用户说明原因与需确认项。
+- **禁止**为 `saveQueryItem` 500 等可降级项循环试参、开浏览器接口返回、阻塞不交布局链接。
+- **禁止**在「获取查询条件失败」上耗尽会话；布局已成功则**先交付设计器地址**。
+
+### 2.3 对用户提示模板（可降级失败）
+
+```markdown
+⚠️ **查询条件未写入**（`saveQueryItem` 返回 …）
+- 报表主体已保存，可先打开设计器查看布局。
+- 请确认：是否仍需高级搜索条件「议题名称 / 申请人 / …」？
+- 也可在设计器：页面 → 查询设置 → 手动添加。
+- 我将在收尾再自动重试一次；若仍失败以你确认为准。
+```
+
+同类可替换：数据集筛选、权限、字段绑定抽检等。
+
+### 2.4 推荐执行序（建表）
+
+```
+找表 → 建壳 → 布局落库 → 【立刻可交设计器地址】
+  → 查询条件（失败则提示+跳过）
+  → 其它可降级项（失败则提示+跳过）
+  → 收尾：对失败的可降级项自动补救 1 次
+  → 汇总：成功项 / 需用户确认项
+  → finally：删除本任务产生的空壳
+```
+
+### 2.5 与交付合同
+
+- 布局成功 → 遵守 `report-delivery-contract.md` §〇 **先交地址**。
+- 可降级失败 → **不阻塞**首轮链接；在回复中列出「未完成项 + 请用户确认」。
+- 阻断失败 → 不交假链接 + **删空壳** + 说明卡点。
+
+---
+
+## 三、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `api-report-build-fast-path.md` | 建表主流程；引用本节清理与失败前进 |
+| `query-condition-api-guide.md` §二点五 | 查询 500 形态；失败后按本节降级 |
+| `report-delivery-contract.md` | 先交地址 |
+| `report-lifecycle-api-guide.md` | deleteReport |
+| `app-datasource-lookup-guide.md` §六 | 找表预算用尽则询问，不盲扫 |

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

@@ -0,0 +1,110 @@
+# 卡片式报表 · 直构指南（e10-cli report card build）
+
+> 场景：**每条记录 = 一张卡片**（增值税发票、设备卡、工单卡、资产卡…），纵向堆叠**同页不分页**。
+> 首次打通：2026-09-15 「合同收票发票卡片-20260915」，落库 686ms / 20 格。
+> 固化为命令：**`e10-cli report card build`** —— 同类需求不再写脚本。
+
+## 0. 三条铁律
+
+1. **先查 CLI 再动手**：`e10-cli report card example` 出模板 spec，改字段即可；**禁止**重写建表脚本。
+2. **字段锚点唯一**：锚点格必须是 Field 且 `expandType: Vertical` + `isActiveParent: true` + 左父格 `-1,-1`；
+   卡片内**其余全部格子**（含 Const 文本）左父格一律显式指向锚点坐标 → 随记录整块复制。
+3. **字段精确预检**：`spec.cells[].field` 用**字段中文显示名**，精确命中失败 → exit 4 + 候选（禁止模糊兜底/系统字段回退）。
+
+## 1. 快速用法
+
+```bash
+e10-cli report card example > card.json                # 导出模板（含发票卡片示例）
+e10-cli report card example paragraph > card.json      # 导出「段落明细表」模板（多信息区块版式）
+# 改 spec：appId / reportName / sourceId / sourceName / cells
+e10-cli report card build --spec card.json       # dry-run（默认）
+e10-cli report card build --spec card.json --apply
+```
+
+## 2. spec 字段表
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `appId` | ✅ | 目标应用 |
+| `reportName` | ✅ | 报表名（建议带日期戳） |
+| `reportId` | ✖ | 缺省则**自动建壳**（`baseInfo`）；给了则覆盖该报表 |
+| `sourceId` | ✅ | 表单 sourceId（跨应用用 `find form-global` 找） |
+| `sourceName` | ✅ | 表单名 → 规范数据集名 `X(业务模块)` |
+| `sourceType` | ✖ | `logic`(默认) / `form` |
+| `tableName` | ✖ | 缺省 = `normalizeDatasetName(sourceName, sourceType)` |
+| `anchor` | ✖ | `{x,y}` 默认 `{1,1}`（B2），必须落在 Field 格上 |
+| `rowSizes` / `colSizes` | ✖ | 行高 / 列宽（隐藏列写 `0`） |
+| `sheetConfig` | ✖ | 默认 `{dataPreAgg:false, simpleList:false}`（卡片式字段常含 TextArea，默认关预聚合） |
+| `pageSetting` | ✖ | 默认 `{rowHeader:0,colHeader:0,gridLine:0,pagination:false}` → **不分页同页展示** |
+| `showLocation` | ✖ | 默认 `1`（居左）；`2` 居中。**改它会动全表显示位置**，非用户点名勿改 |
+| `cells[]` | ✅ | `{x,y,text \| field, fmt, span, style}`；`x`=行(0基)，`y`=列(0基)，`span`=向右跨列数 |
+
+`fmt`：`common`(默认) / `value`(0.00) / `int` / `percent` / `shortdate`
+`style`：`{fore, back, bold, size, hAlign, border}`；`border:NOBORDER` 用于卡片间距行（`border:{color:'#FFFFFF',style:0}`）
+
+## 3. 卡片排版约定（发票类参考）
+
+- 卡片行结构：标题行（跨列合并）→ 字段行（标签在左、值合并跨列）→ 内表头行 → 值行 → 单位行 → **间距行（空文本格，必须随块复制）**
+- 标题：`fore:'#E36C09'` + `bold` + `size:16` + `hAlign:1`
+- 合并用 `span`（脚本自动生成 `spans[]` + `cell.colCount`），**不要**手写 spans
+- 无对应字段的格（如效果图里的「税额」）用 Const 文本占位（`--`），不要硬凑字段
+
+## 3.1 段落明细表（段落式卡片 · 2026-10-29 固化）
+
+> 形态：**每条记录 = 一个规则段落块**，块内再分**多个信息区**（如「订单基本信息 / 货主信息 / 运货信息」），
+> 每区一行**绿色区块标题条** + 若干**标签/值网格行**；记录间留空行；纵向堆叠随记录数复制。
+> 与发票卡片**同一机制**（锚点格纵向扩展 + 全格左父格跟随），仅版式约定不同 —— 直接复用 `card build`。
+
+**与发票卡片的版式差异**：
+
+| 要素 | 发票卡片 | 段落明细表 |
+|---|---|---|
+| 块内分区 | 单一信息面 | 多个信息区，每区一条**区块标题条**（整行跨列 Const + 底色 `#C9E7D2` + bold） |
+| 网格 | 标签左·值右合并 | 规则**标签/值交替网格**（6 列：标签|值|标签|值|标签|值），值一般不跨列 |
+| 间距行 | 卡片间 1 行 | 段落间 1 行（空文本 + `border:NOBORDER`，必须随块复制） |
+| 锚点 | 卡片首格 Field | 段落内**任一 Field 格**均可（建议第一区首行值格） |
+
+**要点**：
+- 区块标题条是 **Const**（不是数据字段），`span` 到全宽；锚点机制会让它随记录整块复制。
+- 所有 Field 值格 `expandType:'Vertical'` 由脚本自动写入；**只有锚点格** `isActiveParent:true`，
+  其余格（含标签 Const、区块标题条、间距行）左父格全部指向锚点 → 回读验证 `misParent=0`。
+- 字段仍走**精确预检**（exit 4 + 候选）；表单没有的格用 Const 占位，不硬凑。
+- `pageSetting.pagination:false` 同页堆叠；要按记录分页 → 交用户在设计器选（能力边界见 §5）。
+
+**搭建提示语句（用户可直接照此提需求 / AI 照此执行）**：
+
+> 按段落明细表格式搭一张报表：每条记录一个段落块，块内分「XX信息 / YY信息 / ZZ信息」三个信息区，
+> 每区一条整行底色标题条 + 标签/值网格；数据源表 `<sourceName>`（sourceId `<id>`，appId `<appId>`）；
+> 字段映射：区块1 用字段 A/B/C，区块2 用字段 D/E/F……；记录间空一行，同页堆叠不分页；
+> 用 `e10-cli report card example paragraph` 导出模板改字段后 `card build`，dry-run 通过再 `--apply`，落库后回读验收（格数/锚点/全格左父格）并交设计器地址。
+
+## 4. 落库通道（脚本内置，勿改）
+
+1. `saveReportDevInfo` —— `form` 里 **`designKey` 传空串**（构建态公式/结构存活路径），workbook gzip+base64
+2. `saveReportWithCacheConfig` —— 同 workbook + `dataset` 清单 + `pageSetting`（**不分页只在这里生效**）
+3. 回读 `getReportDevInfo` 六项验证：格数 / Field 数 / 锚点 `isActiveParent` / 全格左父格→锚点 / 合并跨度 / `sheetProps.sheetConfig`
+   ⚠️ 环境兼容（2026-10-29 yunteams 实证）：① 部分环境 fields 回读**不含 `isActiveParent` 键** → 锚点判据退化为
+   `expandType=Vertical + left=-1,-1`；② `sheetProps` 可能是**数组**且 `sheetConfig` 为 **JSON 字符串**
+   （`sheetProps[0].sheetConfig`）→ 两种形状都已兼容（e10-cli report card build 内置）。
+
+## 5. 能力边界（无 API 写法，交设计器并**明确告知用户**）
+
+| 效果 | 结论 |
+|---|---|
+| 发票编号条形码/二维码 | 单元格不支持 → 默认文本；需设计器配条码属性 |
+| 价税合计(大写/小写) | 表单无字段 → 不放该行，或设计器内加公式 |
+| 一条记录按记录数**真实分页** | 与「不分页堆叠」互斥；`pageSetting.pagination` 由用户选择 |
+
+## 6. 验证与交付
+
+- dry-run 会打印：格数 / 形状(x行 y列) / 字段数 / 锚点 / 预聚合开关
+- `--apply` 后脚本自报 `VERIFY OK|FAIL`（FAIL → exit 2），并打印**纯文本**设计器地址
+- 交付：纯文本地址，交链即停（见 `report-delivery-contract.md`）
+
+## 7. 历史耗时教训（14 分钟那次）
+
+| 白烧点 | 对策 |
+|---|---|
+| 建壳不知有命令 → 读源码反推 6~7 次 | 规则：「确定性动作先查 CLI」（pitfalls `PERF-7`） |
+| 表不在应用内 → 手工循环探测，失败 2 次 | `e10-cli report find form-global`（pitfalls `FIND-2`），验证 3.5s 命中 |
+| 卡片式无固化命令 → 每轮重写脚本 | 本指南 + `card build`（pitfalls `BUILD-24`） |

package/skill-docs/references/report/cell-config-echo-guide.md

@@ -28,7 +28,7 @@
 **指纹示例**：`formatterType[0] + '|' + formatter + '|' + font + '|' + backColor`
 相同指纹 → 直接复用已通过的 style 对象引用（或深拷贝），**不再**走 JSON 样例确认。
 
-## 二、数字格式目录（工具栏回显参照）
+## 二、数字格式目录（工具栏回显金标准）
 
 > 来源：设计器静态资源 `main.js` 中格式下拉 `g()` 目录。`￥` 为全角 `U+FFE5`（JSON 中写 `\uFFE5`）。
 
@@ -55,15 +55,50 @@
 | 只改 `formatter`、不改 `formatterType` | key1 仍为 common → 常规 |
 | 半角 `¥`（U+00A5）代替全角 `￥`（U+FFE5） | 与目录 id 不全等 |
 
+### ★ 「常规」口径与短码踩雷（注意点 BUILD-47）
+
+> **预览渲染吃 `style.formatter`，不是顶层 `formatterType`。** 构建器会把 `formatterType[0]`（短码）**透传**进 `style.formatter`。
+
+| 目标 | ✅ 正确 | ❌ 踩雷 |
+|------|--------|--------|
+| **常规** | `formatterType:["common"]` + **`style.formatter:"General"`** | `style.formatter:"common"`（字面量短码） |
+| 货币 | `formatterType:["huobi"]` + `style.formatter:'"￥"#,##0.00_);[Red]("￥"#,##0.00)'` | `style.formatter:"huobi"` |
+
+- 若 `style.formatter` 落成**字面量 `common`**，SpreadJS 会把它**当数字格式串解释**（`m`=月份）→ 在 12 月预览显示成 **`co12on`**。
+- 写 `0.00` / `0.##` 功能正常但设计器会归「**其他数字格式**」；用户要求「保持常规」→ 一律用 **`General` + `common`** 口径。
+- **格式调整范围以用户点名的单元格区域为准**，未点名区域**不顺手改**。
+- `e10-cli report validate format --map "常规"` 自动纠正并告警；`--inline '{"formatter":"common"}'` 命中断码误写。
+
+#### 短码直通对照表（`formatterType[0]` → 必须写进 `style.formatter` 的**格式串**）
+
+| `formatterType[0]`（短码） | `style.formatter` 必须是 |
+|---------------------------|--------------------------|
+| `common` | `General` |
+| `percent` | `0.00%` |
+| `value` | `0.00_);[Red](0.00)` |
+| `huobi` | `"￥"#,##0.00_);[Red]("￥"#,##0.00)` |
+| `kuaiji` | `_ "￥"* #,##0.00_ ;_ "￥"* -#,##0.00_ ;_ "￥"* "-"??_ ;_ @_ ` |
+| `shortdate` | `yyyy/m/d;@__@` |
+| `longdate` | `yyyy"年"m"月"d"日";@` |
+| `time` | `h:mm:ss;@` |
+| `fenshu` | `# ?/?` |
+| `kexuejishu` | `0.00E+00` |
+| `text` | `@` |
+
+**铁律**：`formatterType` 的**字面量绝不能直通** `style.formatter`（透传 bug）。
+保存前统一归一 `style.formatter` 为合法 SpreadJS 格式串 —— 已由 落库前防御层的 **R9**
+（落库前自动纠正 + action 留痕）与 构建层的 `normalizeFormulaCellShape()` 兜底。
+目录**单一事实来源**见 ``（校验器 / 保存层共用，避免漂移）。
+
 ### 正确写入示例（货币）
 
 ```json
 {
- "style": {
- "formatter": "\"￥\"#,##0.00_);[Red](\"￥\"#,##0.00)"
- },
- "formatterType": ["huobi"],
- "tag": { "formatterType": ["huobi"] }
+  "style": {
+    "formatter": "\"￥\"#,##0.00_);[Red](\"￥\"#,##0.00)"
+  },
+  "formatterType": ["huobi"],
+  "tag": { "formatterType": ["huobi"] }
 }
 ```
 
@@ -116,7 +151,7 @@ UI 内部拼串形态（勿原样当 formatter）：`"<formatter>__@__<key1>"`
 
 1. 写入前用 CLI `validate format` / 本指南目录校验字体、字号是否在设计器支持列表内。
 2. **不支持**（例：用户要 10 号但当前租户目录无 10）→ **明确提示用户**：「报表不支持 N 号字体，已按默认字号（通常 12）展示」→ **继续用默认字号落库**，禁止中断任务。
- - **禁止变通**：不要手工换算 px（如 10pt→`13.3333px`）绕过目录。后端不校验会照存，但设计器无该项、工具栏回显异常，属于假装支持。
+   - **禁止变通**：不要手工换算 px（如 10pt→`13.3333px`）绕过目录。后端不校验会照存，但设计器无该项、工具栏回显异常，属于假装支持。
 3. 字体名优先使用设计器可选名（如 `微软雅黑`）；未知字体 → 提示并回退默认字体，同样不卡住。
 
 ---
@@ -141,7 +176,7 @@ e10-cli report validate format --map "货币"
 e10-cli report validate transform --map "人员"
 e10-cli report validate transform --map "部门全路径"
 e10-cli report validate transform --list
-```
+
 e10-cli report validate format --map "货币"
 e10-cli report validate format --map "年份"
 e10-cli report validate format --file cell.json
@@ -150,7 +185,7 @@ e10-cli report validate format --file cell.json
 e10-cli report verify format <reportId> [appId]
 ```
 
-脚本：`e10-cli report verify format`。
+脚本：`e10-cli report validate format`。
 
 ---
 

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

@@ -37,7 +37,7 @@
 | 颜色选择框 | `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，**以实际请求为准**） |
+| 关联类型 | `browser` | 弹窗写入 `browserType`（如 `{module,type}` / ComInfo id，**以接口返回为准**） |
 | 图片 | `picture` | — |
 
 > Java 仍兼容遗留 `hrm` / `dept` / `subcom` / `fill`，**新写禁止**用遗留值；人员/部门一律走 `browser`+ComInfo。
@@ -46,13 +46,13 @@
 
 ```json
 {
- "transType": "browser",
- "browserType": [{ "id": "HrmEmployeeComInfo" }],
- "isHtml": "0",
- "qrcodeType": "no",
- "prefixAndSuffix": ["", ""],
- "hiddenContext": "0",
- "textDirection": "FromLeftToRight"
+  "transType": "browser",
+  "browserType": [{ "id": "HrmEmployeeComInfo" }],
+  "isHtml": "0",
+  "qrcodeType": "no",
+  "prefixAndSuffix": ["", ""],
+  "hiddenContext": "0",
+  "textDirection": "FromLeftToRight"
 }
 ```
 
@@ -144,4 +144,4 @@ e10-cli report validate transform --list
 - `cell-config-echo-guide.md` — 数字格式 / 日期分组 / 字体
 - `report-designer-feature-map.md` — 右侧面板总览
 - `report-data-model.md` §八 — 已废弃错误表，以本文为准
-- `safe_report_save.js` — `fieldToCell` 透传
+- `` — `fieldToCell` 透传