weaver-e10-builder 1.1.9 → 1.2.2

package/skill-docs/references/report/report-config-schema.md

@@ -0,0 +1,445 @@
+# 报表配置 JSON Schema
+
+> **冷启动禁止通读**：见 `cold-start-scan-guide.md`。仅生成整包配置 / Schema 校验时再读。
+
+## 一、完整配置结构
+
+```json
+{
+ "name": "报表名称",
+ "appId": "应用ID",
+ "config": {
+ "ds": [
+ {
+ "id": "数据集ID",
+ "name": "数据集名称",
+ "type": "form",
+ "sourceId": "源表单ID",
+ "sourceGroup": "源分组",
+ "fields": [
+ {
+ "id": "字段ID",
+ "name": "字段名",
+ "text": "显示文本",
+ "fieldType": "字段类型",
+ "dataSetId": "数据集ID",
+ "datasetName": "数据集名称"
+ }
+ ]
+ }
+ ],
+ "fields": [
+ {
+ "cellType": "Field",
+ "displayType": "Group",
+ "expandType": "Vertical",
+ "dataSet": "数据集ID",
+ "field": "字段ID",
+ "leftParent": ["default", 0, 0],
+ "topParent": ["empty", 0, 0],
+ "groupType": "none",
+ "countType": "none",
+ "orderType": "no",
+ "cellText": "字段显示名",
+ "x": 2,
+ "y": 0,
+ "rowCount": 1,
+ "colCount": 1,
+ "style": {
+ "backColor": "#B6D6FF",
+ "foreColor": "#000000",
+ "hAlign": 1,
+ "vAlign": 1,
+ "font": "12px Arial",
+ "wordWrap": true
+ }
+ }
+ ],
+ "sheetProps": {
+ "rowHeights": { "0": 30, "1": 25 },
+ "colWidths": { "0": 120, "1": 150 }
+ }
+ }
+}
+```
+
+## 二、单元格配置 Schema
+
+### 2.1 必填字段
+
+| 字段 | 类型 | 说明 | 枚举值 |
+|------|------|------|--------|
+| cellType | string | 单元格类型 | Const, Field, Formula, DateTime, DateField, SequenceNumber, AllCheck, SlashWord, SystemField, Control, TreeField |
+| displayType | string | 显示方式 | List, Group, Count, Tree |
+| expandType | string | 扩展方向 | NoExpand, Horizontal, Vertical |
+| dataSet | string | 数据集ID | - |
+| field | string | 字段ID | - |
+| leftParent | array | 左父格 [type, x, y] | type: empty/default/custom |
+| topParent | array | 上父格 [type, x, y] | type: empty/default/custom |
+| groupType | string | 分组类型 | year, yearmonth, month, yearmonthday, yearweekday, monthweekday, none |
+| countType | string | 统计类型 | sum, max, min, avg, count, distinctcount, none |
+| orderType | string | 排序方式 | no, asc, desc |
+| cellText | string | 内容/文本 | - |
+| x | number | 行坐标 | >= 0 |
+| y | number | 列坐标 | >= 0 |
+| rowCount | number | 占行数 | >= 1 |
+| colCount | number | 占列数 | >= 1 |
+
+### 2.2 可选字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| style | object | SpreadJS 样式 |
+| leftFilterField | array | 左父格过滤（跨数据集必填，字段引用用 fieldKey） |
+| topFilterField | array | 上父格过滤（字段引用用 fieldKey） |
+| customFilterField | array | 单元格自定义筛选（字段引用用 fieldKey） |
+| subordination | string[2] | 从属关系/VLOOKUP 映射（两段 fieldKey） |
+
+### 2.3 样式 Schema
+
+```json
+{
+ "style": {
+ "backColor": "#FFFFFF",
+ "foreColor": "#000000",
+ "hAlign": 1,
+ "vAlign": 1,
+ "font": "12px Microsoft YaHei",
+ "formatter": "0.00",
+ "borderLeft": { "color": "#000000", "style": 1 },
+ "borderTop": { "color": "#000000", "style": 1 },
+ "borderRight": { "color": "#000000", "style": 1 },
+ "borderBottom": { "color": "#000000", "style": 1 },
+ "textIndent": 0,
+ "wordWrap": false,
+ "textDecoration": 0
+ }
+}
+```
+
+对齐值映射：
+- hAlign: 0=左对齐, 1=居中, 2=右对齐
+- vAlign: 0=上对齐, 1=居中, 2=下对齐
+- textDecoration: 0=无, 1=下划线, 2=删除线
+- borderStyle: 0=无, 1=细线, 2=中粗线, 3=虚线
+
+### 2.4 过滤 Schema
+
+> **重要**：设计器按 **fieldKey** 回显筛选字段，格式 `{dataSetId}.{sourceId}.{fieldName}`。
+> 不可用显示名（如「销售经理」）或裸系统名（如 `field_xxx`）。详见 `cross-dataset-filter-guide.md`。
+
+**fieldKey 示例**：`1304979556231593994.1299763447342276611.field_1299763447342276617`
+
+```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"
+ }
+ ],
+ "topFilterField": [
+ {
+ "parentField": "{父格fieldKey}",
+ "currentField": "{当前fieldKey}",
+ "type": "Equals",
+ "id": "{当前fieldKey}"
+ }
+ ],
+ "customFilterField": [
+ {
+ "currentField": "{当前fieldKey}",
+ "type": "NotContain",
+ "value": "排除值",
+ "id": "{当前fieldKey}"
+ }
+ ]
+}
+```
+
+workbook 内上述字段写在 `style.cellType` 上；API 保存后同步到 `getReportDevInfo.fields[]` 顶层。
+
+### 2.5 Formula Schema
+
+> **完整规范见 `formula-cell-api-guide.md`。** 以下为 Schema 摘要。
+
+Formula 单元格（ReportProps `fields[]` 或 workbook `dataTable`）必填约定：
+
+| 字段 | 值 | 说明 |
+|------|-----|------|
+| cellType | `Formula` | 固定 |
+| cellText | 无前导 `=` | 如 `IF(J3=0,0,L3/J3)`，**禁止** `=IF(...)` |
+| displayType | `Group` | 勿用 `List` |
+| countType | `count` | 勿用 `none` |
+| groupType | `null` | 勿用 `"none"` |
+| expandType | `NoExpand` | 公式格通常不扩展 |
+
+workbook 额外要求：
+
+```json
+{
+ "formula": "IF(J3=0,0,L3/J3)",
+ "style": {
+ "formatter": "",
+ "cellType": {
+ "typeName": "FormulaCellType",
+ "cellType": "Formula",
+ "cellText": "IF(J3=0,0,L3/J3)",
+ "displayType": "Group",
+ "countType": "count",
+ "groupType": null,
+ "expandType": "NoExpand",
+ "subordination": ["", ""]
+ }
+ }
+}
+```
+
+## 三、数据集配置 Schema
+
+```json
+{
+ "ds": [
+ {
+ "id": "唯一标识",
+ "name": "数据集显示名",
+ "type": "form",
+ "sourceId": "源ID",
+ "sourceGroup": "源分组标识",
+ "fields": [
+ {
+ "id": "字段唯一标识",
+ "name": "字段系统名",
+ "text": "字段显示名",
+ "fieldType": "string|number|date|datetime",
+ "originFieldType": "原始类型",
+ "dataSetId": "所属数据集ID",
+ "datasetName": "所属数据集名",
+ "tableId": "表ID",
+ "tableName": "表名",
+ "tableText": "表显示名",
+ "nameIndex": "名称索引",
+ "fieldKey": "字段键",
+ "fieldTitle": "字段标题"
+ }
+ ]
+ }
+ ]
+}
+```
+
+## 四、工作表属性 Schema
+
+```json
+{
+ "sheetProps": {
+ "rowHeights": { "0": 30, "1": 25, "2": 20 },
+ "colWidths": { "0": 120, "1": 150, "2": 100 },
+ "styleConfig": {
+ "custom": false,
+ "theme": 1,
+ "alternateMode": "row",
+ "titleBg": "#B6D6FF",
+ "alternateBg1": "#FFFFFF",
+ "alternateBg2": "#FFEDB8",
+ "titleStyle": {
+ "fontSize": 12,
+ "color": "#000000",
+ "bold": true,
+ "italic": false
+ },
+ "bodyStyle": {
+ "fontSize": 12,
+ "color": "#000000",
+ "bold": false,
+ "italic": false
+ }
+ },
+ "pageProps": {
+ "pageNum": 1,
+ "pageRowCount": 200,
+ "dynamicField": "",
+ "scrollPage": false,
+ "rowMode": false,
+ "preAggregate": true,
+ "frozenCell": null,
+ "showGridLine": false,
+ "showRowColHeader": false,
+ "showLocation": "center",
+ "childMerge": false,
+ "columnFilter": true
+ }
+ }
+}
+```
+
+## 五、查询条件 Schema
+
+> **API 写入完整规范见 `query-condition-api-guide.md`。**
+> **默认规则**：数据集合选取后，选择类型未特别指定 SQL 时，均为 **条件字段**（`filterType: "default"`；`conditions` 仅含 `dataSetId` + `fieldId` + `relation`，**勿写** `filterType: "field"`）。
+
+### 5.1 saveQueryItem（条件字段，非 SQL）
+
+> 完整字段说明与 EBU 示例见 `query-condition-api-guide.md`。
+> **调用**：`queryItems` 参数必须是**单个对象**的 JSON 字符串（`JSON.stringify(item)`），禁止传数组；见该指南 §二 / §二点五（防 500）。
+
+```json
+{
+ "dataSetId": null,
+ "nameIndex": "0",
+ "name": null,
+ "text": "集团军",
+ "displayType": "text",
+ "filterType": "default",
+ "showWhere": "advancedSearch",
+ "advancedSearchType": "openCondition",
+ "showOrder": 1,
+ "asNameIndex": 1,
+ "defaultValueType": "default",
+ "defaultValue": "[\"\",\"\"]",
+ "conditions": [{
+ "dataSetId": "1304979556231593994",
+ "fieldId": "1304979556231593994.1299763447342276611.field_1299763447342276612",
+ "relation": "Contain"
+ }],
+ "fieldOptions": {
+ "selected": "1304979556231593994",
+ "1304979556231593994": [{
+ "id": "1305320275886522369",
+ "dataSetField": "1304979556231593994.1299763447342276611.field_1299763447342276612",
+ "relation": "Contain",
+ "queryItemValue": "输入值"
+ }]
+ },
+ "sqlOptions": {}
+}
+```
+
+| 字段 | 条件字段（默认） | SQL（显式指定） |
+|------|------------------|-----------------|
+| 顶层 `filterType` | `"default"` | `"sql"` |
+| `conditions[]` | 仅 `dataSetId` + `fieldId` + `relation` | 含 `filterType: "sql"` + `sql` |
+| `fieldOptions` | 保存时必传（含 `id`）；读回可能为空 | 通常不用 |
+
+### 5.2 ReportProps queryFields（AI 生成摘要）
+
+```json
+{
+ "queryFields": [
+ {
+ "uuid": "唯一标识",
+ "id": "关联字段ID",
+ "text": "条件显示名",
+ "displayType": "date",
+ "selectOptions": [],
+ "filterOptions": [],
+ "defaultValue": ["", ""],
+ "param": "参数名",
+ "filterType": "default",
+ "conditions": [
+ {
+ "dataSetId": "数据集ID",
+ "fieldId": "字段ID",
+ "relation": "between",
+ "sql": ""
+ }
+ ],
+ "showOrder": 1,
+ "queryType": "filter"
+ }
+ ]
+}
+```
+
+## 六、条件格式 Schema
+
+> **完整算子白名单、区间映射、冲突确认**：见 `condition-format-guide.md`。
+> **忌**：`highlight:between`（引擎不识别 → 规则不生成）。区间用 **`highlight:interval`**。
+
+```json
+{
+ "conditionRule": {
+ "highlightDatas": [
+ {
+ "index": 0,
+ "conditionType": "currCell",
+ "relation": "highlight:interval",
+ "value1": "1",
+ "value2": "5",
+ "fontFamily": "Calibri",
+ "fontSize": "12",
+ "bold": false,
+ "italic": false,
+ "underline": false,
+ "backColor": "",
+ "foreColor": "#FF0000"
+ },
+ {
+ "index": 1,
+ "conditionType": "currCell",
+ "relation": "highlight:greater",
+ "value1": "5",
+ "value2": "",
+ "fontFamily": "Calibri",
+ "fontSize": "12",
+ "bold": true,
+ "italic": false,
+ "underline": false,
+ "backColor": "",
+ "foreColor": "#0000FF"
+ }
+ ],
+ "lineDatas": [
+ {
+ "index": 0,
+ "leftType": "min",
+ "rightType": "max",
+ "gradient": "gradient",
+ "color": "#6495ED",
+ "negativeFillColor": "#FF0000"
+ }
+ ],
+ "iconDatas": [
+ {
+ "index": 0,
+ "iconSetType": "direction",
+ "iconCriteria": [
+ {
+ "iconValue": "33",
+ "isGreaterThanOrEqualTo": true,
+ "iconValueType": 1
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+支持的 `relation`：`greater` / `greaterAndEquals` / `less` / `lessAndEquals` / `equals` / `noEquals` / **`interval`（介于）** / `include` / `happenDate` / `sameValue`（均带 `highlight:` 前缀）。
+
+## 七、配置生成检查清单
+
+生成报表配置时必须验证以下项目：
+
+- [ ] 报表名称非空且不重复
+- [ ] 至少配置一个数据集（ds）
+- [ ] 至少配置一个字段（fields）
+- [ ] 每个字段的 cellType/displayType/expandType 值合法
+- [ ] groupType 仅对分组字段生效，其余为 none
+- [ ] countType 仅对指标字段生效，其余为 none
+- [ ] 父格坐标不形成循环引用
+- [ ] 多数据集时配置了 subordination + leftFilterField（fieldKey 格式，含 id）
+- [ ] customFilterField（若有）使用平台 type 枚举且 currentField/id 为 fieldKey
+- [ ] 公式字段的 cellType 为 Formula
+- [ ] 公式字段 cellText **不以 `=` 开头**（见 `formula-cell-api-guide.md`）
+- [ ] 公式字段 countType 为 `count`、displayType 为 `Group`、groupType 为 `null`
+- [ ] workbook Formula 格顶层 `formula` 与 cellText 一致且无前导 `=`
+- [ ] 常量字段的 cellType 为 Const
+- [ ] 样式配置的颜色值为有效 hex 或 rgb 格式

package/skill-docs/references/report/report-create-modes-guide.md

@@ -0,0 +1,182 @@
+# 新建报表 · 三种创建模式（强制）
+
+> **页面**：`/sp/ebdapp/detail/{appId}/report` → **新建报表** 对话框
+> **UI 三卡片**：从空白创建 · **模版创建** · **快速构建-列表式**
+> **源码**：`EdcReportDevBaseController.saveReportBaseInfo` + `EdcReportDevBaseServiceImpl.addReportBaseInfo`
+> **CLI**：`e10-cli report create blank|template|quick` · `e10-cli report create models`
+
+---
+
+## 〇、结论（Agent 必读）
+
+| UI 卡片 | 是否支持 | 怎么走 |
+|---------|----------|--------|
+| **从空白创建** | ✅ 已支持 | `POST baseInfo`，`reportModel=0`，不传 `quicklyParam` |
+| **模版创建** | ✅ **本指南 / CLI 已支持** | `GET getReportModels` 选模板 → `POST baseInfo` 且 **`reportModel={模板报表ID}`** |
+| **快速构建-列表式** | ✅ **本指南 / CLI 已支持** | `POST baseInfo` 且 **`quicklyParam={QuicklyParam JSON 串}`**（`reportModel=0`） |
+
+服务端分支（**互斥，模板优先**）：
+
+```text
+modelId > 0 → 模版创建（copySheet）
+else quicklyParam 非空 → 快速构建-列表式
+else → 从空白创建（空 workbook + sheet）
+```
+
+**禁止混淆**：Skill 自带的 `assets/template-*-report.json` 是 **Agent 布局脚手架**，**不是**平台「模版创建」的 `getReportModels` 模板池。
+
+---
+
+## 一、共享入口
+
+`POST /api/bs/edc/report/baseInfo`（`multipart/form-data`，`id=0` 新建）
+
+| 参数 | 空白 | 模版创建 | 快速构建-列表式 |
+|------|------|----------|-----------------|
+| `appId` | 必填 | 必填 | 必填 |
+| `id` | `0` | `0` | `0` |
+| `name` | 必填 | 必填 | 必填 |
+| `nameLabelId` | `-1` | `-1` | `-1` |
+| `groupId` | `0` | `0` | `0` |
+| `showOrder` | `1` | `1` | `1` |
+| `permission` | `[]` | `[]` | `[]` |
+| **`reportModel`** | **`0`** | **模板报表 ID（>0）** | **`0`** |
+| **`quicklyParam`** | **省略** | **省略** | **QuicklyParam JSON 字符串** |
+
+返回 `data` = 新报表 ID（雪花字符串）。
+
+设计器地址：
+
+```text
+{host}/sp/edc/report/design/{reportId}?appId={appId}&type=1&from=management
+```
+
+---
+
+## 二、模版创建
+
+### 2.1 列模板
+
+```http
+GET /api/bs/edc/report/getReportModels
+```
+
+系统模板池（`getReportList(-999, -1, user)`）。Agent 须把列表展示给用户或按名称精确匹配后再创建。
+
+### 2.2 创建
+
+```bash
+e10-cli report create models
+e10-cli report create template --app-id <appId> --name "新报表" --model-id <模板ID>
+```
+
+Python：
+
+```python
+models = client.get_report_models()
+rid, obj = client.create_report_shell(name, report_model=str(model_id))
+# 或
+rid, obj = client.create_from_model(name, model_id)
+```
+
+服务端：`addReportByModel` → `copySheet(modelId)`，布局/字段随模板复制。
+
+---
+
+## 三、快速构建-列表式
+
+### 3.1 QuicklyParam 结构（源码 `quicklycreate.bean.QuicklyParam`）
+
+```json
+{
+ "dataSetList": [
+ {
+ "id": "<临时UUID，与 showField[].dataSetId 一致>",
+ "sourceType": "1",
+ "sourceId": "<表单/数据源 ID>",
+ "sourceName": "表单名",
+ "sourceGroup": ""
+ }
+ ],
+ "showField": [
+ {
+ "dataSetId": "<同上临时UUID>",
+ "tableId": "...",
+ "name": "fieldKey",
+ "text": "显示名"
+ }
+ ],
+ "fieldConfig": {
+ "<dataSetId>.<tableId>.<name>": {
+ "colName": "列标题",
+ "colWidth": "170",
+ "vAlign": "1",
+ "hAlign": "1",
+ "group": "0",
+ "hideCol": "0",
+ "lockCell": "0",
+ "textWrap": "0"
+ }
+ },
+ "theme": "-1",
+ "sheetIndex": 0,
+ "startRow": 0,
+ "startCol": 0
+}
+```
+
+要点：
+
+- `showField[].dataSetId` 必须与 `dataSetList[].id` **同一临时 ID**（同数据源多选时靠临时 id 区分）。
+- `fieldConfig` 的 key = `{dataSetId}.{tableId}.{name}`。
+- 任一字段 `group=1` → 服务端 **关闭** `simpleList`；否则默认 **开启** `simpleList:true`（列表加速）。
+- `theme` 默认 `"-1"`（无主题样式）。
+
+示例文件：`assets/quickly-param.example.json`
+
+### 3.2 CLI
+
+```bash
+e10-cli report create quick --app-id <appId> --name "列表报表" --quickly-file assets/quickly-param.example.json
+# 或
+e10-cli report create quick --app-id <appId> --name "列表报表" --quickly-json "{...}"
+```
+
+Python：`client.create_from_quickly_param(name, quickly_param_dict_or_str)`
+
+### 3.3 与设计器内「快速构建」的区别
+
+| | 列表页「快速构建-列表式」 | 设计器「更多 → 快速构建」 |
+|--|--------------------------|---------------------------|
+| 时机 | **新建** `baseInfo` + `quicklyParam` | **已有报表** 设计保存 `quicklyParamList` |
+| 本指南 | §三 | 见 `report-help-guide.md` §13.2；不走 create CLI |
+
+---
+
+## 四、Agent 选型
+
+| 用户意图 | 模式 |
+|----------|------|
+| 从零搭布局 / API 细粒度单元格 | **从空白创建** + `api-report-build-fast-path.md` |
+| 「用某某模板」「系统模板」 | **模版创建** |
+| 「选表选字段一键列表」「快速构建」 | **快速构建-列表式** |
+| 未说明 | 默认空白；或 AskUserQuestion 三选一 |
+
+---
+
+## 五、禁令
+
+- 禁止同时依赖 `reportModel>0` 与 `quicklyParam` 指望「都生效」——服务端 **模板优先**，快速构建被跳过。
+- 禁止把 `assets/template-list-report.json` 当成平台 `getReportModels` 模板去传 `reportModel`。
+- 禁止未登录乱扫前端 bundle 猜参数；以本指南 + 源码 bean 为准。
+
+---
+
+## 六、相关文档
+
+| 文档 | 用途 |
+|------|------|
+| `report-lifecycle-api-guide.md` | 列表页生命周期；含新建三模式入口 |
+| `report-baseinfo-defaults-guide.md` | baseInfo 默认值 + `reportModel` / `quicklyParam` |
+| `api-report-build-fast-path.md` | 空白创建后的细粒度搭建 |
+| `report-help-guide.md` §十三 | 产品 UX 说明 |