weaver-e10-builder 1.6.14 → 1.6.16

package/skill-docs/references/report/report-data-model.md

@@ -1,447 +1,447 @@
-# E-Builder 报表数据模型参考
-
-> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅生成整包 ReportProps / 深分析时再读。
-
-## 一、核心枚举类型
-
-### 1.1 单元格类型 (CellTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `Const` | 常量字段（自定义文本内容） |
-| `Field` | 数据字段（数据集选取的字段） |
-| `Formula` | 公式字段（公式计算） |
-| `DateTime` | 日期时间 |
-| `DateField` | 日期字段 |
-| `SequenceNumber` | 序号字段（自动生成序号） |
-| `AllCheck` | 全选字段（全选框） |
-| `SlashWord` | 斜线文字（多维交叉表头） |
-| `SystemField` | 系统字段 |
-| `Control` | 控件字段（多级填报） |
-| `TreeField` | 树形字段 |
-
-### 1.2 显示方式 (DisplayTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `List` | 排列（数据逐条展示） |
-| `Group` | 分组（相同数据合并为一组） |
-| `Count` | 汇总（求和/最大值/最小值/平均数/个数） |
-| `Tree` | 树形（上下级层级展示） |
-
-### 1.3 扩展方向 (ExpandTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `Vertical` | 纵向扩展（从上至下，不同单元格展示） |
-| `Horizontal` | 横向扩展（从左至右，不同单元格展示） |
-| `NoExpand` | 不扩展（所有数据在一个单元格） |
-
-### 1.4 分组类型 (GroupTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `year` | 按年份分组 |
-| `yearmonth` | 按年月分组 |
-| `month` | 按月份分组 |
-| `yearmonthday` | 按年月日分组 |
-| `yearweekday` | 按年周分组 |
-| `monthweekday` | 按月周分组 |
-| `none` | 不进行时间分组 |
-
-### 1.5 统计类型 (CountTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `sum` | 求和 |
-| `max` | 最大值 |
-| `min` | 最小值 |
-| `avg` | 平均值 |
-| `count` | 计数 |
-| `distinctcount` | 去重计数 |
-| `none` | 无统计 |
-
-### 1.6 排序方式 (OrderTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `no` | 不排序 |
-| `asc` | 升序 |
-| `desc` | 降序 |
-
-### 1.7 父格类型 (CellParentType)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `empty` | 无父格 |
-| `default` | 默认父格（相邻左/上单元格） |
-| `custom` | 自定义父格（指定具体单元格坐标） |
-
-父格值格式: `[CellParentType, x坐标, y坐标]`
-
-### 1.8 数据源类型 (SourceTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `local` | 本地 |
-| `form` | e-builder 表单 |
-| `eteams` | eTeams |
-| `logic` | 逻辑（数据加工） |
-| `external` | 外部数据源 |
-| `externaldataset` | 外部数据集 |
-| `localds` | 本地数据集 |
-| `systemField` | 系统字段 |
-| `localView` | 本地视图 |
-| `integration` | 集成 |
-
-## 二、报表配置数据模型
-
-### 2.1 报表配置 (ReportProps)
-
-```typescript
-interface ReportProps {
-    config: {
-        fields: CellProps[];           // 字段列表
-        ds: SourceTableResult[];       // 数据源列表
-        sheetProps?: {                 // 工作表属性
-            rowHeights: Record<number, number>;
-            colWidths: Record<number, number>;
-        };
-    };
-    name: string;                       // 报表名称
-    appId: string;                     // 应用ID
-}
-```
-
-### 2.2 单元格配置 (CellProps)
-
-```typescript
-interface CellProps {
-    cellType: CellTypeEnum;             // 字段类型
-    displayType: DisplayTypeEnum;       // 显示方式
-    expandType: ExpandTypeEnum;         // 扩展方向
-    dataSet: string;                    // 数据集主键
-    field: string;                     // 字段主键
-    leftParent: CellParentValueType;    // 左父格 [类型, x, y]
-    topParent: CellParentValueType;     // 上父格 [类型, x, y]
-    groupType: GroupTypeEnum;           // 分组类型
-    countType: CountTypeEnum;           // 统计类型
-    orderType: OrderTypeEnum;           // 排序方式
-    cellText: string;                   // 内容/显示文本
-    x: number;                          // 行号
-    y: number;                          // 列号
-    rowCount: number;                   // 所占行数
-    colCount: number;                   // 所占列数
-    style?: SpreadJSCellStyle;           // 单元格样式
-    leftFilterField?: FilterFieldItem[];  // 左父格过滤
-    topFilterField?: FilterFieldItem[];   // 上父格过滤
-}
-```
-
-### 2.3 单元格样式 (SpreadJSCellStyle)
-
-```typescript
-interface SpreadJSCellStyle {
-    backColor?: string;       // 背景颜色
-    foreColor?: string;       // 字体颜色
-    hAlign?: number;          // 水平对齐 (0=左, 1=居中, 2=右)
-    vAlign?: number;          // 垂直对齐 (0=上, 1=居中, 2=下)
-    font?: string;            // 字体 (如 "12px Arial")
-    formatter?: string;       // 数字格式
-    borderLeft?: { color: string; style: number };
-    borderTop?: { color: string; style: number };
-    borderRight?: { color: string; style: number };
-    borderBottom?: { color: string; style: number };
-    textIndent?: number;      // 缩进
-    wordWrap?: boolean;       // 自动换行
-    textDecoration?: number; // 文本装饰 (0=无, 1=下划线, 2=删除线)
-}
-```
-
-### 2.4 过滤配置
-
-```typescript
-// fieldKey 格式：{dataSetId}.{sourceId}.{fieldName}
-// 设计器筛选下拉按 fieldKey 匹配，不可用显示名或裸 field_xxx
-
-// 父格过滤（跨数据源关联）
-type ParentFilter = {
-    parentField?: string;      // 父格字段 fieldKey
-    currentField?: string;     // 当前字段 fieldKey
-    type?: FilterOptionEnum;   // 匹配关系（如 Equals）
-    id?: string;               // 必须等于 currentField（设计器回显）
-}
-
-// 自定义过滤（单元格级）
-type CustomFilter = {
-    currentField?: string;     // fieldKey
-    type?: FilterOptionEnum;   // 平台枚举，禁止 eq/uncontains/empty/nempty
-    value?: string;
-    id?: string;               // 必须等于 currentField
-}
-
-// 从属关系（VLOOKUP 映射，与 leftFilterField 配套）
-type Subordination = [string, string];  // [父格fieldKey, 当前fieldKey]
-```
-
-// 数据行过滤
-type DataFilter = {
-    currentField?: DataRowFilterType;  // Before|Last|Odd|Even|Designates
-    value?: string;
-}
-```
-
-### 2.5 过滤操作符 (FilterOptionEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `Equals` | 等于 |
-| `NotEquals` | 不等于 |
-| `Greater` | 大于 |
-| `GreaterOrEquals` | 大于等于 |
-| `Less` | 小于 |
-| `LessOrEquals` | 小于等于 |
-| `StartsWith` | 开始于 |
-| `NotStartsWith` | 不开始于 |
-| `EndsWith` | 结束于 |
-| `NotEndsWith` | 不结束于 |
-| `Contain` | 包含 |
-| `NotContain` | 不包含 |
-| `Include` | 属于 |
-| `NotInclude` | 不属于 |
-| `Null` | 为空 |
-| `NotNull` | 不为空 |
-
-## 三、AI 报表配置 DTO
-
-### 3.1 ReportAIDto
-
-```java
-class ReportAIDto {
-    Long appId;               // 所属应用ID
-    Long reportId;            // 报表ID（更新时使用）
-    String reportName;        // 报表名称
-    String formId;            // 数据源表单ID
-    String formName;          // 数据源表单名称
-    List<FieldAIDto> groupFields;   // 分组字段（维度字段）
-    List<FieldAIDto> listFields;    // 列表字段（不分组只展示）
-    List<FieldAIDto> targetFields;   // 指标/度量字段（要聚合计算的字段）
-    String theme;             // 报表主题/样式
-    List<FieldAIDto> queryFields;    // 查询筛选字段
-    String version;           // 版本标识（"v2"表示直接创建）
-}
-```
-
-### 3.2 FieldAIDto
-
-```java
-class FieldAIDto {
-    String fieldName;   // 字段显示名称（中文业务名）
-    String groupType;   // 分组时间粒度（仅分组字段使用）
-    String countType;   // 聚合计算类型（仅指标字段使用）
-}
-```
-
-### 3.3 字段类型映射
-
-| AI 字段类型 | fieldType | 含义 | groupType | countType |
-|-------------|-----------|------|-----------|-----------|
-| groupFields | GROUP | 分组/维度字段 | year/yearmonth/month/none | - |
-| listFields | LIST | 列表/展示字段 | none | - |
-| targetFields | COUNT | 指标/度量字段 | - | sum/max/min/avg/count/distinctcount |
-
-## 四、报表类型判断规则
-
-### 4.1 三种报表类型的字段组织方式
-
-**类型一：简单列表**（只有 listFields + targetFields）
-- dimensionFields = groupFields + listFields（全部作为行维度）
-- yDimensionFields = [] （无列维度）
-- targetFields = 指标字段
-
-**类型二：分组表**（只有 groupFields < 2 或无 targetFields）
-- dimensionFields = groupFields（全部分组字段作为行维度）
-- yDimensionFields = [] （无列维度）
-- targetFields = 指标字段
-
-**类型三：交叉表/统计表**（groupFields >= 2 且有 targetFields）
-- 行维度 (yDimensionFields) = groupFields 的最后一个
-- 列维度 (dimensionFields) = groupFields 的前 N-1 个 + listFields
-- 指标 (targetFields) = 指标字段
-
-## 五、主题配置
-
-### 5.1 预置主题模板（10 个）
-
-| 主题编号 | 标题背景 | 交替色1 | 交替色2 | 风格 |
-|----------|----------|---------|---------|------|
-| 1 | #B6D6FF | #FFFFFF | #FFEDB8 | 蓝+黄 |
-| 2 | #CAF5BF | #FFFFFF | #FFEDED | 绿+粉 |
-| 3 | #C6C0FF | #FFFFFF | #ECECEC | 紫+灰 |
-| 4 | #FFC0C0 | #FFFFFF | #DBEBFF | 红粉+蓝 |
-| 5 | #FFDD7A | #FFFFFF | #FFEFDD | 金+橙 |
-| 6 | #33B617 | #FFFFFF | #FFEDB8 | 深绿 |
-| 7 | #15A8FB | #FFFFFF | #F0F0F0 | 蓝 |
-| 8 | #F38114 | #FFFFFF | #E4E4E4 | 橙 |
-| 9 | #F03112 | #FFFFFF | #FFF5D6 | 红 |
-| 10 | #B035F4 | #FFFFFF | #FFF2CD | 紫 |
-
-### 5.2 自定义主题结构
-
-```typescript
-interface StyleConfig {
-    custom: boolean;              // 是否自定义
-    theme: number | null;         // 主题编号 (1-10)
-    alternateMode: 'row' | 'col'; // 交替方式
-    titleBg: string;              // 标题背景色
-    alternateBg1: string;         // 交替背景色1
-    alternateBg2: string;         // 交替背景色2
-    titleStyle: {
-        fontSize: number;
-        color: string;
-        bold: boolean;
-        italic: boolean;
-    };
-    bodyStyle: {
-        fontSize: number;
-        color: string;
-        bold: boolean;
-        italic: boolean;
-    };
-    area: { row: number; col: number; rowCount: number; colCount: number } | null;
-}
-```
-
-## 六、条件格式配置
-
-### 6.1 条件规则类型
-
-```typescript
-interface ConditionRuleType {
-    highlightDatas?: HightlightRuleType[];  // 高亮规则
-    lineDatas?: DataLineRuleType[];         // 数据条规则
-    iconDatas?: DataIconRuleType[];         // 图标集规则
-}
-```
-
-### 6.2 高亮规则
-
-```typescript
-interface HightlightRuleType {
-    index: number;
-    conditionType?: 'currCell' | 'otherCell';
-    relation?: HighlightRelationEnum;  // equals/greater/less/interval/include/happenDate/sameValue 等
-    value1?: any;
-    value2?: any;
-    fontFamily?: string;
-    fontSize?: string;
-    bold?: boolean;
-    italic?: boolean;
-    underline?: boolean;
-    backColor?: string;
-    foreColor?: string;
-}
-```
-
-### 6.3 数据条规则
-
-```typescript
-interface DataLineRuleType {
-    index: number;
-    leftType: 'min' | 'custom';
-    leftValue?: number;
-    rightType: 'max' | 'custom';
-    rightValue?: number;
-    gradient?: 'gradient' | 'solid';
-    color?: string;
-    negativeFillColor?: string;
-}
-```
-
-## 七、查询条件配置
-
-```typescript
-interface IReportConditionItemType {
-    uuid: string;
-    id: string;
-    text: string;                           // 条件名称
-    displayType: ReportConditionDisplayTypeEnum;  // 显示类型
-    selectOptions: any[];
-    filterOptions: any[];
-    defaultValue: [string, string];
-    param: string;
-    filterType: 'default' | 'sql';
-    conditions: IReportConditionRel[];      // 条件关联
-    showOrder: number;
-    queryType?: 'filter' | 'advance';
-}
-
-// 查询条件显示类型
-enum ReportConditionDisplayTypeEnum {
-    text = 'text',         // 文本
-    number = 'number',     // 数字
-    select = 'select',     // 下拉选择
-    cascader = 'cascader', // 级联
-    date = 'date',         // 日期范围
-    singleDate = 'singleDate', // 单日期
-    eBuilder = 'eBuilder', // e-builder组件
-    browser = 'browser',   // 浏览框
-    custom = 'custom',     // 自定义
-    time = 'time'          // 时间
-}
-```
-
-## 八、字段转换类型（已更正 · 以「转换」面板为准）
-
-> **权威**：`references/cell-transform-guide.md`。下列旧表 **作废**，勿再使用 `person`/`department`/`image`/`html`/`barcode` 作为单一 `transType`。
-
-### 8.1 `transType`（字段转换）
-
-| UI | `transType` | 附加 |
-|----|-------------|------|
-| 无 | `default` | — |
-| 人员 / 部门 / 部门全路径 / 关联类型 | `browser` | `browserType`（ComInfo id 等） |
-| Checkbox | `checkbox` | — |
-| 选择框 | `select` | `transSelectOptions` |
-| 颜色选择框 | `colorSelect` | `transSelectOptions` |
-| 分值图标 | `scoreIcon` | `transSelectOptions` |
-| 斜线文字 | `slashWord` | `transSelectOptions` |
-| 图片 | `picture` | — |
-
-### 8.2 同面板其它键（独立字段，不是 transType）
-
-| UI | 键 | 值 |
-|----|-----|-----|
-| HTML转换 | `isHtml` | `"0"` / `"1"` |
-| 前缀后缀 | `prefixAndSuffix` | `["前","后"]` |
-| 条码 | `qrcodeType` | `no` / `barcode` / `qrcode`（另 `qrcodelink`） |
-| 隐藏内容 | `hiddenContext` | `"0"` / `"1"` |
-| 文字方向 | `textDirection` | `FromLeftToRight` / `FromRightToLeft` / `VerticalArrangement` / `CW` / `CCW` |
-
-## 九、填报字段配置
-
-### 9.1 填报数据类型 (FillingDataTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `Text` | 单行文本 |
-| `TextArea` | 多行文本 |
-| `Number` | 整数 |
-| `Float` | 浮点数 |
-| `Date` | 日期 |
-| `Employee` | 人力资源 |
-| `Department` | 部门 |
-| `Subcompany` | 分部 |
-| `Browser` | 浏览框 |
-| `FileComponent` | 文件 |
-| `ImageComponent` | 图片 |
-
-### 9.2 填报显示方式 (FillingShowTypeEnum)
-
-| 枚举值 | 说明 |
-|--------|------|
-| `Input` | 输入框 |
-| `Browser` | 浏览按钮 |
-| `CheckBox` | check 框 |
-| `Select` | 选择框 |
-| `FileUpload` | 文件上传 |
+# E-Builder 报表数据模型参考
+
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅生成整包 ReportProps / 深分析时再读。
+
+## 一、核心枚举类型
+
+### 1.1 单元格类型 (CellTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `Const` | 常量字段（自定义文本内容） |
+| `Field` | 数据字段（数据集选取的字段） |
+| `Formula` | 公式字段（公式计算） |
+| `DateTime` | 日期时间 |
+| `DateField` | 日期字段 |
+| `SequenceNumber` | 序号字段（自动生成序号） |
+| `AllCheck` | 全选字段（全选框） |
+| `SlashWord` | 斜线文字（多维交叉表头） |
+| `SystemField` | 系统字段 |
+| `Control` | 控件字段（多级填报） |
+| `TreeField` | 树形字段 |
+
+### 1.2 显示方式 (DisplayTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `List` | 排列（数据逐条展示） |
+| `Group` | 分组（相同数据合并为一组） |
+| `Count` | 汇总（求和/最大值/最小值/平均数/个数） |
+| `Tree` | 树形（上下级层级展示） |
+
+### 1.3 扩展方向 (ExpandTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `Vertical` | 纵向扩展（从上至下，不同单元格展示） |
+| `Horizontal` | 横向扩展（从左至右，不同单元格展示） |
+| `NoExpand` | 不扩展（所有数据在一个单元格） |
+
+### 1.4 分组类型 (GroupTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `year` | 按年份分组 |
+| `yearmonth` | 按年月分组 |
+| `month` | 按月份分组 |
+| `yearmonthday` | 按年月日分组 |
+| `yearweekday` | 按年周分组 |
+| `monthweekday` | 按月周分组 |
+| `none` | 不进行时间分组 |
+
+### 1.5 统计类型 (CountTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `sum` | 求和 |
+| `max` | 最大值 |
+| `min` | 最小值 |
+| `avg` | 平均值 |
+| `count` | 计数 |
+| `distinctcount` | 去重计数 |
+| `none` | 无统计 |
+
+### 1.6 排序方式 (OrderTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `no` | 不排序 |
+| `asc` | 升序 |
+| `desc` | 降序 |
+
+### 1.7 父格类型 (CellParentType)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `empty` | 无父格 |
+| `default` | 默认父格（相邻左/上单元格） |
+| `custom` | 自定义父格（指定具体单元格坐标） |
+
+父格值格式: `[CellParentType, x坐标, y坐标]`
+
+### 1.8 数据源类型 (SourceTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `local` | 本地 |
+| `form` | e-builder 表单 |
+| `eteams` | eTeams |
+| `logic` | 逻辑（数据加工） |
+| `external` | 外部数据源 |
+| `externaldataset` | 外部数据集 |
+| `localds` | 本地数据集 |
+| `systemField` | 系统字段 |
+| `localView` | 本地视图 |
+| `integration` | 集成 |
+
+## 二、报表配置数据模型
+
+### 2.1 报表配置 (ReportProps)
+
+```typescript
+interface ReportProps {
+    config: {
+        fields: CellProps[];           // 字段列表
+        ds: SourceTableResult[];       // 数据源列表
+        sheetProps?: {                 // 工作表属性
+            rowHeights: Record<number, number>;
+            colWidths: Record<number, number>;
+        };
+    };
+    name: string;                       // 报表名称
+    appId: string;                     // 应用ID
+}
+```
+
+### 2.2 单元格配置 (CellProps)
+
+```typescript
+interface CellProps {
+    cellType: CellTypeEnum;             // 字段类型
+    displayType: DisplayTypeEnum;       // 显示方式
+    expandType: ExpandTypeEnum;         // 扩展方向
+    dataSet: string;                    // 数据集主键
+    field: string;                     // 字段主键
+    leftParent: CellParentValueType;    // 左父格 [类型, x, y]
+    topParent: CellParentValueType;     // 上父格 [类型, x, y]
+    groupType: GroupTypeEnum;           // 分组类型
+    countType: CountTypeEnum;           // 统计类型
+    orderType: OrderTypeEnum;           // 排序方式
+    cellText: string;                   // 内容/显示文本
+    x: number;                          // 行号
+    y: number;                          // 列号
+    rowCount: number;                   // 所占行数
+    colCount: number;                   // 所占列数
+    style?: SpreadJSCellStyle;           // 单元格样式
+    leftFilterField?: FilterFieldItem[];  // 左父格过滤
+    topFilterField?: FilterFieldItem[];   // 上父格过滤
+}
+```
+
+### 2.3 单元格样式 (SpreadJSCellStyle)
+
+```typescript
+interface SpreadJSCellStyle {
+    backColor?: string;       // 背景颜色
+    foreColor?: string;       // 字体颜色
+    hAlign?: number;          // 水平对齐 (0=左, 1=居中, 2=右)
+    vAlign?: number;          // 垂直对齐 (0=上, 1=居中, 2=下)
+    font?: string;            // 字体 (如 "12px Arial")
+    formatter?: string;       // 数字格式
+    borderLeft?: { color: string; style: number };
+    borderTop?: { color: string; style: number };
+    borderRight?: { color: string; style: number };
+    borderBottom?: { color: string; style: number };
+    textIndent?: number;      // 缩进
+    wordWrap?: boolean;       // 自动换行
+    textDecoration?: number; // 文本装饰 (0=无, 1=下划线, 2=删除线)
+}
+```
+
+### 2.4 过滤配置
+
+```typescript
+// fieldKey 格式：{dataSetId}.{sourceId}.{fieldName}
+// 设计器筛选下拉按 fieldKey 匹配，不可用显示名或裸 field_xxx
+
+// 父格过滤（跨数据源关联）
+type ParentFilter = {
+    parentField?: string;      // 父格字段 fieldKey
+    currentField?: string;     // 当前字段 fieldKey
+    type?: FilterOptionEnum;   // 匹配关系（如 Equals）
+    id?: string;               // 必须等于 currentField（设计器回显）
+}
+
+// 自定义过滤（单元格级）
+type CustomFilter = {
+    currentField?: string;     // fieldKey
+    type?: FilterOptionEnum;   // 平台枚举，禁止 eq/uncontains/empty/nempty
+    value?: string;
+    id?: string;               // 必须等于 currentField
+}
+
+// 从属关系（VLOOKUP 映射，与 leftFilterField 配套）
+type Subordination = [string, string];  // [父格fieldKey, 当前fieldKey]
+```
+
+// 数据行过滤
+type DataFilter = {
+    currentField?: DataRowFilterType;  // Before|Last|Odd|Even|Designates
+    value?: string;
+}
+```
+
+### 2.5 过滤操作符 (FilterOptionEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `Equals` | 等于 |
+| `NotEquals` | 不等于 |
+| `Greater` | 大于 |
+| `GreaterOrEquals` | 大于等于 |
+| `Less` | 小于 |
+| `LessOrEquals` | 小于等于 |
+| `StartsWith` | 开始于 |
+| `NotStartsWith` | 不开始于 |
+| `EndsWith` | 结束于 |
+| `NotEndsWith` | 不结束于 |
+| `Contain` | 包含 |
+| `NotContain` | 不包含 |
+| `Include` | 属于 |
+| `NotInclude` | 不属于 |
+| `Null` | 为空 |
+| `NotNull` | 不为空 |
+
+## 三、AI 报表配置 DTO
+
+### 3.1 ReportAIDto
+
+```java
+class ReportAIDto {
+    Long appId;               // 所属应用ID
+    Long reportId;            // 报表ID（更新时使用）
+    String reportName;        // 报表名称
+    String formId;            // 数据源表单ID
+    String formName;          // 数据源表单名称
+    List<FieldAIDto> groupFields;   // 分组字段（维度字段）
+    List<FieldAIDto> listFields;    // 列表字段（不分组只展示）
+    List<FieldAIDto> targetFields;   // 指标/度量字段（要聚合计算的字段）
+    String theme;             // 报表主题/样式
+    List<FieldAIDto> queryFields;    // 查询筛选字段
+    String version;           // 版本标识（"v2"表示直接创建）
+}
+```
+
+### 3.2 FieldAIDto
+
+```java
+class FieldAIDto {
+    String fieldName;   // 字段显示名称（中文业务名）
+    String groupType;   // 分组时间粒度（仅分组字段使用）
+    String countType;   // 聚合计算类型（仅指标字段使用）
+}
+```
+
+### 3.3 字段类型映射
+
+| AI 字段类型 | fieldType | 含义 | groupType | countType |
+|-------------|-----------|------|-----------|-----------|
+| groupFields | GROUP | 分组/维度字段 | year/yearmonth/month/none | - |
+| listFields | LIST | 列表/展示字段 | none | - |
+| targetFields | COUNT | 指标/度量字段 | - | sum/max/min/avg/count/distinctcount |
+
+## 四、报表类型判断规则
+
+### 4.1 三种报表类型的字段组织方式
+
+**类型一：简单列表**（只有 listFields + targetFields）
+- dimensionFields = groupFields + listFields（全部作为行维度）
+- yDimensionFields = [] （无列维度）
+- targetFields = 指标字段
+
+**类型二：分组表**（只有 groupFields < 2 或无 targetFields）
+- dimensionFields = groupFields（全部分组字段作为行维度）
+- yDimensionFields = [] （无列维度）
+- targetFields = 指标字段
+
+**类型三：交叉表/统计表**（groupFields >= 2 且有 targetFields）
+- 行维度 (yDimensionFields) = groupFields 的最后一个
+- 列维度 (dimensionFields) = groupFields 的前 N-1 个 + listFields
+- 指标 (targetFields) = 指标字段
+
+## 五、主题配置
+
+### 5.1 预置主题模板（10 个）
+
+| 主题编号 | 标题背景 | 交替色1 | 交替色2 | 风格 |
+|----------|----------|---------|---------|------|
+| 1 | #B6D6FF | #FFFFFF | #FFEDB8 | 蓝+黄 |
+| 2 | #CAF5BF | #FFFFFF | #FFEDED | 绿+粉 |
+| 3 | #C6C0FF | #FFFFFF | #ECECEC | 紫+灰 |
+| 4 | #FFC0C0 | #FFFFFF | #DBEBFF | 红粉+蓝 |
+| 5 | #FFDD7A | #FFFFFF | #FFEFDD | 金+橙 |
+| 6 | #33B617 | #FFFFFF | #FFEDB8 | 深绿 |
+| 7 | #15A8FB | #FFFFFF | #F0F0F0 | 蓝 |
+| 8 | #F38114 | #FFFFFF | #E4E4E4 | 橙 |
+| 9 | #F03112 | #FFFFFF | #FFF5D6 | 红 |
+| 10 | #B035F4 | #FFFFFF | #FFF2CD | 紫 |
+
+### 5.2 自定义主题结构
+
+```typescript
+interface StyleConfig {
+    custom: boolean;              // 是否自定义
+    theme: number | null;         // 主题编号 (1-10)
+    alternateMode: 'row' | 'col'; // 交替方式
+    titleBg: string;              // 标题背景色
+    alternateBg1: string;         // 交替背景色1
+    alternateBg2: string;         // 交替背景色2
+    titleStyle: {
+        fontSize: number;
+        color: string;
+        bold: boolean;
+        italic: boolean;
+    };
+    bodyStyle: {
+        fontSize: number;
+        color: string;
+        bold: boolean;
+        italic: boolean;
+    };
+    area: { row: number; col: number; rowCount: number; colCount: number } | null;
+}
+```
+
+## 六、条件格式配置
+
+### 6.1 条件规则类型
+
+```typescript
+interface ConditionRuleType {
+    highlightDatas?: HightlightRuleType[];  // 高亮规则
+    lineDatas?: DataLineRuleType[];         // 数据条规则
+    iconDatas?: DataIconRuleType[];         // 图标集规则
+}
+```
+
+### 6.2 高亮规则
+
+```typescript
+interface HightlightRuleType {
+    index: number;
+    conditionType?: 'currCell' | 'otherCell';
+    relation?: HighlightRelationEnum;  // equals/greater/less/interval/include/happenDate/sameValue 等
+    value1?: any;
+    value2?: any;
+    fontFamily?: string;
+    fontSize?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    backColor?: string;
+    foreColor?: string;
+}
+```
+
+### 6.3 数据条规则
+
+```typescript
+interface DataLineRuleType {
+    index: number;
+    leftType: 'min' | 'custom';
+    leftValue?: number;
+    rightType: 'max' | 'custom';
+    rightValue?: number;
+    gradient?: 'gradient' | 'solid';
+    color?: string;
+    negativeFillColor?: string;
+}
+```
+
+## 七、查询条件配置
+
+```typescript
+interface IReportConditionItemType {
+    uuid: string;
+    id: string;
+    text: string;                           // 条件名称
+    displayType: ReportConditionDisplayTypeEnum;  // 显示类型
+    selectOptions: any[];
+    filterOptions: any[];
+    defaultValue: [string, string];
+    param: string;
+    filterType: 'default' | 'sql';
+    conditions: IReportConditionRel[];      // 条件关联
+    showOrder: number;
+    queryType?: 'filter' | 'advance';
+}
+
+// 查询条件显示类型
+enum ReportConditionDisplayTypeEnum {
+    text = 'text',         // 文本
+    number = 'number',     // 数字
+    select = 'select',     // 下拉选择
+    cascader = 'cascader', // 级联
+    date = 'date',         // 日期范围
+    singleDate = 'singleDate', // 单日期
+    eBuilder = 'eBuilder', // e-builder组件
+    browser = 'browser',   // 浏览框
+    custom = 'custom',     // 自定义
+    time = 'time'          // 时间
+}
+```
+
+## 八、字段转换类型（已更正 · 以「转换」面板为准）
+
+> **权威**：`references/cell-transform-guide.md`。下列旧表 **作废**，勿再使用 `person`/`department`/`image`/`html`/`barcode` 作为单一 `transType`。
+
+### 8.1 `transType`（字段转换）
+
+| UI | `transType` | 附加 |
+|----|-------------|------|
+| 无 | `default` | — |
+| 人员 / 部门 / 部门全路径 / 关联类型 | `browser` | `browserType`（ComInfo id 等） |
+| Checkbox | `checkbox` | — |
+| 选择框 | `select` | `transSelectOptions` |
+| 颜色选择框 | `colorSelect` | `transSelectOptions` |
+| 分值图标 | `scoreIcon` | `transSelectOptions` |
+| 斜线文字 | `slashWord` | `transSelectOptions` |
+| 图片 | `picture` | — |
+
+### 8.2 同面板其它键（独立字段，不是 transType）
+
+| UI | 键 | 值 |
+|----|-----|-----|
+| HTML转换 | `isHtml` | `"0"` / `"1"` |
+| 前缀后缀 | `prefixAndSuffix` | `["前","后"]` |
+| 条码 | `qrcodeType` | `no` / `barcode` / `qrcode`（另 `qrcodelink`） |
+| 隐藏内容 | `hiddenContext` | `"0"` / `"1"` |
+| 文字方向 | `textDirection` | `FromLeftToRight` / `FromRightToLeft` / `VerticalArrangement` / `CW` / `CCW` |
+
+## 九、填报字段配置
+
+### 9.1 填报数据类型 (FillingDataTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `Text` | 单行文本 |
+| `TextArea` | 多行文本 |
+| `Number` | 整数 |
+| `Float` | 浮点数 |
+| `Date` | 日期 |
+| `Employee` | 人力资源 |
+| `Department` | 部门 |
+| `Subcompany` | 分部 |
+| `Browser` | 浏览框 |
+| `FileComponent` | 文件 |
+| `ImageComponent` | 图片 |
+
+### 9.2 填报显示方式 (FillingShowTypeEnum)
+
+| 枚举值 | 说明 |
+|--------|------|
+| `Input` | 输入框 |
+| `Browser` | 浏览按钮 |
+| `CheckBox` | check 框 |
+| `Select` | 选择框 |
+| `FileUpload` | 文件上传 |