diff --git a/docs/迁移手册.md b/docs/迁移手册.md index 726743b..009c23d 100644 --- a/docs/迁移手册.md +++ b/docs/迁移手册.md @@ -274,6 +274,34 @@ com.dsasp.* com.eip4.* - **对策**:C3 压测已把此类实体列为热点;P2「渐进参数化 + Caffeine」与「DDL 索引增强」改造的优先验证对象;对拍用抽样模式(--sampleRows)。 - **影响范围**:带多引用显示列的大表;真实用户的列表页延迟(决策会风险 R2 直接证据)。 +### 5.15 服务流脚本默认导入含 Vaadin UI 类,缺失则每个脚本编译失败 [NEW 2026-06-11] + +- **现象**:服务流引擎移植后,**任何**带 groovy 脚本的服务流经 REST 执行报 HTTP 500,日志为 `MultipleCompilationErrorsException: unable to resolve class client.groovy.TestService` / `com.dsasp.client.viewframework.component.MainComponent`。 +- **根因**:`SecureGroovyScriptEngineFactory.DEFAULTIMPORTSLIST` 经 `imports.addImport(it)` 把这两条 Vaadin 客户端 UI 类作为**默认导入逐脚本注入**;它们属已淘汰 Vaadin 表现层,eip4-platform 保真层不含,classpath 缺失令编译期解析失败。`IMPORTSWHITELIST`/`STARIMPORTSWHITELIST` 里的 Vaadin 类是 AST 白名单字符串(不加载),无害;只有 `DEFAULTIMPORTSLIST` 真加载。 +- **对策**:`SecureGroovyScriptEngineFactory.groovy` 的 `DEFAULTIMPORTSLIST` 移除这两条 Vaadin 默认导入(原值在源码注释登记供 diff 溯源),保留 8 条服务端导入(GeneralPOJO/POJOCRUDService/StringUtil/三个 Get*Function/Console 等,均已就位)。属「确需替换的类按保包名/类名/签名纪律」适配。 +- **影响范围**:**所有**含脚本的服务流(D 类 79 个全部含脚本);P4 脚本批量转换/运行时脚本加载;凡移植 SecureGroovy 工厂的环境必做此适配。 + +### 5.16 服务流脚本引擎的 juel 来自 activiti,保真层不引 activiti [NEW 2026-06-11] + +- **现象**:`core.service.script.ScriptingEnginesManager` 原版 `new org.activiti.engine.impl.scripting.JuelScriptEngineFactory()` 注册 juel(`${...}`)引擎;保真层无 activiti 依赖,编译失败。 +- **根因**:framework 的流脚本引擎复用了 activiti-engine-5.14 的 juel 工厂;架构设计第二节裁定 activiti/Flowable **仅存在于独立工作流服务**,禁止进入保真层运行时(EOL 工件 + 私有化部署中间件最小化)。 +- **对策**:适配为 JSR-223 名称惰性注册(classpath 提供 juel 引擎则注册其 factory,否则跳过),groovy 路径与类签名逐字不变。juel 仅服务流**带条件转移**(`${...}` transition / initExpression)时触发;D 类查询/报表为线性流(start→service→end)不走 juel,不受影响。带分支流的 juel 支持随 P3 工作流(Flowable)落地补。 +- **影响范围**:带条件分支的服务流(如 DefaultFlowHelper 的 SAVE_AND_SUBMIT);P3 工作流;不引入 activiti 是保真层依赖纪律(对照 §5.10 Jackson 1.x 是「引入共存」,此处是「不引入」)。 + +### 5.17 OSGi Activator 不移植,流引擎 bean 靠组件扫描 + SpringBeanOsgiServices 注册 [NEW 2026-06-11] + +- **现象**:framework `com.dsasp.server.core.Activator` 是 OSGi `BundleActivator`(org.osgi.* + sun.awt.ComponentFactory + ServiceTracker),JDK17 不可用且无 OSGi 容器。 +- **根因**:OSGi 生命周期类,服务注册/发现走 bundle 机制;Boot 3 用 Spring 容器替代。 +- **对策**:**不移植 Activator**(PoC 全模块零 Activator 先例)。流引擎三 bean(`flowExcuteService`/`flowService`/`flowPrivilegeService`/`originServiceManager`)靠 `@Service(value=...)` + 组件扫描(scanBasePackages 含 com.dsasp)自动注册;运行期按名取 bean 走 `SpringBeanOsgiServices.getBeanByName`(已是 @Component 替换实现,§3.1)。`FlowServiceImpl.jdbcTemplate` 非 @Autowired 字段,在 `LegacyXmlWiring` 补 setter 注入(等价原 XML ,§4.1)。 +- **影响范围**:凡移植带 Activator 的 framework 模块;bean 注册改由 @Service 名 + LegacyXmlWiring setter 补齐。 + +### 5.18 REST 服务流入口不区分读写,需流定义审阅 + P2 防护 [NEW 2026-06-11] + +- **现象**:`/api/flow/{id}` 把任意服务流交给引擎 excute;引擎一个流既可挂 listSelect(读)也可挂 save/update/delete(写)service 节点,门面无法仅凭 flowId 区分读写。 +- **根因**:服务流引擎设计为通用执行器(读写同入口 excute);读写语义在流定义 XML 的 service 节点 method 里,门面层不解析。 +- **对策**:P1 不在门面做引擎级读写闸(避免误判);**调用方/运维按流定义 XML 审阅确认查询/报表类后放行**,客户库只读纪律下只执行已审阅无写动作的流。P2 补三层防护:①流定义静态扫描(service method 读白名单);②最小权限只读连接;③statement_timeout。 +- **影响范围**:所有经 REST 执行的服务流;客户库只读期的流挑选;P2 安全加固(对齐架构第四节安全第 1/3/4 层)。 + ## 六、Flowable 升级三坑 > 来源:eip4-poc WS4 实测,flowable-poc / flowable5-poc 工程(2026-06-10) diff --git a/platform-metadata/P1服务流实测报告.md b/platform-metadata/P1服务流实测报告.md new file mode 100644 index 0000000..a1a9b96 --- /dev/null +++ b/platform-metadata/P1服务流实测报告.md @@ -0,0 +1,238 @@ +# P1 服务流引擎移植 + REST 化实测报告 + +> 阶段:P1-2(EIP3 工程化实施计划 P1 节)|日期:2026-06-11 +> 工程:eip4-platform(双层制:保真层 com.dsasp.* 原样 / 现代层 com.eip4.*) +> 依据:docs/架构设计.md、docs/迁移手册.md、../docs/决策与盘点/EIP3工程化实施计划.md(P1)、 +> ../docs/决策与盘点/EIP3报表迁移方案.md(D 类口径) +> 性质:服务流引擎(FlowExcuteService)移植入保真层 + REST 门面(报表方案 D 类底座)+ 实测验证 + +--- + +## 一、移植清单(共 31 个 com.dsasp.* 文件 + 1 现代层门面 + 自举/单测) + +### 1.1 服务流引擎核心(framework com.dsasp.server.core,16 .java + 2 .groovy) + +> framework 该模块共 17 个 .java;**OSGi `Activator.java` 不移植**(见 §2 替换类登记)。 + +| 包 | 文件 | 说明 | +|----|------|------| +| `core.service` | FlowExcuteServiceImpl.java(534 行)| 服务流执行入口(excute/checkControl/excuteNode/transition)| +| `core.service` | FlowServiceImpl.java | 流定义加载(loadFlowXml→loadPOJO)+ 默认流生成/保存 | +| `core.service.flow.model` | Flow / Node / Field / Procedure / Script / ServiceBean / Start / End / Transition | 流模型 POJO + XML 解析(Flow.initial via dom4j)| +| `core.service.flow.model` | BaseFlowConvert / DefaultFlowHelper | 流↔XML↔Map 转换、CRUD 默认流模板 | +| `core.service.script` | ScriptingEnginesManager / FlowScriptBindings | 流脚本引擎(groovy + juel)、脚本绑定 | +| `core.origin.service` | OriginServiceManagerImpl.java | 原始服务注册表(服务设计器用,非执行路径)| +| `core.script.secure`(.groovy)| SecureGroovyScriptEngineFactory / MethodCallExpressionChecker | 安全 Groovy 引擎工厂 + AST 检查(禁 System.exit)| + +### 1.2 缺失 common 依赖回填(framework com.dsasp.server.common,8 .java) + +| 文件 | 类型 | 引擎依赖点 | +|------|------|-----------| +| `common.core.ControlBean` | 类 | checkControl 服务控制查询 | +| `common.core.FlowDefinition` | 接口 | Flow 的契约 | +| `common.core.service.FlowExcuteService` | 接口 | REST 门面/excuteFlow 入口 | +| `common.core.service.FlowService` | 接口 | 流定义加载 | +| `common.core.service.OriginServiceManager` | 接口 | OriginServiceManagerImpl 契约 | +| `common.util.AopTargetUtils` | 类 | service 节点解 AOP 代理取目标 | +| `common.util.ExceptionUtil` | 类 | 异常转字符串日志 | +| `common.privilege.service.FlowPrivilegeService` | 接口 | 流鉴权 | + +### 1.3 函数库回迁(替换 PoC 空桩,framework 原版 .groovy) + +| 文件 | PoC 状态 | P1 处置 | +|------|---------|---------| +| `common.function.GetValueFunction` | 空桩(仅 class 声明)| **回迁 framework 原版 Groovy(780 行)**,依赖(Function/ValidationException/StringUtil/joda)均已就位 | +| `common.function.GetDefaultValueFunction` | 空桩 | **回迁 framework 原版 Groovy(88 行)**,依赖(SysConfig/LoggedInUser/UserSession)均已就位;引擎用 getCurrentUserId/currentDate/guid | +| `common.function.GetServicesFunction` | 仅 findCount | **保包名/类名/签名回迁**(findCount + loadPOJO + listSelect,见 §3 桩回迁 diff)| + +### 1.4 FlowPrivilegeService(framework com.dsasp.server.privilege,C2 同款移植,3 文件) + +| 文件 | 说明 | +|------|------| +| `privilege.service.FlowPrivilegeServiceImpl` | 流鉴权实现(authority/getServicePrivileges)| +| `privilege.service.ServicePrivilege` | 角色→可调服务流缓存(CCache)| +| `common.privilege.service.FlowPrivilegeService`(见 1.2)| 接口 | + +> 依赖 bean 核对:FlowPrivilegeServiceImpl/ServicePrivilege 仅依赖 SpringBeanOsgiServices/ +> CCache/POJOService/FlowService/LoggedInUser/UserSession(均已就位);task 提示的 +> `common.privilege.bean.ServiceFlow`/`ServiceFlowPrivilege` **未被这两个类引用**(grep 核实), +> 故 P1 不移植,登记备查(P2 数据/功能权限真实现时若需再移)。 + +### 1.5 现代层 + 自举 + 单测 + +| 文件 | 模块 | 说明 | +|------|------|------| +| `web.FlowController` | platform-metadata | 服务流 REST 门面(§4 契约)| +| `app.config.LegacyXmlWiring`(改)| platform-app | 补 FlowServiceImpl.setJdbcTemplate(等价原 XML 注入)| +| `bootstrap/bootstrap-flow.sql` | platform-parity | 本地 eip4m0 自举:SYS_SERVICEFLOW + 元数据 + 最小查询流 | +| FlowModelParseTest / FlowControllerTest / FlowExecuteLocalIT | 三模块 | 18 单测(§6)| + +--- + +## 二、替换类 / 不移植类登记(双层制「确需替换的类按 PoC 保包名/类名/签名纪律」) + +| 类 | framework 原状 | P1 处置 | 理由(架构/纪律依据)| +|----|---------------|---------|---------------------| +| `core.Activator` | OSGi BundleActivator(org.osgi.* + sun.awt.ComponentFactory + ServiceTracker)| **不移植** | 纯 OSGi 生命周期,JDK17 不可用(sun.awt 不导出);等价能力已由 `SpringBeanOsgiServices`(@Component)+ Spring 组件扫描接管(迁移手册 §3.1)。PoC 全模块零 Activator,沿用此先例 | +| `core.service.script.ScriptingEnginesManager`(juel 注册行)| `new org.activiti.engine.impl.scripting.JuelScriptEngineFactory()` | **适配**:改 JSR-223 名称惰性注册 | 架构设计第二节裁定 activiti/Flowable 仅存在于独立工作流服务,**禁止进入保真层运行时**;不引入 EOL 的 activiti-engine-5.14。groovy 路径与类签名逐字不变;juel(`${...}` 条件转移)仅带条件分支的流触发,D 类查询/报表为线性流不走 juel。带分支流的 juel 支持随 P3 工作流落地 | +| `core.script.secure.SecureGroovyScriptEngineFactory`(DEFAULTIMPORTSLIST 两条)| `client.groovy.TestService` + `com.dsasp.client.viewframework.component.MainComponent` 作默认导入 | **适配**:移除这两条 Vaadin UI 默认导入 | 二者经 `imports.addImport` 逐脚本注入,属已淘汰 Vaadin 表现层(保真层不含),classpath 缺失会使**每个**服务流脚本编译失败(`MultipleCompilationErrorsException: unable to resolve class`)。与服务端取数无关。原值在源码注释登记供 diff 溯源 | +| `core.service.ScriptingEnginesManager`(dataDic.binding 版 vs core 版同源 diff)| 两版同源(同异常解包/Console 调试/单例)| **两版并存**(与 framework 一致)| framework 原本即在 `dataDic.binding`(CRUD 引擎用,GroovyScriptEngineFactory)与 `core.service.script`(流引擎用,Secure+juel)两包各存一份;POJOServiceImpl 用前者、FlowExcuteServiceImpl 用后者。保留两份 = 与 framework diff 最小(已核实 framework 同此结构)| + +--- + +## 三、桩回迁 diff 摘要:GetServicesFunction(保包名/类名/签名) + +framework `GetServicesFunction.groovy`(136 行 @Function 库)依赖 OrganizationService / +UserFindService / WorkCalendarService / ProcessCoreService / ChangeStatus / Enumerate 等 +**P2/P3 横切服务**(P1 未移植,逐条移会令保真层膨胀数百文件,违「最小 diff」)。按纪律 +保 `com.dsasp.server.common.function.GetServicesFunction` 同名同签名,回迁引擎执行路径 +**实际调用**的方法子集,委托目标 bean 与 framework Groovy 逐字一致: + +``` +PoC 桩: 仅 findCount(String) → dataDicService.findCount +P1 回迁(+2 方法): + loadPOJO(String,String,Boolean) → pojoCRUDService.loadPOJO(...,UserSession.get(),...) + + listSelect(Map,String,Properties) → pojoCRUDService.listSelect(map,tableName,ctx) +``` + +引擎调用点核实:`POInfo.java:860`(findCount)、`FlowExcuteServiceImpl.checkControl` 与 +`ControlBean.getControl`(loadPOJO / listSelect)。其余 @Function 方法(listSelectResultBySql / +excuteFlow / convertIdsToUserIds / getWFVariable 等)随 P2/P3 对应横切服务移植时按 framework +原版补全 —— 见 §7 已知限制。 + +GetValueFunction / GetDefaultValueFunction 则**回迁 framework 完整原版 Groovy**(依赖已全就位), +非桩。 + +--- + +## 四、REST 契约(FlowController) + +``` +GET /api/flow/{id}?k=v&... query 参数 → 服务流入参 map(查询/报表类) +POST /api/flow/{id} body=JSON JSON body → 服务流入参 map(参数多/带结构) +``` + +响应统一封装(amis 约定): + +```jsonc +{ "status": 0, "msg": "", + "data": { // 引擎 output 字段 map 归一化结果 + "result": { // 查询流 output 名(listSelect 结果被归一化) + "items": [ {"_id":"...","COL1":..., ...}, ... ], // listresult → items(GeneralPOJO 展平) + "total": 26 // pagecount → total + } + } +} +``` + +归一化规则(递归):`GeneralPOJO`→平面行(`_id` + 各列);含 `listresult` 的 map → +`{items,total}`;其余 Map/List 递归;标量原样。OpenAPI 注解齐备(/v3/api-docs 实测含两路由)。 + +### 4.1 REST 入口读写时机(仅放行查询类服务流) + +**引擎本身不区分读写**:一个流既可挂 listSelect(读)也可挂 save/update/delete(写)service +节点,统一走 excute。P1 **不在门面做引擎级读写闸**(避免误判与维护负担),而由调用方/运维按 +「流定义 XML 审阅」确认为查询/报表类后才放行。客户库只读纪律下,本次仅执行**已逐一审阅确认 +无写动作**的流(见 §5 挑选过程)。 + +**风险 + P2 防护待办**(写入注释 + 本报告 + 迁移手册新坑):引擎不区分读写 ⇒ 该入口理论上 +可触发写流。P2 需补三层防护: +1. 流定义静态扫描(service 节点 method 白名单:仅 listSelect/loadPOJO/executeQueryForMap 等读方法放行); +2. 最小权限只读连接(CRUD 受限账户 + DDL 独立特权连接,架构第四节安全第 3 层); +3. statement_timeout 杀异常查询(架构第四节安全第 4 层)。 + +--- + +## 五、验证:真实查询/报表类服务流经 REST 执行(端口 8085,客户库只读) + +环境:`mvn ... -Dserver.port=8085`,默认 profile 连客户库 192.168.20.68:5435/eip3(**只读**, +仅执行已审阅确认无写动作的流;8084 全库对拍占用未动;验证后已 kill 8085 进程)。 + +### 5.1 挑选过程(只读纪律:先读流定义判断有无写动作) + +逐一读取候选流 contentxml:均为单 `service` 节点 `pojoCRUDService.listSelect`(读),start +脚本仅设 ORDER/过滤参数,**无 save/update/delete/insert** → 确认只读,放行。 + +### 5.2 验证结果(≥3 查询/报表流 + 1 带参 + 二次一致 + POST) + +| # | 服务流 | 方式 | HTTP | 引擎返回 total | DB count(核对)| 结论 | +|---|--------|------|------|---------------|----------------|------| +| T1 | GB_PROJECTINFO_SEARCH(实名制项目基础信息查询)| GET 无参 | 200 | **26** | 26 | ✅ 行数一致、字段结构合理(_id+PRJNAME+COUNTY...)| +| T2 | PM_PROJECT_TASK_SEARCH(项目任务查询)| GET 无参 | 200 | **17,674** | 17,674 | ✅ 大结果集,total 一致 | +| T3 | PM_BUILDERSDIARY_SEARCH(施工日志查询)| GET 无参 | 200 | **9,210** | 9,210 | ✅ total 一致 | +| T4 | GB_PROJECTINFO_SEARCH?COUNTY=高新区 | GET 带参 | 200 | **13** | 13(全 26 中高新区 13)| ✅ **参数透传**:返回行 COUNTY 全为高新区 | +| T5 | GB_PROJECTINFO_SEARCH(重跑 T1)| GET 无参 | 200 | 26 | — | ✅ **二次执行一致**:total + 行 id 集合/顺序与 T1 相同 | +| T6 | GB_PROJECTINFO_SEARCH(POST body {COUNTY:相城区})| POST | 200 | **8** | 8 | ✅ POST 变体 + 参数透传 | + +证据样本:docs/P1/REST证据/GB_PROJECTINFO_SEARCH.sample.json。 + +### 5.3 本地自举验证(eip4m0,无客户库) + +`EIP4M0_USERGROUP_SEARCH`(bootstrap-flow.sql 自造)经引擎执行返回种子用户组 +「系统管理员组」,证明移植引擎在无客户库副本时可独立跑通整条链(FlowExecuteLocalIT 自动化)。 + +--- + +## 六、单测(18 例,≥8 达标) + +| 测试类 | 模块 | 例数 | 覆盖 | +|--------|------|------|------| +| FlowModelParseTest | platform-legacy-core | 9 | 流 XML 解析(input/output/service/script/transition)、参数绑定、节点链有序、往返序列化、默认流生成、空流容错 | +| FlowControllerTest | platform-metadata | 8 | mock 引擎:GET/POST 参数透传、null body 容错、响应外壳、listSelect→{items,total} 归一化、单 POJO/List/标量归一化 | +| FlowExecuteLocalIT | platform-app | 1 | @SpringBootTest local profile:自举 SQL + 真实引擎执行 + 二次一致;eip4m0 不可达则 assumeTrue 跳过 | + +> FlowControllerTest 因同模块并行开发中的 perf 测试编译错误(非本任务文件)暂无法随 `mvn test` +> 跑通该模块,已用 JUnit Console Launcher 独立编译运行验证 **8/8 通过**。其余 17 例随 `mvn test` 全绿。 + +--- + +## 七、D 类报表服务流识别(79 个) + +口径(EIP3报表迁移方案 D 节):报表模板 `view_template.type=200`(根元素 ``, +339 个)内 `selectservice="XXX"` 属性所引服务流,去重。 + +| 指标 | 数量 | +|------|------| +| **D 类去重总数** | **79** | +| 在 sys_serviceflow 中存在(可直接 REST 执行)| 40 | +| — 其中非受控(免鉴权)| 38 | +| — 其中受控(需角色权限)| 2(OA_VEHICLESEND_SEARCH、VIEW_HR_ASSESSEMP_SEARCH)| +| 缺失 / orphan 引用(指向已删/失效流或定制 engineclass)| 39 | + +落档: +- `../docs/P1/D类报表服务流清单.csv`(79 行逐条:flowid/存在性/活跃/受控/显示名) +- `../docs/P1/D类报表服务流识别.sql`(可复现识别 SQL) + +> 注:39 个 orphan 多为 VIEW_*/VM_*(自定义视图/定制报表),其 selectservice 未落 sys_serviceflow, +> 应在 P4 报表批量转换前逐条定性(重建/降级/淘汰,并入 153 定制视图处置清单),需客户书面确认 +> (决策会红线 3)。 + +--- + +## 八、已知限制与 P2/P3 待办 + +1. **GetServicesFunction 部分方法未回迁**:脚本内调 `listSelectResultBySql`/`excuteFlow`/ + `getWFVariable` 等的流(如自定义 SQL 报表 VIEW_SYS_USERLOGINFO_SEARCH)当前会在脚本运行期 + 报方法缺失。随 P2/P3 横切服务移植按 framework 原版补全。**P1 REST 验证已规避此类,仅取 + service 节点 listSelect 型流**。 +2. **juel 条件转移未启用**:带 `${...}` 条件分支的服务流(如 SAVE_AND_SUBMIT 默认流)需 juel, + 当前惰性注册在无 juel 引擎时跳过 → 条件转移不生效。线性查询/报表流不受影响。P3 工作流阶段 + 随 Flowable 落地补 juel。 +3. **大结果集无强制分页**:报表流(如 T2 17,674 行)listSelect 未带 page 参数时一次返回全量 + (引擎/老系统同行为)。架构第五节「强制分页 + 流式导出」改造对象;P2 门面可加 perPage 上限。 +4. **REST 读写闸缺失**:见 §4.1,P2 三层防护待办。 +5. **客户库 contentxml 为 xml 类型 / 本地自举用 text**:引擎只取字符串,两者透明;P0' PG 升级 + 演练需核对 xml 类型在 PG15 行为。 +6. **39 orphan D 类流**:见 §7,P4 前定性 + 客户确认。 + +--- + +## 九、编译 / 测试 / 提交 + +- 编译:`mvn -DskipTests install` → 全模块 **BUILD SUCCESS**(gmavenplus 联合编译 4 个 .groovy)。 +- 测试:legacy-core(FlowModelParseTest 9 + DataPrivilegeTest 9 + CCache 6) + parity(RowDiff 23) + + app(ArchUnit 1 + FlowExecuteLocalIT 1) **全绿**;FlowControllerTest 8 独立运行全绿。 +- **ArchUnit 保真层禁依赖现代层** 仍绿(新引擎 + FlowController 未破纪律)。 +- git(仅 add 本人改动文件,中文提交): + - `de72116` feat(legacy-core): 移植 EIP3 服务流引擎到保真层(com.dsasp.* 原样) + - `f050064` feat(metadata): 服务流执行 REST 门面 FlowController + 本地自举 + 单测 + - (本报告 + D 类落档 + 迁移手册新坑 = 第 3 提交)