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>
230 lines
16 KiB
Markdown
230 lines
16 KiB
Markdown
# 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.script` 17 处(JSR-223,JDK17 原样可用)、`javax.servlet` 6 处(→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、对拍测试设计、最终评分)
|
||
|
||
**原则**:
|
||
1. PoC 代码按一次性看待,但**三样产物必须可复用**:XML→amis 转换映射表、SQL 对拍测试框架、Groovy 脚本分桶盘点结果。
|
||
2. 一切以「对拍」为准:新服务的正确性不靠人工目测,靠与旧系统输出逐字节比对。
|
||
3. 不做美化、不做性能优化、不接真实权限——横切服务一律打桩(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 生产库盘点(连客户库只读副本执行)
|
||
|
||
```sql
|
||
-- ① 模板类型分布
|
||
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 的质量核心)
|
||
|
||
1. 在**旧系统**的 `POJOServiceImpl` 关键出口(SQL 即将交给 JdbcTemplate 处)加日志切面,录制选定实体的全部操作 SQL + 参数 + 结果集行数,存为基准文件。
|
||
2. 新服务以同一元数据执行同一操作序列,输出同格式文件。
|
||
3. `diff` 两份文件:**SQL 文本允许空白差异,语义必须一致;结果集必须逐行一致。**
|
||
4. 操作序列至少覆盖:新增实体建表、单表 CRUD、主子表级联保存、分页+排序+查询条件组合、含数据字典翻译的查询。
|
||
|
||
> **✅ WS1 实测进展(2026-06-10,Day 1–2)**:`eip4-poc` 工程已搭建并对客户库副本跑通。
|
||
> 核心引擎(POJOCRUDServiceImpl 610 行 + POJOServiceImpl 1,346 行)**零修改编译**;
|
||
> Spring API 断点仅 `queryForInt/queryForLong` 7 处;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 任务
|
||
|
||
1. 在 `eip4-poc-metadata` 上加 REST 层:`GET/POST /api/entity/{name}`(列表/分页/CRUD),响应格式直接做成 **amis CRUD 约定格式**(`{status, msg, data: {items, total}}`),省一层适配。
|
||
2. 加 `springdoc-openapi`,确认 OpenAPI 文档自动生成(AI 友好度的后端半边)。
|
||
3. 手写选定功能的 amis schema:`crud`(列/查询区/工具栏按钮,对照模板 XML 的 display/search/button)+ 主子表(行展开或 form 内 `input-table`)。
|
||
4. **校验闭环**:用 ajv(draft-07)加载存档的 `schema.json`,对手写及 AI 生成的页面 schema 做机器校验,记录误报/漏报。
|
||
5. 产出 **XML→amis 映射表**:模板 XML 每个元素/属性 → amis schema 对应物 → 映射难度标记(自动转/半自动/人工),这是 P4 批量转换器的种子。
|
||
|
||
### 4.2 还原度评分卡(对照旧系统逐项打分:0 不可用 / 1 有差距 / 2 等价)
|
||
|
||
| 项 | 旧系统行为 | 得分 |
|
||
|----|-----------|------|
|
||
| 列表列渲染(含字典翻译、格式化) | | |
|
||
| 查询区(含默认值、联动过滤) | | |
|
||
| 主子表级联编辑与保存 | | |
|
||
| 工具栏按钮 + 权限位 | | |
|
||
| 表单校验(对照「校验器」配置) | | |
|
||
| 分页/排序/列宽 | | |
|
||
|
||
**证伪条件**:总分 < 满分 60%,或出现「无 amis 对应物且自定义组件工作量 > 3 人日」的必需交互 ≥ 2 项。
|
||
|
||
---
|
||
|
||
## 5. WS3:Groovy 脚本双轨验证(Q3)
|
||
|
||
**负责**:后端 | **工期**:Day 4–5
|
||
|
||
1. **S1 轨(零翻译)**:取选定功能的 1 个纯服务端脚本(校验/计算类),在新服务的 `ScriptingEnginesManager`(JSR-223 + Groovy 4.x)上原样执行,对拍输出。预期:除 Groovy 2→4 语法边角(如 `@TypeChecked` 行为、JDK 内部 API)外零修改。
|
||
2. **S2 轨(声明式翻译)**:取 1 个真实 valueChange 联动脚本,翻译为 amis `onEvent` + 表达式,旧新行为录屏对照。
|
||
3. **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
|
||
|
||
1. Flowable 7.x 开源版独立部署(Docker + PG,启用 REST API)。
|
||
2. 将脱敏库的 ACT_* 表整体指给 Flowable,启用 `flowable5-compatibility`,验证:
|
||
- 存量流程定义可见、可发起新实例
|
||
- **运行中的旧实例**可继续办理至结束
|
||
- 历史查询(已办/待办)数据完整
|
||
3. 新服务通过 REST 完成一次「发起 → 审批 → 回写业务表」闭环(审批结果回写用事件/回调,验证与元数据服务的集成面)。
|
||
|
||
**证伪条件**:运行中实例续跑失败且无官方解法;或选定流程用到 Activiti 5 专有扩展(自定义 ServiceTask 类)无法在兼容层加载——后者需盘点全部流程定义中的 `activiti:class` 引用再评估。
|
||
|
||
---
|
||
|
||
## 7. WS5:AI 闭环冒烟(半天,Day 6)
|
||
|
||
**负责**:架构 | 目的:给「AI 友好度 8.5 分」找实证,不追求完整 MCP Server。
|
||
|
||
1. 写一个最小 MCP Server(或直接给 Claude Code 提供 OpenAPI 文档 + schema.json + 映射表作为上下文)。
|
||
2. 任务:「新增一个实体(含 5 个字段)+ 生成其管理列表页」。
|
||
3. 记录:成功率(3 次尝试)、人工干预次数、ajv 校验拦截了多少无效生成。
|
||
4. 关注点: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. 交付物清单
|
||
|
||
1. PoC 决策会报告(评分卡 + 录屏 + 对拍 diff 报告)
|
||
2. Groovy 脚本分桶盘点报告(S1/S2/S3 数量、占比、Top 风险脚本清单)
|
||
3. XML→amis 映射表 v0(P4 转换器的输入)
|
||
4. SQL 对拍测试框架(P1 阶段持续使用)
|
||
5. `eip4-poc` 代码仓库(标注哪些可进正式工程、哪些抛弃)
|
||
6. amis 6.13.0 + schema.json 锁定存档与 fork 维护成本测算备忘(供管理层做 fork 预算对齐)
|