weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/report/default-header-style-guide.md

@@ -1,70 +1,70 @@
-# 默认表头样式（强制分流）
-
-> **适用**：新建 / `e10-cli report build spec` 搭表时的标题行、列表字段表头行外观。
-> **CLI**：`e10-cli report validate style --list` / `--inline '{...}'`
-> **实现**：`e10-cli report validate style` → `e10-cli report build` 分层套用。
-
----
-
-## 〇、何时用默认、何时听用户（强制）
-
-| 用户输入 | 行为 |
-|----------|------|
-| **未提样式**、**未给效果图/截图配色** | 自动套 **默认表头样式**（本页 §一）；正文保持素色 |
-| **明确样式**（颜色/字体/主题/「表头蓝色」等） | **完全按用户**；写入 `spec.style` / `titleStyle` / `headerStyle`；**不再**叠默认蓝灰头 |
-| **有效果图 / 原型截图** | 从效果图提取配色写入 spec，并设 `styleFromMockup: true`；**禁止**再盖默认头 |
-| `applyDefaultHeader: false` 或 `stylePreset: "plain"` | 强制素色，不要装饰表头 |
-
-**禁止**：用户已指定样式或已给效果图时，仍强行刷默认 `#B6D6FF` / `#E6E6E6`。
-**禁止**：定点改已有报表时，未点名「改样式」却整表套默认头（见 `user-request-scope-only-guide.md`）。
-
----
-
-## 一、默认值（与 assets 列表模板一致）
-
-| 层级 | 用途 | backColor | foreColor | font | 对齐 |
-|------|------|-----------|-----------|------|------|
-| **title** | `layout.title` 合并标题行 | `#B6D6FF` | `#000000` | 微软雅黑 **14** 加粗 | 居中 |
-| **header** | 列名 Const 表头行 | `#E6E6E6` | `#000000` | 微软雅黑 **12** 加粗 | 居中 |
-| **body** | Field / 公式数据格 | `#FFFFFF` | `#333333` | 微软雅黑 **12** | 居左 |
-
-边框默认 `#CCCCCC`（标题边略深 `#99B8D9`）。字号须落在设计器目录（无 10 号）。
-
----
-
-## 二、spec 字段
-
-```json
-{
-  "styleFromMockup": false,
-  "applyDefaultHeader": true,
-  "style": { },
-  "titleStyle": { },
-  "headerStyle": { },
-  "bodyStyle": { }
-}
-```
-
-| 字段 | 说明 |
-|------|------|
-| （均省略） | → `source=default-header`，套 §一 |
-| `style` / 任一层 `*Style` | → `source=user`，用户优先 |
-| `styleFromMockup: true` | → `source=user`，禁止默认头 |
-| `applyDefaultHeader: false` | → `source=plain` |
-
-`build_from_spec` 回读/日志含 `styleSource`。
-
----
-
-## 三、Agent 话术
-
-- 未指定时：落库后可一句带过「已套用默认表头（蓝标题 + 灰列头）；若要改配色请说明」。
-- 有指定/效果图：不要提默认头，只按用户视觉落地。
-
----
-
-## 四、相关
-
-- `spec-build-schema.md` §三
-- `cell-config-echo-guide.md`（同款样式复用、字号目录）
-- `assets/template-list-report.json`（同色脚手架）
+# 默认表头样式（强制分流）
+
+> **适用**：新建 / `e10-cli report build spec` 搭表时的标题行、列表字段表头行外观。
+> **CLI**：`e10-cli report validate style --list` / `--inline '{...}'`
+> **实现**：`e10-cli report validate style` → `e10-cli report build` 分层套用。
+
+---
+
+## 〇、何时用默认、何时听用户（强制）
+
+| 用户输入 | 行为 |
+|----------|------|
+| **未提样式**、**未给效果图/截图配色** | 自动套 **默认表头样式**（本页 §一）；正文保持素色 |
+| **明确样式**（颜色/字体/主题/「表头蓝色」等） | **完全按用户**；写入 `spec.style` / `titleStyle` / `headerStyle`；**不再**叠默认蓝灰头 |
+| **有效果图 / 原型截图** | 从效果图提取配色写入 spec，并设 `styleFromMockup: true`；**禁止**再盖默认头 |
+| `applyDefaultHeader: false` 或 `stylePreset: "plain"` | 强制素色，不要装饰表头 |
+
+**禁止**：用户已指定样式或已给效果图时，仍强行刷默认 `#B6D6FF` / `#E6E6E6`。
+**禁止**：定点改已有报表时，未点名「改样式」却整表套默认头（见 `user-request-scope-only-guide.md`）。
+
+---
+
+## 一、默认值（与 assets 列表模板一致）
+
+| 层级 | 用途 | backColor | foreColor | font | 对齐 |
+|------|------|-----------|-----------|------|------|
+| **title** | `layout.title` 合并标题行 | `#B6D6FF` | `#000000` | 微软雅黑 **14** 加粗 | 居中 |
+| **header** | 列名 Const 表头行 | `#E6E6E6` | `#000000` | 微软雅黑 **12** 加粗 | 居中 |
+| **body** | Field / 公式数据格 | `#FFFFFF` | `#333333` | 微软雅黑 **12** | 居左 |
+
+边框默认 `#CCCCCC`（标题边略深 `#99B8D9`）。字号须落在设计器目录（无 10 号）。
+
+---
+
+## 二、spec 字段
+
+```json
+{
+  "styleFromMockup": false,
+  "applyDefaultHeader": true,
+  "style": { },
+  "titleStyle": { },
+  "headerStyle": { },
+  "bodyStyle": { }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| （均省略） | → `source=default-header`，套 §一 |
+| `style` / 任一层 `*Style` | → `source=user`，用户优先 |
+| `styleFromMockup: true` | → `source=user`，禁止默认头 |
+| `applyDefaultHeader: false` | → `source=plain` |
+
+`build_from_spec` 回读/日志含 `styleSource`。
+
+---
+
+## 三、Agent 话术
+
+- 未指定时：落库后可一句带过「已套用默认表头（蓝标题 + 灰列头）；若要改配色请说明」。
+- 有指定/效果图：不要提默认头，只按用户视觉落地。
+
+---
+
+## 四、相关
+
+- `spec-build-schema.md` §三
+- `cell-config-echo-guide.md`（同款样式复用、字号目录）
+- `assets/template-list-report.json`（同色脚手架）

package/skill-docs/references/report/designer-blank-prevention-guide.md

@@ -1,111 +1,111 @@
-# 设计器空白防护（强制 · 不允许发生）
-
-> **事故（已验证 · 报表 `1312790168931180545`）**：设计区中间空白，但 `fields.length` 仍 > 0 —— **不是删格**，是配置毒化导致前端加载崩溃/空白。
-> **硬约束**：下列写入错误 **一律禁止**；落库前必须校验；发现设计区空白优先按本指南定位，禁止盲目整表覆盖。
-
----
-
-## 一、已验证会导致「设计区空白」的写入（禁令）
-
-| # | 错误写法 | 后果 | 正确做法 |
-|---|----------|------|----------|
-| **1** | `snapshot.sheetId = Number(reportId)`（及 `id`/`jobId` 用 Number） | 雪花 ID 超 `MAX_SAFE_INTEGER` 截断（`…0545`→`…0500`），快照 sheetId 错位 → **设计区空白** | **一律 `String(reportId)`**；禁止对雪花 ID 做 `Number()` |
-| **2** | `showLocation: 0`（或从 sheetProps 原样回传 0） | 前端 truthy 判断异常，布局空白/错乱 | 仅允许 **`1`（居左）或 `2`（居中）**；读到 0 必须改成 2（或用户点名居左则 1） |
-| **3** | `scrollPage: "1"` 且 `scrollContentField` 为空 | 滑动分页表单项 required，配置残缺 → 设计器异常 | 开滑动分页必须带有效 `scrollContentField`；否则 **`scrollPage: "0"`** |
-| **4** | 空 workbook / 空 dataTable 提交 `saveReportDevInfo` | fields 被全量清空 → 真空白 | `mergeWorkbookSafe` / 从 fields 重建；见 `safe-partial-save-guide.md` |
-| **5** | Formula `cellText` 带前导 `=` / 错误 countType | 设计器整页空白 | 见 `formula-cell-api-guide.md` |
-
-**禁止**：为「开快照 / 改分页 / 改打印」而提交会触发上表任一错误的 payload。
-
----
-
-## 二、定时快照命名与 ID 契约
-
-### 2.1 默认快照名称（强制）
-
-用户**未指定**快照名称时，默认：
-
-```text
-{当前报表名}-{date}-{time}
-```
-
-示例：报表名 `测试报表-chl` → `测试报表-chl-{date}-{time}`
-
-| 占位符 | 含义 |
-|--------|------|
-| `{date}` | 生成日（平台解析） |
-| `{time}` | 生成时分（平台解析） |
-
-**禁止**再默认写成 `{year}-{month}-{day}`（旧习惯）。用户显式传入 `--snapshot-name` 时才用自定义名。
-
-### 2.2 sheetId / id / jobId
-
-```javascript
-{
-  enableSnapshot: true,
-  cron: '0 0/1 * * * ?',           // 例：每分钟
-  snapshotName: `${reportName}-{date}-{time}`,
-  params: JSON.stringify({ searchCondition: {} }),
-  sheetId: String(reportId),         // 禁止 Number()
-  // id / jobId 若回传：同样 String(...)
-}
-```
-
-落库后门禁：
-
-- `enableSnapshot === true`（若本次为开启）
-- `String(snapshot.sheetId) === String(reportId)`（在**未经过 JSON number 污染的原始串**上比；Node `JSON.parse` 大整数可能已截断，**写入侧必须保证字符串**）
-- `fields.length` 不下降
-
-CLI：`e10-cli report snapshot set --report-id <id> [--cron "..."] [--snapshot-name "..."]`
-
----
-
-## 三、其它本会话沉淀（写入时一并遵守）
-
-| 主题 | 规则 | 文档 / CLI |
-|------|------|------------|
-| 数字格式回显 | formatter **目录全等** + `formatterType` 成对；货币=`huobi`+全角￥格式串 | `cell-config-echo-guide.md`；`validate format` |
-| 日期分组回显 | `groupType=year/yearmonth/...` 写入 fields + cellType | 同上 |
-| 字体字号 | 不支持则**提示**并用默认字号继续，**不卡住** | 同上 |
-| 禁整表刷样式/边框 | 用户要整表设样式 → **提示不支持**，须给区域 | 同上 + scope |
-| `showLocation` | 禁止 0 | `layout-showlocation-freeze-guide.md` |
-| **网格线** | workbook **禁止** `gridline` 键（存在→500）；page `gridLine=0` | §4.6.1；`validate gridline` |
-| 滑动分页 | `scrollPage=1` 须有内容字段；每页条数 `pageRowCount` | `allPageSetting` |
-| 打印眉头页码 | Spread `headerCenter: "&[Page]"`；重复行 0-based | sheet `printInfo` |
-| 局部保存 | 快照必须 `mergeWorkbookSafe`；禁空 workbook | `safe-partial-save-guide.md` |
-
----
-
-## 四、保存前 Agent / CLI 检查清单（防空白）
-
-任意 `saveReportDevInfo`（含快照）前：
-
-- [ ] `fields.length > 0`（已有报表）
-- [ ] workbook 重建后 `countCells > 0`
-- [ ] `showLocation` ∈ `{1, 2}`，若为 0 → 改为 2
-- [ ] **网格线**：workbook sheets **无** `gridline`/`gridLine`/`__gridline`；page 层默认 `gridLine=0` → `validate gridline`
-- [ ] 若写 snapshot：`sheetId`/`id`/`jobId` 均为**字符串**；`snapshotName` 未指定则用 `{报表名}-{date}-{time}`
-- [ ] 若 `scrollPage==="1"` → `scrollContentField` 非空，否则改 `"0"`
-- [ ] 保存后 `fields.length` 不降；提示用户 Ctrl+F5
-
-CLI 自检：`e10-cli report verify blank <reportId>`（含网格线联动）；`e10-cli report validate gridline --inline '...'`
-
----
-
-## 五、设计区已空白时的处置
-
-1. **先** `getReportDevInfo`：若 `fields.length > 0` → 多半是配置毒化（快照 ID / showLocation / scrollPage），**不是**删光了
-2. 关闭或修复坏快照（`enableSnapshot:false` 或重写 **String** sheetId）
-3. 纠正 `showLocation`、关闭残缺滑动分页
-4. 从 fields 安全重建 workbook 再存
-5. 仅当 `fields.length===0` 才走 `rollbackReport`（版本 snapshotId）
-
----
-
-## 六、与 Skill 映射
-
-- SKILL 硬规则 **§L**
-- `safe-partial-save-guide.md` §3.2
-- `e10-cli report-cli.md` §一
-- 脚本：`e10-cli report snapshot`、`e10-cli report validate blank`
+# 设计器空白防护（强制 · 不允许发生）
+
+> **事故（已验证 · 报表 `1312790168931180545`）**：设计区中间空白，但 `fields.length` 仍 > 0 —— **不是删格**，是配置毒化导致前端加载崩溃/空白。
+> **硬约束**：下列写入错误 **一律禁止**；落库前必须校验；发现设计区空白优先按本指南定位，禁止盲目整表覆盖。
+
+---
+
+## 一、已验证会导致「设计区空白」的写入（禁令）
+
+| # | 错误写法 | 后果 | 正确做法 |
+|---|----------|------|----------|
+| **1** | `snapshot.sheetId = Number(reportId)`（及 `id`/`jobId` 用 Number） | 雪花 ID 超 `MAX_SAFE_INTEGER` 截断（`…0545`→`…0500`），快照 sheetId 错位 → **设计区空白** | **一律 `String(reportId)`**；禁止对雪花 ID 做 `Number()` |
+| **2** | `showLocation: 0`（或从 sheetProps 原样回传 0） | 前端 truthy 判断异常，布局空白/错乱 | 仅允许 **`1`（居左）或 `2`（居中）**；读到 0 必须改成 2（或用户点名居左则 1） |
+| **3** | `scrollPage: "1"` 且 `scrollContentField` 为空 | 滑动分页表单项 required，配置残缺 → 设计器异常 | 开滑动分页必须带有效 `scrollContentField`；否则 **`scrollPage: "0"`** |
+| **4** | 空 workbook / 空 dataTable 提交 `saveReportDevInfo` | fields 被全量清空 → 真空白 | `mergeWorkbookSafe` / 从 fields 重建；见 `safe-partial-save-guide.md` |
+| **5** | Formula `cellText` 带前导 `=` / 错误 countType | 设计器整页空白 | 见 `formula-cell-api-guide.md` |
+
+**禁止**：为「开快照 / 改分页 / 改打印」而提交会触发上表任一错误的 payload。
+
+---
+
+## 二、定时快照命名与 ID 契约
+
+### 2.1 默认快照名称（强制）
+
+用户**未指定**快照名称时，默认：
+
+```text
+{当前报表名}-{date}-{time}
+```
+
+示例：报表名 `测试报表-chl` → `测试报表-chl-{date}-{time}`
+
+| 占位符 | 含义 |
+|--------|------|
+| `{date}` | 生成日（平台解析） |
+| `{time}` | 生成时分（平台解析） |
+
+**禁止**再默认写成 `{year}-{month}-{day}`（旧习惯）。用户显式传入 `--snapshot-name` 时才用自定义名。
+
+### 2.2 sheetId / id / jobId
+
+```javascript
+{
+  enableSnapshot: true,
+  cron: '0 0/1 * * * ?',           // 例：每分钟
+  snapshotName: `${reportName}-{date}-{time}`,
+  params: JSON.stringify({ searchCondition: {} }),
+  sheetId: String(reportId),         // 禁止 Number()
+  // id / jobId 若回传：同样 String(...)
+}
+```
+
+落库后门禁：
+
+- `enableSnapshot === true`（若本次为开启）
+- `String(snapshot.sheetId) === String(reportId)`（在**未经过 JSON number 污染的原始串**上比；Node `JSON.parse` 大整数可能已截断，**写入侧必须保证字符串**）
+- `fields.length` 不下降
+
+CLI：`e10-cli report snapshot set --report-id <id> [--cron "..."] [--snapshot-name "..."]`
+
+---
+
+## 三、其它本会话沉淀（写入时一并遵守）
+
+| 主题 | 规则 | 文档 / CLI |
+|------|------|------------|
+| 数字格式回显 | formatter **目录全等** + `formatterType` 成对；货币=`huobi`+全角￥格式串 | `cell-config-echo-guide.md`；`validate format` |
+| 日期分组回显 | `groupType=year/yearmonth/...` 写入 fields + cellType | 同上 |
+| 字体字号 | 不支持则**提示**并用默认字号继续，**不卡住** | 同上 |
+| 禁整表刷样式/边框 | 用户要整表设样式 → **提示不支持**，须给区域 | 同上 + scope |
+| `showLocation` | 禁止 0 | `layout-showlocation-freeze-guide.md` |
+| **网格线** | workbook **禁止** `gridline` 键（存在→500）；page `gridLine=0` | §4.6.1；`validate gridline` |
+| 滑动分页 | `scrollPage=1` 须有内容字段；每页条数 `pageRowCount` | `allPageSetting` |
+| 打印眉头页码 | Spread `headerCenter: "&[Page]"`；重复行 0-based | sheet `printInfo` |
+| 局部保存 | 快照必须 `mergeWorkbookSafe`；禁空 workbook | `safe-partial-save-guide.md` |
+
+---
+
+## 四、保存前 Agent / CLI 检查清单（防空白）
+
+任意 `saveReportDevInfo`（含快照）前：
+
+- [ ] `fields.length > 0`（已有报表）
+- [ ] workbook 重建后 `countCells > 0`
+- [ ] `showLocation` ∈ `{1, 2}`，若为 0 → 改为 2
+- [ ] **网格线**：workbook sheets **无** `gridline`/`gridLine`/`__gridline`；page 层默认 `gridLine=0` → `validate gridline`
+- [ ] 若写 snapshot：`sheetId`/`id`/`jobId` 均为**字符串**；`snapshotName` 未指定则用 `{报表名}-{date}-{time}`
+- [ ] 若 `scrollPage==="1"` → `scrollContentField` 非空，否则改 `"0"`
+- [ ] 保存后 `fields.length` 不降；提示用户 Ctrl+F5
+
+CLI 自检：`e10-cli report verify blank <reportId>`（含网格线联动）；`e10-cli report validate gridline --inline '...'`
+
+---
+
+## 五、设计区已空白时的处置
+
+1. **先** `getReportDevInfo`：若 `fields.length > 0` → 多半是配置毒化（快照 ID / showLocation / scrollPage），**不是**删光了
+2. 关闭或修复坏快照（`enableSnapshot:false` 或重写 **String** sheetId）
+3. 纠正 `showLocation`、关闭残缺滑动分页
+4. 从 fields 安全重建 workbook 再存
+5. 仅当 `fields.length===0` 才走 `rollbackReport`（版本 snapshotId）
+
+---
+
+## 六、与 Skill 映射
+
+- SKILL 硬规则 **§L**
+- `safe-partial-save-guide.md` §3.2
+- `e10-cli report-cli.md` §一
+- 脚本：`e10-cli report snapshot`、`e10-cli report validate blank`

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

@@ -1,69 +1,69 @@
-# 档案式报表 · 场景 G（SKILL A0.17）
-
-> 典型案例：FineReport「帆软集团基本档案」—— 一个实体一份档案，纵向多区块：
-> ①基本信息（左右两组标签/值网格）②教育经历（标题条+表头行+多行明细）
-> ③工作经历（同上）④职称资格（单行带）⑤培训记录；**保持 A4 自然分页**（第1页/共3页）。
-
----
-
-## 一、案例解析（特性 → 机制 → CLI 落点）
-
-| # | 特性 | 机制 | CLI 落点 |
-|---|---|---|---|
-| ① | 一个实体一份档案（基本信息区） | 标签 Const + 值 Field 链式跟随（卡片机制同源），**不扩展或随实体锚点扩展** | 单源：`card build` cells 网格直写（label/value） |
-| ② | 多个一对多明细带（教育/工作/培训） | **每个带 = 独立扩展块**：带锚点 = 带内首格 Field（Vertical 扩展），带标题条+表头行 Const 左父格挂**公共父格或带锚点**（场景 A 三类口径：入口格/标题行/表头行整行 Const），带内数据格默认链 | 多源走 `rebuild from-blueprint`（`datasets[]` + 格上 `datasetKey`）；带结构同场景 A 多扩展块 |
-| ③ | 多数据源（主表 + N 个子表） | 主表一个数据集，每个子表单/明细各自 addDataset，格按 `dataSetId` 归片 | **datasetId 隔离铁律照常**：`check-ids` / `assertNoStaleDatasetIds` |
-| ④ | A4 自然分页（第N页/共M页） | 分页**开着**（默认）—— 与段落/卡片式（不分页）**相反** | card spec **不要写** `pageSetting.pagination:false`；要显式则 `pagination:true`。跨页时区块/明细带是否断行 = 平台渲染（验证项） |
-
-## 二、与相近场景的边界
-
-| 场景 | 数据形态 | 分页 | 通道 |
-|---|---|---|---|
-| 卡片式（发票） | 一条记录=一张卡片，块内 label/value | 不分页 | `card build`（单源） |
-| 段落明细表 | 同上，块内多信息区 | 不分页 | `card example paragraph` |
-| **档案式（本节）** | **一个实体 + N 个一对多明细带**（通常多数据集） | **分页开** | 单源 `card build` / 多源 `rebuild from-blueprint` |
-| 分页分组报表（E） | 平铺列表 + 分组 + 每页 N 行 | 固定行数分页 | `build spec` |
-
-## 三、多源档案 spec 骨架（rebuild from-blueprint）
-
-```json
-{
-  "datasets": [
-    { "key": "main",  "sourceId": "<主表sid>",  "sourceName": "<主表>" },
-    { "key": "edu",   "sourceId": "<教育子表sid>", "sourceName": "<教育经历>" },
-    { "key": "work",  "sourceId": "<工作子表sid>", "sourceName": "<工作经历>" }
-  ],
-  "cells": [
-    { "r": 0, "c": 0, "text": "基本信息", "span": 4, "style": { "back": "#BDD7EE", "bold": true } },
-    { "r": 1, "c": 0, "text": "编号" },  { "r": 1, "c": 1, "datasetKey": "main", "field": "编号" },
-    { "r": 1, "c": 2, "text": "姓名" },  { "r": 1, "c": 3, "datasetKey": "main", "field": "姓名" },
-    { "r": 3, "c": 0, "text": "教育经历", "span": 5, "style": { "back": "#BDD7EE", "bold": true } },
-    { "r": 4, "c": 0, "text": "学习时间" }, { "r": 4, "c": 1, "text": "性质" }, { "r": 4, "c": 2, "text": "学历" }, { "r": 4, "c": 3, "text": "学校" }, { "r": 4, "c": 4, "text": "专业" },
-    { "r": 5, "c": 0, "datasetKey": "edu", "field": "学习时间", "expand": "Vertical", "isActiveParent": true },
-    { "r": 5, "c": 1, "datasetKey": "edu", "field": "性质", "left": [5, 0] },
-    { "r": 5, "c": 2, "datasetKey": "edu", "field": "学历", "left": [5, 0] },
-    { "r": 5, "c": 3, "datasetKey": "edu", "field": "学校", "left": [5, 0] },
-    { "r": 5, "c": 4, "datasetKey": "edu", "field": "专业", "left": [5, 0] }
-  ]
-}
-```
-
-- 带标题条/表头行：整行 Const 左父格挂**公共父格**（场景 A）或带锚点；不可悬空（悬空 = 随机扩展事故）。
-- 每带锚点 `isActiveParent:true` 且**各带锚点独立**；带间用空行/标题条隔开。
-
-## 四、搭建提示语句（用户照此说即可）
-
-> 按档案式报表搭一张「XX基本档案」：一个实体一份档案，纵向分区块——
-> 「基本信息」（标签/值网格，字段 A/B/C/D…）＋「教育经历」（表头：时间/性质/学历/学校/专业，一对多明细）
-> ＋「工作经历」（表头：…）＋「培训记录」（表头：…）；
-> 主表 sourceId `<sid0>`，各明细子表 sourceId `<sid1/sid2/…>`（appId `<appId>`）；
-> 保持 A4 自然分页；多源走 `rebuild from-blueprint`（datasets[]+datasetKey），
-> 落库后回读验收：各带锚点独立扩展、带标题/表头行父格齐全、check-ids 无外来 datasetId。
-
-## 五、验证清单
-
-1. 回读：每个明细带锚点 `expandType=Vertical` 且各带独立；带内数据格左父格→带锚点
-2. 带标题条/表头行 Const 的左父格指向公共父格/带锚点（非悬空）
-3. 多源：`e10-cli report check-ids` exit 0；各格 `fieldKey` 首段 == 本格 `dataSetId`
-4. 分页：`allPageSetting` pagination=true（或未写 false）
-5. 单实体/多实体表现（整份档案是否随实体复制）以设计器确认为准；验证后回填本指南
+# 档案式报表 · 场景 G（SKILL A0.17）
+
+> 典型案例：FineReport「帆软集团基本档案」—— 一个实体一份档案，纵向多区块：
+> ①基本信息（左右两组标签/值网格）②教育经历（标题条+表头行+多行明细）
+> ③工作经历（同上）④职称资格（单行带）⑤培训记录；**保持 A4 自然分页**（第1页/共3页）。
+
+---
+
+## 一、案例解析（特性 → 机制 → CLI 落点）
+
+| # | 特性 | 机制 | CLI 落点 |
+|---|---|---|---|
+| ① | 一个实体一份档案（基本信息区） | 标签 Const + 值 Field 链式跟随（卡片机制同源），**不扩展或随实体锚点扩展** | 单源：`card build` cells 网格直写（label/value） |
+| ② | 多个一对多明细带（教育/工作/培训） | **每个带 = 独立扩展块**：带锚点 = 带内首格 Field（Vertical 扩展），带标题条+表头行 Const 左父格挂**公共父格或带锚点**（场景 A 三类口径：入口格/标题行/表头行整行 Const），带内数据格默认链 | 多源走 `rebuild from-blueprint`（`datasets[]` + 格上 `datasetKey`）；带结构同场景 A 多扩展块 |
+| ③ | 多数据源（主表 + N 个子表） | 主表一个数据集，每个子表单/明细各自 addDataset，格按 `dataSetId` 归片 | **datasetId 隔离铁律照常**：`check-ids` / `assertNoStaleDatasetIds` |
+| ④ | A4 自然分页（第N页/共M页） | 分页**开着**（默认）—— 与段落/卡片式（不分页）**相反** | card spec **不要写** `pageSetting.pagination:false`；要显式则 `pagination:true`。跨页时区块/明细带是否断行 = 平台渲染（验证项） |
+
+## 二、与相近场景的边界
+
+| 场景 | 数据形态 | 分页 | 通道 |
+|---|---|---|---|
+| 卡片式（发票） | 一条记录=一张卡片，块内 label/value | 不分页 | `card build`（单源） |
+| 段落明细表 | 同上，块内多信息区 | 不分页 | `card example paragraph` |
+| **档案式（本节）** | **一个实体 + N 个一对多明细带**（通常多数据集） | **分页开** | 单源 `card build` / 多源 `rebuild from-blueprint` |
+| 分页分组报表（E） | 平铺列表 + 分组 + 每页 N 行 | 固定行数分页 | `build spec` |
+
+## 三、多源档案 spec 骨架（rebuild from-blueprint）
+
+```json
+{
+  "datasets": [
+    { "key": "main",  "sourceId": "<主表sid>",  "sourceName": "<主表>" },
+    { "key": "edu",   "sourceId": "<教育子表sid>", "sourceName": "<教育经历>" },
+    { "key": "work",  "sourceId": "<工作子表sid>", "sourceName": "<工作经历>" }
+  ],
+  "cells": [
+    { "r": 0, "c": 0, "text": "基本信息", "span": 4, "style": { "back": "#BDD7EE", "bold": true } },
+    { "r": 1, "c": 0, "text": "编号" },  { "r": 1, "c": 1, "datasetKey": "main", "field": "编号" },
+    { "r": 1, "c": 2, "text": "姓名" },  { "r": 1, "c": 3, "datasetKey": "main", "field": "姓名" },
+    { "r": 3, "c": 0, "text": "教育经历", "span": 5, "style": { "back": "#BDD7EE", "bold": true } },
+    { "r": 4, "c": 0, "text": "学习时间" }, { "r": 4, "c": 1, "text": "性质" }, { "r": 4, "c": 2, "text": "学历" }, { "r": 4, "c": 3, "text": "学校" }, { "r": 4, "c": 4, "text": "专业" },
+    { "r": 5, "c": 0, "datasetKey": "edu", "field": "学习时间", "expand": "Vertical", "isActiveParent": true },
+    { "r": 5, "c": 1, "datasetKey": "edu", "field": "性质", "left": [5, 0] },
+    { "r": 5, "c": 2, "datasetKey": "edu", "field": "学历", "left": [5, 0] },
+    { "r": 5, "c": 3, "datasetKey": "edu", "field": "学校", "left": [5, 0] },
+    { "r": 5, "c": 4, "datasetKey": "edu", "field": "专业", "left": [5, 0] }
+  ]
+}
+```
+
+- 带标题条/表头行：整行 Const 左父格挂**公共父格**（场景 A）或带锚点；不可悬空（悬空 = 随机扩展事故）。
+- 每带锚点 `isActiveParent:true` 且**各带锚点独立**；带间用空行/标题条隔开。
+
+## 四、搭建提示语句（用户照此说即可）
+
+> 按档案式报表搭一张「XX基本档案」：一个实体一份档案，纵向分区块——
+> 「基本信息」（标签/值网格，字段 A/B/C/D…）＋「教育经历」（表头：时间/性质/学历/学校/专业，一对多明细）
+> ＋「工作经历」（表头：…）＋「培训记录」（表头：…）；
+> 主表 sourceId `<sid0>`，各明细子表 sourceId `<sid1/sid2/…>`（appId `<appId>`）；
+> 保持 A4 自然分页；多源走 `rebuild from-blueprint`（datasets[]+datasetKey），
+> 落库后回读验收：各带锚点独立扩展、带标题/表头行父格齐全、check-ids 无外来 datasetId。
+
+## 五、验证清单
+
+1. 回读：每个明细带锚点 `expandType=Vertical` 且各带独立；带内数据格左父格→带锚点
+2. 带标题条/表头行 Const 的左父格指向公共父格/带锚点（非悬空）
+3. 多源：`e10-cli report check-ids` exit 0；各格 `fieldKey` 首段 == 本格 `dataSetId`
+4. 分页：`allPageSetting` pagination=true（或未写 false）
+5. 单实体/多实体表现（整份档案是否随实体复制）以设计器确认为准；验证后回填本指南