Files
eip4-platform/platform-metadata/P1服务流实测报告.md
zhengwr 185c18d38f docs(P1): 服务流实测报告 + 迁移手册新增四坑(替换类/读写闸)
P1-2 第三步:交付文档。

platform-metadata/P1服务流实测报告.md:移植清单(31 com.dsasp 文件 + 门面 + 自举/单测)、
替换类/不移植类登记(Activator 不移植、juel 不引 activiti、SecureGroovy 去 Vaadin 默认导入、
两版 ScriptingEnginesManager 并存)、GetServicesFunction 桩回迁 diff、REST 契约、
6 条 REST 实测(端口 8085 客户库只读:T1-T6,total 与 DB 逐一核对一致 + 参数透传 + 二次一致 + POST)、
D 类 79 流识别结果(40 存在/39 orphan,38 非受控)、已知限制与 P2/P3 待办。

docs/迁移手册.md 新增四坑(四栏格式,[NEW 2026-06-11]):
  5.15 服务流脚本默认导入含 Vaadin UI 类缺失则每脚本编译失败
  5.16 流脚本 juel 来自 activiti,保真层不引 activiti(惰性注册适配)
  5.17 OSGi Activator 不移植,bean 靠组件扫描 + SpringBeanOsgiServices + LegacyXmlWiring
  5.18 REST 服务流入口不区分读写,需流定义审阅 + P2 三层防护

D 类识别 SQL/清单落档于 ../docs/P1/(D类报表服务流清单.csv + 识别.sql + REST证据/),
该目录在 eip4-platform 仓库外(eip3 工作区非 git,与 ../docs/M0交付 同级)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 12:06:24 +08:00

239 lines
16 KiB
Markdown
Raw 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.
# 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 <property> 注入)|
| `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`(根元素 `<report>`,
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 提交)