Files
eip4-platform/docs/架构设计.md
zhengwr b4baca5d94 docs: 架构图快照(2026-06-26)入库 + 生成式OS驾驶舱迁出指针存根
- 架构设计.md 头部挂当前架构图 assets/eip4-architecture-2026-06-26.png(此前改动遗留未提交)
- plans/2026-06-24-生成式OS数据驾驶舱-design.md 为指针存根,权威文档在独立仓 genos-cockpit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 08:01:23 +08:00

127 lines
9.0 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.
# eip4-platform 架构设计
> 版本 v1.0(2026-06-10)| 上承《EIP3工程化实施计划》,是 P1「eip4-poc → eip4-platform」的设计依据
> 本文档固化了立项后关于工程结构、选型、中间件、保真层安全/性能的全部架构决策。
> **新会话/新成员开工 eip4-platform 前必读本文。**
## 当前架构图(2026-06-26)
![EIP4 最新架构](assets/eip4-architecture-2026-06-26.png)
---
## 一、总原则:双层制——保真层供奉,现代层生长
**移植的旧代码不重写、不"现代化改造"**。理由: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 AI Agent 开发底座、schema 双闸校验、自动修复、本地门禁和人工部署包
├── platform-cli EIP4 Agent 受控命令入口:环境探测、AI 自动开发、后续发布编排
├── platform-parity C1 逐行对拍框架:录制/重放/逐行 diff(P1 一级交付物,可独立 CLI 跑批)
└── platform-app Spring Boot 启动器,组装上述模块
```
**纪律(ArchUnit 规则固化)**:`com.eip4.*` 可调 `com.dsasp.*`,反向禁止;新代码必须单测,旧代码以对拍为完成定义;`com.dsasp.*` 与 framework 源码的 diff 保持最小。
## 二、选型决策表
| 决策 | 选择 | 理由 |
|------|------|------|
| 整体形态 | 模块化单体 + Flowable 独立服务(仅此一个独立) | 4 人团队 + 按客户私有化部署,拒绝微服务 |
| 运行时 | **JDK 21**(LTS)+ Spring Boot 3.3.x | PoC 起于 JDK 17(Boot 3 最低要求、当时 LTS、不追新),F2-13 起编译目标升 `release=21`(修报表 500,见下)。**红线:不可用 JDK 26**——保真层服务流走 Groovy 4.0.27,其 ASM 不认 JDK 26 字节码(major 70),编译/运行均崩;升 JDK 须同步升 Groovy,目标取下个 LTS=25 而非 26 |
| 数据访问 | 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 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。