docs(P1): 引擎加固三件实测报告 + 迁移手册新增三坑(5.19/5.20/5.21)

P1加固实测报告.md 三件各一节(实现/8086实测证据/边界):P1-3 注入负例逐条 curl、
P1-4 C1坑3 不重启回归全链路、P1-5 索引规则正确性+幂等+诚实延迟边界。
迁移手册 5.19 引擎裸拼点清单、5.20 setChangePOInfo 冷态装载、5.21 createTableSql
不建索引;3.1 CCache 行更新为 Caffeine 版。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 12:11:13 +08:00
parent 3fa970adbf
commit ca2a6db0ab
2 changed files with 186 additions and 1 deletions

View File

@@ -105,7 +105,7 @@ com.dsasp.* com.eip4.*
|------|-------------|---------|---------|---------|---------|
| `SpringBeanOsgiServices` | OSGi BundleListener 服务定位器 | `ApplicationContext.getBean(name)` | 72 行 | 43 行 | 注入 `ApplicationContext`,按名取 bean;删除 BundleListener 逻辑 |
| `ScanServiceBeanXml` | OSGi bundle 启动期 SAX 扫描 service XML | no-op(保留 `classList` 契约) | 待查 | 极简 | 业务调用方只用 classList 返回值 |
| `CCache` | Adempiere 缓存(GPL 头 + CacheMgt 注册) | 极简 HashMap 版 | 待查 | 极简 | 调用方只用 Map API,实现可直接换 |
| `CCache` | Adempiere 缓存(GPL 头 + CacheMgt 注册) | **Caffeine 版**(P1-4 由极简 HashMap 升级) | 待查 | 极简 | 调用方只用 Map API;**公共签名零改动**(仍 extends HashMap + 双构造器 + getName/reset),`get/put/remove/size/clear` 覆写代理到内部 Caffeine `Cache`。详见 5.15 |
| `Console` | Vaadin 浏览器控制台推送 | `slf4j` | 待查 | 极简 | 日志语义等价 |
| `InstallOrUpdate` | 启动期按版本跑 install SQL | `isDevDB()=false` 桩 | 待查 | 极简 | 生产环境不触发 |
| `GetServicesFunction` 等 3 个 | Groovy 脚本函数库(约 2,600 行) | Java 桩(仅实现 `findCount`);WS3 回迁 | 约 2,600 行 | 最小桩 | P1/P3 阶段补全真实现 |
@@ -302,6 +302,28 @@ com.dsasp.* com.eip4.*
- **对策**:P1 不在门面做引擎级读写闸(避免误判);**调用方/运维按流定义 XML 审阅确认查询/报表类后放行**,客户库只读纪律下只执行已审阅无写动作的流。P2 补三层防护:①流定义静态扫描(service method 读白名单);②最小权限只读连接;③statement_timeout。
- **影响范围**:所有经 REST 执行的服务流;客户库只读期的流挑选;P2 安全加固(对齐架构第四节安全第 1/3/4 层)。
### 5.19 标识符白名单——引擎裸拼点清单(安全第 1 层落地) [NEW 2026-06-11]
- **现象**:`POJOCRUDServiceImpl.listSelectSpecialCol` 把查询条件 Map 的 key 经 `get_SearchWhereClause(map)` 拼成 WHERE 列名;`ORDER` 键(值 `" ORDER BY ..."`)经 `sql = sql + order` **裸拼**到 SQL 末尾(见 POJOCRUDServiceImpl.java:101/309/318/388)——列名/排序列是残余注入面。
- **根因**:引擎值位置已经 `StringUtil.TO_STRING` 单引号转义,但标识符(列名/排序列/表名)位置无转义概念,只能靠白名单。
- **对策(P1-3 已落地)**:`com.eip4.platform.metadata.security.IdentifierWhitelist` 用「该实体 `SYS_ENTITYATTRIBUTE` 合法列集」做白名单,`EntityController.list` 的查询条件 key、`orderBy`、表名全过白名单,非法 → HTTP 400(不回显载荷);`orderDir` 限 `asc/desc`。保留键放行清单:`page/perPage/asUser/roles/orderBy/orderDir`。**新增列/排序参数进引擎前必过白名单**,这是现代层对引擎裸拼点的纪律。
- **影响范围**:所有经现代层进引擎拼接的标识符;新写 Controller 透传查询条件/排序时必须复用 `IdentifierWhitelist`;详见 platform-metadata/P1加固实测报告.md 第一节。
### 5.20 POInfo 缓存失效靠 setChangePOInfo,冷态需先装载 id_cache [NEW 2026-06-11]
- **现象**:C1 坑 3「POInfo 缓存元数据变更后不失效须重启」。引擎公共静态钩子 `AbstractPOJOInfo.setChangePOInfo(entityId)` 清 `id_cache[entityId]→tableName` 再清 `s_cache[tableName]`;但若 `id_cache` 冷态(该 entityId 未被读过),钩子拿不到 tableName,**清不掉 s_cache**。
- **根因**:`setChangePOInfo` 依赖 `id_cache` 已装载 entityId→tableName 映射;首次读才装载。
- **对策(P1-4 已落地)**:现代层 `PoInfoCacheInvalidator.evictByTable` **先 `POInfo.getPOInfo(table)` 装载映射(顺带拿 entityId)再调 `setChangePOInfo`**,保证冷态也能命中;`evictByEntityId` 用于已知 entityId 的删除场景。接入 `MetaController.createEntity/dropEntity` + 新增 `POST /api/meta/evict/{table}` 运维出口。**全程只用引擎公共 API,不改 com.dsasp**。8086 实测:旁路加列 → 未失效仍 400(复现坑)→ 调 evict(不重启)→ 200(修复)。
- **影响范围**:所有元数据旁路写入(直改 SYS_ENTITYATTRIBUTE 等)后须调失效钩子;CCache 换 Caffeine 后失效语义不变(reset/remove 仍即时生效)。
### 5.21 引擎 createTableSql 只建表不建索引,补索引须现代层后置 [NEW 2026-06-11]
- **现象**:`Entity.createTableSql` 只产 `CREATE TABLE` + 主键 + `unique`(标识符列),**不建普通索引**;外键列(REFERENCEID=36 位 uuid)、审计列 UPDATETIME 无索引,大表首页 count/扫描/排序慢(C3 客户库 34k 行 P95 1.18s)。
- **根因**:引擎 DDL 生成器设计只保证结构正确性,不含查询优化索引。
- **对策(P1-5 已落地)**:`com.eip4.platform.metadata.perf.IndexEnhancer` 现代层后置——建表后按元数据补 `CREATE INDEX IF NOT EXISTS`(外键 uuid 列 + UPDATETIME;**跳过** ISIDENTIFIER/ISCOMBIDENTIFIER 因引擎已建 unique);`BacklogIndexScriptGenerator` 为存量实体**只生成补索引 SQL 落盘,不对客户库执行**(执行排切流期变更窗口)。**不改引擎**。
- **诚实边界**:本地 20k 行口径索引延迟改善边际(planner 小表仍 Seq Scan);真实收益在 34k+ 行 + JOIN/count 档,需客户库副本切流期执行脚本后用 load_p95.py 同口径复测验证。
- **影响范围**:所有动态建表的业务实体;客户库存量补索引执行排变更窗口;新建实体经 MetaController 自动补索引。
## 六、Flowable 升级三坑
> 来源:eip4-poc WS4 实测,flowable-poc / flowable5-poc 工程(2026-06-10)