- 新建 项目进度与路线-总览-2026-06-21(取代06-17版),刷新A/B矩阵+增量交付+下一步+§9实施记录 - README 索引刷新到06-21;旧总览+14份过时/已完成文档加状态横幅;落地路线图回写里程碑 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5.6 KiB
📌 现状以总览为准(2026-06-21):正文若将 master-detail 列为「未来 TODO / 未覆盖」已过时——
master-detail-v1.yamlrecipe 已存在并交付(含派生/聚合/引用联动)。进度见 总览-2026-06-21 §2。
AI Agent Page Blueprint Contract
日期:2026-06-17
目标
EIP4 的 AI Agent 不直接自由生成 amis JSON。Agent 应先生成 EIP4 PageBlueprint,再由平台编译器输出 amis schema,并继续通过 typed page schema、amis schema 和真实浏览器 E2E。
这条路径借鉴 NocoBase 的做法:AI 操作受控配置模型,平台负责规范化、校验、模板复用和版本证据。
当前已落地对象
代码位置:
platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprint.javaplatform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintField.javaplatform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompiler.javaplatform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.javaplatform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeValidator.javaplatform-ai/src/main/resources/ai/page-recipes/maintenance-crud-v1.yamlplatform-ai/src/main/resources/ai/page-recipes/tree-crud-v1.yaml
AI 可查询入口:
GET /api/ai/page-recipesGET /api/ai/page-recipes/{recipe}
工具注册表中对应工具为 page-recipe.read,所需 scope 为 ai:page-recipe:read。Agent 生成
PageBlueprint 前应先读取 recipe 定义,再生成草稿。
AI 辅助开发链路中的 PAGE_SCHEMA 草稿仍然保存编译后的 amis schema,保持现有落库和前端渲染契约不变;草稿 metadata 额外保存:
pageRecipepageBlueprintVersionpageBlueprint
声明了 pageRecipe 的草稿必须通过 page-recipe 门禁。该门禁会重新解析 metadata 中的
pageBlueprint,用平台注册的 recipe/compiler 重新编译,并要求草稿 payload 与编译结果一致。
因此 Agent 不能一边声明使用标准 recipe,一边绕过 compiler 私改 amis JSON。没有声明 recipe 的
历史/手工 PAGE_SCHEMA 草稿暂按自由 schema 处理,只走 amis schema 和 typed page schema。
Recipe: maintenance-crud-v1
适用范围:
- 普通实体维护页
- 单主表列表
- 新增、编辑、删除
- 本地 smoke 可覆盖列表、新增、服务流搜索
标准输出结构:
- 顶层
type=page body为crudcrud.name固定为{lowerCamel(tableName)}Crudcrud.syncLocation=false- 列表 API 固定为
/api/entity/{table}/list?page=${page}&perPage=${perPage} - 新增按钮位于
headerToolbar[0] - 新增按钮使用
level=primary、icon=fa fa-plus、actionType=dialog - 新增和编辑表单提交到
post:/api/entity/{table}/save - 编辑按钮位于操作列第一位
- 删除按钮位于操作列第二位
- 删除按钮使用
className=text-danger、actionType=ajax、confirmText - 删除 API 固定为
/api/entity/{table}/delete - 页大小默认
20 footerToolbar固定包含statistics和pagination
Recipe: tree-crud-v1
适用范围:
- 自引用层级实体维护页
- 实体必须包含
PARENTID字段 - 覆盖树形列表、新增顶级节点、加子节点、编辑、删除
标准输出结构:
- 顶层
type=page body为crudcrud.name固定为{lowerCamel(tableName)}TreeCrudcrud.childrenColumnName=children- 列表 API 固定为
/api/entity/{table}/tree?parentKey=PARENTID&idKey={primaryKey}&perPage=2000 - 新增顶级按钮位于
headerToolbar[0] - 新增顶级按钮使用
level=primary、icon=fa fa-plus、actionType=dialog - 操作列按钮顺序固定为:加子项、编辑、删除
- 加子项表单必须隐藏写入
PARENTID=${primaryKey} - 编辑表单必须保留隐藏主键和
PARENTID - 删除按钮使用
className=text-danger、actionType=ajax、confirmText - 树数据端点返回
data.items层级数组,每个节点的子节点字段为children
字段映射:
string->input-textinteger/number->input-numberdate->input-datedatetime->input-datetimeboolean->switch- 主键不出现在新增表单,编辑表单最后追加
hidden
当前边界
本阶段只解决“AI 生成维护类 CRUD 页时走受控 recipe”。还未覆盖:
- 主子表页面
- 审批办理页面
- 看板、日历、图表、报表页
- 复杂字段分组
- 条件联动
- 引用选择器策略
- 权限按钮策略
这些类型必须作为新的 recipe 增量加入,不能让 Agent 直接绕过 blueprint 生成最终 amis JSON。
已落地门禁
page-recipe:校验 recipe 已注册、metadata 证据完整、payload 等于 blueprint 编译结果。typed-page-schema:校验组件和 actionType 来自 EIP4 注册表。amis-schema:校验最终 schema 符合 amis schema。local-smoke:本地发布后访问页面、实体、服务流和新增接口。render-plan:TEST草稿必须提供 Playwright 可消费的renderTests,包含 recipe、schemaUrl、previewUrl、预期根组件、CRUD 名、数据 API、列表列、页面动作和关键文本。
后续演进
- 增加
master-detail-v1、approval-task-v1recipe。 - 让设计器 overlay 保存也能记录对应 blueprint 或 template 来源。
- 在功能包中导出 blueprint,线上部署包继续导出编译后的 amis schema。
- Playwright E2E 消费
renderTests,执行真实浏览器渲染并回写运行证据。