From c2b3c5004fc5ee2f7979c335ed13f4038e479ad3 Mon Sep 17 00:00:00 2001 From: zhengwr Date: Thu, 11 Jun 2026 11:26:44 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8A=80=E6=9C=AF=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E9=9A=8F=E4=BB=93=E5=BA=93=E2=80=94=E2=80=94=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1/=E8=BF=81=E7=A7=BB=E6=89=8B=E5=86=8C/C3?= =?UTF-8?q?=E5=9F=BA=E7=BA=BF/C5=E6=8A=A5=E5=91=8A=E8=BF=81=E5=85=A5=20doc?= =?UTF-8?q?s/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审); 决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。 全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释) Co-Authored-By: Claude Fable 5 --- README.md | 2 +- docs/C3压测基线.md | 94 ++++ docs/C5构建预演报告.md | 148 ++++++ docs/架构设计.md | 121 +++++ docs/迁移手册.md | 423 ++++++++++++++++++ .../platform/app/ArchitectureRulesTest.java | 2 +- platform-auth/C2实测报告.md | 2 +- platform-parity/C1实测报告.md | 2 +- pom.xml | 2 +- 9 files changed, 791 insertions(+), 5 deletions(-) create mode 100644 docs/C3压测基线.md create mode 100644 docs/C5构建预演报告.md create mode 100644 docs/架构设计.md create mode 100644 docs/迁移手册.md diff --git a/README.md b/README.md index fe66b1a..cb790a0 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # eip4-platform EIP4 平台正式工程(路线 A'):双层制模块化单体——**保真层供奉,现代层生长**。 -架构依据:`../docs/eip4-platform架构设计.md`(必读);坑位台账:`../docs/M0交付/EIP4迁移手册v1.md`。 +架构依据:`docs/架构设计.md`(必读);坑位台账:`docs/迁移手册.md`。 ## 模块 diff --git a/docs/C3压测基线.md b/docs/C3压测基线.md new file mode 100644 index 0000000..641130f --- /dev/null +++ b/docs/C3压测基线.md @@ -0,0 +1,94 @@ +# C3 压测基线 v1(M0 交付物) + +> 版本 v1.0(2026-06-10)| 工具:`eip4-platform/tools/loadtest/load_p95.py`(零依赖,可复跑) +> 环境:**本地自举环境**——eip4-platform(profile=local,单实例,HikariCP max=5,日志 INFO)+ PG 15(localhost:5433/eip4m0),M2 Mac +> 数据规模:每实体 50 行(子表 EIP4PT_ORDERLINE 108 行),C1 自举种子(固定随机种子可复现) +> 口径:`GET /api/entity/{t}/list?page=1&perPage=20`,每实体预热 3 次后 300 请求 + +## 一、主基线(并发 10) + +| 实体 | P50(ms) | P90(ms) | P95(ms) | P99(ms) | Max(ms) | RPS | 错误 | +|------|--------:|--------:|--------:|--------:|--------:|----:|----:| +| EIP4PT_ORDERLINE(子表,108行) | 37.0 | 51.9 | 56.3 | 65.2 | 69.5 | 247.4 | 0 | +| EIP4PT_ORDER(主表) | 42.3 | 58.8 | 62.9 | 66.1 | 76.5 | 224.7 | 0 | +| EIP4PT_EMPLOYEE | 81.7 | 117.4 | 121.7 | 130.4 | 141.2 | 114.5 | 0 | +| EIP4PT_CUSTOMER | 82.9 | 111.3 | 118.7 | 134.8 | 143.2 | 115.3 | 0 | +| EIP4PT_PRODUCT | 80.9 | 110.3 | 116.4 | 133.8 | 139.5 | 115.8 | 0 | +| EIP4PT_CONTRACT | 81.3 | 111.7 | 117.3 | 126.3 | 136.6 | 115.6 | 0 | +| EIP4PT_INVOICE | 83.2 | 112.9 | 122.4 | 134.2 | 147.8 | 113.3 | 0 | +| EIP4PT_ALLTYPE(全显示类型) | 80.2 | 111.2 | 120.7 | 138.8 | 146.5 | 114.5 | 0 | +| EIP4PT_DEVICE | 80.6 | 111.9 | 121.0 | 135.8 | 139.7 | 115.7 | 0 | +| EIP4PT_PROJECT | 82.1 | 112.3 | 124.5 | 132.0 | 153.1 | 114.1 | 0 | + +> 原始数据:`eip4-platform/tools/loadtest/baseline-local-20260610.json`。**10 实体 × 300 请求全程 0 错误。** + +## 二、对照组(并发 4,连接池内) + +| 实体 | P95(ms) | P99(ms) | RPS | +|------|--------:|--------:|----:| +| EIP4PT_ORDERLINE | 26.2 | 28.3 | 230.4 | +| EIP4PT_ORDER | 26.3 | 27.8 | 233.1 | +| EIP4PT_ALLTYPE | 52.1 | 58.0 | 117.5 | + +> 原始数据:`baseline-local-c4-20260610.json` + +## 三、归因分析(基线的核心价值) + +1. **延迟按列类型复杂度分两档**:仅基础类型列的实体(ORDERLINE/ORDER)P95≈56–63ms;含枚举/引用/布尔列的实体 P95≈117–125ms,**约 2 倍差距**。对照组同样呈现(26ms vs 52ms)。印证 C1 报告坑 1——引擎对 BOOLEAN/ENUMERATE/引用列**每行回调字典查询**(getEnumerateItems → SELECT SYS_ENUMERATE),这是《架构设计》(docs/架构设计.md)第五节「元数据反复读 → Caffeine 缓存」改造点的直接量化证据。 +2. **并发超过连接池容量后,P95 主体是排队**:并发 10 / 池 5 时,ORDERLINE P95 从 26→56ms、ALLTYPE 从 52→121ms(均 ≈2.2 倍)。生产部署须按预期并发定容连接池,这是配置项;基线对比时务必固定 并发≤池容量 的口径。 +3. **吞吐瓶颈同源**:复杂实体 RPS 恒定在 ~115(并发 4 和 10 一样),说明瓶颈在引擎单请求 CPU/字典查询,不在连接数——加池不解决,缓存才解决。 +4. 本基线是 P2「渐进参数化 + Caffeine」改造收益的**对照原点**:改造后同口径复测,期望复杂实体向简单实体档位收敛。 + +## 四、诚实边界与待办 + +| 边界 | 说明 | 待办 | +|------|------|------| +| 数据规模 | 每实体 50 行,远小于客户库真实表 | 5435 网络恢复后在副本上以真实数据重跑 | +| Top10 口径 | 生产访问日志不可得,以 C1 种子实体代理(覆盖全部显示类型与主子表) | 切流前用 Nginx 访问日志统计真实 Top10 重跑 | +| 环境 | M2 Mac 单机,非交付形态(4 进程 docker-compose) | 检查点①前在准生产环境复测 | +| 决策会风险 R2(单请求延迟) | 旧系统侧无对照数据,「打平与否」尚不可答 | C1 录制切面部署旧系统后同口径采集对照 | + +**结论:C3 通过标准「出 P95 延迟基线文档」已达成(本地口径,含归因);客户库口径复测列为遗留动作。** + +## 五、复跑命令 + +```bash +# 1) 起服务 +cd eip4-platform && mvn spring-boot:run -pl platform-app -Dspring-boot.run.profiles=local +# 2) 压测 +cd eip4-platform/tools/loadtest +python3 load_p95.py --base http://localhost:8084 \ + --entities EIP4PT_ORDERLINE,EIP4PT_ORDER,... --requests 300 --concurrency 10 \ + --out-md 基线.md --out-json 基线.json +``` + + +--- + +## 【2026-06-11 增补】客户库口径基线(5435 网络恢复后实测) + +> 环境:同一 eip4-platform 实例连客户库副本(192.168.20.68:5435,**共享副本,测时有他方活跃查询,数字含噪声**) +> 口径:page=1&perPage=20,预热 3 次,150 请求/实体,并发 4(与本地对照组同口径);重实体单列 30 请求/并发 2 + +| 实体 | 表行数 | P50(ms) | P95(ms) | P99(ms) | RPS | 错误 | +|------|-------:|--------:|--------:|--------:|----:|----:| +| SYS_HZPY | 6,727 | 22.2 | 78.9 | 107.1 | 143.7 | 0 | +| OA_FILESENDUSER | 40,983 | 28.5 | 113.3 | 115.3 | 111.6 | 0 | +| PM_BUILDERSDIARY | 9,210 | 42.2 | 129.1 | 132.5 | 74.9 | 0 | +| OA_SEALUSEAPPLY | 10,751 | 49.1 | 134.7 | 139.5 | 64.0 | 0 | +| PM_PROJECT_TASK | 17,674 | 72.2 | 160.2 | 189.3 | 46.2 | 0 | +| GB_WORKER(照片大列) | 13,697 | 258.8 | 363.5 | 517.6 | 15.0 | 0 | +| PM_CONTRACTBALANCE | 34,774 | 299.9 | 465.2 | 530.9 | 12.1 | 0 | +| HR_ATTENDLOG | 33,766 | 923.3 | **1,179.8** | 1,322.3 | 4.1 | 0 | +| PM_PAYMENTAPPLY(DISTINCT+4 LATERAL) | 38,138 | 4,192.9 | **4,630.0** | 4,649.2 | 0.5 | 0 | + +原始数据:`eip4-platform/tools/loadtest/baseline-real-20260611.json` + `baseline-real-heavy-20260611.json`。全程 0 错误。 + +### 客户库口径归因(对 P2 改造优先级的直接输入) + +1. **首页延迟与表行数强相关**(6.7k 行 22ms → 34k 行 923ms → 38k 行复杂视图 4.2s,P50 口径):每个 list 请求都含全表 count + 无索引扫描/排序 + 每页全量重算,放大了「动态表无索引 + 计划缓存不可复用」两笔税。**架构第五节的 DDL 索引增强 + 参数化改造,优先验证对象就是 HR_ATTENDLOG / PM_CONTRACTBALANCE / PM_PAYMENTAPPLY 这一档**。 +2. **大文本列(GB_WORKER 照片)抬高传输/物化成本**:行数不大(13.7k)但 P50 达 259ms,印证 SqlRowSet 全量物化税(第五节「大结果集流式」改造点)。 +3. **决策会风险 R2(单请求延迟)有了真实锚点**:旧系统跑同样的 SQL(引擎同源),这些数字大概率与旧系统同档——待 C1 录制切面部署后采集旧系统侧同口径对照,才能下「打平」结论。 +4. 共享副本噪声:他方查询并发存在,本表为「带噪基线」;切流前在隔离准生产环境复测一轮作为正式 SLA 锚点。 + +**C3 双口径(本地自举 + 客户库真实数据)至此齐备,通过标准达成。** diff --git a/docs/C5构建预演报告.md b/docs/C5构建预演报告.md new file mode 100644 index 0000000..f3ea1b5 --- /dev/null +++ b/docs/C5构建预演报告.md @@ -0,0 +1,148 @@ +# C5 任务:amis 6.13.0 Fork 构建预演报告 + +**任务编号**:EIP4 M0 – C5 +**执行日期**:2026-06-10 +**结论**:**构建成功 ✅** + +--- + +## 一、环境 + +| 项目 | 值 | +|------|-----| +| 操作系统 | macOS Darwin 25.5.0 | +| Node.js | v22.22.3 | +| npm | 10.9.8 | +| 仓库来源 | 浅克隆 amis tag 6.13.0(/Users/zhengwr/workspace/eip3/amis-fork) | + +--- + +## 二、构建命令序列 + +### 2.1 依赖安装 + +```bash +cd /Users/zhengwr/workspace/eip3/amis-fork +npm install --legacy-peer-deps +``` + +- 耗时:约 7 分钟 +- 安装包数:2794 个 +- 说明:使用 `--legacy-peer-deps` 绕过 peer dependency 冲突(amis monorepo 中各子包相互依赖版本声明不严格);Node 22 下正常通过,**未触发 openssl ERR_OSSL 问题**(rollup/fis3 本身不依赖老 openssl API,无需 `--openssl-legacy-provider`) + +### 2.2 子包顺序构建 + +amis 是 monorepo,packages/amis 依赖其他子包的 `lib/` 产物,必须按依赖拓扑顺序构建: + +```bash +# 1. 基础公式库(无依赖) +cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis-formula +npm run build # rollup, ~1s + +# 2. 核心库(依赖 amis-formula) +cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis-core +npm run build # rollup, ~4s + +# 3. UI 组件库(依赖 amis-core) +cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis-ui +npm run build # rollup + SCSS, ~25s + +# 4. amis 主包 + SDK(依赖以上全部) +cd /Users/zhengwr/workspace/eip3/amis-fork/packages/amis +npm run build # rollup + fis3 + postcss + build-schemas, ~60s +``` + +**注意**:直接从根目录执行 `npm run build --workspaces` 理论上可行,但 npm workspaces 并行执行会因依赖顺序竞争失败。按手动拓扑顺序逐包构建是安全做法。 + +--- + +## 三、遇到的坑与绕法 + +| 坑 | 根因 | 绕法 | +|----|------|------| +| 直接 `cd packages/amis && npm run build` 报 `Cannot find module 'amis-core'` | 子包尚未构建,`lib/` 不存在;rollup 从 workspace symlink 找不到 TS 声明 | 先逐包构建 formula → core → ui,再构建 amis | +| rollup 警告 `Unknown output options: commonConfig` | rollup.config.js 中使用了旧版 API,当前 rollup 2.79 已不支持 `commonConfig` 字段 | 仅为警告,不影响产物生成,忽略即可 | +| SCSS `sass deprecation: Using / for division` 大量警告 | dart-sass 新版本废弃 `/` 除法语法 | 仅为警告,CSS 仍正常生成,忽略 | +| fis3 `Can't resolve fs/stream in xlsx.js` | xlsx.js 包含 Node.js 内置模块引用,fis3 浏览器打包时找不到 | 仅为警告(xlsx 会 graceful fallback),产物可用 | +| 端口 18080 被占用 | 本机其他进程占用 | 换 18081 端口 | + +**openssl 问题**:Node 22 + rollup 2.x + fis3 3.5 组合**未触发** ERR_OSSL_EVP_UNSUPPORTED,无需 `NODE_OPTIONS=--openssl-legacy-provider`。 + +--- + +## 四、产物清单与体积 + +构建产出目录:`packages/amis/sdk/`,已复制至: +`src/main/resources/static/sdk-local/` + +| 文件 | 体积 | 说明 | +|------|------|------| +| `sdk.js` | **2.0 MB** | 核心 JS,含 amisRequire 全局导出 | +| `sdk.css` | 2.5 MB | 默认 cxd 主题样式 | +| `helper.css` | 952 KB | 辅助样式 | +| `iconfont.css` | 152 KB | 图标字体 CSS | +| `iconfont.ttf` | 192 KB | 图标字体 TTF | +| `iconfont.woff` | 116 KB | 图标字体 WOFF | +| `iconfont.eot` | 176 KB | 图标字体 EOT(IE 兼容) | +| `iconfont.svg` | 696 KB | 图标字体 SVG | +| `ang.css` / `antd.css` / `dark.css` / `cxd.css` | 各约 1-2 MB | 主题变体 | +| `sdk-ie11.css` | - | IE11 兼容版(PostCSS 处理后) | +| `charts.js` / `markdown.js` / `codemirror.js` 等 | - | 按需加载的分包 | +| **sdk-local/ 总计** | **52 MB** | 含所有主题、分包、字体 | + +--- + +## 五、替换 CDN 的改法 + +原 `amis.html`(CDN 引用): +```html + + + + +``` + +替换为本地路径(`amis-local.html`): +```html + + + + +``` + +已生成文件:`src/main/resources/static/amis-local.html` + +--- + +## 六、冒烟验证 + +```bash +cd src/main/resources/static +python3 -m http.server 18081 + +# 验证结果: +curl -I http://localhost:18081/sdk-local/sdk.js +# → HTTP 200 + +wc -c sdk-local/sdk.js +# → 2,060,802 字节(约 2 MB,>1 MB ✅) + +grep -o 'amisRequire' sdk-local/sdk.js | head -1 +# → amisRequire ✅ +``` + +所有冒烟检查通过。 + +--- + +## 七、结论 + +| 项目 | 结果 | +|------|------| +| 构建结果 | **成功** | +| Node 22 兼容性 | **兼容**,无需降级或 openssl 绕法 | +| SDK 产物 | sdk.js(2MB)+ sdk.css(2.5MB)+ 字体图标完整 | +| CDN 替换 | 完成(amis-local.html) | +| 止损 S2 评估 | **暂不触发**,amis 6.13.0 在 Node 22 本机环境可正常构建,无需切换备选方案 | + +**下一步建议**:将 sdk-local/ 纳入版本管理或 CI 构建流程,部署时直接使用本地产物,彻底消除对 CDN 的依赖。 diff --git a/docs/架构设计.md b/docs/架构设计.md new file mode 100644 index 0000000..35e0413 --- /dev/null +++ b/docs/架构设计.md @@ -0,0 +1,121 @@ +# eip4-platform 架构设计 + +> 版本 v1.0(2026-06-10)| 上承《EIP3工程化实施计划》,是 P1「eip4-poc → eip4-platform」的设计依据 +> 本文档固化了立项后关于工程结构、选型、中间件、保真层安全/性能的全部架构决策。 +> **新会话/新成员开工 eip4-platform 前必读本文。** + +--- + +## 一、总原则:双层制——保真层供奉,现代层生长 + +**移植的旧代码不重写、不"现代化改造"**。理由:1,956 行 SQL 引擎的价值就在于与老系统行为逐字节一致——它是逐行对拍的基线、「业务数据零搬迁」的载体、老员工认知的延续。 + +``` +eip4-platform(Maven 多模块单体) +├── platform-legacy-core 保真层:移植引擎原样,包名 com.dsasp.* 不动 +│ POJOService/POJOCRUDService/Entity/POInfo/服务流引擎/脚本引擎 +├── platform-metadata 现代层:REST API、DTO、OpenAPI(com.eip4.*) +├── platform-auth P2:组织/权限/数据权限真实现(替换 PoC 桩) +├── platform-flow-gateway Flowable REST 客户端、待办聚合、3 个 handler bean +├── platform-converter 模板转换器 + S3 脚本改写器(可独立 CLI 跑批) +├── platform-ai MCP Server、schema 双闸校验 +├── platform-parity C1 逐行对拍框架:录制/重放/逐行 diff(P1 一级交付物,可独立 CLI 跑批) +└── platform-app Spring Boot 启动器,组装上述模块 +``` + +**纪律(ArchUnit 规则固化)**:`com.eip4.*` 可调 `com.dsasp.*`,反向禁止;新代码必须单测,旧代码以对拍为完成定义;`com.dsasp.*` 与 framework 源码的 diff 保持最小。 + +## 二、选型决策表 + +| 决策 | 选择 | 理由 | +|------|------|------| +| 整体形态 | 模块化单体 + Flowable 独立服务(仅此一个独立) | 4 人团队 + 按客户私有化部署,拒绝微服务 | +| 运行时 | JDK 17 + Spring Boot 3.3.x | PoC 已验证,不追新 | +| 数据访问 | JdbcTemplate,**不引入 ORM** | 引擎本就是 JdbcTemplate;动态建表与 JPA 范式相克 | +| 平台表管理 | Flyway(只管 SYS_* 平台表) | 业务表由引擎动态建,不进 Flyway | +| 认证 | Spring Security + 无状态 JWT | 免 session 共享,REST 自然选择 | +| 前端 | 独立 React 工程(amis 渲染宿主+设计器),Nginx 托管 | amis 锁 6.13.0 本地化部署(fork 预演产物),不依赖 CDN | +| 多租户 | 不做,按客户独立部署 | 项目制现实,砍掉整个复杂度维度 | + +## 三、中间件:默认只有 PG + Nginx + +压倒性约束:**每个客户私有化部署,每多一个中间件 = 每个客户终身多一份运维负担**。 + +| 中间件 | 决策 | 留口 | +|--------|------|------| +| PostgreSQL 15+ | ✅ 唯一必需 | 单库分 schema(业务/元数据/Flowable) | +| Redis | ❌ 不上 | 元数据缓存用进程内 Caffeine(接替 CCache,语义同为本地缓存);走 Spring Cache 抽象,多实例横扩时换 Redis 只改配置 | +| 消息队列 | ❌ 不上 | Quartz 定时沿用;轻量异步用 Spring 事件 + DB 表队列;Flowable 自带 DB-based async executor | +| Elasticsearch | ❌ 不上 | PG 能力足够 | +| MinIO | ⭕ 可选 | FileService 默认本地盘(保持原行为),接口已抽象 | +| Nginx | ✅ 标配 | 静态托管 + 反代 + **切流期新旧路由分发(绞杀者流量阀门)** | +| 监控 | Actuator + 日志 | 不上 Prometheus 全家桶,留 endpoint | + +**单客户交付形态 = 4 进程**:`nginx + eip4-platform.jar + flowable-service.jar + postgres`(docker-compose 模板复制)。 + +## 四、保真层安全方案(四层纵深) + +代码实况(已读源码核实):值位置经 `StringUtil.TO_STRING` 单引号转义,最低级注入已挡;**残余注入面 = 标识符裸拼(列名/表名/ORDER BY)+ 个别 ID 直拼点 + 转义本身脆弱**。 + +| 层 | 做法 | 关键点 | +|----|------|--------| +| 1. 标识符白名单(最优先) | 列名/表名/排序列必须存在于该实体 SYS_ENTITYATTRIBUTE 元数据,否则拒绝 | **元数据即白名单**——动态 SQL 引擎独有的安全红利,零维护零误杀。P1 随 REST 层实现 | +| 2. 渐进参数化 | 热点路径值位置改 `?` 占位,每改一处过对拍 | 同时根治性能的计划缓存抖动(见下),一箭双雕。P2 后渐进,优先级=C3 热点∩安全风险点 | +| 3. 最小权限账户 | CRUD 走受限账户;动态建表 DDL 走独立特权连接 | 漏一个点也炸不掉库。P2 实施 | +| 4. 检测兜底 | 对拍套件加注入负例(`' OR 1=1--`、`'; DROP` 等);REST 入参校验;statement_timeout 杀异常查询 | 把"不可注入"变成可回归的断言,而非一次性人工保证。M0 随 C1 对拍套件建立 | + +**核心洞察**:第 1 层「标识符白名单」是杀手锏——元数据驱动引擎的"合法列名集合"是现成、精确、零维护的,普通手写 DAO 反而没有这个红利。 + +## 五、保真层性能方案 + +代码实况:`JdbcTemplate` + `SqlRowSet`(全量物化到内存);**每次查询是全新拼出的 SQL 字符串 → PG 执行计划缓存几乎无法复用(头号性能税)**;级联/主子表有按行 N+1。 + +| 问题 | 解法 | 性质 | +|------|------|------| +| 计划缓存抖动(头号) | 值位置参数化(=安全第 2 层)→ SQL 结构稳定 → 计划复用 | **根子级修复,实测更快** | +| 动态表无索引 | DDL 生成器增强:建表自动给主键/外键/常用查询列加索引(引擎现仅建表不建索引) | **根子级修复** | +| 大结果集内存 | 强制分页(已有)+ perPage 上限封顶;导出走 `RowCallbackHandler` 流式 | 补齐填坑 | +| 元数据反复读 | POInfo 用 Caffeine 缓存(接替 CCache),避免每请求读 SYS_ENTITY | 补齐填坑 | +| N+1 级联 | C3 压测定位热点 → 批量化(batch insert / IN 查询)→ 过对拍 | 补齐填坑 | +| 报表重查询 | 79 个服务流走 PG 只读副本,与 OLTP 隔离 | 隔离 | + +**关键协同**:安全(值参数化)和性能(计划缓存)的根子是同一处——参数化一次还两笔债。改造优先级 = C3 压测热点 ∩ 安全风险点。 + +## 六、相对旧系统的诚实结论(决策层口径) + +**不能把性能当重构卖点。** 正确对外口径: + +| 维度 | 相比旧系统 | 性质 | +|------|-----------|------| +| 安全 | **明显且不可逆提高** | 从人工保证 → 工程能力(测试守着不退化) | +| 性能-计划缓存/索引 | **实测更快** | 根子级修复 | +| 性能-内存/N+1 | 补齐填坑 | 不变慢,非超越 | +| 性能-单请求延迟 | **打平或略增** | 架构代价(前后端分离多一次网络跳),搬不动 | + +被问"重构后是不是更快了",答案不是"是",而是"**高负载下更稳、更安全、可持续,单次响应打平**——而性能从来不是重构目标,AI 友好与摆脱 EOL 才是"。C3 压测的作用是**量化**这一点(验证不退化 + 高负载改善),不是证明"更快"。决策会已将单请求延迟列为风险 R2。 + +## 七、渲染层备选(amis fork 失败时的 Plan B) + +「渲染层可替换」已被架构保证:后端引擎、79 服务流、REST API、元数据占总投入 ~70%,与渲染层无关;转换器的 XML 解析半段也中立。换渲染器损失 = 转换器后半段 + 已转页面 schema,量级 1–2 人月,非推倒重来。 + +触发(决策会止损 S2 / 触发条件 1:fork 预演失败或 amis 正式归档)后,按序做 1–2 天 spike: +1. **阿里 lowcode-engine**(MIT,2026-02 仍发版 v1.3.2,自带设计器)— 首位备选 +2. **antd ProComponents 薄渲染器**(MIT,事实标准)— 次位,需自建协议解释器 + 设计器 +3. Vue 系(avue)、国际 headless(RJSF/JSONForms)— 不进备选(换栈 / 中国式表格弱) + +## 八、落地映射(接《工程化实施计划》) + +| 架构决策 | 落在哪个阶段 | +|---------|-------------| +| 模块拆分 + ArchUnit 纪律 | P1 仓库正规化 | +| 标识符白名单 + Caffeine + DDL 索引 | P1 | +| 注入负例进对拍 + C3 压测基线 | M0 | +| 最小权限账户 + DDL 特权连接隔离 | P2(同数据权限真实现) | +| 渐进参数化 | P2 后,C3 热点 ∩ 安全风险点排序 | +| JWT 认证 | P2 | +| 只读副本 / 报表隔离 | P4 报表 D 类 | +| MCP Server | P5 | + +--- + +**本文档维护**:随 P1 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。 \ No newline at end of file diff --git a/docs/迁移手册.md b/docs/迁移手册.md new file mode 100644 index 0000000..726743b --- /dev/null +++ b/docs/迁移手册.md @@ -0,0 +1,423 @@ +# EIP4 迁移手册 v1 + +> 版本:v1.0(2026-06-10)| 性质:M0 强制交付物,老员工知识转移 + PoC 坑位整编 +> 适用对象:所有参与 eip4-platform 工程化的开发人员,新成员上手必读 +> 维护原则:每个坑位必须补全「现象/根因/对策/影响范围」四栏后方可关闭;新发现的坑位在 +> 对应章节追加,打 `[NEW]` 标记并注明发现时间 + +--- + +## 一、移植总则 + +### 1.1 双层制架构纪律 + +eip4-platform 采用**双层制**: + +``` +保真层(platform-legacy-core) 现代层(platform-metadata 等) +com.dsasp.* com.eip4.* +────────────────────────────── ────────────────────────────── +移植引擎原样保留 REST API / DTO / 转换器 / MCP +包名不动、行为不动 新代码、新范式 +以对拍为完成定义 以评审+单测为完成定义 +``` + +**纪律(ArchUnit 规则固化,编译期强制)**: +- `com.eip4.*` 可调用 `com.dsasp.*`,**反向绝对禁止** +- `com.dsasp.*` 与 framework 源码的 diff 保持最小——移植不是重构 +- 保真层代码改动必须附一份对拍测试通过截图,否则 PR 不得合入 + +### 1.2 保真层纪律 + +| 原则 | 含义 | 违规后果 | +|------|------|---------| +| 不重写 | 610 行引擎、1,346 行 SQL 拼装,原样搬入,不"现代化" | 破坏对拍基线,视同 P1 返工 | +| 不改包名 | `com.dsasp.server.dataDic` 等包名不变 | 所有 import 和反射引用失效 | +| 不引 ORM | JdbcTemplate 是引擎的血液,JPA/MyBatis 不得引入保真层 | 动态 DDL 与 ORM 范式相克 | +| diff 最小化 | 每次修改记录为「必要改动」(API 断点修复)或「适配」(桩替换),不顺手改 | 下一次升级时无法 diff 溯源 | + +### 1.3 对拍 = 完成定义 + +**移植代码的唯一完成标准是逐行对拍通过,不接受人工目测。** + +- **计数级对拍(已完成)**:`tools/eip4_sweep.py`,全量 1,166 实体,0 计数不一致,通过率 99.1% +- **逐行对拍(C1,工程化第一周强制)**:在旧系统关键出口加 SQL 录制切面,新旧结果集逐行 diff。≥20 个代表性实体(含主子表/字典翻译/数据权限/深分页),一致率必须 100% +- **C1 前提**:旧系统需有可运行环境供 SQL 录制。若旧系统不可得,需设计生产流量旁路录制方案并报批(决策会开放项,P1 第一周第一个问题) + +> 对外口径:「计数级一致性 99.1%(0 计数不一致),逐行对拍待工程化阶段 C1 补全」 +> **禁止**在 C1 完成前使用「99.1% 一致」表述(决策会书面更正) + +--- + +## 二、Spring 3.1 → Boot 3 API 断点台账 + +> 来源:eip4-poc Day 1 实测,framework/ 静态扫描 + 编译验证 +> 结论:**断点仅此一类,已全部修复**;未发现其他不兼容 API + +### 2.1 queryForInt / queryForLong(7 处) + +| 栏目 | 内容 | +|------|------| +| **现象** | 编译期报错:`The method queryForInt(String) is undefined for the type JdbcTemplate` | +| **根因** | `JdbcTemplate.queryForInt()` 和 `queryForLong()` 在 Spring 4.2 已废弃,Spring 6(Boot 3 内置)彻底移除 | +| **对策** | 改为 `queryForObject(sql, Integer.class)` 或 `queryForObject(sql, Long.class)`;另有 1 处 `(String, Object[], Class)` 重载参数顺序变更,须同步调整 | +| **影响范围** | `com.dsasp.server.dataDic.POJOServiceImpl`(1,346 行内),共 7 处;已在 eip4-poc 全部修复 | + +### 2.2 javax → jakarta(6 处) + +| 栏目 | 内容 | +|------|------| +| **现象** | 编译期报错:`javax.servlet` 包找不到 | +| **根因** | Spring Boot 3 对应 Jakarta EE 9+,`javax.*` 命名空间已迁移为 `jakarta.*` | +| **对策** | dataDic + common + core 三模块内 6 处 `javax.servlet` 机械替换为 `jakarta.servlet`;`javax.script`(JSR-223,共 17 处)**不动**,JDK 17 原样可用 | +| **影响范围** | 仅 6 处,半天内完成;已在 eip4-poc 全部修复 | + +### 2.3 数据源与事务 XML 配置(1 处) + +| 栏目 | 内容 | +|------|------| +| **现象** | 旧 `META-INF/spring/db.xml` 用 Spring XML 配置 commons-dbcp 连接池与事务管理器,Boot 3 不识别 | +| **根因** | Spring Boot 3 推荐 Java Config;commons-dbcp 已被 HikariCP 替代 | +| **对策** | `com.dsasp.server.db/META-INF/spring/db.xml` 事务配置转换为 `@Configuration` Java Config;连接池替换为 HikariCP(Boot 3 默认);已在 eip4-poc 实测通过 | +| **影响范围** | 单处配置文件;业务代码无感知 | + +### 2.4 SimpleJdbcTemplate(0 处) + +| 栏目 | 内容 | +|------|------| +| **现象** | 预核查前担心此 API 大量使用(Spring 4.x 已删除) | +| **根因** | N/A | +| **对策** | **源码实测零使用**,此风险解除;无需任何改动 | +| **影响范围** | 无 | + +> **完整结论**:Spring 3.1/JDK 6 → Boot 3/JDK 17 的移植,全部 API 断点仅 8 处(7 处 queryForInt/Long + 1 处重载顺序),已在 eip4-poc 全部修复,WS1 通过。 + +--- + +## 三、OSGi 解耦做法 + +> 来源:framework/ 源码实测(源码预核查报告核查 2) +> 结论:OSGi 耦合面高度集中,等价替换成本极低 + +### 3.1 替换类清单(6 个) + +| 类名 | 原版(OSGi) | 替换实现 | 原版行数 | 替换行数 | 替换要点 | +|------|-------------|---------|---------|---------|---------| +| `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,实现可直接换 | +| `Console` | Vaadin 浏览器控制台推送 | `slf4j` | 待查 | 极简 | 日志语义等价 | +| `InstallOrUpdate` | 启动期按版本跑 install SQL | `isDevDB()=false` 桩 | 待查 | 极简 | 生产环境不触发 | +| `GetServicesFunction` 等 3 个 | Groovy 脚本函数库(约 2,600 行) | Java 桩(仅实现 `findCount`);WS3 回迁 | 约 2,600 行 | 最小桩 | P1/P3 阶段补全真实现 | + +**注意**:替换时必须**保持包名/类名/方法签名完全一致**,旧引擎代码对这些类的引用不做任何修改——「旧代码零感知」是双层制的核心约定。 + +### 3.2 横切服务桩清单(P2 换真实现) + +| 桩 | 包路径 | 当前行为 | P2 真实现要点 | +|----|--------|---------|-------------| +| ~~`dataPrivilegeService`~~ | ~~`com.eip4.poc.stub`~~ | **已由 M0/C2 真实现接管** | 桩已删除;保真层 `com.dsasp.server.privilege.service.DataPrivilegeServiceImpl`(原样移植)提供行级过滤原版语义;P2 在此之上接组织数据源 + 管理 UI(见 §5.8 / platform-auth/C2实测报告.md) | +| `fileService` | `com.eip4.poc.stub` | no-op | 本地盘 / MinIO 接口 | +| `projectSwitchService` | `com.eip4.poc.stub` | no-op | 项目上下文切换 | +| `systemLogManager` | `com.eip4.poc.stub` | slf4j | 业务操作日志入库 | + +--- + +## 四、XML 装配补齐 + +> 来源:eip4-poc 移植台账,Day 1 实测发现 + +### 4.1 LegacyXmlWiring(setter 注入补齐) + +| 栏目 | 内容 | +|------|------| +| **现象** | 旧 `service.xml` 用 `` setter 注入 `systemLogManager` / `dataOperatorLog`(非 `@Autowired` 字段),Boot 3 注解驱动容器不会自动装配这些 setter | +| **根因** | 引擎代码是旧 Spring XML 编程模型,没有 `@Autowired` 注解;直接移植后 setter 未被调用,引用为 null | +| **对策** | 新增 `LegacyXmlWiring`(实现 `SmartInitializingSingleton`),在容器启动后手动将这些 bean 注入到引擎的对应 setter,等价于 XML `` 注入行为 | +| **影响范围** | `systemLogManager`、`dataOperatorLog` 两个依赖;已在 eip4-poc 实测通过;**转换器和新模块不受影响** | + +### 4.2 JodaModule(Jackson 序列化) + +| 栏目 | 内容 | +|------|------| +| **现象** | 引擎内部日期值为 `joda.time.DateTime` 对象,REST 层序列化时 Jackson 抛 `InvalidDefinitionException: No serializer found` 或输出异常 JSON | +| **根因** | Spring Boot 3 不再自动注册 `JodaModule`(Boot 2.x 会自动注册) | +| **对策** | 显式在 `ObjectMapper` 配置中 `registerModule(new JodaModule())`;`jackson-datatype-joda` 依赖加入 pom.xml | +| **影响范围** | 所有包含 DATE 显示类型字段的实体查询响应;已在 eip4-poc 实测通过 | + +--- + +## 五、引擎行为契约清单 + +> 来源:eip4-poc Day 2 移植对拍记录(README.md 坑位章节) +> 性质:这些是引擎内部**已经确认的行为**,不是 bug,移植工具和转换器必须遵守 + +### 5.1 updatePO 审计列强制追加 + +| 栏目 | 内容 | +|------|------| +| **现象** | 对某些表执行 update 路径时,引擎抛 SQL 错误:`column UPDATETIME does not exist` | +| **根因** | 引擎 `updatePO` 无条件追加 `UPDATETIME` / `UPDATEBY` 两个审计列到 UPDATE 语句,不判断目标表是否存在这两列 | +| **对策** | insert-only 设计的表(如 `SYS_DATA_LOGITEM`,物理表无这两列)**不可走 update 路径**,必须走 insert-only 路径;新建实体时审计列存在与否须与设计意图对齐;老系统行为一致(非新引入缺陷) | +| **影响范围** | 所有无 `UPDATETIME`/`UPDATEBY` 列的表;P2 数据权限迁移时需排查;write-test 已验证 | + +### 5.2 DATE 类型 = joda DateTime(非 java.util.Date) + +| 栏目 | 内容 | +|------|------| +| **现象** | REST 入参传 Long 型时间戳给 DATE 类型字段,引擎抛 `ClassCastException` | +| **根因** | 引擎内部 DATE 显示类型存储为 `org.joda.time.DateTime` 对象,不接受 `Long`;引擎从未把这个内部约定暴露为接口文档 | +| **对策** | REST 层适配器必须将前端传入的时间戳(Long)或 ISO 字符串转换为 `joda.time.DateTime` 后再传给引擎;反向序列化(引擎 → REST 响应)见 4.2 JodaModule | +| **影响范围** | 所有 DATE 显示类型字段的写入接口;P1 REST 层实现时必须加适配,P4 转换器生成 amis 日期组件时需对齐格式 | + +### 5.3 dom4j 取脚本必须用 getText(),不得用 getTextTrim() + +| 栏目 | 内容 | +|------|------| +| **现象** | 取出的 Groovy 脚本源码缩进/换行消失,执行时 `GroovyShell` 报语法错误 | +| **根因** | `getTextTrim()` 会压扁所有前后空白和换行符;Groovy 是换行敏感语言,多行脚本的换行是语法的一部分,压扁后源码损坏 | +| **对策** | 所有从 XML/dom4j 节点取脚本文本的地方**一律改用 `getText()`**;转换器(P4)和运行时的脚本读取处都须核对,已有问题处一并修复 | +| **影响范围** | `TemplateToAmisConverter` 的脚本提取逻辑;运行时 ScriptingEnginesManager 的脚本加载路径;全量 1,427 条脚本转换质量 | + +### 5.4 PK 列名 = `{表名}_ID` 约定 + +| 栏目 | 内容 | +|------|------| +| **现象** | 克隆实体或用转换工具新建实体后,PK 列名与引擎预期不符,查询报 `column not found` | +| **根因** | 引擎的 DDL 生成器在创建 PK 属性时,列名硬编码为 `{表名}_ID`(例如 `SYS_USERGROUP` 的主键列为 `SYS_USERGROUP_ID`);这是设计器创建时的约定,但未在文档中明示 | +| **对策** | 克隆工具、批量转换工具、P4 的迁移脚本在新建或克隆实体元数据时**必须同步按此约定命名 PK 列**;引擎不接受其他命名的主键列 | +| **影响范围** | P4 批量转换 1,516 个模板;P1 对拍测试中克隆实体场景;所有新建实体的 DDL 生成 | + +### 5.5 MIDTABLE 类型无主键子句 + +| 栏目 | 内容 | +|------|------| +| **现象** | MIDTABLE(中间表/关联表)类型实体的 DDL 中没有 PRIMARY KEY 子句,但调用了 CRUD 路径 | +| **根因** | 引擎设计:MIDTABLE 是多对多中间表,无业务主键,DDL 生成时故意不加 PRIMARY KEY | +| **对策** | 对 MIDTABLE 类型实体**不走引擎的 updatePO 路径**(见 5.1),只走 insert/delete;P2 数据权限中涉及关联表的场景需特别处理 | +| **影响范围** | 所有 MIDTABLE 类型实体(数量待 P1 统计);P4 转换器需识别并生成对应的 amis 组件 | + +### 5.6 REFERENCES 外键自动生成 + +| 栏目 | 内容 | +|------|------| +| **现象** | 动态建表后,发现某些列带有外键约束,但元数据 XML 中并未显式声明 | +| **根因** | 引擎 DDL 生成器:引用类型(REFERENCE 属性)的列自动生成 `REFERENCES` 外键约束;这是引擎的内置行为 | +| **对策** | P0' PG 升级演练时需检查外键约束在 PG 15 下的行为;P4 转换器处理引用列时不需要额外指定外键,引擎自动处理;批量删除/清理测试数据时须注意外键级联 | +| **影响范围** | 所有引用类型属性;对拍测试中的数据清理逻辑;P0' PG 升级兼容性扫描 | + +### 5.7 listSelect(String sql) 混合大小写表名在 PG 取值异常 + +| 栏目 | 内容 | +|------|------| +| **现象** | `DataDicServiceImpl.getEntityAttributes` 使用混合大小写表名(如 `"SYS_EntityAttribute"`)调用 `listSelect(sql,...)` 时,PG 返回空集或查询结果字段映射异常;使用条件 Map 的规范路径(全大写表名)正常 | +| **根因** | PostgreSQL 默认将未加双引号的标识符折叠为小写;混合大小写表名在未加引号时匹配不到实际的大写物理表名(EIP3 在 PG 下所有表名均大写);`listSelect(String sql)` 直接传 SQL 字符串时绕过了引擎的标准化处理 | +| **对策** | 正式移植时核查所有 `listSelect(String sql, ...)` 调用点,确认表名大小写;所有直接 SQL 路径中的表名统一用双引号包裹(`"SYS_EntityAttribute"`)或改用全大写;**优先改用条件 Map 路径,让引擎统一处理标识符** | +| **影响范围** | `DataDicServiceImpl` 中的直接 SQL 调用路径;P1 全量移植时的回归扫描重点;P4 转换器生成 SQL 片段时的命名规范 | + +### 5.8 ROLES 多值列经 LIST + 中间表落地(数据权限规则装载) + +> 来源:eip4-platform M0 任务 C2 实测(2026-06-11),详见 platform-auth/C2实测报告.md + +| 栏目 | 内容 | +|------|------| +| **现象** | `SYS_FILTERRULE.ROLES` 是「一条规则关联多个角色」的多值列,`DataFilterHelper.converToDataFilterRule` 直接 `po.get_Value("ROLES")` 期望拿到 `List`;但物理表上并无 ROLES 列,值如何加载不直观 | +| **根因** | 引擎对 `DisplayType.List`(REFERENCEID='LIST')列的多值加载走「中间表(MIDTABLE)」路径:ROLES 列的 `REFERENCEVALUE` 指向一条 `SYS_REFERENCEVALUE`,其 `ENTITYID`→中间表实体(`SYS_FILTERRULEROLE`,tabletype=2,恰 2 列),`ENTITYATTRIBUTEID`→回引列(`FILTERRULEID`)。`POJOServiceImpl.loadPOJO(isHierarchical=true)` 的 `hierarchicalQuery` 对 LIST 列查 `SELECT * FROM 中间表 WHERE 回引列=规则id`,收集「另一列」(`ROLEID`)全部值组成 `List` 设回 ROLES(见 POInfo.getReferenceValueTable/ColumnName + POJOServiceImpl.java:1256-1262) | +| **对策** | 自举建模需三件齐备:①中间表 `SYS_FILTERRULEROLE`(恰 2 列 `FILTERRULEID`+`ROLEID`,tabletype=2,元数据 seq 决定 getColumnName(0/1) 次序,第 0 列必须是回引列);②ROLES 列 `REFERENCEID='LIST'` + `REFERENCEVALUE` 指向一条 `SYS_REFERENCEVALUE`(ENTITYID=中间表实体、ENTITYATTRIBUTEID=回引列属性);③配套一条 `SYS_REFERENCE`(ENTITYID=中间表实体)。读路径必须走 `loadPOJO(...,isHierarchical=true)`(getEntityDataFilterRule 已如此),否则 LIST 列不展开。本地用 bootstrap-privilege.sql 直插中间表行种规则角色 | +| **影响范围** | 所有 LIST(多值/子表)显示类型列的自举与对拍;P1 客户库副本不可达期间,凡需种多值列数据都按此三件套建模;P2 数据权限管理 UI 写规则时引擎自身的写路径(saveOrUpdateDataPrivilege)会按同口径落中间表 | + +### 5.9 行级过滤仅在非 ADMIN 上下文触发 + +| 栏目 | 内容 | +|------|------| +| **现象** | 即便实体配了 `SYS_FILTERRULE` 规则,用默认(ADMIN)上下文 `listSelect` 仍返回全量,过滤「不生效」 | +| **根因** | `POJOCRUDServiceImpl.listSelectSpecialCol` 显式判断 `ctx.get(CURRENTUSER) != LoggedInUser.ADMIN` 才调 `dataPrivilegeService.getWhereClause`;ADMIN 视角天然不过滤(管理员看全量)。这是引擎设计而非缺陷 | +| **对策** | 对拍/验证行级过滤必须构造**非 ADMIN** 的 `ctx`(`CURRENTUSER`=具体用户 + `ROLES`=List)。C2 通过 EntityController 增 `asUser`/`roles` 查询参可选项构造该上下文驱动引擎过滤路径;不传则沿用 ADMIN(不过滤),向后兼容 | +| **影响范围** | 所有行级数据权限验证与对拍场景;P2 管理 UI / 网关须在请求上下文正确填充 CURRENTUSER + ROLES;`LoggedInUser.ADMIN` 是补足 36 位的 `'ADMIN'`(char(36) 比较口径) | + +### 5.10 DataFilterHelper 用 Jackson 1.x(org.codehaus.jackson) + +| 栏目 | 内容 | +|------|------| +| **现象** | 移植 `DataFilterHelper` 时其 import `org.codehaus.jackson.*`(Jackson 1.x,`ObjectMapper`/`JsonNode`/`ArrayNode`),与现代层用的 `com.fasterxml.jackson`(Jackson 2)是两套不兼容 API | +| **根因** | framework 原版即用 Jackson 1.x 做 FILTERRULE(Conditional[])的 JSON 互转;保真层纪律「com.dsasp 旧代码一行不改」,不得改写为 Jackson 2 | +| **对策** | platform-legacy-core pom 显式引入 `org.codehaus.jackson:jackson-mapper-asl:1.9.13`(传递带 jackson-core-asl),与 Jackson 2 共存(包名不同不冲突);代码原样保留 1.x API | +| **影响范围** | platform-legacy-core 依赖树(多一条 1.x 链);P1 全量移植中凡用 Jackson 1.x 的旧类同此处理;现代层序列化仍用 Jackson 2,互不干扰 | + +--- + +### 5.11 引擎 JSON 对 null 值列整列省略 [NEW 2026-06-11] + +- **现象**:对拍中物理列值为 NULL 的列(如 WF_HI_TASKINST.DUEDATE 全表 null),引擎 REST 输出的行 JSON 里整列缺失,被误判 MISSING_RIGHT。 +- **根因**:GeneralPOJO.toRow / JSON 序列化跳过 null 值键。 +- **对策**:对拍 harness 规则「右缺列 + 左值 NULL = 语义等值」(platform-parity RowDiff 自对拍模式);前端/AI 消费 API 时不可假设所有元数据列必出现。 +- **影响范围**:所有 list/load REST 输出消费方。 + +### 5.12 BOOLEAN 列域外脏数据引擎归 null [NEW 2026-06-11] + +- **现象**:BOOLEAN 元数据列物理值存在 2、-1 等域外值(旧库脏数据,如 PM_BUDGETRCJ.ISTURNOVERMATERIALS=2 共 1,094 行、PM_BUDGETLIST.ISLIST=-1),引擎读出为 null。 +- **根因**:引擎布尔解析只认 0/1,域外值归 null;**旧系统行为相同**,非移植缺陷。 +- **对策**:对拍按「已归因差异」处理(可见不判负);数据治理时这批脏值应与客户确认语义后清洗。 +- **影响范围**:全库 BOOLEAN 列;涉及行数见 C1 客户库对拍报告。 + +### 5.13 "胖列"实体大结果集不可单次取全 [NEW 2026-06-11] + +- **现象**:GB_PRJ_WORKER(15,814 行,含工人照片类大文本列)单次全量 REST 响应达 1.7GB,超 Jackson 1GB 字符串上限,解析失败。 +- **根因**:引擎 SqlRowSet 全量物化 + 大文本列;消费端单响应承载有上限。 +- **对策**:此类实体必须分页消费;对拍 harness 已做"单次抓取失败自动回退翻页"。架构第五节「大结果集流式导出」改造时此类实体优先。 +- **影响范围**:含 BLOB/大文本列的实体;P4 导出功能设计。 + +### 5.14 复杂视图实体的分页查询是 O(N) 重算 [NEW 2026-06-11] + +- **现象**:PM_PAYMENTAPPLY(38,138 行)引擎 SQL 为 DISTINCT + 4 个 LATERAL 子查询,**每页 500 行耗时 ≈61 秒**,深页更慢;全量遍历约 78 分钟。 +- **根因**:每页请求都重新执行完整 DISTINCT/JOIN 再 OFFSET,计划缓存不可复用叠加显示列翻译子查询。 +- **对策**:C3 压测已把此类实体列为热点;P2「渐进参数化 + Caffeine」与「DDL 索引增强」改造的优先验证对象;对拍用抽样模式(--sampleRows)。 +- **影响范围**:带多引用显示列的大表;真实用户的列表页延迟(决策会风险 R2 直接证据)。 + +## 六、Flowable 升级三坑 + +> 来源:eip4-poc WS4 实测,flowable-poc / flowable5-poc 工程(2026-06-10) +> 背景:客户库引擎版本 **5.13-SNAPSHOT**(非评估报告所写 5.14); +> 全量 1,509 个 BPMN 定义,零 `activiti:class` 自定义扩展, +> 但有 3 个表达式 bean(见 6.3) + +### 6.1 版本串 5.13-SNAPSHOT 不被升级链识别 + +| 栏目 | 内容 | +|------|------| +| **现象** | 将 ACT_* 表指给 Flowable 5.23 时报错 `"unknown version from database"`,升级脚本终止 | +| **根因** | Flowable 5.x 升级链通过 `act_ge_property` 表中 `schema.version` 字段识别当前版本,`5.13-SNAPSHOT` 不是正式版本号,升级链无法匹配版本范围 | +| **对策** | 升级前必须执行:`UPDATE act_ge_property SET value_='5.13' WHERE name_='schema.version'`;执行完成后再启动 Flowable 5.23 升级 | +| **影响范围** | **每一个客户库升级前的必执行步骤**,写入《Flowable 升级 Runbook》变更四要素前置;漏做则整个升级链中断 | + +### 6.2 5.13 不能直接跳 6.x(两步升级强制) + +| 栏目 | 内容 | +|------|------| +| **现象** | 尝试直接用 Flowable 6.8.1 连接 5.13 版本数据库时,迁移脚本因缺少 `TENANT_ID_` 列而报错并回滚 | +| **根因** | v5→v6 的 DDL 迁移脚本假设数据库已达到 Flowable 5.15 引入的 `TENANT_ID_` 列;5.13 没有该列,跳版直升会触发 DDL 错误 | +| **对策** | **强制两步升级路径**:① 先用 Flowable 5.23(v5 末版)引擎升级数据库到 v5 最终 schema;② 再换 Flowable 6.8.1(启用 `flowable5-compatibility`)升级到 v6;两步均需全量备份回退点 | +| **影响范围** | 生产升级 Runbook 中必须明确两步窗口(决策会已拍板 PG 升级与 Flowable 升级分两个独立停机窗口);PoC 已完整实测,1,509 定义 / 9,383 执行 / 9,321 待办 / 26,749 历史全部就地保留 | + +### 6.3 表达式 handler bean 移植面(3 个类) + +| 栏目 | 内容 | +|------|------| +| **现象** | Flowable 独立服务启动后,BPMN 流程中的候选人表达式 `${candidateUsersHandler.getUsers(...)}` 解析失败,抛 `FlowableException: Unknown property used in expression` | +| **根因** | 这 3 个 bean 定义在 `com.dsasp.server.wf` 模块中,Flowable 独立服务(`flowable-service.jar`)需要显式注册;PoC 扫描时遗漏了表达式 bean 层(仅扫描了 `activiti:class`,零结果),表达式层是独立入口 | +| **对策** | 将 3 个 handler 类从 `com.dsasp.server.wf` 移植到 `platform-flow-gateway` 模块;通过 `ProcessEngineConfiguration.setBeans(Map)` 注册(PoC 已验证注册机制有效);P3 阶段优先级最高 | +| **影响范围** | **引用量**:`candidateUsersHandler` × 4,761 处(全量 1,509 个 BPMN)、`wfContextService` × 175 处、`multiInstanceUsersHandler` × 33 处;这 3 个 bean 未移植则流程发起/审批全部无法运行 | + +**三坑汇总检查清单(写入升级 Runbook)**: + +``` +□ 升级前:UPDATE act_ge_property SET value_='5.13' WHERE name_='schema.version' +□ 第一步:Flowable 5.23 完整升级 + 验证 schema.version 达到 5.x 末版 +□ 第二步:Flowable 6.8.1 启用 flowable5-compatibility 升级 +□ 升级后:验证 1,509 个定义可见 + 抽取 3 个运行中实例续跑 + 候选人表达式解析正常 +□ platform-flow-gateway 已包含 3 个 handler bean + cfg.setBeans 注册 +``` + +--- + +## 七、库内数据质量已知问题 + +> 来源:eip4-poc Day 2 全量扫描结果(tools/eip4_sweep.py)+ 移植台账 +> 性质:旧系统库内存量问题,非移植缺陷;工程化前必须定性处置(决策会切流红线 3) + +### 7.1 55 个孤儿元数据 + +| 栏目 | 内容 | +|------|------| +| **现象** | `eip4_sweep.py` 对拍时,55 个实体的 `listSelect` 返回 0 条但引擎无错——但直接查 `count(*)` 也返回 0(物理表不存在) | +| **根因** | `SYS_ENTITY` 中存在元数据定义,但对应的物理表已不存在于数据库——元数据孤儿,可能是历史删表未清元数据 | +| **对策** | **逐条定性**:① 已废弃(可归档元数据);② 需要重建物理表;③ 业务仍在使用(严重问题,需客户确认);定性结果需**客户书面确认**后方可进切流(决策会红线 3) | +| **影响范围** | 55 个实体从全量 1,166 中排除后,有效对拍范围为 1,111 个;P1 对拍框架建立时需排除或单独标记这 55 个 | + +### 7.2 9 个元数据漂移 + +| 栏目 | 内容 | +|------|------| +| **现象** | 引擎查询返回 500 错误,但旧系统行为一致(老系统同样报错);全量扫描中 9 个 500 实体排除在通过率计算之外 | +| **根因** | 元数据声明与物理表结构不一致:典型案例 `SYS_DATASTATUS`,元数据声明为普通表但物理表无主键列;引擎拼出的 SQL 在 PG 下执行失败 | +| **对策** | 逐条排查漂移原因(元数据错误 vs 物理表被手工改过 vs 历史 bug);修复方向:对齐元数据或对齐物理表;需**客户书面确认**后处理(决策会红线 3) | +| **影响范围** | 9 个实体;`SYS_DATASTATUS` 已知 1 例;P1 对拍框架需将这 9 个标记为「已知漂移,人工定性中」 | + +### 7.3 HR_ATTENDLOGDETAIL.UNITNAME 物理列缺失 + +| 栏目 | 内容 | +|------|------| +| **现象** | 主子表级联测试中,`HR_ATTENDLOGDETAIL` 的 `UNITNAME` 属性读取返回 null;写入时无报错但值丢失 | +| **根因** | `SYS_ENTITYATTRIBUTE` 中存在 `UNITNAME` 属性定义,但 `HR_ATTENDLOGDETAIL` 物理表中该列不存在——属于 7.2 元数据漂移的又一具体案例 | +| **对策** | 与 7.2 同:客户确认是否需要补列还是废弃该属性定义;**在客户确认前,涉及 UNITNAME 的查询/写入不得进切流** | +| **影响范围** | `HR_ATTENDLOGDETAIL` 相关的考勤详情功能;如有其他 HR 表存在类似问题需一并排查 | + +### 7.4 entityid 非法字符孤儿模板 + +| 栏目 | 内容 | +|------|------| +| **现象** | WS2 转换器处理某些模板(如「信息价管理」)时,`entityid` 字段值包含非法字符,无法在 `SYS_ENTITY` 中找到对应实体 | +| **根因** | 部分老模板的 `entityid` 值使用了历史 ID 格式(含特殊字符或已被删除的实体 ID),指向已不存在的实体 | +| **对策** | P4 批量转换前需先跑一轮盘点 SQL,识别所有 entityid 异常的模板并单独标记;转换器需要 null-safe 处理(entityid 解析失败时输出错误日志而非抛异常终止批量任务) | +| **影响范围** | 全量 1,516 模板中的孤儿模板数量待 P1 盘点确认;P4 转换器需增加异常模板的旁路处理流程 | + +--- + +## 八、amis 侧已知坑 + +> 来源:eip4-poc WS2 实测(2026-06-10) +> amis 版本:6.13.0(锁定,本地化部署,不依赖 CDN) + +### 8.1 官方 schema.json 宽松语义与 additionalProperties 预处理 + +| 栏目 | 内容 | +|------|------| +| **现象** | 直接用 ajv(draft-07)加载官方 `schema.json` 进行校验时,大量结构上合法的 amis schema 被报错为「额外属性不被允许」,与实际浏览器渲染结果矛盾 | +| **根因** | 官方 `schema.json` 中大量位置存在 `{"$ref":..., "additionalProperties":true}` 的**兄弟键覆盖写法**;在 draft-07 严格语义下,兄弟键被忽略,引用定义的 `additionalProperties:false` 生效,拒绝一切额外属性;但 amis 官方编辑器(VS Code 插件等)使用更宽松的 JSON Schema 实现,会合并引用 schema 与兄弟键 | +| **对策** | 校验前做**预处理**:递归剥除所有含 `$ref` 节点的兄弟 `additionalProperties:false`;已在 `GET /api/poc/amis-validate` 实现,3 个真实模板转换后校验通过(0 错误) | +| **影响范围** | P4 双闸中的「官方 schema 校验」闸;MCP Server 的 validate-schema 工具;AI 生成管线的校验-重试环节;**所有使用 ajv 校验 amis schema 的地方都需要这个预处理步骤** | + +### 8.2 双闸必要性(校验闸 + 渲染冒烟闸) + +| 栏目 | 内容 | +|------|------| +| **现象** | schema 校验通过(0 错误)的页面,在浏览器 amis 渲染时出现组件类型未识别或渲染为空 | +| **根因** | schema.json 含 loose 宽松分支,「未知渲染器类型」会通过校验(schema 设计内)但运行时 amis 渲染器不识别;schema 校验只能抓结构错误/已知属性类型错误/必填缺失,无法保证可渲染性 | +| **对策** | **双闸缺一不可**:第一闸(schema 校验)抓结构问题;第二闸(headless 渲染冒烟,如 Puppeteer/Playwright 执行 `amis.embed`)抓渲染问题;P4 批量转换流水线必须两闸串联,两闸都过才入库 | +| **影响范围** | P4 全量 1,516 模板转换流水线;AI 生成管线;MCP Server validate-schema(需升级为双闸);决策会已将「双闸」作为质量门禁第 2 条 | + +--- + +## 九、待补章节占位 + +> 以下章节在 M0 期间需要补充,当前为占位。责任人需在 M0 出口前完成。 + +### 9.1 知识 backup 人选(待定) + +| 事项 | 状态 | 责任人 | 期限 | +|------|------|--------|------| +| 熟引擎老员工 backup 人选确定 | **待定** | 项目负责人 | M0 出口 | +| backup 人员与老员工 1:1 交接会(≥2 次) | **待定** | 老员工 + backup | P1 第一周 | +| backup 人员能独立运行 eip4-poc + 解释对拍结果 | **待定** | backup | P1 结束 | + +**背景**:决策会将熟引擎老员工列为单点风险(R3),backup + 本手册是降险硬要求;立项决议含「backup 人选确定」为 M0 出口条件之一。 + +### 9.2 手册过评审记录(待补) + +| 评审项 | 评审人 | 日期 | 结论 | +|--------|--------|------|------| +| 第二至八章坑位完整性 | 待定 | 待定 | 待定 | +| 对拍框架设计(C1)评审 | CTO + 老员工 | 待定 | 待定 | +| Flowable 升级三坑与 Runbook 对应 | P3 责任人 | 待定 | 待定 | + +### 9.3 WS3 facade 动词表扩展(待补 P1) + +当前已确认的 4 个基础辅助函数(`getFieldValue` / `bindField` / `setFieldReadOnly` / `showConfirmDialog`)之外,盘点报告 Top S3 API 调用显示需扩展至 ~20 个: + +已知待补:`addButton`×100、`getValue`×68、`getContainerDataSource`×61、`setFilter`×56、`removeAllItems`×29、`group.setReadOnly`×27、`getDisplay`×27、`setVisible`×21、`setCaption`×16…… + +P1/P4 阶段由老员工与后端架构逐条补全,补全后回填本节。 + +--- + +**手册维护说明**:本手册随工程化进展持续更新;新坑位发现即追加,以 `[NEW yyyy-mm-dd]` 标记;章节完成后移除「待补」标记。任何对引擎行为契约的更改必须同步更新第五章并过 code review。 diff --git a/platform-app/src/test/java/com/eip4/platform/app/ArchitectureRulesTest.java b/platform-app/src/test/java/com/eip4/platform/app/ArchitectureRulesTest.java index 2df3059..e2f8961 100644 --- a/platform-app/src/test/java/com/eip4/platform/app/ArchitectureRulesTest.java +++ b/platform-app/src/test/java/com/eip4/platform/app/ArchitectureRulesTest.java @@ -7,7 +7,7 @@ import com.tngtech.archunit.lang.ArchRule; import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses; /** - * 架构纪律(《eip4-platform架构设计》第一节,ArchUnit 固化): + * 架构纪律(《架构设计》(docs/架构设计.md)第一节,ArchUnit 固化): * com.eip4.* 可调 com.dsasp.*,反向禁止——保真层不得感知现代层。 */ @AnalyzeClasses(packages = {"com.dsasp", "com.eip4"}) diff --git a/platform-auth/C2实测报告.md b/platform-auth/C2实测报告.md index a133fb8..d38d3f9 100644 --- a/platform-auth/C2实测报告.md +++ b/platform-auth/C2实测报告.md @@ -147,7 +147,7 @@ com.dsasp.server.common.exception.PrivilegeException: 没有任务数据访问 --- -## 九、遇到的坑(已同步《EIP4迁移手册v1.md》§5.8/5.9/5.10) +## 九、遇到的坑(已同步《eip4-platform/docs/迁移手册.md》§5.8/5.9/5.10) 1. **ROLES 多值列经 LIST + 中间表落地**(§5.8):多值列不落物理列,值在中间表;需 LIST + REFERENCEVALUE + SYS_REFERENCE + 中间表(恰 2 列、回引列在前)四要素齐备,且读路径走 `loadPOJO(...,isHierarchical=true)` 才展开 List。 2. **行级过滤仅在非 ADMIN 上下文触发**(§5.9):`listSelectSpecialCol` 判断 `ctx.CURRENTUSER != ADMIN` 才调过滤;ADMIN 天然看全量。验证必须构造非 ADMIN ctx(本 C2 经 EntityController 的 asUser/roles 可选参实现)。 diff --git a/platform-parity/C1实测报告.md b/platform-parity/C1实测报告.md index be53fe4..cd21c45 100644 --- a/platform-parity/C1实测报告.md +++ b/platform-parity/C1实测报告.md @@ -1,7 +1,7 @@ # C1「逐行对拍框架」实测报告 > 模块:`platform-parity` | 阶段:M0 | 日期:2026-06-10 -> 上承《eip4-platform架构设计.md》第四节「检测兜底」层与 eip4-poc 决策口径更正 +> 上承《架构设计》(docs/架构设计.md)第四节「检测兜底」层与 eip4-poc 决策口径更正 > (PoC 仅做到「计数级一致 99.1%」,逐行对拍列为工程化第一周 C1 强制补验项)。 > 本报告固化 C1 框架的架构、归一化规则、本地实证数字、与客户库全量对拍的差距与待办、风险论证。 diff --git a/pom.xml b/pom.xml index 3c052f4..9ecbf1c 100644 --- a/pom.xml +++ b/pom.xml @@ -16,7 +16,7 @@ 0.1.0-SNAPSHOT pom eip4-platform - EIP4 平台(路线 A'):双层制模块化单体——保真层供奉,现代层生长。见《eip4-platform架构设计.md》 + EIP4 平台(路线 A'):双层制模块化单体——保真层供奉,现代层生长。见 docs/架构设计.md platform-legacy-core