Files
eip4-platform/docs/plans/2026-06-19-EIP4开发平台-架构方向-design.md
zhengwr da3ad35821 docs(plan): land EIP4 dev-platform direction + reconciled execution roadmap
Commit the architecture-direction design doc (D1-D7 locked decisions) and add a companion living execution roadmap reconciling the design with the already-merged AI agent module (main 9aea6c1): phase-by-phase delivery account + ordered milestones (M0 component L1 -> render-smoke gate -> 先宽度 M1/M3a/M2/M3b -> 再深度 M4/M5/M7/M8), split autonomous-build vs env-verification.

Roadmap revised after adversarial review: restored the D2-locked P0 prerequisite (component L1), moved the render-smoke correctness gate ahead of real-DB dogfood, split net-new write-path convergence ahead of the new endpoint, marked code-complete vs integration-pending.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-19 16:59:16 +08:00

15 KiB
Raw Blame History

EIP4 开发平台 · 架构方向(与最初设计对齐版)

日期:2026-06-19 | 性质:方向级 design(brainstorm 收敛 + 最初设计考古 + 引擎代码核实 + 对抗审查产出) 配套权威:项目进度与路线-总览-2026-06-17.md(A 兼容 / B 新功能全景)、架构设计.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;细化实施计划见配套《落地执行路线图》。