weaver-e10-builder 1.1.9 → 1.2.2

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

@@ -0,0 +1,447 @@
+# E-Builder 报表数据模型参考
+
+> **冷启动禁止通读**：见 `cold-start-scan-guide.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` | 文件上传 |

package/skill-docs/references/report/report-delivery-contract.md

@@ -0,0 +1,101 @@
+# 报表搭建完成交付规范（强制）
+
+> **冷启动**：开场只读 `cold-start-scan-guide.md`；交链后禁止续跑（含 verify/HTML）。
+> **适用范围**：凡通过本 Skill 完成「线上建表 / 布局落库」或「需求分析」的任务。
+> **优先级**：高于 Agent 默认收尾习惯。
+
+---
+
+## 搭完即停（最高 · 防「报表好了 Agent 还在忙」）
+
+`saveReportDevInfo`（或等价落库）成功，且对话中已给出 **设计器地址** 后：
+
+1. **本轮任务立即结束** —— 停止调用工具、停止读文档、停止写脚本。
+2. **禁止**再跑：`verify_*`、预聚合、HTML 手册、需求分析模板、配置 JSON 检测、再 save、回读全表、截图比对、通读 knowledge-base。
+3. **禁止**在交链后再开「后台继续」长链（旧文「可后置校验」已废止为默认行为）。
+4. 硬失败才允许修；软告警 **最多补丁 1 次** 后仍须结束并告知用户。
+5. 单步 API 最多重试 1 次，**不得**叠成无限交付轮。
+
+---
+
+## 模式分流
+
+| 用户意图 | 判定 | Agent 做什么 | **禁止** |
+|----------|------|--------------|----------|
+| **A. 直接搭建**（默认） | 「搭建」「创建报表」「生成报表」 | 定源 → 落库 → **交设计器地址 → 停** | 分析模板、配置检测、HTML、verify 环 |
+| **B. 需求分析** | 「需求分析」「搭建指导」「图示」 | 按 `report-requirement-analysis-template.md` | 未点名却搭表；未点名却 HTML |
+| **C. 分析 + 搭表** | 同时含 B 与 A | 短分析（若需要）→ A → **停** | 把 HTML/verify 当完成条件 |
+
+**HTML 手册**：非强制；仅用户明确要「HTML/指导文档」时生成，且不得拖延首链、不得在交链后自动生成。
+
+**已移除能力**：测试用例生成、功能原型图 —— 包内无对应脚本/指南，禁止查找 `generate_test_case` / `prototype-design` / 测试用例模板。
+
+---
+
+## 〇、先交地址（强制）
+
+布局落库成功并拿到稳定 `reportId` 后，**立即**输出 §一 模板，然后 **结束**。
+
+**禁止**为下列事项拖延或续跑：视觉比对、多轮 `getReportDevInfo`、SpreadJS 黑盒、HTML、verify、预聚合、需求分析、配置检测、「再确认一下」。
+
+### 与门禁
+
+- **硬失败** → 不交假链；删空壳（`failure-cleanup-and-nonblocking-guide.md`）。
+- **会话终止未交付** → `cleanup shells`。
+- **附属失败**（如查询条件）→ 提示后 **仍交主表链接并结束**；最多补试 1 次。
+
+---
+
+## 一、对话收尾（模式 A）
+
+```markdown
+## 应用信息
+- **应用名称**：…
+- **应用 ID**：…
+- **应用地址**：…
+
+## 报表信息
+- **报表名称**：…
+- **报表 ID**：…
+- **设计器地址**：…
+```
+
+**禁止**附加：搭建指导手册段、changed files、verify 报告（除非用户本轮点名）。
+
+---
+
+## 二、HTML（按需 · 非强制）
+
+仅用户明确要求时：
+
+```bash
+python （未移植，需要时另议） --config <guide_config.json> --output <输出路径>.html
+```
+
+建议：`outputs/<reportId>/《报表名称》·搭建配置指导.html`
+
+---
+
+## 三、直接搭建跳过
+
+模式 A **禁止**：分析模板 8 章节、ReportProps 整包检测、`build_guide_html`、交链后 verify/预聚合环。
+
+最小路径：`auth ready` → 定源 → 建壳 → addDataset → 布局 → save → **交链停**。
+
+---
+
+## 四、自检清单
+
+- [ ] 含应用三要素 + 报表三要素（含设计器地址）
+- [ ] 交链后已停止（无续跑工具）
+- [ ] 未主动生成 HTML / 测例 / 原型
+- [ ] 未展示 changed files
+
+---
+
+## 五、相关文档
+
+- `api-report-build-fast-path.md`
+- `session-build-performance-guide.md`
+- `report-requirement-analysis-template.md`（仅分析意图）
+- `failure-cleanup-and-nonblocking-guide.md`