Files
eip4-platform/docs/plans/2026-06-25-报表迁移-JOR引擎重宿主-design.md
zhengwr 3a04b869fe docs(report): B 类图表验证结论=暂缓为独立 ECharts 小特性 + 收尾纪要
design §7 记录 B 类图表验证:ischart=true 仅 4 张且 reportfile 全空——不是 JOR/jfreechart,
是老客户端从图表数据流(POST 写流,GET 被拒)画的 ECharts,当前降级成加载不出数据的破表。
faithful 迁移=独立特性(POST 图表端点 + 流结果→amis chart option,但图表类型/系列映射在老客户端、
每张形状不同难通用、出图保真须完整客户库),仅 4 张低优先,待产品定夺口径。用户拍板暂缓。
§6 遗留同步:中文字体保真 + PDF/Excel 下载入口已收尾(均真镜像/真验)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 23:08:37 +08:00

9.4 KiB

报表迁移: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 张、低优先,需产品定夺图表口径后再做。

  • 仍剩余:<Url>reportviewer.jsp 钻取链接改 EIP4 路由、完整客户库数据对账(eip4dev 部分库,源表/视图缺→渲布局但空数据,非引擎问题)。