Files
eip4-platform/docs/plans/2026-06-19-EIP4开发平台-架构方向-design.md
zhengwr 1b02036153 docs+javadoc: 文档-代码对抗核查对齐 + 归档候选物理归档
5 路并行核对总览 §9/§10/§11 + A/B 矩阵声明 vs 两仓代码(48 条 46 条完全一致,无虚报),修正不一致处:
- A10 行 🔴→🟡:W1 Flyway(V1-V3)+W2-W4 容器化/nginx/compose 骨架 06-25 已合 main,文档此前低报;§10.2 Flyway/compose 两条标 ✅
- §9 P0② 表格「同族扩长」与对抗审查①矛盾(代码一律拒 TYPE 变更)改齐
- §10.2 render-plan 行号迁 AiDraftGateValidator.java:246(SRP 拆分后位置)
- §11 报表单测 73→79;§2「五步编排壳」改四步向导
- CandidateUsersHandler 类级 javadoc:scriptUser 已于 06-26 接入(resolveScriptUsers),删「WARN 降级未接入」陈旧表述(纯注释零行为变更)

归档整理(总览 §8 归档候选落地):
- 10 份已完成/被取代文档 git mv 入 docs/归档/(06-14×3/06-15/06-16/06-20 plans、CRUD-QA、C3/C5、总览-06-17)
- 引用同步改路径:README 索引、M0剩余项登记、通用模板收口计划、架构方向-design、新闻管理plan
- README 刷新至 07-02:补 06-22→06-26 增量一节、审批/报表行状态、§2 补登 06-25/06-26 四份 design/计划、§4 过时「未 push」表述修正

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

134 lines
15 KiB
Markdown
Raw Permalink 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 开发平台 · 架构方向(与最初设计对齐版)
> 日期:2026-06-19 | 性质:方向级 design(brainstorm 收敛 + 最初设计考古 + 引擎代码核实 + 对抗审查产出)
> 配套权威:`项目进度与路线-总览-2026-06-21.md`(A 兼容 / B 新能力全景,取代 06-17 版)、`架构设计.md`(双层制/选型/红线)、`决策与盘点/EIP4前端与收尾实施计划.md`(F4 低代码工具链原始定义)
> 方法:9-agent workflow(7 路考古/代码核实 → 综合 → 对抗审查),逐行核实引擎实况。
---
## 0. 一句话结论
**「153 收尾后做可视化开发平台」不是另起炉灶,是项目最初路线图里 F4「低代码工具链 L1→L3」的兑现。** 方向成立(对抗审查判决 `sound-with-fixes`),但最初设计逼出三根硬约束(一根是「触发重新决策」级),需带 6 条修正落地。
## 1. 背景与驱动(用户拍板)
- **先 B 提效、再 A 卖点**:先用新能力填「建页/建模/交付太慢太贵」的钱坑,再讲 AI/现代化差异化。
- **递进**:存量 153 定制视图用现有兼容方式(转换器 mutator)啃完(已完成几十个);真正重点是 153 后,面向「**未来功能维护 + 新功能开发**」要有一套现代可视化开发平台,覆盖【**元数据 → 表结构 → 设计 → 实现功能 → 发布**】五环。
- **AI 独立轨**:已在另一分支做,定位=给 AI coding 工具(Claude Code/Cursor)供 **MCP + CLI**,不是应用内 AI 生成 schema。
- **定位**:内部交付提效工具(**非**对客户售卖的低代码/自助配置平台——见 §5 红线)。
## 2. 与最初设计「一脉相承」的依据(5 处文档锚点)
| 本方向 | 最初设计原文锚点 |
|---|---|
| 五环【元数据→表→设计→实现→发布】 | 《EIP4前端与收尾实施计划》F4 总览:**「低代码工具链 L1→L3,门控:无(架构已拍板)」**;§七:L1 页面设计器=amis-editor 二开 / L2 实体建模器=可视化维护 SYS_ENTITY / L3 流程设计器=bpmn.js + Flowable。末环=§6.3 在线导入发布 |
| 现代层 authoring 长在引擎上 | 架构设计 §一「**保真层供奉、现代层生长**」+ ArchUnit 单向纪律(`com.eip4.*` 可调 `com.dsasp.*`,反向禁止) |
| 一个 schema 世界 | §6.2「SYS_PAGE_SCHEMA 标准层 + overlay 层,升级时标准层整体替换、overlay 保留提示 diff」 |
| AI 独立轨给 MCP+CLI | 最初 **P5「MCP/AI 工具层」** 逐字吻合 |
**引擎实况(已读码核实)**:四环里**三环引擎已在保真层活着**——`Entity.java`/`POInfo.java`/`POJOCRUDServiceImpl`(元数据 CRUD)、`Entity.createTableSql`→`DataDicServiceImpl`(动态建表)、`FlowExcuteServiceImpl`(534 行,含 `insertNodeAfter/removeNode` 图编辑原语 + `saveOrUpdate` 写回 `SYS_SERVICEFLOW`)、Groovy/JUEL 脚本引擎。
## 3. 最初设计强加的三根硬约束(对抗审查核实)
### ① 最大矛盾 · 焊死退路(go/no-go 级)—— 决策:**签字下注 amis**
最初把 amis-editor/自研设计器钉为「amis fork 失败时的防御性 **Plan B**」(止损 S2,换渲染器损失仅 1–2 人月)。架构决策报告 §四「触发重新决策条件#1」:*若决策层不接受永久 fork + 终身自维护前端渲染器的预算 → 须重评其他 Apache 渲染层*。把 amis-editor 升为战略主线 = 主动焊死退路 = 踩中该触发条件。
**已知天花板(写进立项)**:amis-fork 6.13.0 冻结于 2025-08、近 3 月零上游提交、bus factor≈1、需 **0.5–1 人/年自维护**。
**用户拍板**:✅ 签字下注 amis。**但附带关键现实**:**DesignerPage 当前还无法真正使用**(见 §7)——下注成立的前提是先把它弄到能用。
### ② 「补 UI 非造引擎」被系统性低估 —— 真实=「一环就位 + 两环要补引擎」
- **设计环**:✅ 就位,但**仅 edit-only on 存量页**(e2e 68/68 验的是 overlay 存取往返,**不等于设计器可用**)。
- **建模环**:🔴 引擎层**不能 ALTER**(`executeCreateSql` 只接受 CREATE,`DataDicServiceImpl:193-200`);`MetaController` 是克隆 SYS_USERGROUP、限 `EIP4AI_` 前缀的 **AI 雏形**,非面向人。新建实体后改字段**零迁移路径**。
- **编排环**:🔴 `FlowController` **只执行不编辑**,flow 仍是老 XML,EIP4 侧 **0 个 authoring REST**。
### ③ overlay 是 edit-only —— 「一个 schema 世界」附条件成立(一次性数据建模门)
`SYS_PAGE_SCHEMA_OVERLAY` 以 `template_id` 为主键、`base_etag` 挂靠**转换器产出的标准层**。「一个 schema 世界 + 可升级」的优雅**只在「先有标准底版、overlay 是其差量」时成立**。**从零新建的页没有标准底版**,其生命周期/升级/diff 在最初设计里是**空白**。「改存量页已上线」≠「新建页平台就绪」。
## 4. 逻辑编排器(唯一硬骨头)—— 决策:**b 主干 + 人工 20% + c 增量,否决 a**
- **否决 a(节点图编辑器)**:最初零根基;`Flow.java:422/454` 对非线性流主动抛「请用高级配置进行编辑」——证明**连老 EIP3 自己的可视化也只覆盖线性流**。节点图是最重前端投资、对冻结栈纯新增,ROI 最差。
- **b 主干**:80% 常规联动/线性服务流走声明式配置面(32 个 facade 动词 onEvent 面板,复用已有),不写代码即提效。
- **诚实修正(对抗审查)**:b 只覆盖**老系统已能可视化的线性流**;那 20% 复杂逻辑(非线性流/有副作用 Groovy/跨流条件=最初 S3 留下的 **115 份人工作业单**)**b 接不住**。
- **故**:那 20% **默认保留「人工作业单」兜底**(人写 Groovy/JUEL,复用 `field-editor`);**c(AI 生成)仅「加速人工 + 人工复核入库」增量**,platform-ai 空壳未落地前**不算进对外交付能力**。对外能力边界=「**b 声明式 80% + 人工 20%**」。
## 5. 落地形态(与最初设计对齐)
不立「新平台」为独立大项目,而是把 F4 三件套 + §6.2 overlay + §6.3 发布 + P5 MCP 正式化为一套「**现代层 authoring 模块集合**」,落在 `platform-metadata` 等现有模块内(不新进程),守三红线:
> **4 进程私有化单体 / 无新中间件 / 无多租户**;authoring 必须走既有引擎接口签名(POInfo/Entity/DataPrivilege/FlowExcuteService)**不旁路**。
- **存储层零新增**:authoring 全部读写 `SYS_ENTITY`/`SYS_ENTITYATTRIBUTE`(元数据真相)、`SYS_SERVICEFLOW.CONTENTXML`(服务流真相)、`SYS_PAGE_SCHEMA`+overlay(页面真相)。「元数据即白名单」运行期/开发期同源。
- **定位红线**:架构决策报告 §2.1a 已把「交付带动态建表的低代码平台能力给客户继续配置」定性为合同敏感地带(曾用于否决路线 B)。新平台守在**内部提效工具**,不对外做 SaaS/多租户配置平台。
## 6. 分期路线(每期标复用什么 / 补什么引擎欠账)
| 期 | 目标 | 关键交付 | 真实前置 / 复用 |
|---|---|---|---|
| **P0** | 立底座 + 门禁 | 组件设计体系 **L1 主题 token 做到生产级**(决策2「先 B 提效」的 UI 前提);为新 authoring 产物补**正确性门禁**(新建页无对拍基准!→ 元数据变更 CRUD 烟测 + 编排执行对拍 + overlay 版本可审计回滚 + schema 双闸复用);amis 战略取舍立项书签字 | **真实前置=组件 L1,非 153**;复用 overlay 双层、schema 双闸 |
| **P1** | 设计环正式化 + **先修 DesignerPage 可用性** | 诊断并修复 DesignerPage「无法使用」(见 §7);从「改存量」升级到能用;**补 net-new 页数据模型/生命周期**(闭合 §3③门);收敛独立设计中心(评估 `DesignCenterPage.tsx` 雏形);facade onEvent 声明式面板第一块 | 复用 DesignerPage/overlayApi、PageSchemaController、facade 动词表 |
| **P2** | 建模环 | **先补引擎安全 `alterTableSql`**(加法在线/改删走升级窗口,守 §6.3 红线)再做 L2 建模器 UI;MetaController 从 AI 雏形重写为面向人 | 复用 Entity.createTableSql + 缓存失效免重启 |
| **P3** | 编排环(硬骨头·打法 b) | 服务流 authoring REST 出口(暴露 `FlowServiceImpl.saveOrUpdate` + 图编辑原语)+ 声明式线性流配置面 + Groovy 代码编辑器兜底;BPMN 审批流走 L3 bpmn.js | 复用 FlowExcuteService + Flow 图编辑原语 + DefaultFlowHelper |
| **P4** | 发布环 + 链条贯通 | §6.3 元数据资产包另存/导入;「建实体→合成默认流→生成默认页→设计器微调→发布」串通 | 复用 §6.3 资产包 + 缓存失效 + DefaultFlowHelper |
| **P5** | AI 工具面(决策3 独立轨·c 兜底) | Meta/Flow 端点升级为正式 MCP,接通 platform-ai 空壳,消除两套 authoring 入口 | 复用已建端点 + schema 校验 |
> 启动次序:**与 153 收尾并行**(用户拍板)。解除「153 收尾后才做」硬前置——153 进度由商务 S1 拍板、不由技术,挂其后会被无限期阻塞。**但据实承认**:新平台真实前置是组件 L1,不是把「等 153」换成「等组件 L1」的隐藏依赖游戏。
## 7. DesignerPage 现状(状态标记,非当前动手任务)
> 定性:这是一个**已知状态**(用户实测不可用),作为 D1 amis 下注的前置验证项纳入 P1,**不在架构方向讨论里展开 debug**。诊断已查实环境层根因嫌疑(见下),最终复现/修复留到 P1 执行期。
**入口模型(D5 已定)**:单一「设计中心」菜单入口(运行态/设计态分离),废弃每页注入按钮。`DesignCenterPage.tsx`(fetchMenu→collectLeaves 列页 + 「设计」入口)是正确雏形方向,需补「新建页」与 net-new 生命周期(§3③)。
**「打开没有内容」环境层查实(curl/lsof 实测,2026-06-19)**:
- **8093 是纯 API 后端,完全不托管前端**(`/`、`/index.html`、`/assets/*`、`/editor.html` 全 404);
- 前端只活在 **4 个 stale 重复 vite dev server**(5174-5177);`.env` 有重复 `VITE_BACKEND_TARGET`(8084→8093)——**stale 实例代理到死端口 8084 → schema 拉不到 → 画布空** 是头号嫌疑;
- editor.html 入口页本身没坏(vite 上 200 + CSS 直链 200,dist 构建也正确);
- 这同时暴露 **A10:整个前端(设计器在内)没有被托管的家,只跑临时 dev 进程** —— 设计器「无法使用」一半是部署/托管缺失。
**旧线索(仍待 P1 复现确认)**:
- e2e 只验 overlay 存取往返,**未验设计器作为 authoring 工具可用**;
- 报告自承「**facade onEvent 可视化面板未做**」——能拖布局、配不了行为;
- `editor.html` CSS 走 `/node_modules/...` 直链(dev-only hack),**生产构建可能裂**;
- **edit-only on 存量页**,不能新建/绑新实体(§3③门);
- `DesignerPage.handleRestore` 注释自承:amis-editor 整体替换 value 会「白屏」,故还原后整页 reload(提示 amis-editor 二开的脆性)。
**下一步**:钉准「无法使用」的真实症状(开不了 / 白屏 / 只能改存量 / 能改但太糙/配不了逻辑 / 生产构建裂),再定 P1 第一锤。
## 8. 6 条必须吞下的修正(对抗审查 fixes)
1. 「放弃渲染层可换退路」升为立项**硬 go/no-go**,立项书签字接受 amis-fork 冻结天花板。(✅ 用户已签)
2. 为 net-new 页补数据模型与生命周期,再谈「一个 schema 世界」;闭合前不把「设计中心」当「新平台就绪」对外宣称。
3. 拆 b/c 真空:20% 复杂逻辑默认「人工作业单」兜底,c 仅「加速人工 + 人工复核」,platform-ai 落地前不算进交付。
4. 引擎层**先补安全 `alterTableSql` 并冻结边界**再做 L2 UI;MetaController 重写为面向人,别在 AI 雏形上长 UI。
5. 解除「153 后才做」硬前置,但 P0 据实命名「L1 底座 + authoring 门禁」,不用隐藏前置替换显式前置。
6. 为新 authoring 产物新设正确性门禁(新建页无对拍基准)——提为 **P0 交付物**,是绕过最初数据事故控制机制的唯一补偿。
## 9. 顶层风险
- 逻辑编排环是最初真空地带、无对拍基准、最高不确定(S3 自动化率 <80% 即触发工期重估)。
- amis-fork 冻结天花板被加码(押更多二开在 bus factor≈1 的栈上)。
- 建表 ALTER 缺口 × §6.3「DDL 只允许加法在线」红线夹击——「改表」体验天然受限,不能做成自由在线 DDL。
- 「元数据即白名单」在线 authoring 下可能反转为约束:白名单变活动目标,并发 authoring 的一致性/缓存时序是新攻击面。
- 组件体系未达生产级即做设计中心=重蹈「功能对但观感差」覆辙。
## 10. 决策记录(本次锁定)
| # | 决策 | 选择 |
|---|---|---|
| D1 | amis-editor 战略下注 | ✅ 签字下注(接受冻结天花板);前提=先修 DesignerPage 可用性 |
| D2 | 新平台启动次序 | ✅ 与 153 并行(真实前置=组件 L1) |
| D3 | 逻辑编排打法 | ✅ b 主干 + 人工 20% + c 增量,否决 a |
| D4 | 对外定位 | 内部提效工具(守 §5 合同红线)|
| D5 | **设计入口模型** | ✅ **单一「设计中心」菜单入口**(运行态/设计态分离);**废弃每页注入的设计按钮**(转换器 `EngineclassDelta:898` + PageRenderPage「设计」按钮,用户已移除)。开发/设计是独立工作区,不混进业务页工具栏 |
| D6 | **AI 轨形态** | ✅ AI = **独立 NocoBase 式 CLI 编程轨**(`feature-package` 为单元的 scaffold→dev→verify→release 生命周期,供 Claude Code/Cursor 等 AI coding 工具操作),**不并入设计中心**。EIP4 的「插件」等价物 = 元数据 feature-package(非代码插件) |
| D7 | **设计中心定位** | ✅ 设计中心 = **给实施人员的纯人工 no-code**(b 轨),不挂 AI 入口;AI 走 D6 独立 CLI 轨 |
---
## 11. 落地状态(2026-06-19 续)
- **AI agent 分支已合入 main(`9aea6c1`)**:交付了五环+横向的后端地基一大半(schema 门禁/三真相 authoring 端点/recipe-blueprint/元数据建实体/CLI 种子),并由 3 个收口提交保障合 main 安全(分流 `bac69d8` / admin 门 `c379f5b` / 对外口径 `9aea6c1`)。逐项对账 + 有序里程碑见 **`2026-06-19-EIP4开发平台-落地执行路线图.md`**(活计划)。
- **仍为 P0 锁定前置且未起步**:组件设计体系 **L1 主题 token 生产级**(D2)——路线图 M0。
- 本方向级 design 为权威决策记录;可执行里程碑/状态以路线图为准。
*本文为方向级 design;细化实施计划见配套《落地执行路线图》。*