JOR 报表 <Hyperlink><Url>reportviewer.jsp?xmluuid=<目标报表ID>&PARAM=${PARAM}…</Url> 经 jatools
HtmlExport 渲成 <a href='reportviewer.jsp?xmluuid=…' target='_blank'>(jar 内确认 <a href' 发射);
EIP4 下老 jsp 已失效,点击钻取 404。ReportService.rewriteDrillLinks(仅 HTML 通道,渲染后处理)正则
reportviewer\.jsp\?xmluuid=([^&'"\s<>]+) → /api/report/render/$1?format=html,其余查询参原样保留
→ 点击钻取在新标签渲出目标报表(目标自身钻取链接亦被同一步递归改写,因每次 render 都过此步)。
- 短路:无 "reportviewer.jsp" 子串原样返回(302/339 报表跳过正则);Pattern 静态编译一次。
- replaceAll(Function) 字面量拼接,即便目标 id 含 $/\ 也不破坏替换(评审 MINOR-1 收口)。
- 6 单测:真发射锚格式(单引号 href+&+target=_blank)/裸&分隔/多处/无链接短路同实例/null。
验证边界:钻取行在报表明细行,eip4dev 缺源数据 → dev 渲不出 drill 链接,点击直通须完整客户库;
本批=改写逻辑单测 + jar 发射证实(HtmlExport <a href')+ 评审实证全 37 张 xmluuid 恒首参 +
live 正常报表(5558497f CJK)HTML round-trip 无损、drill 报表渲染 200 不报错。code review APPROVE。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
63 lines
10 KiB
Markdown
63 lines
10 KiB
Markdown
# 报表迁移: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 库,缺部分报表源表/视图;数据验收须对**完整客户库**。
|
|
|
|
## 6. Phase 2/3 实现纪要(2026-06-25,已完成+live验收)
|
|
|
|
报表页**不再手搭**——由转换器对 type=200 统一生成,且查询条件落在 amis `crud.filter`(实测唯一能让 picker 正常加载选项的上下文;独立 form 里 picker 弹窗恒空)。
|
|
|
|
- **后端** `GET /api/report/frame/{templateId}`(`ReportController`):回显 amis CRUD 单行信封 `{status:0,data:{items:[{__url}],total:1}}`,`__url`=`/api/report/render/{id}?format=html&<查询参数>`(templateId 路径段 + 参数键值全 UTF-8 URL 编码,防注入)。crud 的 html 列把 `__url` 渲成 `<iframe>`,JOR HTML 独立加载、CSS 隔离保真。
|
|
- **转换器** `TemplateToAmisConverter.convertReport` 分流:含 `<reportfile>`(JOR 套打,328/339)→ `convertReportViewer` 产 `page→crud{api:/api/report/frame/{id}, filter:buildSearchFilter(查询条件), columns:[单 html 列 iframe], initFetch:false(有查询条件时等用户「查询」再加载)}`;无 reportfile(9/339,纯数据)→ 保留原数据表降级;2/339 为空 XML 孤儿模板(测试动态报表等),无产物属正常。
|
|
- **认证根因修(关键)** `EngineContextBinder`:工程 picker「选不到」的真因**不是**转换器/页面结构,而是**认证 admin 的引擎身份没被识别成超管**——JWT 注入 `CURRENTUSER="ADMIN"`(5 字符),引擎跳过行级数据过滤的判定是 exact `ctx.get(CURRENTUSER).equals(LoggedInUser.ADMIN)`,而该常量是 CHAR(36) 补白的 `"ADMIN"+31 空格`,5 字符 ≠ 36 字符 → admin 被当普通用户走数据权限 → `PM_PROJECT` 无规则 → `PrivilegeException` →「暂无该数据源的查询权限」(无 token 的 curl 走 ADMIN 默认上下文,故误以为后端正常)。修=`bind()` 把系统管理员(userId trim=ADMIN,或 account 精确小写='admin',与全站 `requireAdmin` 同口径,不放宽大小写防变体账号提权)的 CURRENTUSER 归一为引擎规范 36 字符 `LoggedInUser.ADMIN`,引擎识别超管→跳过过滤。各 `requireAdmin` 门控均 `trim().equalsIgnoreCase`,对补白形式同样判真,不破鉴权门。
|
|
- **live 验收**(8093 新 jar + 真库 + Playwright):工程 picker 列出全部 1672 工程→选中值落定→「搜索」→ crud 携 `PROJECTID` 调 frame→iframe `src=…?format=html&PROJECTID=…`→渲出 JOR 套打「在建项目收付款信息表」(单位/中标价/合同价/序号/工程名称/累计收款付款…);菜单 tab 内非独立页。339 报表页已批量重转重导 eip3.sys_page_schema(328 viewer 更新 + 9 表格不变)。
|
|
- **评审**:独立 code-reviewer + security-reviewer;按建议收口 templateId 路径编码、`/render` 端点 page/perPage 行为保持不变(分流到 frame)、account 判定与 requireAdmin 对齐大小写敏感(防变体账号提权)。
|
|
- **已收尾**:headless 中文字体保真(生产镜像装 `fontconfig+fonts-wqy-zenhei+fonts-dejavu-core`,docker 真镜像渲染验证零豆腐块,字体嵌入子集可移植);PDF/Excel 下载入口(查看器 `filter.actions`/`headerToolbar` 加导出按钮 → `/api/report/render?format=pdf|xls`,端点回 `Content-Disposition: attachment`+RFC5987 中文文件名,浏览器+curl 真验下载保真)。
|
|
|
|
## 7. B 类图表报表 backlog(2026-06-25 验证暂缓,独立小特性)
|
|
|
|
**验证结论(暂缓,非 jfreechart)**:`ischart=true` 报表仅 **4 张**(项目考勤图表-前十/单个、未签合同率前十、供应商价格分析土建),且**全部 `<reportfile>` 为空** —— EIP3 图表**不是 JOR/jfreechart 套打**(lib 的 jfreechart 只服务于内嵌在 JOR 版式里的图,这 4 张都没有),而是**老客户端从图表数据流画的 ECharts**。
|
|
- 图表数据流(如 `GB_ATTENDANCEINFO_PRJCHART`)被分类为**写服务流、GET 被拒**;POST 返结构化图数据 `{PRJNAMELIST:[类目], NOWLIST/COUNTLIST/ALLLIST:[系列], …标量}`(dev 库无源数据 → 全空)。
|
|
- 当前转换器把这 4 张走「图表→数据表」降级,crud 指向 `/api/flow/..._PRJCHART` 的 **GET**(被拒)→ 实为一张加载不出数据的破表。
|
|
- **faithful 迁移所需(独立特性)**:①能 POST 取数的图表端点;②把流结果映射成 amis `chart`(ECharts option)——但**图表类型/系列映射在老客户端代码里**(模板 XML 只有 `ischart`+`selectservice`+display,无图表定义),且**每张形状不同**,难用一套通用启发式覆盖;③出图保真还须**完整客户库**(dev 缺源数据)。仅 4 张、低优先,需产品定夺图表口径后再做。
|
|
|
|
- **钻取链接改 EIP4 路由已做**(2026-06-25):JOR 模板 `<Hyperlink><Url>reportviewer.jsp?xmluuid=<目标报表ID>&PARAM=${PARAM}…</Url>` 经 jatools `HtmlExport` 渲成 `<a href='reportviewer.jsp?xmluuid=…' target='_blank'>`(jar 内已确认 `<a href='` 发射);老 jsp 已失效。`ReportService.rewriteDrillLinks`(HTML 输出后处理,仅 HTML 通道)正则 `reportviewer\.jsp\?xmluuid=([^&'"\s<>]+)` → `/api/report/render/$1?format=html`(其余查询参原样保留,目标报表新标签渲出;目标自身钻取链接亦被同一步递归改写)。短路(无 `reportviewer.jsp` 子串原样返回,302/339 报表跳过正则);`replaceAll(Function)` 字面量拼接防 `$/\` 注入。**全 37 张 drill 报表 xmluuid 恒为首参**(评审实证全语料)。坑:钻取行落在报表明细行,eip4dev 缺源数据 → dev 渲不出 drill 链接,**点击直通须完整客户库验**;改写经 6 单测(真发射格式/裸&/多处/短路/null)+ jar 发射证实 + live 正常报表 round-trip 无损。
|
|
- **仍剩余**:完整客户库数据对账(eip4dev 部分库,源表/视图缺→渲布局但空数据,非引擎问题)、B 类图表(§7)。
|