Files
eip4-platform/docs/决策与盘点/EIP3路线A-PoC执行方案.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

230 lines
16 KiB
Markdown
Raw Permalink 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 路线 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 预算对齐)