feat(report): JOR(jatools)报表引擎重宿主 — platform-report 后端 + /api/report 端点

EIP3 真报表=jatools JOR 套打模板(非 amis 表格)。本批次把报表引擎重宿主进 EIP4
(复用客户已持有的预编译引擎 jar,非移植 900 源文件;非重建引擎)。Phase 1 后端完成+真验。

- platform-report 模块:18 个预编译 jar(jatools 引擎 + 改造版 BeanShell + itext/jxl/
  jsqlparser/jfreechart/barcode4j/zxing/…)经项目内 local-repo(install-libs.sh)正常依赖,
  打进 fat jar(BOOT-INF/lib 已确认,非 system scope)。
- ReportService:走 jatools.engine.ReportJob(查询参数 setParameter→declareExternalVariables
  →SQL ${PARAM});headless(java.awt.headless)。三格式 HTML/PDF/XLS。
- JatoolsConfig:把 EIP4 spring.datasource 注入引擎 System2.properties(无 CWD 文件依赖)+
  注册 CJK 字体供 PDF。
- ReportController:GET /api/report/render/{templateId}?format=html|pdf|xls&<查询参数>;
  按 templateId 从 view_template(type=200)的 <reportfile> CDATA 取 JOR 渲染;?tpl= dev 覆盖。
- SecurityConfig:X-Frame-Options DENY→SAMEORIGIN(报表查看器同源 iframe 内嵌;生产 nginx 单源)。

真验:全 reactor mvn clean install 绿(0 失败);8093 端点 GET /api/report/render/{id} 三格式
HTTP 200(HTML 48K/PDF 106K/XLS 21K);查询参数 PROJECTID 流进 SQL 48×;浏览器内 amis 菜单页
(查询表单+iframe 查看器)渲染出 JOR 套打报表(在建工程项目收付款信息表,公式列/分组小计/签字栏)。

边界:Phase 2 前端「报表页 body 换查看器」当前以单页 sys_page_schema 运行态改动演示(非本提交代码);
铺到全部 339 张 type=200 报表页 = Phase 3(转换器侧生成查看器 body)。数据保真须对完整客户库验证
(eip4dev 为部分 dev 库,部分报表源表缺)。design 见 docs/plans/2026-06-25-报表迁移-JOR引擎重宿主-design.md。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-25 17:56:50 +08:00
parent 2ff826505f
commit 702b5e9229
100 changed files with 1181 additions and 0 deletions

View File

@@ -0,0 +1,41 @@
# 报表迁移:JOR(jatools)引擎重宿主到 EIP4 — design + 实施
> 2026-06-25。回答「EIP3 的真报表(JOR 套打)能否迁移」=**能**,PoC 已证(headless 渲染 + 连真库 + 跑报表 SQL,见 `/tmp/eip4-report-poc.html` 与浏览器截图 `在建工程项目收付款信息表`)。本文为把 PoC 变成可用功能的设计与实施。
## 0. 关键结论(PoC 已验)
- EIP3 报表 = `jatools` JOR **套打模板**(633 个 `.xml`,合并单元格/边框/公式列/分组小计/分页/签字栏),引擎是**纯 Java 服务端**,导出 HTML/PDF/XLS/RTF,浏览器显示(H5;旧 ActiveX `.cab` 仅 IE 已死)。
- **不用移植 900 个源文件**:整套**预编译成品**在 `/Users/zhengwr/workspace/eip3/framework/com.dsasp.client.report/lib/`:
`jatools.jar`(引擎) + `bsh2.0.jar`(改造版 BeanShell,含 8 个自定义类) + 全部依赖(`itext.jar`/`jxl.jar`/`jsqlparser.jar`/`jfreechart-1.0.13.jar`+`jcommon`+`chart.jar`/`barcode4j.jar`+`zxing2.1.core.jar`/`commons-*`/`log4j-1.2.8`/`jaxen`/`xercesImpl`/`postgresql.jar`)。授权许可:`jatools.dat`(912B ASCII),预编译 jar 在 server 模式直接跑通(无物理 dongle);生产需确认授权(客户 EIP3 本就在用)。
- **渲染 recipe(已验)**:`ReportDocument.load(xml)` → 设参数 → `jatools.engine.ReportJob.printAsDHTML(imp, writer)`(HTML)/`printAsPDF(os)`/`printAsXLS(ba)`。headless:`-Djava.awt.headless=true`,`java.desktop@21` 在。
## 1. 参数绑定(查询条件,需求①)
EIP3 `ReportExporter` 的真实通道(`jor/jatools/server/ReportExporter.java`):
- 每个请求参数 `job.setParameter(name, value)`;
- `declareExternalVariables(doc, script, params)`:把 params 注入 script,并遍历 `doc.getVariableContext().variables(VariableContext.PARAMETER)`,按 `Parameter.castValue` 类型转换后 `script.set(p.getName(), value)`;
- 报表 SQL 里的 `${PARAM}` 即由这些已声明变量替换(`SqlReader` 检 `sql.indexOf("${")`)。
- 注:`LocalReportJob` 路径**不做** declareExternalVariables(故 PoC 里用 params 传 DBJdbcUrl 无效);**必须走 `ReportJob` 路径**。
- DB 连接:模板 `<Connection>` 用 `${property("DBJdbcUrl")/DBUser/DBPassword}`,`property()=System2.getProperty()=jatools.properties`。EIP4 须在启动时把 `DBJdbcUrl/DBUser/DBPassword` 注入 System2(指向客户库)。
## 2. 目标架构
- **platform-report 模块**:依赖上述预编译 jar。打包进 fat jar 的可靠做法 = `mvn install:install-file` 各 jar 进**项目内本地仓** `platform-report/local-repo/`(随码提交,坐标如 `com.dsasp.thirdparty:jatools:eip3`),pom 加 `<repository>file://.../local-repo</repository>` 正常依赖。**勿用 system scope**(不进 fat jar)。
- **ReportService**(复刻 ReportExporter 核心,去掉 com.dsasp 应用胶水):`render(templateXml, Map<String,String> params, format) → bytes/String`。`ReportJob` + `FileResourceOutputFactory(tmpDir)` + `printAsDHTML/PDF/XLS`。
- **ReportController**:`GET /api/report/{templateId}?format=html|pdf|xls&<查询参数>` → 加载 JOR 模板 → ReportService → `text/html` / `application/pdf` / xls。
- **模板来源**:633 个 `.xml`。v1:配置一个模板根目录(EIP3 report 目录)+ `templateId→xml` 映射;后续:导入 `sys_report_template` 表(随 sys_* 平台表,Flyway 管)。
- **System2 连接注入**:启动时用 EIP4 `spring.datasource` 配置写入 jatools 的 DBJdbcUrl/DBUser/DBPassword(经 System2 的 setProperty 或可解析的 jatools.properties)。
## 3. 前端集成(菜单页,需求②:不是独立 tab)
- type=200 报表页**已是** sys_page_schema 里的菜单功能页(转换器已生成,含查询条件表单——见 `项目安全费用投入明细` 的 amis filter)。
- 改造该页 body:把 amis CRUD 表换成**报表查看器**(amis `iframe`/`html` 组件)指向 `/api/report/{templateId}?{查询表单参数}`;查询表单 onSubmit 刷新 viewer。
- 仍是原菜单页(满足需求②);查询条件表单字段名 = 报表 VariableContext PARAMETER 名(PROJECTID/日期段/…)。
## 4. 分期
- **Phase 1(后端,本批次)**:platform-report 模块 + ReportService + `/api/report` 端点,headless 渲染一张带查询参数的 JOR 模板→HTML/PDF,接进 platform-app,curl 验证返回报表 HTML。
- **Phase 2(前端集成)**:报表页 body 换查看器 + 查询表单喂参数 + 菜单可达,端到端一张报表(对完整客户库出数据)。
- **Phase 3(铺量)**:633 模板导入 `sys_report_template`;type=200 页批量改造;字体保真;PDF/Excel 下载;图表(B 类,jfreechart 已在 lib)。
## 5. 风险
- headless 中文字体保真(版式已通,需装字体)。
- jatools 授权(生产确认;客户已持有)。
- System2 连接为进程级全局(单客户部署 OK;多租户需改造)。
- 模板里 `<Url>reportviewer.jsp?...`(钻取链接)需改写为 EIP4 路由(Phase 3)。
- eip4dev 是**部分** dev 库,缺部分报表源表/视图;数据验收须对**完整客户库**。