docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
Some checks failed
ci / build-test-parity (push) Has been cancelled

- 从工作区根 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>
This commit is contained in:
2026-06-17 14:52:50 +08:00
parent 838669f124
commit 1b69f8b481
54 changed files with 7485 additions and 0 deletions

View File

@@ -0,0 +1,94 @@
# 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 预算。