@lowcodex/gen-report-design-v2

报表设计器 v2（网格直配）：GenSheet 底表 + 设计标注层 + gen-editor 右侧属性面板， 设计模型 ReportModel 编译成 gen-data-processing 的区块式 formConfig。

包内只有设计模型 / 编译 / 标注层 / 预览组装；数据一律由宿主注入， 包里不 import 任何示例数据。

示例站（examples/）

pnpm dev            # 仓库根，vite :5333
# 打开 http://localhost:5333/packages/gen-report-design-v2/

示例站默认走 datav-server 真实接口取数据集 / 层级 / 明细：

| 用途 | 接口 | | ------------------- | ----------------------------------------- | | 数据集目录 | POST /api/dataset/list | | 数据集字段 | GET /api/dataset/dataset-definition/:id | | 取数（带 SQL 参数） | POST /api/dataset/datafetch | | 层级目录 | POST /api/hierarchy/list | | 层级树（带参数） | POST /api/hierarchy/tree |

前置条件：

1. datav-server 跑在 localhost:3000（换端口设环境变量 DATAV_SERVER_ORIGIN）
2. 已执行 pnpm db:seed，库里有「支出明细数据集（150 行 / 5 个参数）、部门信息数据集、功能分类树（24 节点，节点自带预算与支出）」
3. 浏览器请求走 vite 代理 /datav-api → 服务端 /api （前缀不能用 /api，本仓库 dev server 的 mockApiPlugin 占着它）

接口不可用时自动退回 examples/data.ts 的本地样例，页面右上角标出当前数据来源。

请求按需发

目录之外的接口都等「模型真的用到」才调，不会把目录里每个数据集都拉一遍：

| 时机 | 请求 | | ---------------- | ------------------------------------------------ | | 启动 | 登录 1 次（示例站专用）+ 数据集目录 + 层级目录 | | 报表用到某数据集 | 该数据集的字段定义 + 取数各 1 次（已拉过不重复） | | 报表用到某层级 | 层级树 1 次（多棵合并成一个请求） | | 联动重查 | 只对已加载的数据集重新取数（字段定义不再拉） |

默认页（纵向报表 + 一个数据集）首屏 5 个请求，之后每次查询 1 个。

联动

「查询表单 → 报表」链路（示例站默认页已配好）：

查询表单（按数据集/层级声明的参数自动铺）
  ├─ 明细类报表：年度 / 部门 / 功能分类 / 经济分类 / 累计支出下限
  └─ 层级类报表：额外多一个「功能分类（类）」——层级树自己的参数
        │
        └──(事件动作 reload，整组参数)──▶ 报表组件
                                          ├─ 带参重新调取数接口与层级树接口
                                          ├─ 引擎按新数据重新展开
                                          └─ 参数格 ${变量} 同步替换

字段名 = 组件变量名 = 数据集 SQL 参数名（seed 里刻意对齐），链路上不用再做映射。 组件变量在属性面板「组件变量」分组里勾字段生成，参数格在「单元格」分组把格子 改成「参数格」后写 ${变量名} 模板。

默认页（纵向报表样例）自带一个现成的参数格示例：A2 格模板 报表期间：${fiscal_year} 年，引用的组件变量 fiscal_year 已随样例声明 —— 预览时按样本数据首行取值，查询表单换「年度」后同步替换。

报表向外抛事件

反方向的链路：属性面板「事件」Tab 里给报表挂动作，运行态由报表触发。

| 事件 | 触发时机 | 载荷 | | --------------- | ----------------------------------- | ----------------------------------------------------------- | | cellSelected | 单击选中单个单元格 | cell range sri sci eri eci multiple sheetId | | cellsSelected | 框选/扩展选区（拖拽过程中连续触发） | 同上（多格时 range 形如 A1:C3） | | cellEdited | 编辑单元格内容的过程中 | cell range value text sri sci sheetId | | cellFinished | 单元格编辑结束（回车/失焦落值） | 同上 | | sheetChange | 表格底层数据变化（引擎 change） | changeArgs sheetId |

事件定义与载荷同源在包内（REPORT_SHEET_EVENT_DEFS ↔ createReportSheetEventHandlers / attachReportSheetEvents），插件与渲染器 各取一头。只有预览态才派发 —— 编辑态的选格与编辑都是设计动作， 发出去会让人一边配报表一边触发页面的业务动作。