weaver-e10-builder 1.1.9 → 1.2.2

package/skill-docs/references/report/add-dataset-registration-guide.md

@@ -0,0 +1,139 @@
+# addDataset 注册契约 · `field_` 前缀门禁（强制）
+
+> **事故（已验证 · 报表 `1312765120721813505`）**
+> 同一 `sourceId=972019393600233477`（轻资产信息）：
+> - **Agent/API 加的数据集** `1312765120721813506`：`type=form` + `sourceGroup=<appId>` → `fieldsKey.name` 业务字段为**裸雪花**（无 `field_`）
+> - **设计器手动「+」加的数据集** `1312794545670627330`：`type=logic` + `sourceGroup=weaver-ebuilder-form-service` → `fieldsKey.name` 业务字段为 **`field_{雪花}`**
+>
+> **遗漏点不在「写 Field 时忘加 field_」**，而在 **`addDataset` 注册参数与设计器不一致**，导致权威 `fieldsKey` 本身就没有 `field_`。
+> 后续若按设计器习惯臆造 `field_`，或绑错到「裸雪花」那份 dataset，会出现保存 500 / 取数失败 / 与用户手动数据集字段名对不齐。
+
+---
+
+## 一、两种注册形态（必须分清）
+
+| 形态 | 典型 `addDataset` | `dataset/list` 特征 | 业务字段 `fieldsKey.name` | `tableName` 后缀 | 何时用 |
+|------|-------------------|---------------------|---------------------------|------------------|--------|
+| **A. 设计器默认（LOGIC）** | `sourceType=LOGIC`（或 `logic`）+ `sourceGroup=weaver-ebuilder-form-service` + `appid=<appId>` | `type:"logic"`，`sourceGroup:"weaver-ebuilder-form-service"` | **`field_{雪花}`** | **`(业务模块)`** | **普通应用表单（默认强制）** |
+| **B. 共享表 / form 契约** | `sourceType=form` + `sourceGroup=<appId>` | `type:"form"`，`sourceGroup` 等于 appId | 常为**裸雪花** | **`(表单)`** | 仅「xxx-共享表」类应用且已验证必须用此契约时（见 MEMORY/共享表笔记） |
+
+**禁止**：在普通应用里误用形态 B，再抱怨「没有 field_」——那是注册错了，不是 fieldsKey 坏了。
+
+> ⚠️ **`tableName` 后缀必须与注册形态一致**：形态 A → `(业务模块)`，形态 B → `(表单)`。
+> 后缀缺失或写错会导致左侧数据源不显示模块类型。
+> 详见 **`dataset-table-field-contract-guide.md`**（含 `FieldCellType` 必需字段全表 + 落库门禁）。
+
+---
+
+## 二、设计器兼容的 addDataset（默认强制）
+
+```
+POST /api/bs/edc/report/addDataset
+Content-Type: multipart/form-data
+
+reportId = {reportId}
+sourceType = LOGIC
+sourceIds = {sourceId} // 表单/数据源 ID
+sourceName = {显示名} // **回显名强制**：`{表单名}(业务模块)`，如 `轻资产信息(业务模块)`；禁止只传裸表单名
+appid = {appId} // 注意小写 appid（与设计器一致）
+sourceGroup = weaver-ebuilder-form-service
+```
+> **回显名（已验证）**：`sourceName` 写入 `edc_dataset_dev.name`，左侧回显应为 **`xxx(业务模块)`**。
+> 只传 `轻资产信息` 会缺后缀；源合并后的 `tableText` 可能仍是 `轻资产信息(uf_xxx)`，与回显名不是同一字段——**以 `name`=sourceName 为准**。
+
+可选字段以设计器实际请求为准；**不得**把 `sourceGroup` 写成 appId，除非走 §一 形态 B。
+
+`addDataset` **不返回** datasetId → 短轮询：
+
+```
+GET /api/bs/edc/dataset/list?hasField=true&reportId={reportId}
+```
+
+按 **sourceId** 命中；若同 sourceId 多条，**优先选** `sourceGroup=weaver-ebuilder-form-service` / `type=logic` 那条。
+
+### 2.1 同源只挂一次（**强制 · 2026-09-11 事故**）
+
+`spec_lib.resolveDataset()` 在 `addDataset` **之前**先查 `dataset/list`：
+
+| 场景 | 行为 |
+|------|------|
+| 本报表已有同 `sourceId` 数据集 | **复用**（`datasetReused=true`），**不再 addDataset** |
+| 发现同源 ≥2 条 | 回传 `datasetDuplicates[]` + WARN（左侧会出现重复分组） |
+| 传了别的报表的 `datasetId` | 忽略 + WARN（禁止跨报表复用） |
+
+> 事故：同一表单被 `addDataset` 挂载两次（`type=LOGIC` 与 `type=logic` 各一条），
+> 且画布上两个单元格引用第二条 → 设计器左侧出现**两个同名数据源分组**。
+> 未先去重就继续绑字段，会让「绑到哪一份数据源」变得不可预测。
+> 清理顺序见 `dataset-sidebar-ops-guide.md §5.3`（**先改绑/清单元格 → 再 delDataset**）。
+
+---
+
+## 三、addDataset 后强制门禁（遗漏即本事故）
+
+`fieldsAndOriginFields?isFront=true` 拿到 `fieldsKey` 后立刻检查：
+
+```javascript
+const biz = fieldsKey.filter(
+ (f) => /^\d{15,}$/.test(f.name) || /^field_\d{15,}$/.test(f.name)
+);
+const withPrefix = biz.filter((f) => String(f.name).startsWith('field_')).length;
+const bare = biz.filter((f) => /^\d{15,}$/.test(f.name)).length;
+
+// 普通应用（非共享表 form 契约）：业务字段应多数带 field_
+if (!isSharedFormContract && biz.length > 0 && bare > withPrefix) {
+ throw new Error(
+ 'addDataset 注册错误：fieldsKey 业务字段为裸雪花（无 field_）。' +
+ '应使用 sourceType=LOGIC + sourceGroup=weaver-ebuilder-form-service；' +
+ 'delDataset 后重建，禁止在 Field 上凭记忆加 field_ 前缀凑数。'
+ );
+}
+```
+
+| 检查 | 通过标准 |
+|------|----------|
+| 普通应用 | 业务字段 `field_` 数量 **≥** 裸雪花数量（通常裸雪花应为 0） |
+| 共享表 form 契约 | 允许裸雪花；**禁止**再擅自加 `field_` |
+| 同 sourceId 已有手动 LOGIC 数据集 | **绑定/取 fieldsKey 必须用那条**；勿继续用旧的 form+appId 脏注册 |
+
+失败处理：
+
+1. `POST /api/bs/edc/report/delDataset` 删掉错误注册
+ - form：`reportId=<报表ID>` · **`sourceIds=<datasetId>`**（参数名历史遗留，**不是**表单 sourceId）
+ - 建议先 `GET /api/bs/edc/dataset/checkDataSetUsed?reportId=&datasetId=`；CLI：`e10-cli report dataset delete`
+ - 完整侧栏操作见 `dataset-sidebar-ops-guide.md`
+2. 按 §二 重新 `addDataset`
+3. 再拉 `fieldsKey`，确认出现 `field_*`
+4. 再写 Field / `saveReportDevInfo`
+
+---
+
+## 四、与「字段精确绑定」的关系
+
+| 步骤 | 规则 |
+|------|------|
+| 1 注册 | 本指南：让 `fieldsKey` **先**变成设计器同款（含 `field_`） |
+| 2 绑定 | `field-bind-exact-match-guide.md`：`name` **逐字等于** 当前 dataset 的 `fieldsKey.name` |
+| 3 禁止 | 注册错了却在 cell 上「手工补 `field_`」；或注册对了却去前缀 |
+
+**一句话**：`field_` 不是 Agent 写 Field 时发明的，是 **正确 addDataset 之后 fieldsKey 自带的**。
+
+---
+
+## 五、自检清单
+
+- [ ] `addDataset` 使用 `sourceType=LOGIC` + `sourceGroup=weaver-ebuilder-form-service`（除非共享表契约）
+- [ ] `dataset/list` 回读该条 `type/sourceGroup` 与设计器一致
+- [ ] `fieldsKey` 业务字段已出现 `field_*`（普通应用）
+- [ ] Field.`name` / fieldKey 末段 ∈ **该** dataset 的 fieldsKey（`verify_field_bind.js`）
+- [ ] 同 sourceId 多实例时，未误绑到旧的 form+appId 裸雪花数据集
+
+---
+
+## 六、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `field-bind-exact-match-guide.md` | 绑定名权威来源；前置依赖本指南的注册正确 |
+| `api-report-build-fast-path.md` | 建表流程步骤 2 / 2.1 门禁 |
+| `report-designer-feature-map.md` §六 | 设计器「+」对应 addDataset 参数 |
+| `e10-cli report verify bind` | 交付校验；并对「裸雪花 fieldsKey」给出注册错误提示 |

package/skill-docs/references/report/ai-report-workflow.md

@@ -0,0 +1,412 @@
+# AI 报表生成工作流程
+
+> **冷启动禁止通读**：见 `cold-start-scan-guide.md`。纯搭表走 `api-report-build-fast-path.md`，勿开场读本文。
+
+## 一、整体流程概览
+
+```
+用户输入（文本描述 / 图片效果 / 需求文件）
+ |
+ v
+ 1. 需求解析：理解报表类型、数据维度、指标、样式需求
+ |
+ v
+ 2. 字段分类：将需求中的字段映射为三类
+ - groupFields（分组/维度字段）
+ - listFields（列表/展示字段）
+ - targetFields（指标/度量字段）
+ |
+ v
+ 3. 报表类型判定：根据字段组合判断报表类型
+ - 简单列表（LIST）
+ - 分组表（GROUP）
+ - 交叉表/统计表（COUNT）
+ |
+ v
+ 4. 布局规划：确定单元格位置、扩展方向、父格关系
+ |
+ v
+ 5. 样式配置：主题选择、条件格式、字体样式
+ |
+ v
+ 6. 高级配置：查询条件、分页、打印、解析优化
+ |
+ v
+ 7. 输出配置：生成完整的 ReportProps JSON 配置
+```
+
+## 二、需求解析规则
+
+### 2.1 从文本描述解析
+
+识别以下关键信息：
+- **报表名称**：用户提到的报表名称，如"客户信息报表"、"销售统计表"
+- **数据源**：用户提到的数据表/表单名称，如"客户信息表"、"销售合同表"
+- **分组维度**：用户提到"按...分组"、"按...统计"中的字段
+- **指标度量**：用户提到"统计...数量"、"求和...金额"中的字段和聚合方式
+- **列表字段**：用户提到"显示...信息"、"展示...详情"中的字段
+- **查询条件**：用户提到"按...筛选"、"按...查询"中的字段
+- **排序要求**：用户提到"按...排序"中的字段和方向
+- **样式要求**：用户提到的主题颜色、条件格式等
+
+### 2.2 从图片效果解析
+
+分析报表截图中的以下要素：
+- **报表布局**：表头结构、数据排列方式（分组/交叉/列表）
+- **字段位置**：行维度字段、列维度字段、指标字段的位置
+- **样式特征**：背景色、字体样式、交替行颜色
+- **条件格式**：数据条、图标集、高亮规则
+- **功能区域**：查询条件区域、工具栏按钮
+
+### 2.3 从需求文件解析
+
+支持的需求文件格式：
+- **Word/Excel**：提取表格结构、字段列表、统计要求
+- **JSON/YAML**：直接映射为报表配置
+- **Markdown**：提取结构化的报表需求描述
+- **图片**：同图片效果解析流程
+
+## 三、字段分类规则
+
+### 3.1 groupFields（分组/维度字段）
+
+判定条件：
+- 用户提到"按...分组"、"按...分类"、"按...维度"
+- 日期类字段且用户提到时间粒度（年/月/日）
+- 报表中需要横向或纵向展开的分类字段
+
+配置示例：
+```json
+{
+ "fieldName": "创建日期",
+ "groupType": "yearmonth" // 按年月分组
+}
+```
+
+groupType 中文到系统值映射：
+- "年份" → `year`
+- "年月" → `yearmonth`
+- "月份" → `month`
+- "年月日" → `yearmonthday`
+- 无时间分组 → `none`
+
+### 3.2 listFields（列表/展示字段）
+
+判定条件：
+- 用户提到"显示...信息"、"展示...字段"
+- 不需要分组、不需要聚合的普通展示字段
+- 报表中的明细数据列
+
+配置示例：
+```json
+{
+ "fieldName": "客户名称",
+ "groupType": "none"
+}
+```
+
+### 3.3 targetFields（指标/度量字段）
+
+判定条件：
+- 用户提到"统计...数量"、"求和...金额"、"平均...值"
+- 需要聚合计算的数字类型字段
+- 报表中的数据值区域
+
+配置示例：
+```json
+{
+ "fieldName": "合同金额",
+ "countType": "sum" // 求和
+}
+```
+
+countType 中文到系统值映射：
+- "求和" → `sum`
+- "最大值" → `max`
+- "最小值" → `min`
+- "平均值" → `avg`
+- "计数" → `count`
+- "去重计数" → `distinctcount`
+- 默认 → `sum`
+
+## 四、报表类型判定与布局规则
+
+### 4.1 简单列表（LIST）
+
+**触发条件**：只有 listFields 和/或 targetFields，没有 groupFields
+
+**布局规则**：
+- 所有字段纵向扩展（expandType = Vertical）
+- 显示方式为排列（displayType = List）
+- 左父格均为默认（leftParent = ["default", 0, 0]）
+- 无上父格（topParent = ["empty", 0, 0]）
+
+**单元格布局示例**：
+```
+A1: 标题行（常量）
+A2: 字段1(纵向扩展,排列) B2: 字段2(纵向扩展,排列) C2: 字段3(纵向扩展,排列)
+```
+
+### 4.2 分组表（GROUP）
+
+**触发条件**：有 groupFields 但数量 < 2，或没有 targetFields
+
+**布局规则**：
+- 分组字段纵向扩展（expandType = Vertical），显示方式为分组（displayType = Group）
+- 指标字段纵向扩展（expandType = Vertical），显示方式为汇总（displayType = Count）
+- 左父格关系：指标字段的左父格默认依赖相邻的分组字段
+- 无上父格
+
+**单元格布局示例**：
+```
+A1: 标题行（常量）
+A2: 分组字段(纵向扩展,分组) B2: 指标字段(纵向扩展,汇总,求和)
+```
+
+### 4.3 交叉表/统计表（COUNT）
+
+**触发条件**：groupFields >= 2 且有 targetFields
+
+**布局规则**：
+- 行维度 = groupFields 的最后一个（纵向扩展，分组）
+- 列维度 = groupFields 的前 N-1 个（横向扩展，分组）
+- 指标字段在交叉位置（纵向扩展，汇总）
+- 指标字段的左父格自定义指向行维度单元格
+- 指标字段的上父格自定义指向列维度单元格
+- 必须设置父格筛选关联多数据集
+
+**单元格布局示例**（2个分组字段+1个指标）：
+```
+A1: 标题行（常量）
+A2: 行维度字段(纵向扩展,分组) B2: 列维度字段(横向扩展,分组)
+ B3: 指标字段(纵向扩展,汇总,求和)
+ 左父格=自定义(A2), 上父格=自定义(B2)
+```
+
+### 4.4 交叉表父格筛选配置
+
+当使用多个数据集时，必须同时配置 **subordination**（从属关系）和 **leftFilterField**（左父格筛选）。
+字段引用必须使用 **fieldKey**：`{dataSetId}.{sourceId}.{fieldName}`，且 `id` 等于 `currentField`。
+
+> 完整说明、自定义筛选、双保存与定位见 `cross-dataset-filter-guide.md`。
+
+```json
+{
+ "subordination": [
+ "1304979556231593994.1299763447342276611.field_1299763447342276617",
+ "1304979560546713602.1299789221321891842.field_1299789221321891843"
+ ],
+ "leftFilterField": [{
+ "parentField": "1304979556231593994.1299763447342276611.field_1299763447342276617",
+ "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891843",
+ "type": "Equals",
+ "id": "1304979560546713602.1299789221321891842.field_1299789221321891843"
+ }],
+ "customFilterField": [{
+ "currentField": "1304979560546713602.1299789221321891842.field_1299789221321891844",
+ "type": "NotContain",
+ "value": "排除机构",
+ "id": "1304979560546713602.1299789221321891842.field_1299789221321891844"
+ }]
+}
+```
+
+**常见错误**：使用显示名「团队」「销售经理」或裸 `field_xxx` → 设计器筛选下拉空白。
+
+## 五、单元格坐标规划规则
+
+### 5.1 基本布局原则
+
+- 第1行（y=0）：报表标题行，使用常量字段（cellType=Const）
+- 第2行（y=1）：表头/字段名称行
+- 第3行及以后（y>=2）：数据区域
+
+### 5.2 坐标系
+
+- x = 行号（从0开始，向下递增）
+- y = 列号（从0开始，向右递增）
+- 父格坐标：[type, x, y]
+ - `["default", 0, 0]` = 默认（依赖相邻单元格）
+ - `["custom", x, y]` = 自定义（指向坐标 x,y 的单元格）
+ - `["empty", 0, 0]` = 无父格
+
+### 5.3 多数据集布局
+
+当报表使用多个数据集时：
+1. 维度字段通常来自主数据集
+2. 指标字段可能来自不同数据集
+3. 跨数据集字段必须设置父格筛选关联
+
+## 六、公式配置规则
+
+> **API / 脚本保存含 Formula 时，完整规范见 `formula-cell-api-guide.md`。** 本节为工作流摘要。
+
+### 6.1 公式类型
+
+| 分类 | 常用公式 |
+|------|----------|
+| 数学 | SUM, AVERAGE, COUNT, MAX, MIN, ABS, ROUND, CEILING, FLOOR |
+| 文本 | LEFT, RIGHT, MID, LEN, CONCAT, UPPER, LOWER |
+| 日期 | YEAR, MONTH, DAY, DATE, DATEDIF, NOW, TODAY |
+| 逻辑 | IF, IFERROR, AND, OR, NOT |
+| 信息 | ISERROR, ISBLANK, ISNUMBER |
+
+### 6.2 公式配置方式（ReportProps / getReportDevInfo）
+
+公式单元格 `cellType` 为 `Formula`，**cellText 为公式表达式且不带前导 `=`**：
+
+```json
+{
+ "cellType": "Formula",
+ "cellText": "IF(J3=0,0,L3/J3)",
+ "displayType": "Group",
+ "countType": "count",
+ "groupType": null,
+ "expandType": "NoExpand"
+}
+```
+
+**错误示例（会导致设计器空白）**：
+
+```json
+{
+ "cellType": "Formula",
+ "cellText": "=IF(J3=0,0,L3/J3)",
+ "displayType": "List",
+ "countType": "none"
+}
+```
+
+### 6.3 workbook 写入（saveReportWithCacheConfig）
+
+workbook `dataTable` 中 Formula 格需同时设置：
+
+- 顶层 `"formula": "IF(...)"`（无前导 `=`）
+- `style.cellType.cellText` 与顶层 `formula` 内容一致
+- `style.formatter` 为空字符串
+
+参考 `make_formula()` 见 `formula-cell-api-guide.md` §四。
+
+### 6.4 公式与父格关系
+
+若公式需要按特定分组计算，公式单元格也需设置自定义左父格或上父格（`leftX`/`leftY` 指向根格）。
+
+公式格通常 `subordination: ["", ""]`，引用同表内 Field 汇总格而非数据集字段名。
+
+### 6.5 占比 / 除法推荐写法
+
+| 场景 | 设计器输入 | 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)` |
+| 安全除法 | `=IFERROR(G5/F5,"--")` | `IFERROR(G5/F5,"--")` |
+
+### 6.6 保存与验证
+
+1. 双保存：`saveReportWithCacheConfig` + `saveReportDevInfo`
+2. `getReportDevInfo` 回读：确认 `cellText` 不以 `=` 开头
+3. 运行 `validate_report_config.py` 预检 Formula 格式
+
+## 七、高级功能配置
+
+### 7.1 查询条件配置
+
+> **API/脚本写入完整规范**见 `query-condition-api-guide.md`（条件字段形态、asNameIndex、21 项日期选项、系统参数默认值）。以下为 ReportProps 摘要，**不可直接等同于 saveQueryItem payload**。
+
+```json
+{
+ "queryFields": [{
+ "uuid": "query-1",
+ "id": "field-001",
+ "text": "日期范围",
+ "displayType": "date",
+ "conditions": [{
+ "dataSetId": "ds-001",
+ "fieldId": "createdate",
+ "relation": "between"
+ }],
+ "showOrder": 1
+ }]
+}
+```
+
+### 7.2 分页配置
+
+```json
+{
+ "pageNum": 1,
+ "pageRowCount": 200, // 每页行数
+ "dynamicField": "", // 动态Sheet页字段
+ "scrollPage": false // 滚动分页
+}
+```
+
+### 7.3 解析优化配置
+
+```json
+{
+ "rowMode": false, // 行式加载（仅单数据集简单列表）
+ "preAggregate": true // 数据预聚合（默认开启）
+}
+```
+
+### 7.4 打印配置
+
+```json
+{
+ "printInfo": {
+ "area": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
+ "repeatArea": { "startRow": -1, "endRow": -1, "startCol": -1, "endCol": -1 },
+ "printGridLine": false,
+ "printOuterBorder": false,
+ "allRowsInOnePage": false,
+ "allColsInOnePage": false,
+ "printOrder": "auto"
+ },
+ "pageMargin": { "top": -1, "bottom": -1, "left": -1, "right": -1, "header": -1, "footer": -1 },
+ "paperSize": "A4",
+ "paperOrientation": "portrait"
+}
+```
+
+## 八、确认信息生成规则
+
+生成报表配置后，应向用户展示确认信息：
+
+```
+报表创建确认：
+
+名称：{reportName}
+数据源：{formName}
+报表类型：{列表|分组表|交叉表}
+
+行维度字段：{字段名}（{分组类型}）
+列维度字段：{字段名}（{分组类型}）
+列表字段：{字段名}
+指标字段：{字段名}（{聚合方式}）
+
+查询条件：{条件名}（{条件类型}）
+主题样式：主题{编号}
+
+请确认是否创建此报表。
+```
+
+## 九、错误处理与校验
+
+### 9.1 必须校验项
+
+1. **报表名称**：不能为空，不能与已有报表重名
+2. **数据源**：必须指定有效的数据源
+3. **字段配置**：至少需要一个字段
+4. **字段有效性**：指定的字段名必须在数据集可用字段中
+5. **父格一致性**：多数据集时必须设置父格筛选
+
+### 9.2 常见错误及处理
+
+| 错误 | 原因 | 处理方式 |
+|------|------|----------|
+| 字段不存在 | AI 指定的字段名不在数据集中 | 列出可用字段，提示用户修正 |
+| 数据源未找到 | formId 无效 | 提示用户选择有效数据源 |
+| 名称重复 | 报表名已存在 | 提示用户更换名称 |
+| 父格循环引用 | 父格设置形成环 | 检查并修正父格关系 |
+| 聚合字段非数字 | 对文本字段使用求和 | 检查字段类型，使用计数替代 |