weaver-e10-builder 1.6.16 → 1.7.0

package/skill-docs/references/report/formula-cell-api-guide.md

@@ -1,325 +1,325 @@
-# 公式单元格 API 写入规范
-
-> **适用场景**：通过 API / 脚本写入报表 workbook（`saveReportWithCacheConfig` + `saveReportDevInfo`），或生成含 Formula 单元格的 ReportProps JSON。
-> **权威原则**：设计器手动保存的格式为准；文档与脚本冲突时以 `getReportDevInfo` 回读结果为准。
-
----
-
-## 一、问题现象
-
-设计器里输入 `=IF(J3=0,0,L3/J3)` 能正常保存并展示，但 **API 脚本写入「相同公式」可能导致设计器整页空白**。
-
-**根因不是 IF 函数被禁用**，而是持久化字段格式与手动保存不一致：
-
-| 字段 | 设计器手动保存 ✅ | 脚本 API 常见错误 ❌ |
-|------|-------------------|----------------------|
-| `cellText` / 顶层 `formula` | `IF(J3=0,0,L3/J3)` **无前导 `=`** | `=IF(J3=0,0,L3/J3)` **带 `=`** |
-| `countType` | `count` | `none` |
-| `displayType` | `Group` | `List` |
-| `groupType` | `null` | `none` |
-| `style.formatter` | 空字符串 | `0.00%`、`General` 等 |
-
-平台源码（`EdcReportDevDesignServiceImpl`）从 workbook 提取 Formula 时：
-
-```java
-if (field.getCellType() == Formula) {
-    field.setCellText(cell.getFormula());  // 原样写入 DB
-}
-```
-
-设计器保存时会去掉 leading `=`；脚本若 workbook 顶层 `formula` 带 `=`，DB 里 `cellText` 也会带 `=`。
-设计器再次加载时 SpreadJS 可能再补 `=` → 变成 `==IF(...)` 或解析失败 → **整页空白**。
-
-DB 种子数据同样 **不带 `=`**：`'IFERROR(G5/F5,"--")'`、`'SUM(F5)'`。
-
----
-
-## 二、Agent 必遵守则（硬约束）
-
-生成或修改含公式单元格的报表时，**必须**同时满足：
-
-1. **`cellText` 与 workbook 顶层 `formula` 均不带前导 `=`**
-   - 设计器输入：`=IF(J3=0,0,L3/J3)`
-   - API 存储：`IF(J3=0,0,L3/J3)`
-   - 写入前统一：`bare = formula_expr.lstrip("=")`
-
-2. **`countType` 必须为 `count`**（勿用 `none`）
-
-3. **`displayType` 必须为 `Group`**（分组报表中的公式格；勿用 `List`）
-
-4. **`groupType` 必须为 `null`**（JSON 中写 `null`，勿写 `"none"`）
-
-5. **`expandType` 为 `NoExpand`**
-
-6. **`style.formatter` 为空字符串**（与手动保存对齐；百分比展示依赖公式结果或后续在设计器设格式，脚本勿擅自写 `0.00%`）
-
-7. **★ 父格坐标（用户规则）**：公式格的父格 **通常与它引用的、参与计算的字段父格保持统一**
-   —— 两者指向 **同一个单元格**，即被引用字段区域的 **根格**。判定：
-   - 先把每个被引用字段的父格 **沿「左父格链」归一到区域根格**（`B3←A3` → A3；`H3←G3←…←A3` → A3）；
-   - 归一后 **全部落在同一区域** → 取该 **区域根格**（如 A3）。与「合计行左父格指向最前面文本格」同一口径。
-   - 归一后 **分属不同区域（跨源）** → 机器判不了，人工指定。
-   - ⚠️ **只引用 1 个字段时也必须归一**：`IFERROR(H3-TODAY(),"")` 里 H3 的直接父格是 G3，但 G3 自己挂在 A3 下，
-     真正随记录扩展的锚点是根格 **A3** —— 直接用 G3 会让同一区域的公式因「引用字段个数不同」得到不同父格，规则自相矛盾。
-   实操：把选定父格的 `leftX/leftY` 原样写到公式格上（0-based；例 `leftX=2, leftY=5` 对应 F 列）。
-   父格不一致的后果：行 / 列扩展时公式格与数据**错位**，或整块公式不随行复制。
-   自查 / 对齐：`e10-cli report formula parent check`（只读，exit 3 = 不一致）· `formula parent align [--apply]`。
-
-8. **双保存**：`saveReportWithCacheConfig` + `saveReportDevInfo`，保存后用 `getReportDevInfo` 回读验证
-
-9. **除零保护**：占比/达成率类公式推荐 `IF(分母=0,0,分子/分母)`，与设计器手动写法一致
-
----
-
-## 三、workbook 单元格结构（dataTable）
-
-Formula 单元格在 workbook `dataTable[row][col]` 中的标准结构：
-
-```json
-{
-  "formula": "IF(J3=0,0,L3/J3)",
-  "style": {
-    "hAlign": 1,
-    "vAlign": 1,
-    "formatter": "",
-    "cellType": {
-      "typeName": "FormulaCellType",
-      "editorType": 1,
-      "cellType": "Formula",
-      "cellText": "IF(J3=0,0,L3/J3)",
-      "displayType": "Group",
-      "countType": "count",
-      "groupType": null,
-      "expandType": "NoExpand",
-      "leftX": 2,
-      "leftY": 5,
-      "topX": -1,
-      "topY": -1,
-      "refX": -1,
-      "refY": -1,
-      "subordination": ["", ""],
-      "formatterType": [],
-      "orderType": "no",
-      "isActiveParent": false,
-      "arrowType": "None",
-      "textDirection": "FromLeftToRight",
-      "allowOverflow": true,
-      "hiddenContext": "0",
-      "transSelectOptions": [],
-      "browserType": [],
-      "thumbnail": "NoDisplay"
-    }
-  },
-  "tag": { "formatterType": ["common"] }
-}
-```
-
-**注意**：顶层 `formula` 与 `style.cellType.cellText` **内容相同且均无前导 `=`**。
-
----
-
-## 四、参考实现 `make_formula()`
-
-```python
-def make_formula(formula_expr, formatter=""):
-    """构建 Formula 单元格，格式对齐设计器手动保存。"""
-    bare = formula_expr.lstrip("=")
-    ct = {
-        "allowOverflow": True,
-        "typeName": "FormulaCellType",
-        "editorType": 1,
-        "leftX": ROOT_ROW,
-        "leftY": ROOT_COL,
-        "topX": -1,
-        "topY": -1,
-        "refX": -1,
-        "refY": -1,
-        "expandType": "NoExpand",
-        "displayType": "Group",
-        "cellType": "Formula",
-        "cellText": bare,
-        "transSelectOptions": [],
-        "browserType": [],
-        "thumbnail": "NoDisplay",
-        "hiddenContext": "0",
-        "orderType": "no",
-        "formatterType": [],
-        "subordination": ["", ""],
-        "countType": "count",
-        "groupType": None,
-        "isActiveParent": False,
-        "arrowType": "None",
-        "textDirection": "FromLeftToRight",
-    }
-    fmt = formatter if formatter is not None else ""
-    return {
-        "style": {"hAlign": 1, "vAlign": 1, "formatter": fmt, "cellType": ct},
-        "formula": bare,
-        "tag": {"formatterType": ["common"]},
-    }
-```
-
-
----
-
-## 五、公式表达式规范
-
-### 5.1 单元格引用
-
-- 使用 Excel A1 风格：`J3`、`L3`、`AA3`
-- 行号与数据行一致（通常第 3 行即 `x=2` 的数据行写 `...3`）
-- 引用同报表内 Field 汇总格，不引用数据集字段名
-
-### 5.2 常用模式
-
-| 场景 | 设计器输入 | API 存储（无前导 `=`） |
-|------|-----------|------------------------|
-| 达成率 | `=IF(J3=0,0,L3/J3)` | `IF(J3=0,0,L3/J3)` |
-| 业绩占比 | `=IF(L3=0,0,M3/L3)` | `IF(L3=0,0,M3/L3)` |
-| 合计 | `=SUM(F4:F10)` | `SUM(F4:F10)` |
-| 安全除法 | `=IFERROR(G5/F5,"--")` | `IFERROR(G5/F5,"--")` |
-
-### 5.3 IF / IFERROR
-
-- **IF、IFERROR 均允许**通过 API 写入；此前「IF 导致空白」是格式错误，不是函数限制
-- 占比类公式 **推荐** `IF(分母=0,0,...)` 而非裸除法
-
-### 5.4 禁止写法
-
-| 禁止 | 原因 |
-|------|------|
-| `cellText: "=SUM(A1)"` | 双 `=` 导致 SpreadJS 解析失败 |
-| `countType: "none"` | 与手动保存不一致，可能引发展示异常 |
-| `displayType: "List"` | 公式格应为 `Group` |
-| `groupType: "none"` | 应为 `null` |
-| 仅写 `style.cellType.cellText` 不写顶层 `formula` | workbook 与设计器可能不同步 |
-
----
-
-## 六、验证清单
-
-写入公式后，Agent **必须**执行：
-
-### 6.1 `getReportDevInfo` 回读
-
-对每个 Formula 格（如 K3 → `x=2, y=10`）检查：
-
-- [ ] `cellType` 为 `Formula`
-- [ ] `cellText` **不以 `=` 开头**
-- [ ] `countType` 为 `count`
-- [ ] `displayType` 为 `Group`
-- [ ] `groupType` 为 `null`
-- [ ] 公式内容与预期一致（如 `IF(J3=0,0,L3/J3)`）
-
-### 6.2 保存接口
-
-- [ ] `saveReportWithCacheConfig` 返回 200
-- [ ] `saveReportDevInfo` 返回 200
-- [ ] `checkSave` 返回 200（可选）
-
-### 6.3 设计器 smoke test
-
-- [ ] 刷新设计器 URL 后页面非空白
-- [ ] 公式格可点击编辑，显示为 `=IF(...)`（设计器 UI 会自动加 `=`）
-- [ ] 预览/解析后公式列有数值
-
-### 6.4 本地预检
-
-```bash
-e10-cli report py validate <配置文件路径>
-```
-
-脚本会对 Formula 单元格检查前导 `=`、`countType`、`displayType` 等（见脚本内 `validate_formula_fields`）。
-
----
-
-## 七、与父格 / 跨数据集筛选的关系
-
-- 公式格 **不参与** subordination / leftFilterField（通常 `subordination: ["", ""]`）
-- ★ **父格一致性（用户规则）**：公式格父格应与其**引用的、参与计算的字段**父格 **统一为同一个单元格**。
-  判定：把被引用字段的父格沿左父格链**归一到区域根格**后 —— **同区域** → 取该根格（如 A3，与合计行口径一致）；
-  **不同区域（跨源）** → 人工指定。只引用 1 个字段时同样要归一（H3 的直接父格 G3 挂在 A3 下 → 取 A3）。
-  父格不一致会导致扩展时错位、整块不随行复制。
-  只读自查：`e10-cli report formula parent check --report-id <id> --app-id <id>`（解析公式引用 A1 坐标 → 比对 leftX/leftY，不一致 exit 3）；
-  批量对齐：`e10-cli report formula parent align --report-id <id> --app-id <id> [--apply]`（走构建态通道，Formula 格存活）；
-  定点改：`e10-cli report fix parent --set-parent "x,y=L,T"`（**只改左父格**）。
-- ★★★ **扩展数据带内公式格「四件套」—— 缺一即乱码**（注意点 BUILD-46 / BUILD-49）
-  公式格左父格**必须直接挂「块入口格」**（数据带第一格），**禁止链到前一列公式格** —— 否则扩展实例
-  **引用解析错位**：**预览第一行正常（或 `#DIV/0!`）、后续行渲染乱码**。
-
-  | # | 键 | 必须值 | 缺了会怎样（症状 / 注意点） |
-  |---|----|--------|--------------------------|
-  | ① | `leftX`/`leftY` | 直接挂**块入口格** | 扩展时公式格与数据错位 / 整块不随行复制 |
-  | ② | `refX`/`refY` | `(-1,-1)` | 服务端 int 默认补 **0**，回读常带 `0,0` → 被原样复制 → 后续行渲染乱码（**BUILD-46**） |
-  | ③ | `expandType` | `NoExpand`（**禁 `Vertical`**） | `Vertical` 让公式格**自成扩展实例** → 引擎重映射错位（**BUILD-49**） |
-  | ④ | `subordination` | `["",""]` | API 构建默认 `[]` → 公式引用区间**横跨另一公式格**时依赖链建不起来 → **浏览器端**解析进隐藏模板区 → `p1900rc1900nt` 乱码（**BUILD-49**） |
-
-  - **④ 是本次最关键的一条**：设计器写过的公式格**恒为 `["",""]`**；`[]` 只在 API 构建里出现。
-    典型引爆点：公式区间（如 `SUM(AE16:AG16)`）里含**另一个公式格**（AG16）→ `[]` 让展开引擎
-    建不起引用依赖链 → 浏览器端渲染出 `p1900rc1900nt` 之类字面量。
-  - **落库后处理路径** = `wb.sheets[*].data.dataTable[行][列].style.cellType`（`typeName=FormulaCellType`，
-    **不是** `cells`）。构建层的 `normalizeFormulaCellShape()`（构建态出口）与
-    `saveReportDevInfoAuto` 防御层 **R7 / R8** 已自动归位 ①②③④（dry-run 安全）。
-  - ⚠️ **只对 Formula 格强制**：`Field` 格的 `subordination` 承载**跨数据集绑定**，绝不能动
-    （见 `cross-dataset-filter-guide.md`）。
-  - **行号规则**（重申）：引用**带自身行** = `x+1`；**跨带引用** = **目标带** `x+1`。
-  - **`{r}` 占位符藏在两处**：cell 顶层 `formula` 键 + `style.cellType.cellText`。替换必须
-    **两处都做**，且用 `split/join` **全局替换**（只 replace 第一处会留下不一致）。
-  - **蓝图 diff 方法论**：渲染异常时，与「用户认可的正常报表」`getReportDevInfo` 回读做**逐字段 diff**
-    （`left` / `refX` / `refY` / **`subordination`** / **`style.formatter`**）实证定位，**禁止猜测**。
-    ★ diff 键清单**必须含 `subordination` 与 `style`** —— 历次两轮乱码定位正是漏了这两个键才误判「两端等价」（BUILD-53）。
-  - 体检 / 修复：`e10-cli report formula parent check|align --report-id <id> --app-id <id> [--apply]`（align 顺带归 `refX/refY=-1`）。
-- ★★ **上父格（topX/topY）—— 另一条轴，别和左父格混**
-  左父格管「行（纵向扩展）」，上父格管「列（横向扩展）」。判据 = **该格是否必须随横向扩展列保持相对位置**。
-  - 交叉表里位于「**横向扩展列右侧**」的合计 / 汇总列：上父格应**显式指向本列列头格**。
-    验证（`chl测试002` 交叉表 `1324295299769475074`：A 序号 | B 学院 | C 专业 | D 年级(横向扩展) | E 合计）：
-    `E2`/`E3` 上父格 = `E1`（即 `--set-top-parent "1,4=0,4"` / `"2,4=0,4"`）；
-    `D2`/`D3` 上父格 = `D1`（`(0,3)`，跟随年级列）。
-  - 纯纵向的格（如 `A2` 序号）上父格保持**默认 `-1,-1`** —— 它不参与横向扩展，加了反而错。
-  - 症状：列头被横向扩展推走、合计列留在原地 → 与数据列错位。
-  定点改上父格：`e10-cli report formula top --report-id <id> --app-id <id> --set-top-parent "x,y=topX,topY" [--apply]`
-  （走构建态通道、Formula 格存活、落库后逐格回读；`dump cells` 可回看每格 top）。
-  坐标口径：`x` = 行（0 基），`y` = 列（0 基）——即 `A1` 记法 `E2` → `(1,4)`。
-- 公式引用的是 **同报表内已配置好的 Field 汇总格**（如 L3 总业绩、J3 指标）
-- 被引用的 Field 格若跨数据集，须先按 `cross-dataset-filter-guide.md` 配好筛选；公式本身不再重复配 fieldKey
-
-### 7.1 设计器保存的规范化副作用（API 复刻设计器状态时必须对齐）
-
-设计器**每次保存**都会把公式格（以及整数列）归一成下面这套值。API 复刻「设计器写过的格」时，
-**必须产出同样的值** —— 否则 diff 会显示差异，渲染路径也可能不同：
-
-| 键 | 设计器归一后的值 | API 常见错值 |
-|----|-----------------|-------------|
-| `groupType` | `null`（JSON 里就是 `null`） | `"none"` 或省略 |
-| `countType` | 公式格 / 整数列 → `none`；计数列 → `count` | 一律 `count` |
-| `subordination` | `["",""]` | `[]` |
-| `style.formatter` | 合法格式串（`General` / `0.00%` / `￥#,##0.00` …） | 短码 `common` / `percent` |
-| `expandType` | `NoExpand` | `Vertical` |
-
-> ★ 与 `getReportDevInfo` 回读对照时，**这套键是最容易被漏比的部分**（见 §七 diff 键清单）。
-> 脚本侧统一由 构建层的 **R7 / R8 / R9** 归位。
-
----
-
-## 八、EBU 经营报表示例（37 列）
-
-| 列 | 字段 | 公式（API 存储，无前导 `=`） |
-|----|------|------------------------------|
-| K | 达成率 | `IF(J3=0,0,L3/J3)` |
-| R | 新客户业绩占比 | `IF(L3=0,0,M3/L3)` |
-| S | 纯专项业绩占比 | `IF(L3=0,0,N3/L3)` |
-| T | 信创客户业绩占比 | `IF(L3=0,0,O3/L3)` |
-| X | 新签合同个数占比 | `IF(V3=0,0,W3/V3)` |
-| Z | 纯专项合同个数占比 | `IF(V3=0,0,Y3/V3)` |
-| AB | 信创合同个数占比 | `IF(V3=0,0,AA3/V3)` |
-
-报表 ID 示例：`1304979556231593985`
-
----
-
-## 九、相关文档
-
-- `SKILL.md` — 能力一步骤 6.2 公式配置
-- `ai-report-workflow.md` §六 — 工作流中的公式规则
-- `report-config-schema.md` §2.5 — Formula Schema
-- `cross-dataset-filter-guide.md` — 跨数据集筛选（与公式格配合）
-- `report-building-guide.md` §8.2 — 占比/同环比为前端 SpreadJS 计算
+# 公式单元格 API 写入规范
+
+> **适用场景**：通过 API / 脚本写入报表 workbook（`saveReportWithCacheConfig` + `saveReportDevInfo`），或生成含 Formula 单元格的 ReportProps JSON。
+> **权威原则**：设计器手动保存的格式为准；文档与脚本冲突时以 `getReportDevInfo` 回读结果为准。
+
+---
+
+## 一、问题现象
+
+设计器里输入 `=IF(J3=0,0,L3/J3)` 能正常保存并展示，但 **API 脚本写入「相同公式」可能导致设计器整页空白**。
+
+**根因不是 IF 函数被禁用**，而是持久化字段格式与手动保存不一致：
+
+| 字段 | 设计器手动保存 ✅ | 脚本 API 常见错误 ❌ |
+|------|-------------------|----------------------|
+| `cellText` / 顶层 `formula` | `IF(J3=0,0,L3/J3)` **无前导 `=`** | `=IF(J3=0,0,L3/J3)` **带 `=`** |
+| `countType` | `count` | `none` |
+| `displayType` | `Group` | `List` |
+| `groupType` | `null` | `none` |
+| `style.formatter` | 空字符串 | `0.00%`、`General` 等 |
+
+平台源码（`EdcReportDevDesignServiceImpl`）从 workbook 提取 Formula 时：
+
+```java
+if (field.getCellType() == Formula) {
+    field.setCellText(cell.getFormula());  // 原样写入 DB
+}
+```
+
+设计器保存时会去掉 leading `=`；脚本若 workbook 顶层 `formula` 带 `=`，DB 里 `cellText` 也会带 `=`。
+设计器再次加载时 SpreadJS 可能再补 `=` → 变成 `==IF(...)` 或解析失败 → **整页空白**。
+
+DB 种子数据同样 **不带 `=`**：`'IFERROR(G5/F5,"--")'`、`'SUM(F5)'`。
+
+---
+
+## 二、Agent 必遵守则（硬约束）
+
+生成或修改含公式单元格的报表时，**必须**同时满足：
+
+1. **`cellText` 与 workbook 顶层 `formula` 均不带前导 `=`**
+   - 设计器输入：`=IF(J3=0,0,L3/J3)`
+   - API 存储：`IF(J3=0,0,L3/J3)`
+   - 写入前统一：`bare = formula_expr.lstrip("=")`
+
+2. **`countType` 必须为 `count`**（勿用 `none`）
+
+3. **`displayType` 必须为 `Group`**（分组报表中的公式格；勿用 `List`）
+
+4. **`groupType` 必须为 `null`**（JSON 中写 `null`，勿写 `"none"`）
+
+5. **`expandType` 为 `NoExpand`**
+
+6. **`style.formatter` 为空字符串**（与手动保存对齐；百分比展示依赖公式结果或后续在设计器设格式，脚本勿擅自写 `0.00%`）
+
+7. **★ 父格坐标（用户规则）**：公式格的父格 **通常与它引用的、参与计算的字段父格保持统一**
+   —— 两者指向 **同一个单元格**，即被引用字段区域的 **根格**。判定：
+   - 先把每个被引用字段的父格 **沿「左父格链」归一到区域根格**（`B3←A3` → A3；`H3←G3←…←A3` → A3）；
+   - 归一后 **全部落在同一区域** → 取该 **区域根格**（如 A3）。与「合计行左父格指向最前面文本格」同一口径。
+   - 归一后 **分属不同区域（跨源）** → 机器判不了，人工指定。
+   - ⚠️ **只引用 1 个字段时也必须归一**：`IFERROR(H3-TODAY(),"")` 里 H3 的直接父格是 G3，但 G3 自己挂在 A3 下，
+     真正随记录扩展的锚点是根格 **A3** —— 直接用 G3 会让同一区域的公式因「引用字段个数不同」得到不同父格，规则自相矛盾。
+   实操：把选定父格的 `leftX/leftY` 原样写到公式格上（0-based；例 `leftX=2, leftY=5` 对应 F 列）。
+   父格不一致的后果：行 / 列扩展时公式格与数据**错位**，或整块公式不随行复制。
+   自查 / 对齐：`e10-cli report formula parent check`（只读，exit 3 = 不一致）· `formula parent align [--apply]`。
+
+8. **双保存**：`saveReportWithCacheConfig` + `saveReportDevInfo`，保存后用 `getReportDevInfo` 回读验证
+
+9. **除零保护**：占比/达成率类公式推荐 `IF(分母=0,0,分子/分母)`，与设计器手动写法一致
+
+---
+
+## 三、workbook 单元格结构（dataTable）
+
+Formula 单元格在 workbook `dataTable[row][col]` 中的标准结构：
+
+```json
+{
+  "formula": "IF(J3=0,0,L3/J3)",
+  "style": {
+    "hAlign": 1,
+    "vAlign": 1,
+    "formatter": "",
+    "cellType": {
+      "typeName": "FormulaCellType",
+      "editorType": 1,
+      "cellType": "Formula",
+      "cellText": "IF(J3=0,0,L3/J3)",
+      "displayType": "Group",
+      "countType": "count",
+      "groupType": null,
+      "expandType": "NoExpand",
+      "leftX": 2,
+      "leftY": 5,
+      "topX": -1,
+      "topY": -1,
+      "refX": -1,
+      "refY": -1,
+      "subordination": ["", ""],
+      "formatterType": [],
+      "orderType": "no",
+      "isActiveParent": false,
+      "arrowType": "None",
+      "textDirection": "FromLeftToRight",
+      "allowOverflow": true,
+      "hiddenContext": "0",
+      "transSelectOptions": [],
+      "browserType": [],
+      "thumbnail": "NoDisplay"
+    }
+  },
+  "tag": { "formatterType": ["common"] }
+}
+```
+
+**注意**：顶层 `formula` 与 `style.cellType.cellText` **内容相同且均无前导 `=`**。
+
+---
+
+## 四、参考实现 `make_formula()`
+
+```python
+def make_formula(formula_expr, formatter=""):
+    """构建 Formula 单元格，格式对齐设计器手动保存。"""
+    bare = formula_expr.lstrip("=")
+    ct = {
+        "allowOverflow": True,
+        "typeName": "FormulaCellType",
+        "editorType": 1,
+        "leftX": ROOT_ROW,
+        "leftY": ROOT_COL,
+        "topX": -1,
+        "topY": -1,
+        "refX": -1,
+        "refY": -1,
+        "expandType": "NoExpand",
+        "displayType": "Group",
+        "cellType": "Formula",
+        "cellText": bare,
+        "transSelectOptions": [],
+        "browserType": [],
+        "thumbnail": "NoDisplay",
+        "hiddenContext": "0",
+        "orderType": "no",
+        "formatterType": [],
+        "subordination": ["", ""],
+        "countType": "count",
+        "groupType": None,
+        "isActiveParent": False,
+        "arrowType": "None",
+        "textDirection": "FromLeftToRight",
+    }
+    fmt = formatter if formatter is not None else ""
+    return {
+        "style": {"hAlign": 1, "vAlign": 1, "formatter": fmt, "cellType": ct},
+        "formula": bare,
+        "tag": {"formatterType": ["common"]},
+    }
+```
+
+
+---
+
+## 五、公式表达式规范
+
+### 5.1 单元格引用
+
+- 使用 Excel A1 风格：`J3`、`L3`、`AA3`
+- 行号与数据行一致（通常第 3 行即 `x=2` 的数据行写 `...3`）
+- 引用同报表内 Field 汇总格，不引用数据集字段名
+
+### 5.2 常用模式
+
+| 场景 | 设计器输入 | API 存储（无前导 `=`） |
+|------|-----------|------------------------|
+| 达成率 | `=IF(J3=0,0,L3/J3)` | `IF(J3=0,0,L3/J3)` |
+| 业绩占比 | `=IF(L3=0,0,M3/L3)` | `IF(L3=0,0,M3/L3)` |
+| 合计 | `=SUM(F4:F10)` | `SUM(F4:F10)` |
+| 安全除法 | `=IFERROR(G5/F5,"--")` | `IFERROR(G5/F5,"--")` |
+
+### 5.3 IF / IFERROR
+
+- **IF、IFERROR 均允许**通过 API 写入；此前「IF 导致空白」是格式错误，不是函数限制
+- 占比类公式 **推荐** `IF(分母=0,0,...)` 而非裸除法
+
+### 5.4 禁止写法
+
+| 禁止 | 原因 |
+|------|------|
+| `cellText: "=SUM(A1)"` | 双 `=` 导致 SpreadJS 解析失败 |
+| `countType: "none"` | 与手动保存不一致，可能引发展示异常 |
+| `displayType: "List"` | 公式格应为 `Group` |
+| `groupType: "none"` | 应为 `null` |
+| 仅写 `style.cellType.cellText` 不写顶层 `formula` | workbook 与设计器可能不同步 |
+
+---
+
+## 六、验证清单
+
+写入公式后，Agent **必须**执行：
+
+### 6.1 `getReportDevInfo` 回读
+
+对每个 Formula 格（如 K3 → `x=2, y=10`）检查：
+
+- [ ] `cellType` 为 `Formula`
+- [ ] `cellText` **不以 `=` 开头**
+- [ ] `countType` 为 `count`
+- [ ] `displayType` 为 `Group`
+- [ ] `groupType` 为 `null`
+- [ ] 公式内容与预期一致（如 `IF(J3=0,0,L3/J3)`）
+
+### 6.2 保存接口
+
+- [ ] `saveReportWithCacheConfig` 返回 200
+- [ ] `saveReportDevInfo` 返回 200
+- [ ] `checkSave` 返回 200（可选）
+
+### 6.3 设计器 smoke test
+
+- [ ] 刷新设计器 URL 后页面非空白
+- [ ] 公式格可点击编辑，显示为 `=IF(...)`（设计器 UI 会自动加 `=`）
+- [ ] 预览/解析后公式列有数值
+
+### 6.4 本地预检
+
+```bash
+e10-cli report py validate <配置文件路径>
+```
+
+脚本会对 Formula 单元格检查前导 `=`、`countType`、`displayType` 等（见脚本内 `validate_formula_fields`）。
+
+---
+
+## 七、与父格 / 跨数据集筛选的关系
+
+- 公式格 **不参与** subordination / leftFilterField（通常 `subordination: ["", ""]`）
+- ★ **父格一致性（用户规则）**：公式格父格应与其**引用的、参与计算的字段**父格 **统一为同一个单元格**。
+  判定：把被引用字段的父格沿左父格链**归一到区域根格**后 —— **同区域** → 取该根格（如 A3，与合计行口径一致）；
+  **不同区域（跨源）** → 人工指定。只引用 1 个字段时同样要归一（H3 的直接父格 G3 挂在 A3 下 → 取 A3）。
+  父格不一致会导致扩展时错位、整块不随行复制。
+  只读自查：`e10-cli report formula parent check --report-id <id> --app-id <id>`（解析公式引用 A1 坐标 → 比对 leftX/leftY，不一致 exit 3）；
+  批量对齐：`e10-cli report formula parent align --report-id <id> --app-id <id> [--apply]`（走构建态通道，Formula 格存活）；
+  定点改：`e10-cli report fix parent --set-parent "x,y=L,T"`（**只改左父格**）。
+- ★★★ **扩展数据带内公式格「四件套」—— 缺一即乱码**（注意点 BUILD-46 / BUILD-49）
+  公式格左父格**必须直接挂「块入口格」**（数据带第一格），**禁止链到前一列公式格** —— 否则扩展实例
+  **引用解析错位**：**预览第一行正常（或 `#DIV/0!`）、后续行渲染乱码**。
+
+  | # | 键 | 必须值 | 缺了会怎样（症状 / 注意点） |
+  |---|----|--------|--------------------------|
+  | ① | `leftX`/`leftY` | 直接挂**块入口格** | 扩展时公式格与数据错位 / 整块不随行复制 |
+  | ② | `refX`/`refY` | `(-1,-1)` | 服务端 int 默认补 **0**，回读常带 `0,0` → 被原样复制 → 后续行渲染乱码（**BUILD-46**） |
+  | ③ | `expandType` | `NoExpand`（**禁 `Vertical`**） | `Vertical` 让公式格**自成扩展实例** → 引擎重映射错位（**BUILD-49**） |
+  | ④ | `subordination` | `["",""]` | API 构建默认 `[]` → 公式引用区间**横跨另一公式格**时依赖链建不起来 → **浏览器端**解析进隐藏模板区 → `p1900rc1900nt` 乱码（**BUILD-49**） |
+
+  - **④ 是本次最关键的一条**：设计器写过的公式格**恒为 `["",""]`**；`[]` 只在 API 构建里出现。
+    典型引爆点：公式区间（如 `SUM(AE16:AG16)`）里含**另一个公式格**（AG16）→ `[]` 让展开引擎
+    建不起引用依赖链 → 浏览器端渲染出 `p1900rc1900nt` 之类字面量。
+  - **落库后处理路径** = `wb.sheets[*].data.dataTable[行][列].style.cellType`（`typeName=FormulaCellType`，
+    **不是** `cells`）。构建层的 `normalizeFormulaCellShape()`（构建态出口）与
+    `saveReportDevInfoAuto` 防御层 **R7 / R8** 已自动归位 ①②③④（dry-run 安全）。
+  - ⚠️ **只对 Formula 格强制**：`Field` 格的 `subordination` 承载**跨数据集绑定**，绝不能动
+    （见 `cross-dataset-filter-guide.md`）。
+  - **行号规则**（重申）：引用**带自身行** = `x+1`；**跨带引用** = **目标带** `x+1`。
+  - **`{r}` 占位符藏在两处**：cell 顶层 `formula` 键 + `style.cellType.cellText`。替换必须
+    **两处都做**，且用 `split/join` **全局替换**（只 replace 第一处会留下不一致）。
+  - **蓝图 diff 方法论**：渲染异常时，与「用户认可的正常报表」`getReportDevInfo` 回读做**逐字段 diff**
+    （`left` / `refX` / `refY` / **`subordination`** / **`style.formatter`**）实证定位，**禁止猜测**。
+    ★ diff 键清单**必须含 `subordination` 与 `style`** —— 历次两轮乱码定位正是漏了这两个键才误判「两端等价」（BUILD-53）。
+  - 体检 / 修复：`e10-cli report formula parent check|align --report-id <id> --app-id <id> [--apply]`（align 顺带归 `refX/refY=-1`）。
+- ★★ **上父格（topX/topY）—— 另一条轴，别和左父格混**
+  左父格管「行（纵向扩展）」，上父格管「列（横向扩展）」。判据 = **该格是否必须随横向扩展列保持相对位置**。
+  - 交叉表里位于「**横向扩展列右侧**」的合计 / 汇总列：上父格应**显式指向本列列头格**。
+    验证（`chl测试002` 交叉表 `1324295299769475074`：A 序号 | B 学院 | C 专业 | D 年级(横向扩展) | E 合计）：
+    `E2`/`E3` 上父格 = `E1`（即 `--set-top-parent "1,4=0,4"` / `"2,4=0,4"`）；
+    `D2`/`D3` 上父格 = `D1`（`(0,3)`，跟随年级列）。
+  - 纯纵向的格（如 `A2` 序号）上父格保持**默认 `-1,-1`** —— 它不参与横向扩展，加了反而错。
+  - 症状：列头被横向扩展推走、合计列留在原地 → 与数据列错位。
+  定点改上父格：`e10-cli report formula top --report-id <id> --app-id <id> --set-top-parent "x,y=topX,topY" [--apply]`
+  （走构建态通道、Formula 格存活、落库后逐格回读；`dump cells` 可回看每格 top）。
+  坐标口径：`x` = 行（0 基），`y` = 列（0 基）——即 `A1` 记法 `E2` → `(1,4)`。
+- 公式引用的是 **同报表内已配置好的 Field 汇总格**（如 L3 总业绩、J3 指标）
+- 被引用的 Field 格若跨数据集，须先按 `cross-dataset-filter-guide.md` 配好筛选；公式本身不再重复配 fieldKey
+
+### 7.1 设计器保存的规范化副作用（API 复刻设计器状态时必须对齐）
+
+设计器**每次保存**都会把公式格（以及整数列）归一成下面这套值。API 复刻「设计器写过的格」时，
+**必须产出同样的值** —— 否则 diff 会显示差异，渲染路径也可能不同：
+
+| 键 | 设计器归一后的值 | API 常见错值 |
+|----|-----------------|-------------|
+| `groupType` | `null`（JSON 里就是 `null`） | `"none"` 或省略 |
+| `countType` | 公式格 / 整数列 → `none`；计数列 → `count` | 一律 `count` |
+| `subordination` | `["",""]` | `[]` |
+| `style.formatter` | 合法格式串（`General` / `0.00%` / `￥#,##0.00` …） | 短码 `common` / `percent` |
+| `expandType` | `NoExpand` | `Vertical` |
+
+> ★ 与 `getReportDevInfo` 回读对照时，**这套键是最容易被漏比的部分**（见 §七 diff 键清单）。
+> 脚本侧统一由 构建层的 **R7 / R8 / R9** 归位。
+
+---
+
+## 八、EBU 经营报表示例（37 列）
+
+| 列 | 字段 | 公式（API 存储，无前导 `=`） |
+|----|------|------------------------------|
+| K | 达成率 | `IF(J3=0,0,L3/J3)` |
+| R | 新客户业绩占比 | `IF(L3=0,0,M3/L3)` |
+| S | 纯专项业绩占比 | `IF(L3=0,0,N3/L3)` |
+| T | 信创客户业绩占比 | `IF(L3=0,0,O3/L3)` |
+| X | 新签合同个数占比 | `IF(V3=0,0,W3/V3)` |
+| Z | 纯专项合同个数占比 | `IF(V3=0,0,Y3/V3)` |
+| AB | 信创合同个数占比 | `IF(V3=0,0,AA3/V3)` |
+
+报表 ID 示例：`1304979556231593985`
+
+---
+
+## 九、相关文档
+
+- `SKILL.md` — 能力一步骤 6.2 公式配置
+- `ai-report-workflow.md` §六 — 工作流中的公式规则
+- `report-config-schema.md` §2.5 — Formula Schema
+- `cross-dataset-filter-guide.md` — 跨数据集筛选（与公式格配合）
+- `report-building-guide.md` §8.2 — 占比/同环比为前端 SpreadJS 计算