- 从工作区根 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>
16 KiB
EIP3 路线 A'(amis + Java/Spring Boot)PoC 详细执行方案
版本:v1.0(2026-06-10) 前置文档:《EIP3重构评估报告.docx》《EIP3架构决策报告.md》 PoC 性质:证伪型验证,不是预研。每个工作流都有明确的「出现即推翻裁决」的中止条件。 时间盒:7 个工作日,超时即按当时证据强制决策,不延期。
0. PoC 要回答的四个问题
| # | 问题 | 对应裁决中的不确定点 |
|---|---|---|
| Q1 | Spring 3.1/JDK6 → Spring Boot 3/JDK17 是「升级移植」还是会退化为「重写」? | 决策报告第六节第 1 条(最大不确定点) |
| Q2 | amis 对「主子表 + 联动」的还原度是否达标?schema.json 校验闭环是否真实可用? | A/A' 共同前提 |
| Q3 | Groovy 脚本「纯服务端零翻译 + UI 绑定走 facade」的分级方案是否成立? | 决策报告第六节第 6 条 |
| Q4 | Activiti 5.14 流程定义 + 运行中历史实例能否在 Flowable 上平滑续跑? | 事实核查已 confirmed,PoC 做实操复核 |
0.1 本次源码预核查结论(2026-06-10,已实测)
PoC 方案中的工作量判断基于以下对 framework/ 的实际检查,不是推测:
POJOCRUDServiceImpl.java(610 行,com.dsasp.server.dataDic):零 Vaadin 依赖,import 只有 JDK、Spring(@Service/@Transactional/@Autowired)和内部服务接口。POJOServiceImpl.java(1,346 行,SQL 拼装引擎):同模块,待 PoC 中逐项核对。- 唯一 OSGi 耦合点
SpringBeanOsgiServices(com.dsasp.server.common,72 行):本质是遍历 bundle 注册服务按名取 bean 的服务定位器,Spring Boot 下可用ApplicationContext.getBean(name)直接等价替换。 - 服务端 import Vaadin 的文件全 framework 仅 2 个:
com.dsasp.server.app/.../WfRestConstroller.java、com.dsasp.server.kaoqin/.../UserSelectWindow.java,均不在 PoC 路径上。 - javax.* 使用(dataDic+common+core 三模块):
javax.script17 处(JSR-223,JDK17 原样可用)、javax.servlet6 处(→jakarta,机械替换)、其余忽略。 com.dsasp.server.dataDic.binding.ScriptingEnginesManager:已是标准javax.script.Bindings+ 编译缓存模式,脚本引擎本身与 Vaadin 无关——Vaadin 对象是 client 侧调用时塞进 Bindings 的,这正是 facade 方案的依据。
1. 范围、人员与原则
验证功能:从生产库选一个真实的「主子表 + 审批流 + 字段联动脚本」功能(P-0 盘点后定,候选优先级:含 1 个 valueChange 联动 + 1 个服务端校验脚本 + 走审批的单据类功能)。
人员(2.5 人 × 7 天):
- 后端 1 名(熟 EIP3 的老员工,负责 WS1/WS3/WS4)
- 前端 1 名(React 背景,负责 WS2,可外部支援)
- 架构/AI 0.5 名(负责 WS5、对拍测试设计、最终评分)
原则:
- PoC 代码按一次性看待,但三样产物必须可复用:XML→amis 转换映射表、SQL 对拍测试框架、Groovy 脚本分桶盘点结果。
- 一切以「对拍」为准:新服务的正确性不靠人工目测,靠与旧系统输出逐字节比对。
- 不做美化、不做性能优化、不接真实权限——横切服务一律打桩(stub),只验证打桩点的接口形状是否可保留。
2. P-0 前置准备(Day 0,半天~1 天)
✅ 2026-06-10 已完成:2.1/2.2 的库上盘点已对客户库测试副本(192.168.20.68:5435/eip3)执行完毕,结果见《EIP3客户库盘点报告.md》。要点:1,516 模板 / 1,427 条脚本,S3 形式占比 43% 但真困难仅 5.3%(facade 动词表扩到 ~20 个可覆盖 88% 的 S3);1,509 个 BPMN 零
activiti:class自定义扩展;新增工作项:153 个 engineclass 定制视图(1.5–3 人月)、PG 9.4→15+ 升级前置。引擎实测 5.13-SNAPSHOT(非 5.14)。
2.1 生产库盘点(连客户库只读副本执行)
-- ① 模板类型分布
SELECT TYPE, COUNT(*) FROM VIEW_TEMPLATE GROUP BY TYPE ORDER BY 2 DESC;
-- ② 含脚本的模板数(XML 里有 <script)
SELECT TYPE, COUNT(*) FROM VIEW_TEMPLATE
WHERE TEMPLATE_XML LIKE '%<script%' GROUP BY TYPE;
-- ③ 实体规模
SELECT COUNT(*) FROM SYS_ENTITY;
SELECT COUNT(*) FROM SYS_ENTITYATTRIBUTE;
字段名以实际表结构为准;若 XML 存于 CLOB,②改为导出后用脚本统计。
2.2 Groovy 脚本分桶(裁决的关键开放变量)
导出全部模板 XML,写一个一次性脚本按以下规则分桶并出报告:
| 桶 | 判定特征(脚本文本匹配) | 处理策略 |
|---|---|---|
| S1 纯服务端 | 不含 FieldGroup、com.vaadin、getField、setVisible 等 UI 词汇 |
A' 下零翻译续跑 |
| S2 简单 UI 联动 | 仅使用平台辅助函数(getFieldValue/bindField/setFieldReadOnly)+ po/event,或 setValue/setVisible/过滤数据源 |
facade 换实现,脚本近零修改(见预核查报告核查 5) |
| S3 复杂 UI 绑定 | 匹配 group. 直接调用 Vaadin API ∪ ConfirmDialogListener(同步等待用户输入)∪ 动态创建 Vaadin 组件 |
逐个评估:改回调链 / 下沉后端 / 人工翻译 |
输出:S1/S2/S3 数量与占比。触发线:S3 占比 > 30% 或 (S2+S3) > 70% → 按决策报告第四节条件 3 上报,重估工期。
2.3 环境
- JDK 17(Temurin)、Spring Boot 3.3.x、Maven/Gradle 新工程
eip4-poc/ - PostgreSQL 15+:恢复一份脱敏的客户库子集(含 SYS_ENTITY、SYS_ENTITYATTRIBUTE、VIEW_TEMPLATE、选定功能的业务表、ACT_* 全套 Activiti 表)。注意:① 客户库实为 PG 9.4.26(EOL),PoC 环境直接用 PG 15 恢复,顺带验证 9.4→15 升级兼容性(这已成为 P1 前置项);② 流程定义与业务模板只存在于库中(源码无 .bpmn 文件),WS4 用的流程从
ACT_GE_BYTEARRAY导出,引擎 schema 实测 5.13-SNAPSHOT - 前端:Node 20 +
amis@6.13.0(锁版本,下载https://unpkg.com/amis@6.13.0/schema.json入库存档) - 旧系统一套可运行环境(对拍基准)
3. WS1:元数据引擎移植(Q1,核心证伪轨)
负责:后端 | 工期:Day 1–4 | 这是整个 PoC 的成败手
3.1 移植清单(按依赖顺序)
| 步骤 | 内容 | 预核查依据 |
|---|---|---|
| 1 | 新建 eip4-poc-metadata Spring Boot 3 模块;拷入 com.dsasp.server.common 中 dataDic 相关接口与 bean(POJOCRUDService、POJOService、GeneralPOJO、POJOInfo、DisplayType 等) |
接口层无 OSGi 依赖 |
| 2 | 拷入 com.dsasp.server.dataDic 全模块(17 个 Java 文件):POJOCRUDServiceImpl(610行)、POJOServiceImpl(1346行)、Entity/POInfo/GeneralPO、binding/ScriptingEnginesManager |
已确认纯 Spring |
| 3 | 替换 SpringBeanOsgiServices.getBeanByName() → 注入 ApplicationContext 的 getBean(name);删除 BundleListener 逻辑 |
72 行服务定位器,等价替换 |
| 4 | 横切依赖打桩:DataPrivilegeService(返回「不过滤」)、SystemLogManager(打日志)、FileService(空实现)、LoggedInUser/UserSession(固定测试用户)。接口签名原样保留——P2 阶段移植真实现时直接替换 |
POJOCRUDServiceImpl import 列表已确认就这几个 |
| 5 | javax.servlet → jakarta.servlet(全 PoC 范围约 6 处);javax.script 不动 |
实测统计 |
| 6 | Spring JDBC 3.1 → 6.x:SimpleJdbcTemplate 改写JdbcTemplate×21/SqlRowSet×15 等 Spring 6 保留 API);改造项只剩 commons-dbcp → HikariCP + com.dsasp.server.db/META-INF/spring/db.xml 事务配置转 Java Config |
预核查已降级,省出的时间投给 3.2 对拍 |
| 7 | 数据源指向 PG 脱敏库,跑通:读 SYS_ENTITY → 动态建一张新表 → CRUD → 分页查询 |
3.2 SQL 对拍测试(本 PoC 的质量核心)
- 在旧系统的
POJOServiceImpl关键出口(SQL 即将交给 JdbcTemplate 处)加日志切面,录制选定实体的全部操作 SQL + 参数 + 结果集行数,存为基准文件。 - 新服务以同一元数据执行同一操作序列,输出同格式文件。
diff两份文件:SQL 文本允许空白差异,语义必须一致;结果集必须逐行一致。- 操作序列至少覆盖:新增实体建表、单表 CRUD、主子表级联保存、分页+排序+查询条件组合、含数据字典翻译的查询。
✅ WS1 实测进展(2026-06-10,Day 1–2):
eip4-poc工程已搭建并对客户库副本跑通。 核心引擎(POJOCRUDServiceImpl 610 行 + POJOServiceImpl 1,346 行)零修改编译; Spring API 断点仅queryForInt/queryForLong7 处;OSGi 解耦 = 1 个 72 行替换类。 全量 1,166 实体一致性扫描 0 计数不一致(99.1% 通过,超 95% 线); 写路径(动态建表 + INSERT/UPDATE/DELETE + 校验)8/8 通过。 3.3 的三个证伪条件均未触发,WS1 实质通过。 详见eip4-poc/README.md。
3.3 WS1 证伪条件(出现即停,回退路线 A)
- 发现业务代码深度依赖 OSGi classloader 行为(如按 bundle 反射加载类、动态导出 package),替换面 > 移植代码量的 30%
- Spring JDBC 升级触发连锁改写(如大量使用已删除 API、事务语义不等价且无法对拍通过)
- Day 4 结束时对拍测试通过率 < 80%,且剩余差异无收敛趋势
4. WS2:REST + JSON Schema 门面 + amis 主子表还原(Q2)
负责:前端 + 后端配合 | 工期:Day 2–5(与 WS1 部分并行,依赖 WS1 步骤 7)
4.1 任务
- 在
eip4-poc-metadata上加 REST 层:GET/POST /api/entity/{name}(列表/分页/CRUD),响应格式直接做成 amis CRUD 约定格式({status, msg, data: {items, total}}),省一层适配。 - 加
springdoc-openapi,确认 OpenAPI 文档自动生成(AI 友好度的后端半边)。 - 手写选定功能的 amis schema:
crud(列/查询区/工具栏按钮,对照模板 XML 的 display/search/button)+ 主子表(行展开或 form 内input-table)。 - 校验闭环:用 ajv(draft-07)加载存档的
schema.json,对手写及 AI 生成的页面 schema 做机器校验,记录误报/漏报。 - 产出 XML→amis 映射表:模板 XML 每个元素/属性 → amis schema 对应物 → 映射难度标记(自动转/半自动/人工),这是 P4 批量转换器的种子。
4.2 还原度评分卡(对照旧系统逐项打分:0 不可用 / 1 有差距 / 2 等价)
| 项 | 旧系统行为 | 得分 |
|---|---|---|
| 列表列渲染(含字典翻译、格式化) | ||
| 查询区(含默认值、联动过滤) | ||
| 主子表级联编辑与保存 | ||
| 工具栏按钮 + 权限位 | ||
| 表单校验(对照「校验器」配置) | ||
| 分页/排序/列宽 |
证伪条件:总分 < 满分 60%,或出现「无 amis 对应物且自定义组件工作量 > 3 人日」的必需交互 ≥ 2 项。
5. WS3:Groovy 脚本双轨验证(Q3)
负责:后端 | 工期:Day 4–5
- S1 轨(零翻译):取选定功能的 1 个纯服务端脚本(校验/计算类),在新服务的
ScriptingEnginesManager(JSR-223 + Groovy 4.x)上原样执行,对拍输出。预期:除 Groovy 2→4 语法边角(如@TypeChecked行为、JDK 内部 API)外零修改。 - S2 轨(声明式翻译):取 1 个真实 valueChange 联动脚本,翻译为 amis
onEvent+ 表达式,旧新行为录屏对照。 - S3 轨(facade 最小实现):预核查已确认平台自带「准 facade」——脚本经
DEFAULTFUNCTION注入的 4 个辅助函数(getFieldValue/bindField/setFieldReadOnly/showConfirmDialog)全部委托FormEngineUtil,且绑定契约只有group/po/event/obj四个变量。本轨直接做FormEngineUtil的 amis 版最小实现:保持 4 个函数签名不变,实现改为「生成 amis 事件动作指令下发前端」,用 1 个真实脚本跑通。重点验证showConfirmDialog类同步交互改回调链的可行性。
证伪条件:S1 脚本在 Groovy 4 上需要实质性改写(不只是边角语法);或 facade 指令通路在 amis 事件模型上无法表达「脚本中途读取用户输入再继续」类交互(同步阻塞语义)——此时 S3 全量降级为人工翻译,需带回 2.2 的占比数据重估工期。
6. WS4:Flowable 迁移实操(Q4)
负责:后端 | 工期:Day 5–6
- Flowable 7.x 开源版独立部署(Docker + PG,启用 REST API)。
- 将脱敏库的 ACT_* 表整体指给 Flowable,启用
flowable5-compatibility,验证:- 存量流程定义可见、可发起新实例
- 运行中的旧实例可继续办理至结束
- 历史查询(已办/待办)数据完整
- 新服务通过 REST 完成一次「发起 → 审批 → 回写业务表」闭环(审批结果回写用事件/回调,验证与元数据服务的集成面)。
证伪条件:运行中实例续跑失败且无官方解法;或选定流程用到 Activiti 5 专有扩展(自定义 ServiceTask 类)无法在兼容层加载——后者需盘点全部流程定义中的 activiti:class 引用再评估。
7. WS5:AI 闭环冒烟(半天,Day 6)
负责:架构 | 目的:给「AI 友好度 8.5 分」找实证,不追求完整 MCP Server。
- 写一个最小 MCP Server(或直接给 Claude Code 提供 OpenAPI 文档 + schema.json + 映射表作为上下文)。
- 任务:「新增一个实体(含 5 个字段)+ 生成其管理列表页」。
- 记录:成功率(3 次尝试)、人工干预次数、ajv 校验拦截了多少无效生成。
- 关注点:929KB 的 schema.json 不能整体进上下文——验证「按组件子集裁剪 schema」的可行性,为 P5 的提示词工程定基调。
8. 日程总表
| 日 | 后端 | 前端 | 架构 |
|---|---|---|---|
| D0 | 盘点 SQL + 脚本分桶 | 环境/amis 跑通 demo | 选定典型功能、对拍方案设计 |
| D1 | WS1 步骤1–3(工程+拷代码+去OSGi) | 研究模板 XML 结构 | — |
| D2 | WS1 步骤4–6(打桩+jakarta+JDBC升级) | WS2.3 手写 amis schema | — |
| D3 | WS1 步骤7 + 旧系统 SQL 录制 | WS2.1/2.2 REST 对接 | 对拍框架就位 |
| D4 | WS1 对拍修差异;WS3 S1 轨 | WS2.4 校验闭环 | — |
| D5 | WS3 S2/S3 轨 | WS2.5 映射表 + 评分卡 | WS4 Flowable 部署 |
| D6 | WS4 兼容性验证 | 还原度终评 | WS5 AI 冒烟 |
| D7 | 缓冲 + 报告 | 缓冲 + 报告 | 汇总评分、决策会材料 |
9. 决策会评分与裁决规则(D7)
| 工作流 | 通过标准 | 证伪后果 |
|---|---|---|
| WS1 | 对拍 ≥ 95% 通过;OSGi/Spring 改造量在移植范围 30% 以内 | 回退路线 A(NestJS 重写后端),前端结论沿用 |
| WS2 | 还原度 ≥ 60%;校验闭环可用 | A 与 A' 同时受损 → 触发前端二次选型 |
| WS3 | S1 零翻译成立;facade 通路证明存在 | S3 全量人工翻译,按分桶占比重估工期,可能上调 2–4 人月 |
| WS4 | 存量实例续跑成功 | 改为「老流程旧系统跑完、新流程 Flowable」双轨过渡 |
| WS5 | 3 次尝试 ≥ 2 次成功 | 不否决路线,但 P5 工期上修并前置提示词工程 |
全局规则:WS1 与 WS2 任一证伪 → 当场按决策报告第三节的回退矩阵改道,不二次延期 PoC。
10. 交付物清单
- PoC 决策会报告(评分卡 + 录屏 + 对拍 diff 报告)
- Groovy 脚本分桶盘点报告(S1/S2/S3 数量、占比、Top 风险脚本清单)
- XML→amis 映射表 v0(P4 转换器的输入)
- SQL 对拍测试框架(P1 阶段持续使用)
eip4-poc代码仓库(标注哪些可进正式工程、哪些抛弃)- amis 6.13.0 + schema.json 锁定存档与 fork 维护成本测算备忘(供管理层做 fork 预算对齐)