weaver-work-cli 0.1.23 → 0.1.25

package/skills/weaver-e10-builder/references/report/default-header-style-guide.md

@@ -0,0 +1,70 @@
+# 默认表头样式（强制分流）
+
+> **适用**：新建 / `e10-cli report build` 搭表时的标题行、列表字段表头行外观。
+> **CLI**：`e10-cli report validate style --list` / `--inline '{...}'`
+> **实现**：`e10-cli report validate style` → `build_from_spec.js` 分层套用。
+
+---
+
+## 〇、何时用默认、何时听用户（强制）
+
+| 用户输入 | 行为 |
+|----------|------|
+| **未提样式**、**未给效果图/截图配色** | 自动套 **默认表头样式**（本页 §一）；正文保持素色 |
+| **明确样式**（颜色/字体/主题/「表头蓝色」等） | **完全按用户**；写入 `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/skills/weaver-e10-builder/references/report/designer-blank-prevention-guide.md

@@ -0,0 +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` §一
+- 脚本：`set_snapshot_schedule.js`、`validate_designer_blank_guard.js`

package/skills/weaver-e10-builder/references/report/event-hreflink-guide.md

@@ -0,0 +1,184 @@
+# 报表事件 · 超链接传参（强制）
+
+> **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.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`）。
+
+示例：
+
+```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 文案已映射
+- [ ] 传单元格：查询串用 `参数名=坐标`（无 `{}`）；路径用 `{坐标}`；仅当前格+父格链
+- [ ] 传查询条件：`{searchfield00x}`，asNameIndex 已对齐
+- [ ] 参数名避免 `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

package/skills/weaver-e10-builder/references/report/field-bind-exact-match-guide.md

@@ -0,0 +1,208 @@
+# 字段精确绑定（强制 · 禁止匹配失败）
+
+> **事故案例（已验证）**：报表 `AAA`（`1312677851392417792`）保存了 9 个 Field 格，但 `name` / `fieldKey` 末段写成裸雪花 ID `3506271516100878845`，而数据源真实字段名是 `field_3506271516100878845` → **设计器有字段格、取数全部匹配失败（字段获取不上）**。 
+> **前置事故（已验证 · `1312765120721813505`）**：Agent 用错 `addDataset`（`type=form` + `sourceGroup=appId`）时，`fieldsKey` **本身只有裸雪花**；用户在设计器手动「+」同表则得到 `field_*`。 
+> **遗漏点**：不是写 Field 时忘加前缀，而是 **注册契约与设计器不一致** —— 必先读 **`add-dataset-registration-guide.md`**，把数据集加成 LOGIC + `weaver-ebuilder-form-service`，再绑定。 
+> **唯一标准**：`name` / `fieldKey` 末段必须 **精确等于** 当前数据集 `fieldsAndOriginFields.fieldsKey[].name`（以接口回读为准）。 
+> **禁止**：注册错了却在 cell 上「手工补 `field_`」；或对正确的 `field_*` fieldsKey 去前缀。 
+> **硬目标**：任意 Field 的 `name` **必须**等于该 dataset 的 `fieldsKey[].name`；**零容忍**猜测、截断、错数据集。
+
+---
+
+## 〇、先保证 fieldsKey 带 `field_`（普通应用）
+
+| 检查 | 说明 |
+|------|------|
+| addDataset | 默认 `sourceType=LOGIC` + `sourceGroup=weaver-ebuilder-form-service` |
+| 门禁 | 业务字段若多为裸雪花 → **注册错误**，`delDataset` 重建；见 `add-dataset-registration-guide.md` |
+| 同 sourceId 多实例 | **优先绑**设计器/LOGIC 那条（`field_*`），勿绑旧 form+appId 实例 |
+
+---
+
+## 一、唯一合法字段名来源
+
+```
+GET /api/bs/edc/dataset/fieldsAndOriginFields
+ ?datasetId={datasetId}&hasField=true&isFront=true&reportId={reportId}
+→ data.fieldsKey[] // 权威列表；isFront=false 常为空，禁止依赖
+```
+
+每个 `fieldsKey` 项的关键属性：
+
+| 属性 | 用途 | 示例 |
+|------|------|------|
+| **`name`** | **写入 Field 的 `name` / fieldKey 末段（唯一正确）** | `field_3506271516100878845`、`create_time` |
+| `text` / `showName` | 仅用于按中文显示名**查找**对应 `name` | `资产类别` |
+| `originName` | 参考，不可直接当 fieldKey 末段（除非与 `name` 相同） | — |
+
+**禁止**从下列来源臆造 `name`：
+
+| 错误来源 | 错误示例 | 后果 |
+|----------|----------|------|
+| 表单字段 ID / 雪花 ID（无 `field_`） | `3506271516100878845` | **取数匹配失败**（本案） |
+| 显示名 | `资产类别` | 设计器/取数均失败 |
+| 截断 / 半截 | `field_5`、`field_3506` | 匹配失败 |
+| 去掉 `field_` 前缀 | 把 `field_xxx` 写成 `xxx` | **取数匹配失败** |
+| 外部字段表 fieldId 未与 fieldsKey 交叉核对 | 形态可能不同 | 须与 fieldsKey.name 对齐后再用 |
+
+---
+
+## 二、绑定算法（强制）
+
+> **⚠️ 2026-09-11 追加门禁（事故：报表 `1313789294296735745`）**：B3 列文案「姓名」，但该表单**没有「姓名」字段**，
+> 旧逻辑静默兜底到系统字段 `name`（真实显示名「标题」）→ 单元格文案与绑定字段语义不符、属性面板回显对不上。
+> **新规则：精确匹配失败必须 `exit 4` 提示用户指定字段，禁止任何自动兜底（尤其禁止回退系统字段）。**
+> 落地实现：`spec_lib.resolveFieldBindings()` + `e10-cli report build` 的**建表前预检**。
+
+对需求中的每一列（显示名 → 数据字段）：
+
+### 2.0 允许的匹配（命中即止，**全为精确匹配**）
+
+| 顺序 | 依据 | 说明 |
+|------|------|------|
+| 1 | `column.fieldName` / `spec.fieldMap[列标题]` | 用户/Agent 显式指定（可为 `field_xxx`、显示名、系统字段名） |
+| 2 | 列标题 === `fieldsKey[].text/showName`（归一化：去空白、全角括号→半角） | 主路径 |
+| 3 | `column.field` === `text/showName` 或 `name` | 兼容旧 spec |
+| 4 | 都不中 | **`unmatched` → exit 4**（附模糊候选供用户挑选） |
+
+**禁止**：包含/被包含（`includes`）等模糊规则自动绑定；**禁止**把 `name`/`id`/`create_time` 等系统字段当作兜底。
+
+### 2.0.1 规则 A · 找不到字段 → **停下让用户指定**（强制 · 2026-09-11）
+
+> **核心**：需求里的字段在当前数据集表单里**找不到**时，**不许猜、不许兜底**，必须停下把候选交给用户。
+
+`resolveFieldBindings()` 的 `unmatched[]` 三种 `reason` 及处置：
+
+| `reason` | 含义 | 退出码 | 处置 |
+|----------|------|--------|------|
+| `no_exact_match` | 列标题在 `fieldsKey.text` 中**无精确命中** | **4** | 把 `candidates` + `allFields` 抛给用户，请其指定字段 |
+| `explicit_not_found` | 显式 `fieldName`/`fieldMap` 指向的字段**不存在** | **4** | 同上（禁止臆造字段名） |
+| `display_mismatch` | 能绑到，但字段**真实显示名 ≠ 列文案**且未确认 | **4** | 用户确认列名有意如此 → `fieldConfirmed` / `--field-confirmed "列标题"` |
+
+**两阶段拦截**（都不建表 / 删未完成表）：
+
+| 阶段 | 时机 | 未通过 |
+|------|------|--------|
+| 预检 | `fieldsBySource`（**建表前**） | **exit 4 · 未创建任何报表** |
+| 复校 | 本表 `addDataset` → `fieldsKey`（落库前） | **exit 4 · 删除本轮未完成报表** |
+
+输出结构（`rule:"A"`）：
+
+```json
+{
+ "action": "confirm_field", "rule": "A", "needConfirm": true, "reportCreated": false,
+ "unmatched": [ { "column": "姓名", "reason": "no_exact_match", "prompt": "…请用户从 allFields/candidates 中指定字段",
+ "candidates": [ { "name": "field_...", "text": "发展人", "system": false } ] } ],
+ "allFields": [ { "name": "field_...", "text": "发展人", "system": false } ],
+ "next": { "specFields": { "fieldMap": { "<列标题>": "<字段显示名 | field_雪花 | 系统字段名>" } } }
+}
+```
+
+用户指定后复跑：`spec.fieldMap = { "姓名": "发展人" }`（或 `field_xxx`）。
+若列名坚持与字段显示名不同 → 另加 `fieldConfirmed: ["姓名"]` / CLI `--field-confirmed "姓名"`。
+
+**禁止**：
+- 用「最相近的」字段顶上（哪怕语义看似接近）；
+- 回退系统字段（`name`→「标题」是历史事故）；
+- 先带病落库、事后再让用户改。
+
+> 一页速览：`e10-cli report --help`。
+
+```javascript
+// 1. 拉权威列表
+const fieldsKey = (await fieldsAndOriginFields(...)).data.fieldsKey;
+
+// 2. 解析（库函数，已含门禁）
+const plan = resolveFieldBindings(fieldsKey, spec.columns, { fieldMap, fieldConfirmed });
+if (!plan.ok) {
+ // exit 4：把每列 candidates 抛给用户，等其指定字段；不要自己猜
+}
+const nf = plan.bindings.find(b => b.index === colIndex).field;
+```
+
+**规则摘要**：
+
+1. **先** `fieldsAndOriginFields`，**再**写任何 Field 单元格 
+2. `name` **逐字等于** `fieldsKey[].name`（含 `field_` 前缀；系统字段如 `create_time` 原样） 
+3. `fieldKey` = `{datasetId}.{sourceId}.{fieldsKey.name}`，三段齐全 
+4. 保存前对**每一个** Field 做 `byName.has(name)`；任一失败 → **中止保存**，禁止带病落库 
+
+---
+
+## 三、保存后强制回读校验（交付门禁）
+
+`getReportDevInfo` 后，对每个 `cellType === 'Field'`：
+
+```javascript
+function assertFieldBindExact(devFields, fieldsKey) {
+ const legal = new Set(fieldsKey.map(f => f.name));
+ const fieldCells = devFields.filter(f => f.cellType === 'Field');
+ if (!fieldCells.length) throw new Error('无 Field 单元格');
+ for (const f of fieldCells) {
+ const last = String(f.fieldKey || '').split('.')[2] || '';
+ if (!f.name || !legal.has(f.name)) {
+ throw new Error(`字段匹配失败 name=${f.name} text=${f.text}`);
+ }
+ if (last !== f.name || !legal.has(last)) {
+ throw new Error(`fieldKey 末段不在 fieldsKey: ${f.fieldKey}`);
+ }
+ // 裸雪花：若 fieldsKey 里已有 field_xxx，则禁止用裸名；否则先查 addDataset 是否注册错
+ }
+}
+```
+
+| 检查 | 失败即 FAIL |
+|------|-------------|
+| 每个 Field 的 `name ∈ fieldsKey.name` | ✅ |
+| `fieldKey` 末段 === `name` | ✅ |
+| 普通应用：fieldsKey 业务字段含 `field_*`（注册门禁） | ✅ 见 `add-dataset-registration-guide.md` |
+| Field 数量 ≥ 需求列数 | ✅ |
+| **单元格文案 === 绑定字段真实显示名**（否则须用户确认） | ⚠ `verify bind` 列出 `display_mismatch` |
+| **同 sourceId 只挂 1 个数据集**（否则左侧重复分组） | ⚠ `verify bind` 列出 `duplicate_dataset_mount` |
+
+`e10-cli report verify bind <reportId> [appId] [--strict]`：门禁失败 exit 1；`--strict` 时「待用户确认项」exit 2。
+
+**未通过校验 → 须修正并告知用户**；可与「已交付的设计器链接」并行：先给链接（见 `report-delivery-contract.md` §〇），校验失败再补丁修复，**禁止**为等校验而拖延首轮地址。
+
+---
+
+## 四、故障对照
+
+| 现象 | 根因 | 处理 |
+|------|------|------|
+| 设计器有 Field 格，预览/取数无数据或字段空白 | `name` 为裸 ID，缺 `field_` | 按 fieldsKey.name 重绑并 saveReportDevInfo |
+| **手动加的数据集有 `field_`，API 加的没有** | **addDataset 用了 form+appId，不是设计器 LOGIC** | 按 `add-dataset-registration-guide.md` del 后重建 |
+| **单元格表头文案 ≠ 属性面板字段名**（如「姓名」实为「标题」） | 旧逻辑把无匹配列**兜底到系统字段** | 改为 `exit 4` 让用户指定；存量报表用 `fieldMap`/重绑修复 |
+| **左侧出现重复数据源分组** | 同 sourceId 被重复 `addDataset` 挂载 + 画布游离单元格引用 | 先改绑/清单元格再 `delDataset`；见 `dataset-sidebar-ops-guide.md §5.3` |
+| `matchByName=false`（自检） | 同上 / 用了显示名 | 强制走 §二 resolve |
+| 部分列有数据部分没有 | 个别列 name 写错 | 逐列对照 fieldsKey |
+| fieldsKey 为空 | 未传 `isFront=true` 或 datasetId 错 | 修正后再绑定，禁止用空列表继续 |
+
+---
+
+## 五、与现有文档关系
+
+| 文档 | 关系 |
+|------|------|
+| **`add-dataset-registration-guide.md`** | **addDataset 与设计器对齐；fieldsKey 无 `field_` 的根因** |
+| `api-report-build-fast-path.md` | 建表流程 §三/§五 引用本节；保存门禁 |
+| `cross-dataset-filter-guide.md` | leftFilter 的 fieldKey 末段同样必须是 fieldsKey.name |
+| `e10-cli report verify bind` | 保存后一键校验（必跑） |
+| `e10-cli report validate` | 离线 JSON 形态检查；**线上以本节 + verify_field_bind 为准** |
+
+---
+
+## 六、Agent 执行清单（复制即用）
+
+- [ ] `sourceName` 为 `{表单名}(业务模块)`（回显名），不是裸表单名（`build spec` 已自动补后缀）
+- [ ] 本报表**已有同 sourceId 数据集 → 复用**，不重复 `addDataset`
+- [ ] `addDataset` 为 `LOGIC` + `weaver-ebuilder-form-service`（非共享表特例）
+- [ ] `fieldsKey` 业务字段已含 `field_*`（否则先修注册）
+- [ ] `fieldsAndOriginFields?isFront=true` 已拿到非空 `fieldsKey`
+- [ ] 每个需求列：`显示名 → fieldsKey.name` 映射表已打印确认（`build spec` 输出 `fieldBindings`）
+- [ ] **任一无精确命中 → exit 4 时，把 `candidates`/`allFields` 交给用户指定字段，禁止自行猜**
+- [ ] 同 sourceId 多实例时绑的是 LOGIC/`field_*` 那条
+- [ ] `name` ∈ 当前 dataset 的 fieldsKey（勿臆造 / 勿手工补 `field_`）
+- [ ] 保存前 `assert` 全部通过
+- [ ] 保存后 `verify_field_bind.js` / 等价断言全部通过
+- [ ] 未通过则**不交付**