Files
eip4-platform/docs/决策与盘点/EIP3报表迁移方案.md
zhengwr 1b69f8b481
Some checks failed
ci / build-test-parity (push) Has been cancelled
docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
- 从工作区根 docs/(非 git,未版本化)合并全部文档进版本控制,消除文档两头分裂
- 新增 README(状态总览+模块完成度+全文档索引)、项目进度与路线-总览-2026-06-17(A兼容/B新功能+关键路径+待拍板决策)
- 被取代的冲突状态/审计快照归入 归档/;对最易误导的两份("16视图已交付"实现交付报告、06-13架构快照)加"已归档"横幅
- 现行权威:engineclass移植backlog(46视图) + 用户管理Delta移植(方法论/交接) + 组件设计体系 + 通用模板收口 + 客户沟通
- 诚实口径:纵向模块仅用户管理 parity,横向引擎地基较全,余 153 定制视图(47 framework+106 业务)多为通用页已产·delta 未移植

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 14:53:29 +08:00

95 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# EIP3 报表系统迁移方案
> 日期:2026-06-10 | 依据:framework 源码考古 + 客户库实测(192.168.20.68:5435/eip3 只读)
> 定位:《架构决策会纪要》P4 阶段的报表专项附件;评估报告表 4 中「报表→中匹配度」一格的展开
---
## 一、旧报表系统的真实形态(考古结论,全部有实证)
旧系统的"报表"不是一个引擎,是**三层混合体**,迁移难度差异极大:
```
337 个声明式报表模板 (view_template, type=200, 根元素 <report>)
├─ 数据层:selectservice 数据服务流(全库去重 79 个)→ 服务流引擎出数据
└─ 渲染层(三条路):
a. 表格式报表 333 个 → ReportTemplateComponent / ReportPowerTableFormat
(Vaadin 表格自渲染,含合计列 issumcolumn / 金额列 ismoney 等特性)
b. ECharts 图表 4 个(ischart="true")→ tools/echart.jsp?flowid=
(服务流出数据,JSP 里拼 ECharts option —— 渲染端已经是 ECharts)
c. 复杂版式/套打 → tools/reportviewer.jsp?xmluuid= → JOR(杰表)引擎
(927 个 Java 文件内嵌源码 + jatoolsPrinter ActiveX 打印控件 .cab)
```
**五个关键事实**:
1. **337 个报表模板是声明式元数据**,结构与 GRID 模板(crud)近乎同构:`<report><display><field…/><search selectservice=…>`,全部含脚本(337/337,归入既有脚本分桶流程);其中仅 6 个带 engineclass 定制类。
2. **取数与展示已经分离**:报表数据全部经 `selectservice` 服务流获取(79 个去重服务流,view_template_service 表 320 行关联)。**取数逻辑是纯后端 Java 资产,与 Vaadin 零耦合**。
3. **图表路径已经是 ECharts**(echart.jsp 实测引用 echarts.min.js、服务流出数据拼 option)。
4. **JOR 引擎自有集成面只有 4 个类**(ReportComponent/ReportPowerTableFormat/ReportResources/Activator),引擎以 servlet `/tools/jatoolsreport` + JSP taglib 方式暴露;布局模板是**部署期 classpath 资源文件**(仓库内仅 demo,生产布局在客户部署包中,数量待盘点)。
5. **打印链路已经死亡**:xmlviewer.jsp 实测嵌入 `<OBJECT CLASSID=… jatoolsPrinter.cab>` —— **IE ActiveX 控件**。IE 已退役,该打印路径在现代浏览器本来就不可用(客户现状即为带病运行或 IE 兼容模式硬撑)。
---
## 二、迁移方案:按四类分治
### A 类:333 个表格式报表 →「扩展现有转换器」(主体工作,性价比最高)
`<report>` 与 `<crud>` 同构,**扩展 PoC 已验证的 TemplateToAmisConverter** 即可:
| 旧特性 | amis 对应 | 备注 |
|--------|----------|------|
| display/field | crud columns | 与 GRID 转换完全相同 |
| `issumcolumn="true"` | 列 `summaryFields` / footer 合计行 | amis crud 原生支持 |
| `ismoney="true"` | 列 `type: number` + 千分位格式 | WS5 截图已实测此渲染 |
| search/field + uitype | filter 表单 | 与 GRID 转换相同(含 NumberField→input-number 等映射表补项) |
| `selectservice="XXX"` | `api: /api/flow/XXX`(服务流 REST 包装) | 见 D 节 |
| isTitle/isDescribe(标题/说明行) | crud 顶部 tpl 区 | 少量人工核对 |
**工作量估算:转换器扩展约 0.5 人月**(report 段规则 + 合计/金额特性 + 对拍抽检),并入 P4。
### B 类:ECharts 图表(4 个 + echart.jsp 模式)→「option 平移」(近零成本)
amis 的 `chart` 组件就是 ECharts 包装。迁移 = 把 JSP 里内联的 option 模板移到 amis chart 的 `config`,数据源从 JSP 服务端取数改为 `api` 指向服务流 REST。**预计 2–3 人日**。
### C 类:JOR 复杂版式与套打 →「不迁移引擎,按场景替换」
**决议建议:JOR 引擎(927 文件)与 ActiveX 打印控件直接淘汰,不做任何移植**。理由:打印链路在现代浏览器已不可用;引擎是嵌入的第三方陈旧源码(含 BeanShell),安全与维护负债远超价值。替换分两个场景:
1. **查看/导出类复杂版式**(中国式格线报表、月报汇总):
- 首选 **univer**(决策报告风险对策已点名)做在线表格呈现与导出;
- 数据加工不愁:月报类已有结构化业务表支撑(pm_mreport* 13 张表实测在库),服务流出数据 → univer/Excel 导出。
2. **套打/打印类**(单据格式打印):
- 首选**浏览器原生打印 + print CSS**(amis 页面可直接 `window.print` 定制样式);
- 版式要求高的用 **hiprint** 类开源 Web 打印或服务端渲染 PDF(openhtmltopdf)输出,避免任何浏览器控件依赖。
**前置盘点(P0 补充项)**:JOR 生产布局文件在客户部署包中、仓库不可见——需在客户环境执行一次「classpath 报表模板文件清点」,按数量定 C 类工作量。**在盘点结果出来前,C 类按 1–2 人月预留**;若清点发现实际在用的 JOR 版式很少(ActiveX 已死多年,存在"早已没人用"的可能),可压缩到 0.5 人月。
### D 类:报表数据服务流 REST 化(核心资产复用,A' 路线红利)
79 个 selectservice 服务流是报表系统真正的核心资产(全部取数/加工逻辑)。它们运行在服务流引擎(FlowExcuteService,纯 Java)上,**A' 路线后端留在 JVM,服务流引擎随 P1/P2 整体移植,报表只需在其上包一层统一 REST**(`/api/flow/{flowId}`,含参数透传与权限上下文)——这正是 PoC 中 echart.jsp 第 25 行 `flowService.excute(map, UserSession.get(), flowid)` 的 REST 化。**约 0.5 人月,且被 A/B 两类共享**。
---
## 三、工作量与排期归并
| 项 | 人月 | 归并阶段 |
|----|------|---------|
| 服务流 REST 化(共享底座) | 0.5 | P1/P2 顺带 |
| A 类转换器扩展 + 333 模板批量转换与抽检 | 0.5–1 | P4 |
| B 类图表平移 | ~0.1 | P4 |
| C 类 JOR 替换(按盘点定,先预留) | 0.5–2 | P4 末批 |
| **合计** | **1.5–3.5 人月** | 与决策会 P4「4–6 人月」中原预留的报表缺口一致,**不突破已批排期** |
## 四、风险与红线衔接
1. **JOR 布局存量是开放变量**——P0 客户环境清点前不锁定 C 类预算(对齐决策会止损线 S1 的精神)。
2. **合计行/金额列的数值正确性必须进对拍**——表格式报表的 issumcolumn 合计结果纳入 C1 逐行对拍样本(报表算错数比页面难看严重得多)。
3. **打印习惯变更需客户沟通**——ActiveX 套打 → 浏览器打印是操作习惯变化,纳入决策会「UI 形态变更」客户沟通条款(开放项 3)一并确认。
4. **337 个报表模板全部含脚本**——已天然落入既有 S1/S2/S3 脚本分桶与 facade 流程,无需新增机制。
5. 6 个 engineclass 定制报表视图并入「153 定制视图处置清单」统一决策(重写/降级/留旧)。
## 五、一句话结论
**报表迁移没有想象中可怕**:333 个表格式报表与已验证的 crud 转换器同构、图表本来就是 ECharts、取数逻辑(79 个服务流)随 Java 后端整体复用;真正要"换"的只有 JOR 复杂版式与已死的 ActiveX 打印,且替换方案(univer + Web 打印)在决策报告中已有预案。总投入 1.5–3.5 人月,不突破决策会已批的 P4 预算。