weaver-work-cli 0.1.24 → 0.1.26

package/skills/weaver-e10-builder/references/report/app-datasource-lookup-guide.md

@@ -0,0 +1,230 @@
+# 应用内数据源查找（强制优先级）
+
+> **适用**：能力一/五、API 从零搭建报表时，需要把「需求里的表单/数据源名称」解析为 `sourceId`。 
+> **核心规则**：**先当前应用、后别处**；命中即停；**禁止**固定 `sleep`；**禁止**为找表启动 浏览器自动化 开应用页。
+
+---
+
+## 一、判定顺序（任务开始后第一步）
+
+| 输入 | 解析 appId | 找 sourceId |
+|------|------------|-------------|
+| **appId + 数据源名** | 直接用 | **① 应用内**（§二）→ 未命中再 **② 别处**（§三，有限次） |
+| **appName + 数据源名** | `GET /api/bs/ebuilder/app/list?name={appName}&pageNo=1&pageSize=20` **1 次** | 同上 |
+| **仅数据源名，无 app** | — | 直接 §三（须带关键字） |
+| **appId + sourceId 已给** | 直接用 | **跳过查找**，直接 `addDataset` |
+
+**禁止（已指定 app 时的首轮）**：
+
+- 一上来就 `GET /ds/group` 全系统遍历
+- 对每个 `groupId` 循环 `listByPage` 空扫
+- 多 module（`ebuilder` / `bs` / `datasource`）无关键字轮询试探
+- **先拉系统级分页再本地过滤「当前应用」**（分页也必须带 appId）
+- **`sleep` / `setTimeout` 固定等待** 代替「读接口直到有数据」
+- **浏览器自动化 打开应用详情页** 扫网络找表单（ ~17s，且非必要）
+
+**强制优先级**：`e10-cli report find` = `getList/{appId}` → 未命中再问用户 / 有限次应用内关键字 listByPage → **最后**才别处。 
+见 `session-build-performance-guide.md` §二。
+
+---
+
+## 二、应用内查找（已指定 appId · 优先 · 通常 1 次）
+
+### 2.0 未指定准确表名（强制 · 二次确认）
+
+> **事故模式**：需求只写业务描述（如「资产统计」「党员发展」）未给表单名 → Agent 模糊匹配错表 → 数据集字段对不上。
+
+| 用户输入 | Agent 行为 | 绑定 |
+|----------|------------|------|
+| **已给准确表名** 且应用内 **exact 唯一** | 可 `find form` 后绑定 | `autoBind=true`（建议仍口头确认） |
+| **未给表名** / 只给业务词 / 报表名 | **只在当前应用** `getList/{appId}` 检索 → 按关键字打分出候选 | **`needConfirm=true`，禁止 addDataset** |
+| **模糊命中 1 条或多条** | 展示候选（表名 + sourceId） | **必须等用户确认** 后再绑 |
+| 应用内无候选 | 问用户准确表名/sourceId；**禁止**立刻全系统 `/ds/group` | 不绑 |
+
+**二次确认话术（强制）**：
+
+```text
+需求未指定准确表名。已在当前应用内检索到以下候选，请确认用哪一张（回复表名或 sourceId）：
+1. {nameA}（sourceId=…）
+2. {nameB}（sourceId=…）
+若都不是，请给出准确表单名或 sourceId。
+```
+
+**禁止**：未确认就 `addDataset` / 落库绑字段；禁止用报表标题「看起来像」的表直接当数据源。
+
+CLI：
+
+```bash
+e10-cli report find <appId> --list
+e10-cli report find <appId> --suggest "资产,台账"
+e10-cli report find <appId> "准确表单名" # exact 才可 autoBind
+```
+
+exit code **3** = 须二次确认（`needConfirm=true`）。
+
+按优先级尝试，**命中即停**（合计计入 §六预算）：
+
+### 2.1 【首选 · eteams 已验证】应用表单列表
+
+```
+GET /api/bs/ebuilder/form/obj/getList/{appId}?apid={appId}
+```
+
+- Header：`eteamsid` + `Cookie: ETEAMSID=…` + `ebBusinessId={appId}`
+- 响应为应用内表单数组（或包在 `data`）；按 `name` **精确或包含**匹配需求表名
+- 取命中项的 **`id`** 作为 `sourceId`（`addDataset` 用）
+- **示例**：应用 `786501450842480640` 中「进销存-销售单」→ `787599094054395904`
+
+```javascript
+async function findFormInApp(host, headers, appId, formName) {
+ const j = await get(`${host}/api/bs/ebuilder/form/obj/getList/${appId}`, { apid: appId }, headers);
+ const rows = Array.isArray(j.data) ? j.data : Array.isArray(j) ? j : j.data?.list || [];
+ const exact = rows.find((r) => r.name === formName);
+ if (exact) return String(exact.id);
+ const fuzzy = rows.find((r) => String(r.name || '').includes(formName) || formName.includes(String(r.name || '')));
+ return fuzzy ? String(fuzzy.id) : null;
+}
+```
+
+### 2.2 CLI（表单类 · 优先）
+
+```bash
+e10-cli report find <appId> <表单名> # 推荐（本包唯一 CLI 入口）
+node e10-cli report find <appId> <表单名> # 仅 CLI 未装时
+```
+
+若 `e10-cli report` auth 与 `e10-login` 不同步失败 → **改走 §2.1**，不要去找 e10-cli。
+
+字段核对（已有 sourceId 后）：
+
+```bash
+# 报表侧（推荐）：
+# GET /api/bs/edc/dataset/fieldsBySource?sourceId=&sourceType=logic&groupId=weaver-ebuilder-form-service
+# 或 addDataset 后 fieldsAndOriginFields?isFront=true
+```
+
+### 2.3 HTTP 备用（仅当 §2.1 失败）
+
+```
+GET /api/datasource/ds/listByPage?sourceType=logic&appid={appId}&condition={关键字}&pageNo=1&pageSize=50
+GET /api/ebuilder/form/ds/listByPage?sourceType=LOGIC&groupId=0&name={关键字}&appId={appId}&pageNo=1&pageSize=50
+```
+
+> **注意**：部分环境 `form/ds/listByPage` 会 500；**不要**因此改去开 浏览器自动化，应回退 §2.1 或进入 §三 / 询问用户。
+
+---
+
+## 三、别处检索（应用内未命中 或 未给 app）
+
+**仅当**：应用内 §二已试完仍无命中，**或**用户未指定应用。
+
+1. `GET /api/datasource/ds/listByPage`（或 `/api/{module}/ds/listByPage`）带 **`name`/`condition` 关键字** + 必要时 `groupId`
+2. **禁止**无关键字翻页扫全库
+3. 仍计入 §六预算；用尽 → **打断询问**，不要继续盲扫
+
+> ** 坑（<your-e10-host>）**：按「应用名」找应用这条路在本环境不可用 ——
+> `GET /api/bs/ebuilder/app/list?name={kw}` 与 `e10-cli report app-search --name {kw}` **服务端忽略 `name`**，
+> 恒返回全量 998 条且顺序固定，**不能**靠它定位应用。找不到表时：直接用 `ds/listByPage` 关键字搜数据源，或向用户要 appId/sourceId。
+
+若用户其实给了应用名但 Agent 漏解析 → 应先补 `app/list` 再回 §二，而不是直接全系统扫。
+
+---
+
+## 四、与报表 API 闭环（禁止固定 sleep）
+
+```
+解析 appId（若需要，最多 1 次 app/list）
+ → findFormInApp / §二（优先 getList）
+ → [未命中] §三 别处（有限次）
+ → POST addDataset(sourceId)
+ → poll GET dataset/list?reportId= 直到出现匹配 sourceId 的行（见下）
+ → GET fieldsAndOriginFields?datasetId=&isFront=true&reportId=
+```
+
+### 4.1 addDataset 后：轮询代替 sleep（强制）
+
+**禁止** `await sleep(800)` / `setTimeout(800)` 之类固定等待。
+
+```javascript
+async function waitDatasetBySource(reportId, sourceId, { tries = 8, gapMs = 100 } = {}) {
+ for (let i = 0; i < tries; i++) {
+ const list = await getDatasetList(reportId); // GET /api/bs/edc/dataset/list?hasField=true&reportId=
+ const hit = (list || []).find((d) => String(d.sourceId) === String(sourceId));
+ if (hit) return hit;
+ await new Promise((r) => setTimeout(r, gapMs)); // 仅短间隔重试，非「盲等 800ms」
+ }
+ throw new Error(`dataset not ready for sourceId=${sourceId}`);
+}
+```
+
+- 首包常立刻命中（~60ms）；未就绪再 100ms 级重试，总等待远小于固定 800ms。
+- `addDataset` 不返回 `datasetId` → **必须**按 **sourceId** 匹配，禁止按下标 `[0]`。
+
+---
+
+## 五、HTTP 客户端优先（强制 · 性能）
+
+| 做法 | 说明 |
+|------|------|
+| **首选** | Node `https` / `fetch` / 浏览器自动化 **仅** `request` API 发 HTTP（若已有 context） |
+| **禁止为找表** | `chromium.launch` + `page.goto(应用详情)` 扫表单（~0.6s+0.5s+打开页数秒） |
+| **禁止为纯 API 建表** | 仅为 `baseInfo/addDataset/save` 而启动浏览器；用 https + multipart 即可 |
+
+纯 API 路径找表 + 建表可压到数秒；浏览器自动化 启浏览器 alone ≈ **1s+**。
+
+---
+
+## 六、探测预算与打断询问（强制 · 防空耗）
+
+### 6.1 单次任务硬上限
+
+| 项 | 上限 | 说明 |
+|----|------|------|
+| 应用解析 `app/list` | **1** | 已有 appId 则 0 |
+| **应用内**找表（`getList` / `form list` / scoped listByPage） | **合计 ≤ 2** | 换关键字也算；命中即停 |
+| **别处** `group` + `listByPage`（应用内未中或未给 app） | **合计 ≤ 3** | 必须带 name；禁止翻页空扫 |
+| 同一关键字换 module 无脑重试 | **禁止** | |
+| 固定 `sleep` ≥ 300ms 等数据集 | **禁止** | 用 §4.1 轮询 |
+| 浏览器自动化 开应用页找表 | **禁止** | |
+
+### 6.2 何时必须打断并询问用户
+
+1. §6.1 预算用尽仍无唯一命中。 
+2. 关键字命中多条，无法确认。 
+3. 表名与应用内列表对不上。 
+4. 连续 2 轮仍在换词/换接口盲扫。 
+5. **用户未指定准确表名**（仅业务描述/报表名）→ 应用内 `--suggest`/`--list` 后 **二次确认**（§2.0）；**禁止**静默绑定。 
+6. **模糊匹配**（`match=fuzzy`）→ 即使只有 1 条也必须确认。
+
+询问：应用？准确表名或 **sourceId**？多候选点选哪张？
+
+### 6.3 禁止的空耗行为
+
+- 未给 app 时先全系统 group「碰运气」
+- 已给 app 却跳过 §二直接别处扫
+- 固定 sleep、开浏览器扫页、输出长探测日志代替提问
+
+---
+
+## 七、耗时对照（优化目标）
+
+| 路径 | 典型耗时 | 说明 |
+|------|----------|------|
+| `getList/{appId}` 应用内命中 | **~0.2–0.5s** | **推荐** |
+| 固定 sleep(800) + 浏览器自动化 启浏览器 | **~2s+** | **禁止** |
+| 浏览器自动化 打开应用详情扫表单 | **~15–20s** | **禁止** |
+| 全系统 group 遍历 | **数秒～数十秒** | 仅 §三兜底 |
+
+API 从零搭建：数据源定位应控制在 **2 秒内**（已给 app 时）；整段建表（已知名）目标 **≤ 5s**（不含用户确认）。
+
+---
+
+## 八、与现有文档关系
+
+| 文档 | 关系 |
+|------|------|
+| `e10-cli report find` | 应用内 `getList` 找 sourceId（无 sleep/无浏览器） |
+| `api-report-build-fast-path.md` | 建表流程 §〇 / 性能纪律引用本节 |
+| `datasource-metadata-guide.md` | 有 app → 本节；无 app → §三 |
+| `datasource-selection-and-parent-filter-guide.md` | 少挂源 |
+| `e10-cli-integration.md` | 本包不含 e10-cli；勿扫描 |

package/skills/weaver-e10-builder/references/report/cell-config-echo-guide.md

@@ -0,0 +1,163 @@
+# 单元格配置回显契约（数字格式 / 日期分组 / 统计等）
+
+> **根因（已验证 · 设计器 `main.js` `getFormaterInfo`）**：工具栏「数字格式」按下拉回显时，用 `getFormaterInfo(formatter, formatterType)` 在目录中查找：`item.id === formatter || item.key1 === formatterType[0]`。
+> 若只写了近似的 `formatter`（如 `¥#,##0.00`）而 `formatterType` 仍为 `["common"]`，会**命中「常规」**，预览可能仍按货币算，但工具栏回显为「常规」。
+> **日期分组**等右侧属性回显依赖 `fields[].groupType`（及 workbook `style.cellType.groupType`）；重建 workbook 时 **禁止丢** `groupType` / `formatterType`。
+
+---
+
+## 一、硬约束
+
+1. **写数字格式必须「formatter + formatterType」成对**，且取值来自下表目录，禁止自造格式串。
+2. **写日期分组必须写 `groupType` 枚举**（见 §三），并写入 `fields[].groupType` + workbook `style.cellType.groupType`。
+3. **重建 workbook（`fieldToCell`）须透传**：`groupType`、`formatterType`、`countType`、`orderType`、`displayType`、`expandType`；`tag.formatterType` 与 `fields[].formatterType` 一致。
+4. **禁止整表一键刷单元格样式/边框**（用户未点名区域时）：见 `user-request-scope-only-guide.md`；若用户要求「整表设样式」→ **提示不支持全量**，请其给出区域（如 B3:H5）。
+5. **字体/字号**须匹配设计器支持列表；不支持时 **提示用户**，按默认字号继续落库，**不要卡住**（见 §五）。
+6. **同款样式复用（强制 · 性能）**：多个单元格配置**相同**数字格式/字体/边框/对齐时 → **只校验/确认一次**，其余格 **深拷贝同一 style 模板**；**禁止**逐格再跑 `validate format`、禁止逐格翻 JSON 样例对照。
+
+---
+
+## 一补充、同款样式复用（强制）
+
+| 场景 | 正确做法 | 禁止 |
+|------|----------|------|
+| N 个度量列都要「货币」 | `e10-cli report validate format --map "货币"` **一次** → 得到成对 formatter/formatterType → 赋给所有目标格 | 对每一格再 `--map` / 再读一遍样例 JSON |
+| 同区标题行同字体同色 | 建 `styleHeader` 对象，循环 `Object.assign` / 结构化克隆 | 每格单独拼 style、每格问目录 |
+| 交付前抽检 | 对**唯一样式指纹**各验 1 次即可 | 按 cells.length 循环 `validate format --file` |
+
+**指纹示例**：`formatterType[0] + '|' + formatter + '|' + font + '|' + backColor`
+相同指纹 → 直接复用已通过的 style 对象引用（或深拷贝），**不再**走 JSON 样例确认。
+
+## 二、数字格式目录（工具栏回显参照）
+
+> 来源：设计器静态资源 `main.js` 中格式下拉 `g()` 目录。`￥` 为全角 `U+FFE5`（JSON 中写 `\uFFE5`）。
+
+| 中文（工具栏） | `style.formatter`（必须全等） | `formatterType[0]`（key1） |
+|----------------|------------------------------|----------------------------|
+| 常规 | `General` | `common` |
+| 数值 | `0.00_);[Red](0.00)` | `value` |
+| **货币** | `"￥"#,##0.00_);[Red]("￥"#,##0.00)` | **`huobi`** |
+| 会计专用 | `_ "￥"* #,##0.00_ ;_ "￥"* -#,##0.00_ ;_ "￥"* "-"??_ ;_ @_ ` | `kuaiji` |
+| 短日期 | `yyyy/m/d;@__@` | `shortdate` |
+| 长日期 | `yyyy"年"m"月"d"日";@` | `longdate` |
+| 时间 | `h:mm:ss;@` | `time` |
+| 百分比 | `0.00%` | `percent` |
+| 分数 | `# ?/?` | `fenshu` |
+| 科学计数 | `0.00E+00` | `kexuejishu` |
+| 文本 | `@` | `text` |
+| 其他 | （自定义） | `custom` |
+
+### 错误写法（会导致回显「常规」）
+
+| 错误 | 原因 |
+|------|------|
+| `formatter: "¥#,##0.00"` + `formatterType: ["common"]` | id 不在目录；key1=common → 命中常规 |
+| 只改 `formatter`、不改 `formatterType` | key1 仍为 common → 常规 |
+| 半角 `¥`（U+00A5）代替全角 `￥`（U+FFE5） | 与目录 id 不全等 |
+
+### 正确写入示例（货币）
+
+```json
+{
+ "style": {
+ "formatter": "\"￥\"#,##0.00_);[Red](\"￥\"#,##0.00)"
+ },
+ "formatterType": ["huobi"],
+ "tag": { "formatterType": ["huobi"] }
+}
+```
+
+UI 内部拼串形态（勿原样当 formatter）：`"<formatter>__@__<key1>"`，如 `..."__@__huobi`。
+
+---
+
+## 三、日期分组（右侧「单元格」面板回显）
+
+| 中文 | `groupType`（落库 / cellType） |
+|------|-------------------------------|
+| 不设置 | `none`（或未设置；面板默认） |
+| **年份** | **`year`** |
+| 年月 | `yearmonth`（部分 UI 文案控件曾用 `yearAndMonth`，**落库一律 `yearmonth`**） |
+| 月份 | `month` |
+| 年月日 | `yearmonthday` |
+| 年周 | `yearweekday` |
+| 月周 | `monthweekday` |
+
+### 写入要求
+
+1. `fields[].groupType = "year"`（等）
+2. workbook `style.cellType.groupType` 同步（`fieldToCell` 必须带上，禁止只改 fields 行却重建时丢掉）
+3. 回读校验：`getReportDevInfo` → 目标格 `groupType` 等于预期
+4. **选中正确单元格再看回显**（例：D5=年月字段才看「日期分组」；在金额格上看必然是「不设置」）
+
+---
+
+## 四、其它常见配置项回显对照（检查清单）
+
+| 设计器位置 | 配置项 | 回显字段 | 注意 |
+|------------|--------|----------|------|
+| 开始 · 数字格式 | 常规/货币/… | `style.formatter` + `formatterType`/`tag.formatterType` | §二 成对 |
+| 单元格 · 日期分组 | 年份/年月/… | `groupType` | §三 |
+| 单元格 · 显示 | 分组/列表/… | `displayType` | `Group` / `List` / … |
+| 单元格 · 扩展 | 纵向/横向/不扩展 | `expandType` | |
+| 单元格 · 汇总 | 求和/计数/… | `countType` | |
+| 单元格 · 排序 | 升/降/无 | `orderType` | `asc`/`desc`/`no` |
+| 开始 · 字体 | 字体名/字号/粗斜体/下划线 | `style.font`、`textDecoration` | §五 |
+| 开始 · 颜色/填充/边框 | fore/back/border* | `style.*` | 禁止未点名整表刷 |
+| 左父格筛选 | 筛选字段 | `leftFilterField` 完整 fieldKey | 见 cross-dataset 回显 |
+| 查询条件 | 类型/默认值 | saveQueryItem 形态 | 见 query-condition 回显 |
+| 数据集名 | 左侧列表名 | addDataset `sourceName`=`{表}(业务模块)` | 见 add-dataset |
+
+**原则**：凡设计器有下拉/单选回显的项，必须以**平台枚举/目录全等值**写入；「看起来生效、面板不对」优先查是否写了近似值或缺了成对字段。
+
+---
+
+## 五、字体与字号（不支持时提示、不卡住）
+
+1. 写入前用 CLI `validate format` / 本指南目录校验字体、字号是否在设计器支持列表内。
+2. **不支持**（例：用户要 10 号但当前租户目录无 10）→ **明确提示用户**：「报表不支持 N 号字体，已按默认字号（通常 12）展示」→ **继续用默认字号落库**，禁止中断任务。
+ - **禁止变通**：不要手工换算 px（如 10pt→`13.3333px`）绕过目录。后端不校验会照存，但设计器无该项、工具栏回显异常，属于假装支持。
+3. 字体名优先使用设计器可选名（如 `微软雅黑`）；未知字体 → 提示并回退默认字体，同样不卡住。
+
+---
+
+## 六、禁止整表全量设样式 / 边框（提示话术）
+
+用户要求「整表单元格样式 / 整表边框」时：
+
+> **不支持**：报表不允许对**整个报表**一次性全量设置单元格样式或边框样式（易误伤未点名区域，且与「仅改用户点名项」冲突）。
+> 请给出具体区域（如 `B3:H5` 或「表头行」），我再按区域设置。
+
+然后 **不要执行**整表 style/border patch。
+
+---
+
+## 七、CLI
+
+```bash
+# 校验 / 规范化数字格式与日期分组（不落库）
+e10-cli report validate format --map "货币"
+# 「转换」面板（字段转换/HTML/条码/隐藏/文字方向）→ cell-transform-guide.md
+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
+
+# 线上回读检查（formatterType 与 groupType）
+e10-cli report verify format <reportId> [appId]
+```
+
+脚本：`e10-cli report verify format`。
+
+---
+
+## 八、Agent 检查清单
+
+- [ ] 货币等格式：formatter **全等**目录 id，且 `formatterType`/`tag` = 对应 key1（货币=`huobi`）
+- [ ] 日期分组：`groupType` 为 `year`/`yearmonth`/…；workbook cellType 未丢
+- [ ] 重建 workbook 使用已修补的 `fieldToCell`（透传 groupType/formatterType）
+- [ ] 未点名禁止整表刷样式/边框；不支持字号已提示并默认继续
+- [ ] 回读 VERIFY：目标格 `formatter`+`formatterType`、`groupType` 与需求一致

package/skills/weaver-e10-builder/references/report/cell-transform-guide.md

@@ -0,0 +1,147 @@
+# 单元格「转换」面板（强制）
+
+> **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` §八 — 已废弃错误表，以本文为准
+- `safe_report_save.js` — `fieldToCell` 透传

package/skills/weaver-e10-builder/references/report/condition-format-guide.md

@@ -0,0 +1,140 @@
+# 条件格式（突出显示 / 数据条 / 图标集）
+
+> **源码**：`ReportUtil.generateConditionRule`（`weaver-edc-common-report-analysis`）
+> **UI**：设计器「开始 → 条件格式」
+> **落库唯一有效点**：`fields[].conditionRule` / workbook `style.cellType.conditionRule`
+> 结构：`{ highlightDatas, lineDatas, iconDatas }`（**不是** sheet 级 `conditionalFormats`，后者不持久化）
+> **禁黑盒**：禁止下载 SpreadJS / 设计器 chunk 循环试探；见 `session-build-performance-guide.md`
+
+---
+
+## 〇、性能与交付（强制）
+
+1. 写入前用 CLI 映射/校验，**禁止**反复保存探结构
+2. 布局已落库 → **先交设计器地址**，条件格式校验可后置补丁
+3. 映射不到 → **提示用户确认**，不要开逆向循环
+
+---
+
+## 一、硬约束（突出显示）
+
+1. **只写平台已识别的 `relation`**。未知值（如 `highlight:between`）会被引擎**静默跳过**。
+2. **区间必须用一条 `highlight:interval`**；禁止拆成两条 `greater`+`less` 冒充 AND（多规则是 OR）。
+3. **配置前先映射再写入**；映射不到或冲突 → **提示用户确认**。
+
+---
+
+## 二、突出显示 `relation` 白名单
+
+| 中文 | `relation` | value |
+|------|------------|-------|
+| 大于 | `highlight:greater` | value1 |
+| 大于等于 | `highlight:greaterAndEquals` | value1 |
+| 小于 | `highlight:less` | value1 |
+| 小于等于 | `highlight:lessAndEquals` | value1 |
+| 等于 | `highlight:equals` | value1 |
+| 不等于 | `highlight:noEquals` | value1 |
+| **介于** | **`highlight:interval`** | value1=下界，value2=上界 |
+| 文本包含 | `highlight:include` | value1 |
+| 发生日期 | `highlight:happenDate` | value1 |
+| 重复值 | `highlight:sameValue` | — |
+
+**禁止**：`highlight:between` → 改 `interval`；缩写 `gt/lte` 等。
+
+### 自然语言 → 突出显示
+
+| 说法 | 映射 |
+|------|------|
+| 大于 N | `greater` |
+| 介于 1 和 5 / 1–5 | **一条** `interval` |
+| 文本包含 xx | `include` |
+
+多档示例：「>0 红；>5 蓝」→ `interval(1,5)` 红 + `greater(5)` 蓝粗。
+
+---
+
+## 三、数据条（lineDatas）
+
+落库：**`lineDatas`**（引擎 `ruleType=databar`）。
+
+```json
+{
+ "lineDatas": [
+ {
+ "index": 0,
+ "leftType": "min",
+ "leftValue": "",
+ "rightType": "max",
+ "rightValue": "",
+ "gradient": "gradient",
+ "color": "#6495ED",
+ "negativeFillColor": "#FF0000"
+ }
+ ]
+}
+```
+
+| 字段 | 取值 |
+|------|------|
+| `leftType`/`rightType` | `min`/`max`/`custom` |
+| `gradient` | `gradient`（渐变）\| `solid`（实心） |
+| `color` / `negativeFillColor` | 正/负色 |
+
+CLI：`e10-cli report validate condition --map "数据条"` / `--map "实心数据条"`
+
+---
+
+## 四、图标集（iconDatas）
+
+落库：**`iconDatas`**（引擎 `ruleType=iconset`；UI 文案偶写 iconSets，JSON **必须** `iconDatas`）。
+
+```json
+{
+ "iconDatas": [
+ {
+ "index": 0,
+ "iconSetType": "0",
+ "iconCriteria": [
+ { "iconValue": "67", "isGreaterThanOrEqualTo": true, "iconValueType": 1 },
+ { "iconValue": "33", "isGreaterThanOrEqualTo": true, "iconValueType": 1 }
+ ]
+ }
+ ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `iconSetType` | **字符串**；常用 `"0"`/`"1"`/`"2"`/`"3"`（方向/形状/标记/等级类） |
+| `iconCriteria` | 分档阈值 |
+
+CLI：`e10-cli report validate condition --map "图标集"`
+
+---
+
+## 五、不支持 / 冲突
+
+映射不到 → 明确告知并请用户确认；禁止静默、禁止黑盒下载。
+多条 greater 样式不同 → 提示重叠冲突，建议 interval + greater。
+
+---
+
+## 六、写入清单
+
+1. `conditionRule = { highlightDatas?, lineDatas?, iconDatas? }` → fields + workbook cellType
+2. save 成功 → **先交设计器 URL**
+3. 可选 `verify condition` 后置
+
+---
+
+## 七、CLI
+
+```bash
+e10-cli report validate condition --file rule.json
+e10-cli report validate condition --map "介于 1 5"
+e10-cli report validate condition --map "数据条"
+e10-cli report validate condition --map "图标集"
+e10-cli report verify condition <reportId> [appId]
+```
+
+脚本：`e10-cli report verify condition`。