Files
eip4-platform/docs/plans/2026-06-20-人走五环建新功能-实施计划.md

266 KiB
Raw Blame History

人走五环建新功能 · NocoBase 式(建模器 + 实时设计器)实施计划

For Claude: REQUIRED SUB-SKILL: 用 superpowers:executing-plans(或 superpowers:subagent-driven-development)逐任务执行本计划。每个 Task 都是 TDD 闭环(写失败测试 → 跑红 → 最小实现 → 跑绿 → 提交),不要跳过红/绿步骤,不要批量合并任务。

日期 2026-06-20 | 配套设计:2026-06-20-人走五环建新功能-NocoBase式-design.md(brainstorm 定型)| 方向:2026-06-19-EIP4开发平台-架构方向-design.md(D1-D7)| 路线图:2026-06-19-EIP4开发平台-落地执行路线图.md(M0-M8)。

本计划由「8 路代码核实 → 6 簇并行撰写 → 对抗评审」产出,所有文件路径/方法签名/行号均对真实代码核实。

Goal: 让实施人员在「设计中心」走完整五环(元数据→表→设计→实现→发布)建出一个新功能(NocoBase 式建模器 + 既有 amis-editor 实时设计器),并保留一个「⚡ AI 建功能」加速入口(外部 agent ①面,平台不内置生成 LLM)。

Architecture: 复用老引擎本就有的「元数据驱动低代码核」——建实体走 POST /api/meta/entity(真写 SYS_ENTITY/SYS_ENTITYATTRIBUTE + 真 CREATE 物理表);建页走 PageBlueprintCompiler 把 recipe 编译成已接 /api/flow/<TABLE>_* 的 amis 页,经 PageSchemaWriter.upsertStandard 单一写真相落标准层;微调走既有 edit-only 设计器(/editor.html?templateId=);发布 = 触发五条默认服务流 + 注册菜单 + 产 production 人审部署包。新建的只有 4 件:①建模器 UI、②recipe→页→标准层单步端点、③「+新建功能」编排壳、④「⚡AI建功能」入口接线(外加引用列后端补齐与发布编排)。

Tech Stack: 后端 Java 21 / Spring Boot(maven 多模块 eip4-platform,现代层 com.eip4.platform.* 单向依赖保真层 com.dsasp.*),PostgreSQL,JUnit5 + Mockito。前端 React + TypeScript + Vite(eip4-web,MPA:主应用 index.html + 设计器 editor.html),amis / amis-editor fork(amis-fork),Vitest + @testing-library/react。


A. 决策与 §7 三未知钉死(执行前必读)

设计文档 §7 列了 3 个「须在 plan 阶段钉死」的未知。本会话已逐一定论:

# 未知 钉死结论 对计划的影响
§7-1 建模器引用列(外键)UI 怎么做 DECISION-1(用户拍板):v1 就做完整引用列。 摸底发现引用列是「元数据 + DDL + 渲染」三层硬缺口,故本计划专列后端补齐:实体目录端点 + 列清单端点 + createEntity 接受 type:'reference'(find/create SYS_REFERENCE + 修 DDL 外键指向目标表)+ 建模器引用选择器 UI + recipe 渲染引用显名(非裸 id)。见第 1/2/4 节。
§7-2 recipe 仅 2 种 = v1 能建的功能类型窄 沿用设计 §5:v1 只覆盖简单 CRUD / 树类(maintenance-crud-v1 / tree-crud-v1)。 复杂功能(主子表/审批/组合)引导走老路或等路线图 M7。计划不扩 recipe。
§7-3 发布 online apply 断档,v1「发布」到哪一步算完 DECISION-2(用户拍板):live 可见 + 同时产 production 部署包。 「发布」= 对当前连接库直写(标准层页 + 触发五流 + 菜单注册)使本环境立即可用,且产一份 production 人审部署包(manifest+SQL+回滚)。生产真上线恒走既有人工部署+人审,v1 不自动执行生产 SQL。见第 3 节。④环 DoD = dev 环境端到端可演示 + 部署包就绪。

B. 关键架构事实校正(摸底揪出的「名实不符」,执行时务必照此)

设计文档若干表述与当前代码有出入,以下以代码为准(均经真实文件核实):

  1. 建实体不自动生成五流。 MetaController.createEntity(MetaController.java:70-148)全程不调 addDefaultFlowService;而 maintenance recipe 页恰恰调 /api/flow/<TABLE>_SEARCH|_ADD|_UPDATE|_DELETE。⇒ 五流必须被发布编排显式触发(第 3 节 Task 11 调 FlowServiceWithSynthesis.addDefaultFlowService,幂等)。设计文档「五流由 DefaultFlowHelper 默认生成、多数不用人管」只在被触发后成立。
  2. maintenance recipe 列表 API = /api/flow/<TABLE>_SEARCH(设计文档对、旧 blueprint 契约文档已漂移)。 当前编译器(PageBlueprintCompiler.java:50,commit 1ff0d33/5f32050/6c60383 house-style 对齐后)maintenance 读走 /api/flow/<TABLE>_SEARCH、写走 /api/flow/<TABLE>_ADD|_UPDATE|_DELETE;tree 读走 /api/entity/<TABLE>/tree、写走 flows。docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md(说 /api/entity/list)已过时,勿据它。
  3. 引用列是三层硬缺口(非「只差一个 UI 控件」)。 createEntity 无 FK 代码路径、saveAttr 永远写类型 token、appendColumnDdl 的 else 分支(MetaController.java:296-297)外键 REFERENCES <自表>(指向正在建的表本身,是 bug),且无「列实体目录 / 列字段」端点供选择器取数,且 applyColumnRender 不读 reference 元数据(裸 id)。DECISION-1 要求逐层补齐。
  4. 标准层单一写真相 + 净新页无运行时删除。 PUT /api/page/schema/{templateId}/standard → PageSchemaWriter.upsertStandard(M3a,commit d3b8846)已是唯一写函数;本计划新端点必须复用它,禁裸 INSERT。注意 upsertStandard 对已存在 template_id 是静默 UPSERT 覆盖(无 create-vs-update 区分),故净新页 templateId 由服务端生成 UUID(第 2 节 Task 7),调用方不得自选。净新标准行目前无运行时 DELETE/回滚端点(仅 overlay 删除 + 离线部署包 SQL),列为 follow-up。
  5. AI 部署包生成器不可跨模块复用。 platform-ai 依赖 platform-metadata(单向),故 platform-metadata 内的发布端点不能调 AiAgentService.createDeploymentPackage(强绑 AiTask/AiChangeSet)。第 3 节据此在 platform-metadata 内新建自包含 DeploymentPackageBuilder(产物与 AI 链同形);二者统一是明确 follow-up。
  6. serving / 构建两处已知坑(dev demo 不阻塞,但计划点名修)。 .env 默认 VITE_BACKEND_TARGET=http://localhost:8084 是死端口(活后端是 dev profile 的 8093,仅 .env.local 覆盖且 .env.local 被 gitignore);editor.html 用 /node_modules/*.css 绝对链接,生产 vite build 后 404(dev 靠 server.fs.allow 才通)。第 6 节 Task 22/23 修。
  7. D7 已被 2026-06-20 设计修订。 架构文档 D7 曾定「设计中心不挂 AI 入口」;2026-06-20 设计 §2 改为设计中心放两个入口([+新建功能] 人工 / [⚡AI建功能] ①面外部 agent 触发 auto-develop)。本计划承接修订版(第 5 节)。AI 入口产物恒 READY_FOR_HUMAN_REVIEW,人回设计器审/改/发。
  8. 跨节缝合点(执行时对齐,勿各写各的):
    • recipe id 全程统一为 maintenance-crud-v1 / tree-crud-v1(YAML 注册 id)。校正(评审揪出):AiFeatureDraftGenerator.normalizePageRecipe(AiFeatureDraftGenerator.java:284-294)只接受 maintenance-crud-v1/tree-crud-v1(= PageBlueprint.RECIPE_MAINTENANCE_CRUD/RECIPE_TREE_CRUD)或空串,传去--v1 名(maintenance-crud)会抛 Unsupported pageRecipe。故 POST /api/ai/features/auto-develop 的 pageRecipe、人工 compile、GET /api/ai/page-recipes 三处都用 *-v1 形,第 5 节 AI 表单不要做任何 *-v1→去-v1 映射。
    • 第 2 节 RecipePageComposer 依赖第 1 节的「实体属性读取」。第 1 节须把列清单逻辑暴露成可复用 service bean(非仅 controller 内联),第 2 节的 EntityAttributeReader 缝接它。
    • RecipeOption 形状:前端统一 {id, label}(第 4/5 节对齐,勿一处 name 一处 label)。
    • 前端 api 解包:http 返回 AxiosResponse,后端统一 {status,data} 信封,api 模块 unwrap 到 .data.data(第 4 节约定,全前端遵循)。

B.9 评审收口修正(4-lens 对抗评审产出,这些覆盖下文对应 Task 的文字/代码,执行时以此为准)

本计划经 4 路对抗评审(跨节一致性 / 代码正确性 / 完备性 / 红线+TDD)逐条核到真实代码。以下 11 条是评审揪出的 blocker/major/minor 修正;下文各 Task 已就地修掉的标「✅已就地修」,结构性的以本节为权威。

  1. ✅已就地修 · recipe id 全程 *-v1(blocker,4 lens 命中):normalizePageRecipe 只接受 maintenance-crud-v1/tree-crud-v1,去-v1 名会抛异常。§B.8、第 5 节 ai.ts/AiFeatureForm/Task 24 curl 已统一为 *-v1,不要做任何归一映射。
  2. listRecipes 改静态常量(非 async)(blocker,覆盖第 4 节 Task 14 recipe.ts + 第 5 节 Task 19/20 消费):真实 GET /api/ai/page-recipes 返回裸数组 List<PageRecipeDefinition>{recipe,schemaVersion,title,fieldMappings,gates}(无 {status,data} 信封、无 id/name,AiAgentController.java:248)。v1 只 2 recipe(YAGNI),故 recipe.ts 改为:
    export interface RecipeOption { id: string; label: string }
    // v1 固定两 recipe,无需调 /api/ai/page-recipes(其裸数组形状与本前端契约不符)。
    export function listRecipes(): RecipeOption[] {
      return [
        { id: 'maintenance-crud-v1', label: '维护型 CRUD' },
        { id: 'tree-crud-v1', label: '树形 CRUD' },
      ];
    }
    
    第 5 节 NewFeatureShell 的 const RECIPES = listRecipes()(同步数组)与 RECIPES.map(r => r.label) 因此成立;统一字段名 label(删除任何 {id,name}/r.name),两处单测 mock 同改为 {id,label}。
  3. 抽 EntityAttributesService bean,删假表 SQL(blocker,覆盖第 1 节 Task 2 + 第 2 节 Task 7):真实表 SYS_ENTITYATTRIBUTE(无 table_name 列,列名 columnname/displayname/referenceid/ismandatory/entitydisplayseq/isentitydisplay,靠 entityid ⋈ SYS_ENTITY 过滤;引用目标表名须 DataDicService.getReferenceEntityTableName(REFERENCEID) 反解)。第 1 节 Task 2 增子任务:把列清单读取逻辑抽成 @Component EntityAttributesService:
    @Component
    public class EntityAttributesService {
      public record Column(String column, String display, String type, boolean mandatory, String referenceTable) {}
      public record Result(String tablename, String displayColumn, java.util.List<Column> columns) {}
      private final DataDicService dataDicService;
      private final JdbcTemplate jdbcTemplate;
      public EntityAttributesService(DataDicService d, JdbcTemplate j){ this.dataDicService=d; this.jdbcTemplate=j; }
      public Result read(String table){
        // SELECT A.COLUMNNAME,A.DISPLAYNAME,A.REFERENCEID,A.ISMANDATORY,A.ISENTITYDISPLAY,A.ENTITYDISPLAYSEQ
        //   FROM SYS_ENTITYATTRIBUTE A JOIN SYS_ENTITY E ON A.ENTITYID=E.SYS_ENTITY_ID
        //  WHERE E.TABLENAME=? ORDER BY A.ENTITYDISPLAYSEQ
        // 对每行:REFERENCEID 是 36 位 uuid → type='reference'、referenceTable=getReferenceEntityTableName(refId);
        //         否则 type=tokenToApiType(REFERENCEID)(NVARCHAR→string/INTEGER→integer/DECIMAL→number/DATE→date/TIME→datetime/BOOLEAN→boolean)。
        //         displayColumn = ISENTITYDISPLAY=1 的列 → 否则首个非主键非审计 NVARCHAR → 否则主键。
      }
    }
    
    MetaController.attributes()(Task 2)与第 2 节 EntityAttributeReader 默认实现(已就地改为 DelegatingEntityAttributeReader)都委托它,保证同源同结果。
  4. 建模器 UI 必须在编排流里可达(blocker,覆盖第 4 节 Task 15/18 + 第 5 节 Task 19 + 第 6 节 Task 24):ModelerPage(/modeler) 当前无任何入口跳转,且 NewFeatureShell 的「实体」步只列已有实体——导致引用列建模器(建新实体+字段表+引用选择器,第①环「元数据→表」)走不到,与设计 §2 冲突。修:在 NewFeatureShell 的实体步加一枚 [+ 新建实体] 按钮,打开 Task 16/17 的建实体 Dialog(复用 FieldTable/ReferencePicker),建成后用返回的 {entityId,tablename} 回填 selectedEntity 进入下一步;并在设计中心或建模器列表加一个跳 /modeler 的入口。Task 24 step(2) 据此核验「从 +新建功能 → +新建实体 建出含引用列的新实体」。
  5. 控制器构造器演化一次定稿(major,覆盖第 2 节 Task 7 + 第 3 节 Task 10-13):DesignFeatureController 在 Task 7 创建、Task 10-13 逐步追加依赖(DefaultFlowPreviewService/PublishOrchestrator/MenuRegistrar/DeploymentPackageBuilder)。纪律:①每追加一个生产构造器依赖,同步更新包级测试构造器(新字段置 null 或注入 mock),保证 Task 7 的 DesignFeatureControllerTest(3 参测试 ctor)始终编译;②PublishOrchestrator 一开始就按最终 4 参签名(FlowServiceWithSynthesis, MenuRegistrar, DeploymentPackageBuilder, DefaultFlowPreviewService)写,删掉 Task 11.3 的 3 参中间态;③DefaultFlowPreviewService 是共享 @Service 单例,被控制器(GET /flows)与 PublishOrchestrator 双注入是预期(非循环依赖);④Task 13 末尾重跑 DesignFeatureControllerTest。
  6. ✅已就地修 · 部署包 SQL 对齐真实列(major):sys_page_schema 真实列 (template_id,name,schema_json,schema_etag,version,update_time)、ON CONFLICT(template_id)(无 layer/updateby/updatetime)。DeploymentPackageBuilderTest 加断言 sqlStatements 不含 'layer' 防回归。
  7. refTargets/DESCRIPTION 收口到 Task 3 单块(major,覆盖第 1 节 Task 3/4/5):Task 3「整段替换业务列循环」的代码块自带 Map<String,String> refTargets = new HashMap<>(); 声明,并直接写出最终的中性 DESCRIPTION 行(如 entityMap.put("DESCRIPTION", resolveDescription(req))),使该块自洽编译;Task 4 只改 createTableDdl(table, created, refTargets) 调用点、不再碰声明;Task 5 不再二次改第 88 行(其逻辑并入 Task 3)。执行顺序仍 T3→T4→T5。
  8. 前端 getProfile mock 补全 UserProfile 形状(minor,覆盖第 5 节 Task 18/19/20/21 单测):token.ts 的 UserProfile.roles: string[] 非可选,npm run build(tsc 严格) 会因 mock 缺字段报错。所有 mock 统一为 { userId:'ADMIN', account:'admin', name:'x', roles:[] }(与 Task 15 一致),或 as UserProfile。
  9. requireAdmin/currentUserId 来源统一(minor):以 PageSchemaController.java:515-540 为唯一逐字复制源(DesignFeatureController 在 Task 7 创建时即从它复制),删除第 3 节前言「复制自 AdminWriteController:665-690」的二次来源标注,避免实现者拿到细节不同的版本。
  10. ai.ts autoDevelop 默认值不被 undefined 覆盖(minor,第 5 节 Task 20):改为 { ...body, baseUrl: body.baseUrl ?? window.location.origin, generateDeploymentPackage: body.generateDeploymentPackage ?? true }(默认值放后、用 ??)。
  11. listApi 字段勿被误用(minor,第 4 节 Task 14):createEntity 返回的 listApi='/api/entity/<TABLE>/list' 是引擎遗留返回,recipe 页不消费它(recipe 列表走 /api/flow/<TABLE>_SEARCH,见 §B.2)。在 CreateEntityResult.listApi 注释里标注,避免建模器/编排壳拿它当页面 api。

Task 24 验收补注:「刷新左侧菜单→新功能目录下出现节点」仅对 admin 成立(§F 已知普通用户可见性需 set-menus,列为 follow-up),演示时如被问及照此说明。

C. 红线(每个 Task 都不得触碰)

  • 发布恒人审:publish 仅对当前连接库 live-apply,绝不自动执行生产 SQL;生产上线恒走人工部署包 + 人审(requiresHumanApproval 恒 true)。
  • AI 入口产物恒 READY_FOR_HUMAN_REVIEW:①面只产草稿,人回设计器审/改/发,永不自动发布。
  • 标准层写恒走 PageSchemaWriter.upsertStandard 单一真相(M3a 已收口),不得旁路裸 INSERT sys_page_schema。
  • 平台进程内不内置生成 LLM:仅 HttpAiLlmRepairClient repair 钩子(@ConditionalOnProperty 默认关,只修不生成)。NL→结构化 spec 的魔法在平台外(外部 coding-agent 经 CLI)。

D. 任务总览与依赖时序

24 个 Task 分 6 节。节内严格顺序(TDD),节间依赖如下:

后端主轨(数据依赖,建议顺序落地):
  第1节 元数据/引用列(T1-5) ──▶ 第2节 recipe→页 compile(T6-9) ──▶ 第3节 发布编排(T10-13)
        │(实体属性 service bean)        │(DesignFeatureController/api/design)
        ▼                               ▼
前端主轨(Section1 契约冻结后可与后端并行,单测用 mock):
  第4节 api模块+建模器UI(T14-17) ──▶ 第5节 编排壳+AI入口(T18-21)
横向(随时可起 / 收尾):
  第6节 T22(serving配置) T23(editor.html CSS) 可尽早;T24(端到端验收) 必须最后

建议执行批次:

  • 批次 0(解阻塞,尽早):T22(把 dev 后端口收敛到 8093,使 fresh checkout 可跑)、T23(修 editor.html 生产 CSS)。
  • 批次 1(后端基座):T1→T2→T3→T4→T5(元数据/引用列)→ T6→T7→T8→T9(recipe compile)→ T10→T11→T12→T13(发布编排)。第 1 节契约一旦冻结即可并行起前端。
  • 批次 2(前端,与批次 1 并行):T14→T15→T16→T17(api+建模器,mock 后端单测)→ T18→T19→T20→T21(编排壳+AI 入口)。第 5 节 PR 须排在第 4 节之后。
  • 批次 3(合龙):T24 端到端 dev 演示验收(需 env + admin/111111 登录),用 @superpowers:verification-before-completion 心法——证据先于「完成」断言。

各节对外契约(缝接点速查):

  • 第 1 节:GET /api/meta/entities、GET /api/meta/entity/{table}/attributes、POST /api/meta/entity(扩展 type:'reference')。
  • 第 2 节:POST /api/design/recipe/compile(服务端生成 templateId)、RecipePageComposer、PageBlueprintField(+referenceTable/displayColumn)。
  • 第 3 节:GET /api/design/flows、POST /api/design/publish、MenuRegistrar、DeploymentPackageBuilder。
  • 第 4 节:src/api/{meta,recipe,publish}.ts、ModelerPage(/modeler)、src/setupTests.ts。
  • 第 5 节:NewFeatureShell(/new-feature)、AiFeatureForm(/ai-feature)、src/api/ai.ts、extractPageSchemaTemplateId。
  • 第 6 节:dev serving 收敛、editor.html 生产样式、端到端验收脚本。

第 1 节 · 元数据/引用列后端(建模器后端 + DECISION-1 完整引用列)

范围:建模器需要的两个只读元数据端点(实体目录 / 列清单),以及 DECISION-1 要求的「完整外键引用列」后端:POST /api/meta/entity 接受 type:'reference' 属性、find-or-create SYS_REFERENCE 行、并修掉 DDL 把外键指向目标表(当前 bug 指向自表)。最后做一处文案卫生(去掉硬编码的 "AI 闭环创建" 描述)。

全部任务都在模块 platform-metadata,遵循 TDD:先写失败测试 → 跑出红 → 最小实现 → 跑出绿 → 提交。控制器单测一律用 Mockito mock 掉 JdbcTemplate / DataDicService / POJOCRUDService,不启 Spring(与现有 MenuControllerTest / AdminWriteControllerTest 同法)。

关键既有事实(已读真实代码,工程师可直接信赖):

  • MetaController 构造器签名(第55-67行):MetaController(DataDicService dataDicService, POJOCRUDService pojoCRUDService, JdbcTemplate jdbcTemplate, IndexEnhancer indexEnhancer, PoInfoCacheInvalidator cacheInvalidator, BacklogIndexScriptGenerator backlogIndexScriptGenerator)。
  • DataDicService 接口上已有 String getReferenceEntityTableName(String referenceId)(反解 SYS_REFERENCE_ID→目标表名)和 SYS_Entity getSYSEntityByTableName(String tableName)(仅 ISACTIVE=1)。
  • SYS_REFERENCE 表列(bootstrap-sys.sql 第116-128行):sys_reference_id(char36,PK) / entityid(char36) / name(varchar100) / description(varchar255) / isactive(int default 1) / createtime,updatetime(bigint) / createby,updateby(char36) / version(int)。find-or-create 直接 INSERT 这些列即可(参照 ParitySeeder.createReference 第190-199行已验证写法)。
  • DDL 生成的 bug 在 appendColumnDdl 第296-297行 else 分支:sql.append(col).append(" character(36) REFERENCES ").append(table) —— 这里 table 是正在建的表本身,外键自指,错误。

Task 1 — GET /api/meta/entities 实体目录端点(引用列选择器的下拉数据源)

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java(新增一个 @GetMapping("/api/meta/entities"),插在第148行 createEntity 方法 } 之后、第150行 dropEntity 之前)
  • Create test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaCatalogControllerTest.java

Step 1.1 — 写失败测试

新建测试文件,内容(用 mock JdbcTemplate,按 SQL 子串桩数据;其余构造器参数都 mock):

package com.eip4.platform.metadata.web;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.ArgumentMatchers.contains;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.core.RowMapper;

import com.dsasp.server.common.dataDic.service.DataDicService;
import com.dsasp.server.common.dataDic.service.POJOCRUDService;
import com.eip4.platform.metadata.perf.BacklogIndexScriptGenerator;
import com.eip4.platform.metadata.perf.IndexEnhancer;
import com.eip4.platform.metadata.perf.PoInfoCacheInvalidator;

@SuppressWarnings({"unchecked", "rawtypes"})
class MetaCatalogControllerTest {

    private MetaController newController(JdbcTemplate jdbc) {
        return new MetaController(
                mock(DataDicService.class),
                mock(POJOCRUDService.class),
                jdbc,
                mock(IndexEnhancer.class),
                mock(PoInfoCacheInvalidator.class),
                mock(BacklogIndexScriptGenerator.class));
    }

    @Test
    @DisplayName("entities() 返回 ISACTIVE=1 AND ISVIEW=0 的实体目录 {entityId,tablename,name}")
    void entitiesReturnsCatalog() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        Map<String, Object> row = new LinkedHashMap<>();
        row.put("entityId", "e-1");
        row.put("tablename", "EIP4_ORDER");
        row.put("name", "订单");
        when(jdbc.query(contains("FROM SYS_ENTITY"), (RowMapper) org.mockito.ArgumentMatchers.any()))
                .thenReturn(List.of(row));

        Map<String, Object> resp = newController(jdbc).entities();

        assertEquals(0, resp.get("status"));
        List<Map<String, Object>> data = (List<Map<String, Object>>) resp.get("data");
        assertEquals(1, data.size());
        assertEquals("EIP4_ORDER", data.get(0).get("tablename"));
        assertEquals("订单", data.get(0).get("name"));
        assertEquals("e-1", data.get(0).get("entityId"));
    }

    @Test
    @DisplayName("entities() 的 SQL 过滤 ISACTIVE=1 AND ISVIEW=0")
    void entitiesSqlFiltersActiveNonView() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        final String[] captured = new String[1];
        when(jdbc.query(anyString(), (RowMapper) org.mockito.ArgumentMatchers.any()))
                .thenAnswer(inv -> { captured[0] = inv.getArgument(0); return List.of(); });

        newController(jdbc).entities();

        assertTrue(captured[0].toUpperCase().contains("ISACTIVE=1")
                || captured[0].toUpperCase().contains("ISACTIVE = 1"));
        assertTrue(captured[0].toUpperCase().contains("ISVIEW=0")
                || captured[0].toUpperCase().contains("ISVIEW = 0"));
    }
}

Step 1.2 — 跑测试,预期编译失败(方法不存在)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest

预期 FAIL(编译错误):cannot find symbol: method entities()(MetaController 还没有 entities())。

Step 1.3 — 最小实现

在 MetaController.java 第148行(createEntity 方法的结束 })之后、第150行 @Operation(summary = "删除实体... 之前插入:

    @Operation(summary = "实体目录:列出 ISACTIVE=1 且 ISVIEW=0 的实体(供引用列选择器)")
    @GetMapping("/api/meta/entities")
    public Map<String, Object> entities() {
        List<Map<String, Object>> data = jdbcTemplate.query(
                "SELECT SYS_ENTITY_ID, TABLENAME, NAME FROM SYS_ENTITY "
                        + "WHERE ISACTIVE=1 AND ISVIEW=0 ORDER BY TABLENAME",
                (rs, i) -> {
                    Map<String, Object> m = new LinkedHashMap<>();
                    m.put("entityId", rs.getString("SYS_ENTITY_ID"));
                    m.put("tablename", rs.getString("TABLENAME"));
                    m.put("name", rs.getString("NAME"));
                    return m;
                });
        Map<String, Object> resp = new LinkedHashMap<>();
        resp.put("status", 0);
        resp.put("data", data);
        return resp;
    }

同时在顶部 import 区(第11行 import org.springframework.web.bind.annotation.DeleteMapping; 附近)补一行:

import org.springframework.web.bind.annotation.GetMapping;

Step 1.4 — 跑测试,预期 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest

预期:BUILD SUCCESS,2 个用例绿。

Step 1.5 — 提交

git -C /Users/zhengwr/workspace/eip3/eip4-platform add platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaCatalogControllerTest.java
git -C /Users/zhengwr/workspace/eip3/eip4-platform commit -m "feat(meta): GET /api/meta/entities 实体目录端点(引用列选择器数据源)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 2 — GET /api/meta/entity/{table}/attributes 列清单 + displayColumn + 引用列反解

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java(在 Task 1 新增的 entities() 之后再加一个 @GetMapping("/api/meta/entity/{table}/attributes");并加一个私有静态 refToApiType 帮助方法)
  • Modify test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaCatalogControllerTest.java

契约:返回 {status:0,data:{tablename, displayColumn, columns:[{column,display,type,referenceTable?}]}}。type 是 API 语义类型(string|integer|number|date|datetime|boolean|reference),由列的 REFERENCEID 反向映射:NVARCHAR/CODE→string、INTEGER/ENUMERATE→integer、DECIMAL/MONEY→number、DATE→date、TIME→datetime、BOOLEAN→boolean、CHAR→string、其余(36位 uuid 引用)→reference(此时 referenceTable = getReferenceEntityTableName(REFERENCEID))。displayColumn 启发式:优先 ISENTITYDISPLAY=1 的列 → 否则首个「非主键、非审计、type==string」的列 → 否则主键列。

Step 2.1 — 写失败测试(追加到 MetaCatalogControllerTest)

在类内追加(先在 import 区补 import com.dsasp.server.common.dataDic.service.DataDicService; —— 已在 Task 1 引入):

    private MetaController newController(JdbcTemplate jdbc, DataDicService dataDic) {
        return new MetaController(
                dataDic,
                mock(POJOCRUDService.class),
                jdbc,
                mock(IndexEnhancer.class),
                mock(PoInfoCacheInvalidator.class),
                mock(BacklogIndexScriptGenerator.class));
    }

    private static Map<String, Object> attrRow(String col, String display, String refId,
                                               int isKey, int isEntityDisplay) {
        Map<String, Object> m = new LinkedHashMap<>();
        m.put("COLUMNNAME", col);
        m.put("DISPLAYNAME", display);
        m.put("REFERENCEID", refId);
        m.put("ISKEY", isKey);
        m.put("ISENTITYDISPLAY", isEntityDisplay);
        return m;
    }

    @Test
    @DisplayName("attributes() 映射类型 + 引用列反解 referenceTable + 推断 displayColumn")
    void attributesMapsTypesAndResolvesReference() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        DataDicService dataDic = mock(DataDicService.class);
        String refUuid = "11111111-1111-1111-1111-111111111111"; // 36 位
        when(jdbc.query(contains("SYS_ENTITYATTRIBUTE"), (RowMapper) org.mockito.ArgumentMatchers.any()))
                .thenReturn(List.of(
                        attrRow("EIP4_ORDER_ID", "主键", "CHAR", 1, 0),
                        attrRow("TITLE", "标题", "NVARCHAR", 0, 0),
                        attrRow("QTY", "数量", "INTEGER", 0, 0),
                        attrRow("CUSTOMERID", "客户", refUuid, 0, 0)));
        when(dataDic.getReferenceEntityTableName(refUuid)).thenReturn("EIP4_CUSTOMER");

        Map<String, Object> resp = newController(jdbc, dataDic).attributes("eip4_order");

        assertEquals(0, resp.get("status"));
        Map<String, Object> data = (Map<String, Object>) resp.get("data");
        assertEquals("EIP4_ORDER", data.get("tablename"));
        // 无 ISENTITYDISPLAY → 首个非主键非审计的 string 列 = TITLE
        assertEquals("TITLE", data.get("displayColumn"));
        List<Map<String, Object>> cols = (List<Map<String, Object>>) data.get("columns");
        Map<String, Object> qty = cols.stream().filter(c -> "QTY".equals(c.get("column"))).findFirst().get();
        assertEquals("integer", qty.get("type"));
        Map<String, Object> cust = cols.stream().filter(c -> "CUSTOMERID".equals(c.get("column"))).findFirst().get();
        assertEquals("reference", cust.get("type"));
        assertEquals("EIP4_CUSTOMER", cust.get("referenceTable"));
        Map<String, Object> title = cols.stream().filter(c -> "TITLE".equals(c.get("column"))).findFirst().get();
        assertEquals("string", title.get("type"));
        assertTrue(title.get("referenceTable") == null);
    }

Step 2.2 — 跑测试,预期编译失败

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest

预期 FAIL:cannot find symbol: method attributes(java.lang.String)。

Step 2.3 — 最小实现

在 MetaController.java 中 entities() 方法之后插入端点 + 类型映射 helper:

    @Operation(summary = "列出某表的列(类型/显示名)并标出引用列目标表与显示列(建模器/recipe 用)")
    @GetMapping("/api/meta/entity/{table}/attributes")
    public Map<String, Object> attributes(@PathVariable String table) {
        String t = table.toUpperCase();
        List<Map<String, Object>> raw = jdbcTemplate.query(
                "SELECT A.COLUMNNAME, A.DISPLAYNAME, A.REFERENCEID, A.ISKEY, A.ISENTITYDISPLAY "
                        + "FROM SYS_ENTITYATTRIBUTE A INNER JOIN SYS_ENTITY E ON A.ENTITYID=E.SYS_ENTITY_ID "
                        + "WHERE E.TABLENAME=? AND E.ISACTIVE=1 AND A.ISACTIVE=1 "
                        + "ORDER BY A.ENTITYDISPLAYSEQ ASC",
                (rs, i) -> {
                    Map<String, Object> m = new LinkedHashMap<>();
                    m.put("COLUMNNAME", rs.getString("COLUMNNAME"));
                    m.put("DISPLAYNAME", rs.getString("DISPLAYNAME"));
                    m.put("REFERENCEID", rs.getString("REFERENCEID"));
                    m.put("ISKEY", rs.getInt("ISKEY"));
                    m.put("ISENTITYDISPLAY", rs.getInt("ISENTITYDISPLAY"));
                    return m;
                },
                t);

        List<Map<String, Object>> columns = new ArrayList<>();
        String displayByFlag = null;
        String displayByString = null;
        String keyColumn = null;
        for (Map<String, Object> r : raw) {
            String col = (String) r.get("COLUMNNAME");
            String refId = (String) r.get("REFERENCEID");
            boolean isKey = asInt(r.get("ISKEY")) == 1;
            boolean isEntityDisplay = asInt(r.get("ISENTITYDISPLAY")) == 1;
            String apiType = refToApiType(refId);

            Map<String, Object> c = new LinkedHashMap<>();
            c.put("column", col);
            c.put("display", r.get("DISPLAYNAME"));
            c.put("type", apiType);
            if ("reference".equals(apiType)) {
                c.put("referenceTable", dataDicService.getReferenceEntityTableName(refId));
            }
            columns.add(c);

            if (isKey) {
                keyColumn = col;
            }
            if (isEntityDisplay && displayByFlag == null) {
                displayByFlag = col;
            }
            if (displayByString == null && !isKey && "string".equals(apiType) && !isAuditColumn(col)) {
                displayByString = col;
            }
        }
        String displayColumn = displayByFlag != null ? displayByFlag
                : (displayByString != null ? displayByString : keyColumn);

        Map<String, Object> data = new LinkedHashMap<>();
        data.put("tablename", t);
        data.put("displayColumn", displayColumn);
        data.put("columns", columns);
        Map<String, Object> resp = new LinkedHashMap<>();
        resp.put("status", 0);
        resp.put("data", data);
        return resp;
    }

    /** REFERENCEID 反映射成 API 语义类型;36 位 uuid(外键引用) → reference。 */
    private static String refToApiType(String referenceId) {
        if (referenceId == null) {
            return "string";
        }
        return switch (referenceId) {
            case "NVARCHAR", "CODE", "CHAR" -> "string";
            case "INTEGER", "ENUMERATE" -> "integer";
            case "DECIMAL", "MONEY" -> "number";
            case "DATE" -> "date";
            case "TIME" -> "datetime";
            case "BOOLEAN" -> "boolean";
            default -> referenceId.length() >= 32 ? "reference" : "string";
        };
    }

    private static boolean isAuditColumn(String col) {
        return "VERSION".equals(col) || "CREATETIME".equals(col) || "UPDATETIME".equals(col)
                || "CREATEBY".equals(col) || "UPDATEBY".equals(col) || "ISACTIVE".equals(col)
                || "ORGID".equals(col) || "DEPARTID".equals(col);
    }

    private static int asInt(Object v) {
        if (v instanceof Number n) {
            return n.intValue();
        }
        if (v != null) {
            try {
                return Integer.parseInt(v.toString());
            } catch (NumberFormatException ignore) {
                return 0;
            }
        }
        return 0;
    }

并确认顶部已有 import org.springframework.web.bind.annotation.PathVariable;(第12行已存在)和 import java.util.ArrayList;(第3行已存在)。

Step 2.4 — 跑测试,预期 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest

预期:3 个用例全绿。

Step 2.5 — 提交

git -C /Users/zhengwr/workspace/eip3/eip4-platform add platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaCatalogControllerTest.java
git -C /Users/zhengwr/workspace/eip3/eip4-platform commit -m "feat(meta): GET /api/meta/entity/{table}/attributes 列清单+displayColumn+引用列反解

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 3 — POST /api/meta/entity 接受 type:'reference':find-or-create SYS_REFERENCE 并写列 REFERENCEID

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java(业务列循环第108-126行;新增私有 findOrCreateReference)
  • Create test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaControllerReferenceTest.java

设计:reference 列在 SYS_ENTITYATTRIBUTE.REFERENCEID 存的是一个 36 位 SYS_REFERENCE_ID(uuid),该 SYS_REFERENCE 行的 ENTITYID 指向目标实体。findOrCreateReference 幂等:先 SELECT SYS_REFERENCE_ID FROM SYS_REFERENCE WHERE ENTITYID=? AND ISACTIVE=1 命中则复用,否则 INSERT 一行(列与 ParitySeeder.createReference 一致)。helper 复用 jdbcTemplate(与既有写法同法)。saveAttr 已支持把任意字符串作为第5参 ref 写进 REFERENCEID,因此 reference 列 = saveAttr(..., col, display, <referenceId-uuid>, 36, mandatory, false, ctx)。

Step 3.1 — 写失败测试

这个测试聚焦 findOrCreateReference 的幂等与 INSERT 语义(纯 mock JdbcTemplate),不跑整条 createEntity(那条依赖 pojoCRUDService 模板克隆,难在单测里全 mock):

package com.eip4.platform.metadata.web;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.ArgumentMatchers.contains;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

import java.util.List;
import java.util.Properties;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.jdbc.core.JdbcTemplate;

import com.dsasp.server.common.dataDic.service.DataDicService;
import com.dsasp.server.common.dataDic.service.POJOCRUDService;
import com.eip4.platform.metadata.perf.BacklogIndexScriptGenerator;
import com.eip4.platform.metadata.perf.IndexEnhancer;
import com.eip4.platform.metadata.perf.PoInfoCacheInvalidator;

@SuppressWarnings({"unchecked", "rawtypes"})
class MetaControllerReferenceTest {

    private MetaController newController(JdbcTemplate jdbc) {
        return new MetaController(
                mock(DataDicService.class),
                mock(POJOCRUDService.class),
                jdbc,
                mock(IndexEnhancer.class),
                mock(PoInfoCacheInvalidator.class),
                mock(BacklogIndexScriptGenerator.class));
    }

    @Test
    @DisplayName("findOrCreateReference 命中既有 SYS_REFERENCE → 复用,不再 INSERT")
    void findOrCreateReuses() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        // 目标实体 id
        when(jdbc.queryForObject(contains("FROM SYS_ENTITY"), eq(String.class), anyString()))
                .thenReturn("target-entity-id");
        // 既有引用行
        when(jdbc.queryForList(contains("FROM SYS_REFERENCE"), eq(String.class), anyString()))
                .thenReturn(List.of("existing-ref-uuid"));

        String refId = newController(jdbc).findOrCreateReference("EIP4_CUSTOMER", "CUSTOMERID", new Properties());

        assertEquals("existing-ref-uuid", refId);
        verify(jdbc, never()).update(contains("INSERT INTO SYS_REFERENCE"),
                (Object[]) any());
    }

    @Test
    @DisplayName("findOrCreateReference 无既有行 → INSERT 一行并返回新 uuid(36位,ENTITYID=目标实体)")
    void findOrCreateInserts() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        when(jdbc.queryForObject(contains("FROM SYS_ENTITY"), eq(String.class), anyString()))
                .thenReturn("target-entity-id");
        when(jdbc.queryForList(contains("FROM SYS_REFERENCE"), eq(String.class), anyString()))
                .thenReturn(List.of());

        String refId = newController(jdbc).findOrCreateReference("EIP4_CUSTOMER", "CUSTOMERID", new Properties());

        assertNotNull(refId);
        assertEquals(36, refId.length());
        verify(jdbc).update(contains("INSERT INTO SYS_REFERENCE"),
                eq(refId), eq("target-entity-id"), anyString(), anyString());
    }
}

Step 3.2 — 跑测试,预期编译失败

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest

预期 FAIL:cannot find symbol: method findOrCreateReference(...)。

Step 3.3 — 最小实现:新增 helper + 业务列循环识别 reference

在 MetaController.java 顶部 import 区补:

import java.util.UUID;

新增 helper(放在 saveAttr 方法第247行 } 之后):

    /**
     * 为引用列 find-or-create 一行 SYS_REFERENCE(ENTITYID=目标实体),返回其 36 位 SYS_REFERENCE_ID。
     * 幂等:命中既有(同目标实体且 ISACTIVE=1)则复用。列与 ParitySeeder.createReference 一致。
     */
    String findOrCreateReference(String targetTable, String column, Properties ctx) {
        String targetEntityId = jdbcTemplate.queryForObject(
                "SELECT SYS_ENTITY_ID FROM SYS_ENTITY WHERE ISACTIVE=1 AND TABLENAME=?",
                String.class, targetTable.toUpperCase());
        List<String> existing = jdbcTemplate.queryForList(
                "SELECT SYS_REFERENCE_ID FROM SYS_REFERENCE WHERE ISACTIVE=1 AND ENTITYID=?",
                String.class, targetEntityId);
        if (!existing.isEmpty()) {
            return existing.get(0);
        }
        String refId = UUID.randomUUID().toString();
        jdbcTemplate.update(
                "INSERT INTO SYS_REFERENCE"
                        + "(SYS_REFERENCE_ID,ENTITYID,NAME,DESCRIPTION,ISACTIVE,CREATETIME,UPDATETIME,CREATEBY,UPDATEBY,VERSION)"
                        + " VALUES (?,?,?,?,1,0,0,'ADMIN','ADMIN',0)",
                refId, targetEntityId, column + "->" + targetTable.toUpperCase(), "设计中心创建");
        return refId;
    }

注意 queryForObject 在目标表不存在时会抛 EmptyResultDataAccessException。业务列循环里调用前先用 getSYSEntityByTableName 校验存在性(见下),并把不存在当作用户错误返回 status:1。

改业务列循环(第108-126行整段替换):

        // 业务列
        @SuppressWarnings("unchecked")
        List<Map<String, Object>> attrs = (List<Map<String, Object>>) req.get("attributes");
        if (attrs != null) {
            for (Map<String, Object> a : attrs) {
                String col = String.valueOf(a.get("column")).toUpperCase();
                String type = String.valueOf(a.getOrDefault("type", "string"));
                boolean mandatory = Boolean.TRUE.equals(a.get("mandatory"));
                String display = String.valueOf(a.getOrDefault("display", col));

                if ("reference".equals(type)) {
                    String refTable = a.get("referenceTable") == null
                            ? null : String.valueOf(a.get("referenceTable")).toUpperCase();
                    if (refTable == null || dataDicService.getSYSEntityByTableName(refTable) == null) {
                        return err("引用目标实体不存在: " + refTable);
                    }
                    String referenceId = findOrCreateReference(refTable, col, ctx);
                    created.add(saveAttr(attrTpl, entityId, col, display, referenceId, 36, mandatory, false, ctx));
                    refTargets.put(col, refTable);
                    continue;
                }

                String ref = switch (type) {
                    case "integer" -> "INTEGER";
                    case "number" -> "DECIMAL";
                    case "date" -> "DATE";
                    case "datetime" -> "TIME";
                    case "boolean" -> "BOOLEAN";
                    default -> "NVARCHAR";
                };
                Integer len = "NVARCHAR".equals(ref)
                        ? (a.get("length") instanceof Number n ? n.intValue() : 100) : null;
                created.add(saveAttr(attrTpl, entityId, col, display, ref, len, mandatory, false, ctx));
            }
        }

refTargets 是新的局部 Map<String,String>,在 Task 4 引入并传入 DDL。这里先声明它(在 created 列表声明附近,即第95行 List<GeneralPOJO> created = new ArrayList<>(); 下面加一行 —— 实际加入放在 Task 4 实现,本 Task 的代码块假定它已存在;为让本 Task 单独编译,先在第95行下临时加:Map<String, String> refTargets = new HashMap<>();,Task 4 会复用同一行,不再重复加)。

Step 3.4 — 跑测试,预期 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest

预期:2 个用例绿。再跑一次全 platform-metadata 编译保障没破坏 createEntity:

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test-compile

预期:BUILD SUCCESS。

Step 3.5 — 提交

git -C /Users/zhengwr/workspace/eip3/eip4-platform add platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaControllerReferenceTest.java
git -C /Users/zhengwr/workspace/eip3/eip4-platform commit -m "feat(meta): POST /api/meta/entity 支持 reference 列(find-or-create SYS_REFERENCE 指向目标实体)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 4 — 修 DDL 外键:把 REFERENCES <self> 改成 REFERENCES <TARGET_TABLE>

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java(createTableDdl 第249-268行、appendColumnDdl 第270-318行加 refTargets 形参;createEntity 第130行调用点)
  • Modify test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaControllerDdlTest.java

Step 4.1 — 改既有测试 + 加引用列用例(先让旧测试编译失败、新断言失败)

把 MetaControllerDdlTest.java 全文替换为(旧两参调用 → 三参;新增 reference 用例):

package com.eip4.platform.metadata.web;

import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;

import java.util.List;
import java.util.Map;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import com.dsasp.server.common.dataDic.bean.GeneralPOJO;

class MetaControllerDdlTest {

    @Test
    @DisplayName("运行态实体 DDL 按旧引擎类型规则生成主键、字符串和布尔列")
    void createTableDdlUsesSavedAttributes() {
        String ddl = MetaController.createTableDdl("EIP4AI_RT_DEMO", List.of(
                attr("EIP4AI_RT_DEMO_ID", "CHAR", null, true),
                attr("NAME", "NVARCHAR", 100, true),
                attr("ENABLED", "BOOLEAN", null, false)
        ), Map.of());

        assertTrue(ddl.contains("CREATE TABLE EIP4AI_RT_DEMO"));
        assertTrue(ddl.contains("EIP4AI_RT_DEMO_ID character(36)  NOT NULL"));
        assertTrue(ddl.contains("NAME character varying(100)  NOT NULL"));
        assertTrue(ddl.contains("ENABLED integer"));
        assertTrue(ddl.contains("primary key (EIP4AI_RT_DEMO_ID)"));
    }

    @Test
    @DisplayName("引用列(36位 uuid REFERENCEID)的外键指向 refTargets 里的目标表,而非自表")
    void referenceColumnPointsAtTargetTable() {
        String refUuid = "11111111-1111-1111-1111-111111111111";
        String ddl = MetaController.createTableDdl("EIP4_ORDER", List.of(
                attr("EIP4_ORDER_ID", "CHAR", null, true),
                attr("CUSTOMERID", refUuid, null, false)
        ), Map.of("CUSTOMERID", "EIP4_CUSTOMER"));

        assertTrue(ddl.contains("CUSTOMERID character(36) REFERENCES EIP4_CUSTOMER"),
                "应指向目标表 EIP4_CUSTOMER, 实际: " + ddl);
        assertFalse(ddl.contains("REFERENCES EIP4_ORDER"),
                "外键不得自指 EIP4_ORDER");
    }

    private static GeneralPOJO attr(String column, String referenceId, Integer length, boolean mandatory) {
        GeneralPOJO po = mock(GeneralPOJO.class);
        when(po.get_Value("COLUMNNAME")).thenReturn(column);
        when(po.get_Value("REFERENCEID")).thenReturn(referenceId);
        when(po.get_Value("FIELDLENGTH")).thenReturn(length);
        when(po.get_ValueAsBoolean("ISMANDATORY")).thenReturn(mandatory);
        return po;
    }
}

Step 4.2 — 跑测试,预期编译失败

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerDdlTest

预期 FAIL:method createTableDdl in class MetaController cannot be applied to given types(现签名只有 2 参)。

Step 4.3 — 最小实现:给 createTableDdl/appendColumnDdl 加 refTargets

createTableDdl(第249行)改签名并把 refTargets 透传:

    static String createTableDdl(String table, List<GeneralPOJO> attrs, Map<String, String> refTargets) {
        if (attrs == null || attrs.isEmpty()) {
            throw new IllegalStateException("实体属性为空,无法建表: " + table);
        }
        Map<String, String> refs = refTargets == null ? Map.of() : refTargets;
        StringBuilder sql = new StringBuilder();
        StringBuilder unique = new StringBuilder();
        StringBuilder combUnique = new StringBuilder();
        sql.append("CREATE TABLE ").append(table).append("\n");
        sql.append("(\n");
        for (GeneralPOJO attr : attrs) {
            appendColumnDdl(table, attr, sql, unique, combUnique, refs);
        }
        sql.append(unique);
        if (!combUnique.isEmpty()) {
            sql.append(combUnique).append("), \n");
        }
        sql.append("primary key (").append(table).append("_ID)\n");
        sql.append("); \n");
        return sql.toString();
    }

appendColumnDdl(第270行)改签名 + 改 else 分支(第296-297行):

    private static void appendColumnDdl(String table, GeneralPOJO attr, StringBuilder sql,
                                        StringBuilder unique, StringBuilder combUnique,
                                        Map<String, String> refTargets) {

把第296-298行的 else 分支:

        } else {
            sql.append(col).append(" character(36) REFERENCES ").append(table);
        }

改成(指向 refTargets 里的目标表;没有则退回自表以保持旧行为不破坏):

        } else {
            String target = refTargets.get(col);
            sql.append(col).append(" character(36) REFERENCES ")
                    .append(target != null && !target.isBlank() ? target : table);
        }

createEntity 第130行调用点改为传 refTargets(Task 3 已在第95行下声明该局部变量):

        String ddl = createTableDdl(table, created, refTargets);

Step 4.4 — 跑测试,预期 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerDdlTest

预期:2 个用例绿,含新 referenceColumnPointsAtTargetTable。再跑 Task 3 测试确保未回归:

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest,MetaCatalogControllerTest,MetaControllerDdlTest

预期:全绿。

Step 4.5 — 提交

git -C /Users/zhengwr/workspace/eip3/eip4-platform add platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaControllerDdlTest.java
git -C /Users/zhengwr/workspace/eip3/eip4-platform commit -m "fix(meta): 引用列 DDL 外键指向目标表而非自表(DECISION-1)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 5 — 卫生:去掉硬编码描述 "AI 闭环创建 (eip4-poc WS5)"

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java(第88行)
  • Modify test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaControllerReferenceTest.java(追加一个纯函数断言)

第88行 entityMap.put("DESCRIPTION", "AI 闭环创建 (eip4-poc WS5)"); 把所有人工建的实体也标成 "AI 闭环创建",误导。改为取请求里的 description(无则中性默认 设计中心创建)。为可单测,抽一个静态纯函数 resolveDescription(Map req)。

Step 5.1 — 写失败测试(追加到 MetaControllerReferenceTest)

    @Test
    @DisplayName("resolveDescription: 无 description → 中性默认; 有则原样")
    void resolveDescriptionNeutralDefault() {
        assertEquals("设计中心创建", MetaController.resolveDescription(java.util.Map.of()));
        assertEquals("我的订单实体",
                MetaController.resolveDescription(java.util.Map.of("description", "我的订单实体")));
    }

Step 5.2 — 跑测试,预期编译失败

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest

预期 FAIL:cannot find symbol: method resolveDescription(...)。

Step 5.3 — 最小实现

新增静态方法(放在 err(...) 第371行附近):

    static String resolveDescription(Map<String, Object> req) {
        Object d = req.get("description");
        if (d != null && !String.valueOf(d).isBlank()) {
            return String.valueOf(d);
        }
        return "设计中心创建";
    }

把第88行:

        entityMap.put("DESCRIPTION", "AI 闭环创建 (eip4-poc WS5)");

改为:

        entityMap.put("DESCRIPTION", resolveDescription(req));

Step 5.4 — 跑测试,预期 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest

预期:含新 resolveDescriptionNeutralDefault 在内全绿。最后跑本节全部新增/改动测试一把总验:

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest,MetaControllerReferenceTest,MetaControllerDdlTest

预期:BUILD SUCCESS,三个测试类全绿。

Step 5.5 — 提交

git -C /Users/zhengwr/workspace/eip3/eip4-platform add platform-metadata/src/main/java/com/eip4/platform/metadata/web/MetaController.java platform-metadata/src/test/java/com/eip4/platform/metadata/web/MetaControllerReferenceTest.java
git -C /Users/zhengwr/workspace/eip3/eip4-platform commit -m "chore(meta): 实体描述取请求 description, 默认中性'设计中心创建'(去硬编码 AI 标记)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

本节产出供后续节使用的契约(务必照搬名字/形状):

  • GET /api/meta/entities → {status:0,data:[{entityId,tablename,name}]}(Section 4 建模器引用列选择器的实体下拉源)。
  • GET /api/meta/entity/{table}/attributes → {status:0,data:{tablename,displayColumn,columns:[{column,display,type,referenceTable?}]}}(Section 2 recipe compile 取列与 displayColumn;Section 4 建模器渲列)。
  • POST /api/meta/entity 的 attributes[] 现接受 {column,type:'reference',referenceTable:'<TARGET_TABLE>',display?,mandatory?};响应结构不变。
  • Java:MetaController.createTableDdl(String,List<GeneralPOJO>,Map<String,String>)、MetaController.findOrCreateReference(String,String,Properties)、MetaController.resolveDescription(Map)。

运行时冒烟(非自动化,发布前人工执行一次):启动 8093(见顶部命令),curl -XPOST localhost:8093/api/meta/entity 建一个带 reference 列的 EIP4DC_ORDER(referenceTable 指向某既有表如 SYS_USERGROUP),确认 (a) SYS_REFERENCE 多一行 ENTITYID=目标实体;(b) 物理表 DDL 的外键 REFERENCES SYS_USERGROUP;(c) GET /api/meta/entity/EIP4DC_ORDER/attributes 该列 type:'reference', referenceTable:'SYS_USERGROUP'。此步同时验证 Task 3 裸 jdbcTemplate INSERT 与引擎 saveAttr 的混合事务在真实库无回滚问题。

第 2 节 · recipe→默认页→落标准层 单步端点(建物 2)+ 引用列渲染

本节交付「建物 2」:一个管理员单步端点 POST /api/design/recipe/compile,它读实体属性 → 组装受控 PageBlueprint → 编译 amis → 严格 typed 校验 → 经唯一真相 PageSchemaWriter.upsertStandard 落标准层,并服务端生成 templateId。同时把「引用列渲染显名而非裸 id」焊进编译器。

红线落地:标准层写入只走 PageSchemaWriter.upsertStandard(不裸 INSERT sys_page_schema);平台进程内无 LLM;本端点不触发任何审批/发布(发布在第 3 节,恒人审)。

关键既有事实(已核实):

  • PageBlueprintCompiler.compile(bp) 对 maintenance-crud-v1 产出 body.api == "/api/flow/<TABLE>_SEARCH";对 tree-crud-v1 产出 body.api.url == "/api/entity/<TABLE>/tree?..."。
  • PageBlueprintField 现为 6-arg record (name,label,type,required,listVisible,formVisible)。
  • applyColumnRender(ObjectNode,String fieldType)(L135)按 type 派生列渲染:boolean→mapping、date/datetime→格式化、其余纯文本。
  • 列表运行时 FlowController(L493)对 _SEARCH 行调 UserColumnResolver.resolveRows(table, rows),为引用列注入 <COL>_DISPLAY__ 显名(house-style,见 PickerController L234-268)。因此引用列只需把 amis 列 name 指向 <COL>_DISPLAY__,无需新组件类型,TypedPageSchemaValidator 平凡通过。
  • requireAdmin() / currentUserId() 的实现见 PageSchemaController L515-540,本节控制器逐字复制该模式。
  • 测试命令:JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=<TestClass>。

可参考技能:@superpowers:test-driven-development(先红后绿)、@superpowers:writing-plans(颗粒度)。


Task 6 · 抽出共享蓝图装配器 RecipePageComposer(DRY)

把「实体属性 → PageBlueprint → PageBlueprintCompiler.compile」装配逻辑收成一个可被人工端点(Task 7)与未来 AI 路径共用的类。本任务先做不含引用字段的主体(引用字段在 Task 9 接线)。

Files:

  • Create /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/RecipePageComposer.java
  • Test (create) /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/schema/blueprint/RecipePageComposerTest.java

Step 6.1 — 写失败测试(compose 出 maintenance-crud 页,断言 crud.api == /api/flow/<TABLE>_SEARCH)

写入 RecipePageComposerTest.java:

package com.eip4.platform.metadata.schema.blueprint;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.List;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;

class RecipePageComposerTest {

    private static final ObjectMapper MAPPER = new ObjectMapper();
    private final RecipePageComposer composer = new RecipePageComposer(MAPPER);

    @Test
    @DisplayName("1. compose maintenance-crud → crud.api == /api/flow/<TABLE>_SEARCH,列= listVisible 业务列")
    void composesMaintenanceCrud() {
        RecipePageComposer.Spec spec = new RecipePageComposer.Spec(
                "EIP4AI_CUSTOMER", "客户", PageBlueprint.RECIPE_MAINTENANCE_CRUD,
                "客户维护", "NAME", 20,
                List.of(
                        new RecipePageComposer.AttrSpec("NAME", "名称", "string", true, null, null),
                        new RecipePageComposer.AttrSpec("LEVEL", "等级", "integer", false, null, null)));

        ObjectNode page = composer.compose(spec);

        assertEquals("page", page.path("type").asText());
        assertEquals("客户维护", page.path("title").asText());
        ObjectNode crud = (ObjectNode) page.path("body");
        assertEquals("/api/flow/EIP4AI_CUSTOMER_SEARCH", crud.path("api").asText());
        ArrayNode columns = (ArrayNode) crud.path("columns");
        assertEquals(2, columns.size());
        assertEquals("NAME", columns.get(0).path("name").asText());
        assertEquals("LEVEL", columns.get(1).path("name").asText());
    }

    @Test
    @DisplayName("2. compose tree-crud → 注入 PARENTID 字段且列表不显示该列")
    void composesTreeCrudWithParent() {
        RecipePageComposer.Spec spec = new RecipePageComposer.Spec(
                "EIP4AI_CATEGORY", "分类", PageBlueprint.RECIPE_TREE_CRUD,
                "分类维护", "NAME", 20,
                List.of(
                        new RecipePageComposer.AttrSpec("NAME", "名称", "string", true, null, null),
                        new RecipePageComposer.AttrSpec("PARENTID", "上级", "string", false, null, null)));

        ObjectNode page = composer.compose(spec);
        ObjectNode crud = (ObjectNode) page.path("body");
        assertEquals("eip4aiCategoryTreeCrud", crud.path("name").asText());
        // 业务列里不含 PARENTID(compiler.treeColumns 跳过 PARENTID),但保留「操作」列。
        ArrayNode columns = (ArrayNode) crud.path("columns");
        boolean hasParentColumn = false;
        for (int i = 0; i < columns.size(); i++) {
            if ("PARENTID".equals(columns.get(i).path("name").asText())) {
                hasParentColumn = true;
            }
        }
        assertTrue(!hasParentColumn);
    }

    @Test
    @DisplayName("3. displayField 省略时回退首个 NAME/required 列")
    void derivesDisplayFieldWhenBlank() {
        RecipePageComposer.Spec spec = new RecipePageComposer.Spec(
                "EIP4AI_ITEM", "条目", PageBlueprint.RECIPE_MAINTENANCE_CRUD,
                "条目维护", null, 20,
                List.of(
                        new RecipePageComposer.AttrSpec("CODE", "编码", "string", false, null, null),
                        new RecipePageComposer.AttrSpec("NAME", "名称", "string", true, null, null)));

        ObjectNode page = composer.compose(spec);
        // displayField 回退到 NAME,filter 兜底用它(此处只需 compose 成功不抛)。
        assertEquals("page", page.path("type").asText());
    }
}

Step 6.2 — 运行测试,预期 FAIL(编译失败)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=RecipePageComposerTest

预期 FAIL,输出含编译错误,例如: cannot find symbol: class RecipePageComposer / package ... does not exist。

Step 6.3 — 写最小实现 RecipePageComposer

写入 RecipePageComposer.java(完整文件):

package com.eip4.platform.metadata.schema.blueprint;

import java.util.ArrayList;
import java.util.List;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;

/**
 * 共享蓝图装配器:实体属性 → 受控 {@link PageBlueprint} → {@link PageBlueprintCompiler#compile}。
 *
 * <p>人工单步端点(DesignFeatureController)与未来 AI 路径共用同一装配口径(DRY),UI/UE 规则集中在
 * recipe/compiler 而非散落在调用方。本类不写库、不校验白名单(严格 typed 闸在端点层),只负责装配+编译。
 *
 * <p>装配口径镜像 {@code AiFeatureDraftGenerator.pageBlueprint}:tree-crud 的 PARENTID 列 listVisible=false;
 * displayField 缺省回退首个 NAME/required 列。引用字段(type=reference + referenceTable/displayColumn)
 * 透传到 {@link PageBlueprintField},由 compiler 渲染显名列(见 applyColumnRender)。
 */
public final class RecipePageComposer {

    private final PageBlueprintCompiler compiler;

    public RecipePageComposer(ObjectMapper objectMapper) {
        this.compiler = new PageBlueprintCompiler(objectMapper);
    }

    public ObjectNode compose(Spec spec) {
        if (spec == null) {
            throw new IllegalArgumentException("compose spec 不能为空");
        }
        PageBlueprint blueprint = toBlueprint(spec);
        return compiler.compile(blueprint);
    }

    PageBlueprint toBlueprint(Spec spec) {
        List<PageBlueprintField> fields = new ArrayList<>();
        for (AttrSpec attr : spec.attributes()) {
            boolean treeParentField = PageBlueprint.RECIPE_TREE_CRUD.equals(spec.recipe())
                    && "PARENTID".equals(attr.column());
            fields.add(new PageBlueprintField(
                    attr.column(), attr.display(), attr.type(),
                    attr.required(), !treeParentField, true,
                    attr.referenceTable(), attr.displayColumn()));
        }
        String displayField = firstNonBlank(spec.displayField(), deriveDisplayField(spec.attributes()));
        int pageSize = spec.pageSize() < 1 ? 20 : spec.pageSize();
        // templateId 由端点层服务端生成;compose 阶段用占位(compiler.validate 只要求非空)。
        return new PageBlueprint(
                PageBlueprint.VERSION, spec.recipe(),
                "compose-placeholder", spec.title(), spec.tableName(), spec.entityName(),
                spec.tableName() + "_ID", displayField, fields,
                true, true, true, pageSize);
    }

    private static String deriveDisplayField(List<AttrSpec> attrs) {
        for (AttrSpec a : attrs) {
            if ("NAME".equals(a.column()) || a.required()) {
                return a.column();
            }
        }
        return attrs.isEmpty() ? "NAME" : attrs.get(0).column();
    }

    private static String firstNonBlank(String preferred, String fallback) {
        if (preferred != null && !preferred.isBlank()) {
            return preferred.trim();
        }
        return fallback;
    }

    /** 装配输入:等价于 GET /api/meta/entity/{table}/attributes 的读取结果 + recipe/title/displayField/pageSize。 */
    public record Spec(
            String tableName,
            String entityName,
            String recipe,
            String title,
            String displayField,
            int pageSize,
            List<AttrSpec> attributes) {
        public Spec {
            attributes = attributes == null ? List.of() : List.copyOf(attributes);
        }
    }

    /** 单个实体属性。referenceTable/displayColumn 仅引用列非空(type=reference)。 */
    public record AttrSpec(
            String column,
            String display,
            String type,
            boolean required,
            String referenceTable,
            String displayColumn) {
    }
}

注意:PageBlueprintField 当前是 6-arg;上面用了 8-arg。这会在 Task 6 阶段编译失败——故 Task 6 与 Task 8 的字段扩展互相依赖。为让本任务独立绿,先在本步顺手加 PageBlueprintField 的 8-arg + 6-arg 兼容构造(Task 8 复用同一记录、不再改签名,只扩 compiler 渲染)。把 PageBlueprintField.java 替换为:

package com.eip4.platform.metadata.schema.blueprint;

public record PageBlueprintField(
        String name,
        String label,
        String type,
        boolean required,
        boolean listVisible,
        boolean formVisible,
        String referenceTable,
        String displayColumn) {

    /** 6-arg 兼容构造:非引用字段(referenceTable/displayColumn 置空)。保持既有调用方/测试零改。 */
    public PageBlueprintField(String name, String label, String type,
                              boolean required, boolean listVisible, boolean formVisible) {
        this(name, label, type, required, listVisible, formVisible, null, null);
    }
}

Step 6.3b — 运行既有蓝图测试,确认 6-arg 兼容未破坏存量

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=PageBlueprintCompilerTest,PageSchemaWriterTest

预期 PASS(既有 PageBlueprintCompilerTest 用 6-arg 构造,应仍编译通过、全绿)。

Step 6.4 — 运行 Task 6 测试,预期 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=RecipePageComposerTest

预期 PASS(3 个用例全绿)。

Step 6.5 — 提交

git add eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/RecipePageComposer.java \
        eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintField.java \
        eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/schema/blueprint/RecipePageComposerTest.java
git commit -m "feat(design): RecipePageComposer 共享蓝图装配器 + PageBlueprintField 引用字段扩展(向后兼容)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 7 · 新建 DesignFeatureController:POST /api/design/recipe/compile(建物 2 主端点)

管理员单步端点:读实体属性 → RecipePageComposer.compose → 服务端生成 templateId → 严格 typed 校验(不通过 400)→ PageSchemaWriter.upsertStandard。

Files:

  • Create /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java
  • Create /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/EntityAttributeReader.java(薄接口,Section 1 的属性读取逻辑可实现它)
  • Test (create) /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/web/DesignFeatureControllerTest.java

Step 7.1 — 写失败测试(compile 端点返回新 templateId 并经 writer 落标准层一次)

用「可注入协作者」的包级构造让单测脱库:注入一个 stub EntityAttributeReader、真 RecipePageComposer、mock PageSchemaWriter。admin 门禁在单测层旁路(用包级 boolean skipAdminCheck 测试构造,生产构造恒开门禁)。

写入 DesignFeatureControllerTest.java:

package com.eip4.platform.metadata.web;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

import java.util.List;
import java.util.Map;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.springframework.http.ResponseEntity;

import com.eip4.platform.metadata.schema.PageSchemaWriter;
import com.eip4.platform.metadata.web.EntityAttributeReader.EntityAttributes;
import com.eip4.platform.metadata.web.EntityAttributeReader.EntityAttribute;

class DesignFeatureControllerTest {

    private DesignFeatureController controller(PageSchemaWriter writer, EntityAttributeReader reader) {
        // 包级测试构造:跳过 admin 门禁(生产构造恒走 requireAdmin)。
        return new DesignFeatureController(writer, reader, true);
    }

    @Test
    @DisplayName("1. compile 返回服务端生成的 design- 前缀 templateId,并经 writer 落标准层一次")
    void compileGeneratesTemplateIdAndWritesOnce() {
        PageSchemaWriter writer = mock(PageSchemaWriter.class);
        when(writer.upsertStandard(anyString(), anyString(), anyString(), anyString()))
                .thenReturn("etag-deadbeef");
        EntityAttributeReader reader = mock(EntityAttributeReader.class);
        when(reader.read("EIP4AI_CUSTOMER")).thenReturn(new EntityAttributes(
                "EIP4AI_CUSTOMER", "NAME", List.of(
                        new EntityAttribute("NAME", "名称", "string", true, null),
                        new EntityAttribute("LEVEL", "等级", "integer", false, null))));

        var body = new DesignFeatureController.CompileRequest();
        body.tableName = "EIP4AI_CUSTOMER";
        body.recipe = "maintenance-crud-v1";
        body.title = "客户维护";
        body.pageSize = 20;

        ResponseEntity<Map<String, Object>> resp = controller(writer, reader).compile(body);

        assertEquals(200, resp.getStatusCode().value());
        @SuppressWarnings("unchecked")
        Map<String, Object> data = (Map<String, Object>) resp.getBody().get("data");
        String tid = String.valueOf(data.get("templateId"));
        assertTrue(tid.startsWith("design-eip4ai-customer-"), "templateId=" + tid);
        assertEquals("etag-deadbeef", data.get("etag"));

        // 标准层只经 writer 写一次,且 templateId == 返回值(非调用方指定)。
        ArgumentCaptor<String> tidCap = ArgumentCaptor.forClass(String.class);
        verify(writer).upsertStandard(tidCap.capture(), eq("客户维护"), anyString(), anyString());
        assertEquals(tid, tidCap.getValue());
    }

    @Test
    @DisplayName("2. tableName/title 为空 → 400,不读实体不写库")
    void blankArgsRejected() {
        PageSchemaWriter writer = mock(PageSchemaWriter.class);
        EntityAttributeReader reader = mock(EntityAttributeReader.class);

        var body = new DesignFeatureController.CompileRequest();
        body.tableName = "  ";
        body.recipe = "maintenance-crud-v1";
        body.title = "x";

        ResponseEntity<Map<String, Object>> resp = controller(writer, reader).compile(body);
        assertEquals(400, resp.getStatusCode().value());
    }
}

Step 7.2 — 运行,预期 FAIL(编译失败:缺类)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=DesignFeatureControllerTest

预期 FAIL:cannot find symbol: class DesignFeatureController / class EntityAttributeReader。

Step 7.3 — 写 EntityAttributeReader(薄接口 + 默认 JdbcTemplate 实现)

写入 EntityAttributeReader.java:

package com.eip4.platform.metadata.web;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

/**
 * 读实体属性给设计单步端点用,等价 GET /api/meta/entity/{table}/attributes 的 data 部分。
 *
 * <p>第 1 节若已提供属性服务 bean,可直接实现本接口或被本默认实现替换;契约不变。
 * 引用列 type=="reference" 且 referenceTable 非空,由第 1 节 createEntity 写入的 SYS_REFERENCE 行驱动。
 */
public interface EntityAttributeReader {

    EntityAttributes read(String tableName);

    record EntityAttributes(String tablename, String displayColumn, List<EntityAttribute> columns) {
        public EntityAttributes {
            columns = columns == null ? List.of() : List.copyOf(columns);
        }
    }

    record EntityAttribute(String column, String display, String type,
                           boolean required, String referenceTable) {
    }

    /**
     * 默认实现:委托第 1 节 Task 2 抽出的 {@code EntityAttributesService}(@Component)。
     * 【评审 §B.9-3 校正】真实表是 SYS_ENTITYATTRIBUTE(**无 table_name 列**,靠 entityid ⋈ SYS_ENTITY 过滤),
     * 列名是 columnname/displayname/referenceid/ismandatory/entitydisplayseq;引用列的目标表名须由
     * REFERENCEID(36 位 uuid)经 {@code DataDicService.getReferenceEntityTableName} 反解——纯 JdbcTemplate 做不到。
     * 故本类**不自写 SQL**,统一委托第 1 节的服务 bean,保证人工 compile 与 GET /api/meta/entity/{table}/attributes 同源同结果。
     */
    @Component
    class DelegatingEntityAttributeReader implements EntityAttributeReader {
        private final EntityAttributesService service; // 第 1 节 Task 2 产出,见 §B.9-3

        public DelegatingEntityAttributeReader(EntityAttributesService service) {
            this.service = service;
        }

        @Override
        public EntityAttributes read(String tableName) {
            EntityAttributesService.Result r = service.read(tableName); // {tablename, displayColumn, columns[]}
            List<EntityAttribute> cols = new ArrayList<>();
            for (EntityAttributesService.Column c : r.columns()) {
                // c.referenceTable() 已由 service 经 getReferenceEntityTableName 反解(引用列非空,否则 null)
                cols.add(new EntityAttribute(c.column(), c.display(), c.type(), c.mandatory(), c.referenceTable()));
            }
            return new EntityAttributes(tableName, r.displayColumn(), cols);
        }
    }
}

装配说明:displayColumn 字段未来供引用渲染(Task 8/9)用;此接口本身先不暴露 target 的 displayColumn(用 <COL>_DISPLAY__ 运行时口径,无需它)。Task 9 在 composer 接线时把 referenceTable 透传即可。

Step 7.4 — 写 DesignFeatureController

写入 DesignFeatureController.java:

package com.eip4.platform.metadata.web;

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.UUID;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.dao.DataAccessException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

import com.dsasp.server.common.user.service.LoggedInUser;
import com.dsasp.server.common.util.UserSession;
import com.eip4.platform.metadata.schema.PageSchemaWriter;
import com.eip4.platform.metadata.schema.TypedPageSchemaReport;
import com.eip4.platform.metadata.schema.TypedPageSchemaValidator;
import com.eip4.platform.metadata.schema.blueprint.PageBlueprint;
import com.eip4.platform.metadata.schema.blueprint.RecipePageComposer;
import com.eip4.platform.metadata.web.EntityAttributeReader.EntityAttribute;
import com.eip4.platform.metadata.web.EntityAttributeReader.EntityAttributes;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

/**
 * 设计中心新建(人走五环)单步端点(建物 2)。
 *
 * <p>{@code POST /api/design/recipe/compile}:读实体属性 → RecipePageComposer 装配+编译 → 服务端生成
 * templateId → 严格 typed 校验(recipe 产物受白名单约束,必须过;不过 400)→ PageSchemaWriter.upsertStandard
 * 落标准层(唯一真相,无裸 INSERT)。本端点不触发审批/发布(发布在 /api/design/publish,恒人审)。
 */
@Tag(name = "设计中心新建", description = "人走五环 · recipe→默认页→落标准层单步端点(建物 2)")
@RestController
@RequestMapping("/api/design")
public class DesignFeatureController {

    private static final Logger log = LoggerFactory.getLogger(DesignFeatureController.class);
    private static final ObjectMapper MAPPER = new ObjectMapper();

    private final PageSchemaWriter pageSchemaWriter;
    private final EntityAttributeReader attributeReader;
    private final RecipePageComposer composer;
    private final TypedPageSchemaValidator strictValidator;
    private final JdbcTemplate jdbcTemplate;     // 仅 requireAdmin 用
    private final boolean skipAdminCheck;        // 仅单测置 true

    /** 生产构造(Spring 注入)。 */
    public DesignFeatureController(JdbcTemplate jdbcTemplate,
                                   PageSchemaWriter pageSchemaWriter,
                                   EntityAttributeReader attributeReader) {
        this.jdbcTemplate = jdbcTemplate;
        this.pageSchemaWriter = pageSchemaWriter;
        this.attributeReader = attributeReader;
        this.composer = new RecipePageComposer(MAPPER);
        this.strictValidator = TypedPageSchemaValidator.defaults();
        this.skipAdminCheck = false;
    }

    /** 包级测试构造:脱库 + 可旁路 admin 门禁。 */
    DesignFeatureController(PageSchemaWriter pageSchemaWriter,
                            EntityAttributeReader attributeReader,
                            boolean skipAdminCheck) {
        this.jdbcTemplate = null;
        this.pageSchemaWriter = pageSchemaWriter;
        this.attributeReader = attributeReader;
        this.composer = new RecipePageComposer(MAPPER);
        this.strictValidator = TypedPageSchemaValidator.defaults();
        this.skipAdminCheck = skipAdminCheck;
    }

    @Operation(summary = "recipe 编译默认页并落标准层(仅管理员)",
            description = "服务端生成 templateId;严格 typed 校验不过 400;写入只走 PageSchemaWriter.upsertStandard")
    @PostMapping("/recipe/compile")
    public ResponseEntity<Map<String, Object>> compile(@RequestBody CompileRequest req) {
        requireAdmin();

        if (req == null || isBlank(req.tableName) || isBlank(req.title)) {
            return ResponseEntity.badRequest().body(fail("tableName 和 title 不能为空"));
        }
        String recipe = isBlank(req.recipe) ? PageBlueprint.RECIPE_MAINTENANCE_CRUD : req.recipe.trim();
        if (!PageBlueprint.RECIPE_MAINTENANCE_CRUD.equals(recipe)
                && !PageBlueprint.RECIPE_TREE_CRUD.equals(recipe)) {
            return ResponseEntity.badRequest().body(fail("不支持的 recipe: " + recipe));
        }
        int pageSize = req.pageSize == null || req.pageSize < 1 ? 20 : req.pageSize;

        // 1. 读实体属性
        EntityAttributes attrs;
        try {
            attrs = attributeReader.read(req.tableName.trim());
        } catch (DataAccessException ex) {
            return ResponseEntity.badRequest().body(fail("读取实体属性失败:" + ex.getMessage()));
        }
        if (attrs == null || attrs.columns().isEmpty()) {
            return ResponseEntity.badRequest().body(fail("实体无可用属性: " + req.tableName));
        }

        // 2. 装配 + 编译(引用字段透传 referenceTable)
        List<RecipePageComposer.AttrSpec> specAttrs = new ArrayList<>();
        for (EntityAttribute a : attrs.columns()) {
            specAttrs.add(new RecipePageComposer.AttrSpec(
                    a.column(), a.display(), a.type(), a.required(), a.referenceTable(), null));
        }
        String displayField = isBlank(req.displayField) ? attrs.displayColumn() : req.displayField.trim();
        ObjectNode schema = composer.compose(new RecipePageComposer.Spec(
                req.tableName.trim(), entityNameOf(req), recipe, req.title.trim(),
                displayField, pageSize, specAttrs));

        String schemaJson;
        try {
            schemaJson = MAPPER.writeValueAsString(schema);
        } catch (JsonProcessingException ex) {
            return ResponseEntity.internalServerError().body(fail("schema 序列化失败"));
        }

        // 3. 严格 typed 校验(recipe 产物白名单约束,必须过;不过 400)
        TypedPageSchemaReport report = strictValidator.validate(schemaJson);
        if (!report.valid()) {
            Map<String, Object> data = new LinkedHashMap<>();
            data.put("issues", report.issues());
            return ResponseEntity.badRequest().body(fail("recipe 产物 typed 校验未通过(应为白名单组件)", data));
        }

        // 4. 服务端生成 templateId(绝不用调用方指定值,避免 UPSERT 覆盖既有页)
        String templateId = "design-" + req.tableName.trim().toLowerCase(Locale.ROOT).replace('_', '-')
                + "-" + UUID.randomUUID().toString().substring(0, 8);

        // 5. 经唯一真相 writer 落标准层
        String etag;
        try {
            etag = pageSchemaWriter.upsertStandard(templateId, req.title.trim(), schemaJson, currentUserId());
        } catch (DataAccessException ex) {
            log.error("[design-compile] 标准层写入失败 templateId={}: {}", templateId, ex.getMessage());
            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                    .body(fail("标准层写入失败:" + ex.getMessage()));
        }

        Map<String, Object> data = new LinkedHashMap<>();
        data.put("templateId", templateId);
        data.put("etag", etag);
        log.info("[design-compile] operator={} table={} recipe={} templateId={}",
                currentUserId(), req.tableName, recipe, templateId);
        return ResponseEntity.ok(ok("默认页已编译并落标准层", data));
    }

    private static String entityNameOf(CompileRequest req) {
        return isBlank(req.entityName) ? req.title.trim() : req.entityName.trim();
    }

    // ===== admin 门禁(逐字对齐 PageSchemaController.requireAdmin / currentUserId)=====

    private void requireAdmin() {
        if (skipAdminCheck) {
            return;
        }
        java.util.Properties ctx = UserSession.get();
        if (ctx == null) {
            throw new ResponseStatusException(HttpStatus.FORBIDDEN, "未登录,禁止访问设计端点");
        }
        String cu = ctx.getProperty(LoggedInUser.CURRENTUSER, "").trim();
        if (cu.isEmpty()) {
            throw new ResponseStatusException(HttpStatus.FORBIDDEN, "未登录,禁止访问设计端点");
        }
        if ("ADMIN".equalsIgnoreCase(cu)) {
            return;
        }
        Integer cnt = jdbcTemplate.queryForObject(
                "SELECT COUNT(*) FROM sys_user WHERE TRIM(sys_user_id)=? AND TRIM(account)='admin'",
                Integer.class, cu);
        if (cnt == null || cnt == 0) {
            throw new ResponseStatusException(HttpStatus.FORBIDDEN, "仅系统管理员可执行设计端点");
        }
    }

    private static String currentUserId() {
        java.util.Properties ctx = UserSession.get();
        if (ctx == null) return "UNKNOWN";
        String u = ctx.getProperty(LoggedInUser.CURRENTUSER, "UNKNOWN");
        return u.isBlank() ? "UNKNOWN" : u.trim();
    }

    private static boolean isBlank(String s) {
        return s == null || s.isBlank();
    }

    private static Map<String, Object> ok(String msg, Map<String, Object> data) {
        Map<String, Object> r = new LinkedHashMap<>();
        r.put("status", 0);
        r.put("msg", msg);
        if (data != null) r.put("data", data);
        return r;
    }

    private static Map<String, Object> fail(String msg) {
        return fail(msg, null);
    }

    private static Map<String, Object> fail(String msg, Map<String, Object> data) {
        Map<String, Object> r = new LinkedHashMap<>();
        r.put("status", 1);
        r.put("msg", msg);
        if (data != null) r.put("data", data);
        return r;
    }

    /** POST /api/design/recipe/compile 请求体。 */
    public static class CompileRequest {
        public String tableName;
        public String recipe;
        public String title;
        public String entityName;
        public String displayField;
        public Integer pageSize;
    }
}

Step 7.5 — 运行,预期 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=DesignFeatureControllerTest

预期 PASS(2 用例全绿)。

Step 7.6 — 提交

git add eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java \
        eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/EntityAttributeReader.java \
        eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/web/DesignFeatureControllerTest.java
git commit -m "feat(design): POST /api/design/recipe/compile 单步端点(建物2)·服务端生成 templateId+严格 typed 闸+唯一真相落标准层

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 8 · 编译器引用列渲染:reference 字段渲染显名而非裸 id

PageBlueprintCompiler.applyColumnRender 当前只认 boolean/date/datetime。扩展为:当字段 type 为 reference 时,列 name 指向 <COL>_DISPLAY__(运行时 _SEARCH 流注入显名),保持纯文本列、白名单安全。

Files:

  • Modify /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompiler.java
    • maintenanceColumns(L116-128):把列 name 从 field.name() 改为「引用字段→显名列」。
    • treeColumns(L255-281):同样处理。
    • applyColumnRender(L135-157):reference 走纯文本(不加 type)。
    • validate(L378-417):把 reference 纳入合法 field.type(否则 controlType/列渲染对未知 type 退化为 input-text/纯文本,但需确保不报错——当前 validate 不校验 type 取值,故无需改;仍加一行注释保险)。
  • Test (modify) /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompilerTest.java

Step 8.1 — 写失败测试(引用列渲染显名列 <COL>_DISPLAY__)

在 PageBlueprintCompilerTest.java 末尾(最后一个 } 之前)追加:

    @Test
    @DisplayName("引用列渲染显名: list 列 name 指向 <COL>_DISPLAY__(运行时 _SEARCH 注入显名),非裸 id")
    void referenceColumnRendersDisplayName() {
        PageBlueprint blueprint = new PageBlueprint(
                PageBlueprint.VERSION,
                PageBlueprint.RECIPE_MAINTENANCE_CRUD,
                "eip4ai-order",
                "订单维护",
                "EIP4AI_ORDER",
                "订单",
                "EIP4AI_ORDER_ID",
                "ORDERNO",
                List.of(
                        new PageBlueprintField("ORDERNO", "订单号", "string", true, true, true, null, null),
                        // 引用列:指向 EIP4AI_CUSTOMER,显名列 NAME
                        new PageBlueprintField("CUSTOMERID", "客户", "reference", false, true, true,
                                "EIP4AI_CUSTOMER", "NAME")),
                true, true, true, 20);

        ObjectNode schema = new PageBlueprintCompiler(MAPPER).compile(blueprint);
        ArrayNode columns = (ArrayNode) schema.path("body").path("columns");

        assertEquals(2, columns.size());
        assertEquals("ORDERNO", columns.get(0).path("name").asText());
        // 引用列:name 改指显名列,label 仍是业务标签,纯文本(无特殊 type → typed 白名单安全)。
        assertEquals("CUSTOMERID_DISPLAY__", columns.get(1).path("name").asText());
        assertEquals("客户", columns.get(1).path("label").asText());
        assertTrue(columns.get(1).path("type").asText().isBlank());
    }

Step 8.2 — 运行,预期 FAIL(断言不匹配)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=PageBlueprintCompilerTest#referenceColumnRendersDisplayName

预期 FAIL,输出形如: expected: <CUSTOMERID_DISPLAY__> but was: <CUSTOMERID>(当前列 name 仍是裸字段名)。

Step 8.3 — 实现:maintenanceColumns 与 treeColumns 用「列名解析器」+ applyColumnRender 收 reference

在 PageBlueprintCompiler.java 修改 maintenanceColumns(L116-128),把:

            ObjectNode column = columns.addObject();
            column.put("name", field.name());
            column.put("label", field.label());
            applyColumnRender(column, field.type());

替换为:

            ObjectNode column = columns.addObject();
            column.put("name", listColumnName(field));
            column.put("label", field.label());
            applyColumnRender(column, field.type());

在 treeColumns(L261-264)把同样的三行(column.put("name", field.name()); ... applyColumnRender(column, field.type());)替换为:

            ObjectNode column = columns.addObject();
            column.put("name", listColumnName(field));
            column.put("label", field.label());
            applyColumnRender(column, field.type());

在 applyColumnRender(L135-157)的 switch 中,在 case "datetime" 之后、default 之前插入 reference 分支:

            case "reference" -> {
                // 引用列:列 name 已在 listColumnName 改指 <COL>_DISPLAY__(运行时 _SEARCH 流
                // 经 UserColumnResolver.resolveRows 注入显名)。此处保持纯文本渲染即可,
                // 不引入新 amis 组件类型 → TypedPageSchemaValidator 白名单平凡通过。
            }

在类内(紧邻 applyColumnRender 之后)新增私有方法 listColumnName:

    /**
     * 列表列 name 解析:引用列改指 {@code <COL>_DISPLAY__}(运行时 _SEARCH 流注入显名,house-style,
     * 见 FlowController.resolveRows / PickerController),其余列用原字段名。修「引用列显裸 id」。
     */
    private static String listColumnName(PageBlueprintField field) {
        if ("reference".equals(field.type()) && field.name() != null && !field.name().isBlank()) {
            return field.name() + "_DISPLAY__";
        }
        return field.name();
    }

validate(L378-417)无需改:它不校验 field.type() 的枚举取值;reference 走 controlType 的 default → input-text 表单控件(合理,引用 id 用文本录入;真正的引用 picker 由第 1 节建模器在新建期完成,超出 compiler v1 范围)。

Step 8.4 — 运行,预期 PASS(含既有用例不回归)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=PageBlueprintCompilerTest

预期 PASS(既有 4 用例 + 新 referenceColumnRendersDisplayName 全绿;非引用列 name 不变,listColumnName 对它们返回原名)。

Step 8.5 — 提交

git add eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompiler.java \
        eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompilerTest.java
git commit -m "feat(design): 编译器引用列渲染显名·list 列 name 指向 <COL>_DISPLAY__(运行时 _SEARCH 注入,白名单安全)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 9 · 端到端接线:composer 透传引用字段 → 编译触发显名渲染

确认 Task 7 的 DesignFeatureController 把 EntityAttribute.referenceTable 喂进 RecipePageComposer.AttrSpec,从而 type=reference 的列经 Task 8 渲染显名——端到端 compose 一张含引用列的页,断言列显名。

Files:

  • Test (modify) /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/schema/blueprint/RecipePageComposerTest.java
  • (仅必要时)Modify RecipePageComposer.toBlueprint:确保引用属性 type 透传为 "reference"。Task 6 已把 attr.type() 直接透传到 PageBlueprintField.type,故只要 AttrSpec.type=="reference" 即生效——本任务主要是端到端断言该链路。

Step 9.1 — 写失败/验证测试(compose 含引用列的页 → 列显名 <COL>_DISPLAY__)

在 RecipePageComposerTest.java 末尾(最后一个 } 之前)追加:

    @Test
    @DisplayName("4. 端到端: compose 含 reference 列的页 → list 列 name 显名 <COL>_DISPLAY__")
    void composeRendersReferenceDisplayEndToEnd() {
        RecipePageComposer.Spec spec = new RecipePageComposer.Spec(
                "EIP4AI_ORDER", "订单", PageBlueprint.RECIPE_MAINTENANCE_CRUD,
                "订单维护", "ORDERNO", 20,
                List.of(
                        new RecipePageComposer.AttrSpec("ORDERNO", "订单号", "string", true, null, null),
                        // 引用列:referenceTable 非空 + type=reference(端点层从 EntityAttribute 透传而来)
                        new RecipePageComposer.AttrSpec("CUSTOMERID", "客户", "reference", false,
                                "EIP4AI_CUSTOMER", "NAME")));

        ObjectNode page = composer.compose(spec);
        ArrayNode columns = (ArrayNode) page.path("body").path("columns");

        assertEquals("ORDERNO", columns.get(0).path("name").asText());
        assertEquals("CUSTOMERID_DISPLAY__", columns.get(1).path("name").asText());
        assertEquals("客户", columns.get(1).path("label").asText());
    }

需在该测试文件顶部确认已 import com.fasterxml.jackson.databind.node.ArrayNode;(Task 6 的测试已用 ArrayNode,应已存在;若缺则补该 import)。

Step 9.2 — 运行,预期 PASS(Task 6+8 已铺好链路)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=RecipePageComposerTest

预期 PASS。若 FAIL(列 name 仍是 CUSTOMERID),原因只可能是 toBlueprint 未透传 type——核对 Task 6 的 toBlueprint 中 new PageBlueprintField(..., attr.type(), ...) 确实用 attr.type() 原值(应已如此),修正后重跑。

Step 9.3 — 整模块回归(确保引用扩展未破坏任何既有测试)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test

预期 PASS / BUILD SUCCESS(含 PageBlueprintCompilerTest、PageSchemaWriterTest、RecipePageComposerTest、DesignFeatureControllerTest 全绿;platform-ai 的 AiFeatureDraftGenerator 仍用 6-arg 构造,向后兼容编译通过)。

Step 9.4 — (可选实证)启后端手验单步端点

仅当本机有 dev 库时;否则跳过,CI 单测已覆盖契约。

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTests
/opt/homebrew/opt/openjdk@21/bin/java -jar platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=dev

另开终端(admin 已登录拿到 token 后):

curl -s -X POST http://localhost:8093/api/design/recipe/compile \
  -H "Authorization: Bearer <ADMIN_TOKEN>" -H "Content-Type: application/json" \
  -d '{"tableName":"EIP4AI_ORDER","recipe":"maintenance-crud-v1","title":"订单维护","displayField":"ORDERNO"}'

预期返回 {"status":0,...,"data":{"templateId":"design-eip4ai-order-xxxxxxxx","etag":"<64hex>"}};随后 GET /api/page/schema/<templateId> 返回该 amis 页,引用列 name 为 <COL>_DISPLAY__。

Step 9.5 — 提交

git add eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/schema/blueprint/RecipePageComposerTest.java
git commit -m "test(design): 端到端·composer 透传 reference 列→编译显名 <COL>_DISPLAY__

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

本节产出供第 3 节消费:POST /api/design/recipe/compile 返回的 templateId(标准层已存在该页,可直接被设计器 editor.html?templateId= EDIT-ONLY 打开),第 3 节 POST /api/design/publish 接收该 templateId 触发五默认流 + 注册菜单 + 生产部署包(恒人审)。

第 3 节 · 发布编排后端:五流落库 + 菜单注册 + production 部署包(建物 3 后端 + DECISION-2)

本节实现 发布编排后端:用户走完五环点「发布」后,后端一次性完成 (a) 确保实体的 5(+2) 条默认服务流落库、(b) 注册菜单使页面在当前库立即可用、(c)(DECISION-2)生成一份 production 人审部署包。所有标准层写已在 Section 2 经 PageSchemaWriter.upsertStandard 完成,本节不再碰 sys_page_schema。

红线复述(每个 Task 必须守住):发布恒人审(部署包 requiresHumanApproval:true、不在 publish 执行任何生产 SQL);平台进程内不内置 LLM;标准层写唯一真相走 PageSchemaWriter(本节不触碰)。

依赖图事实(决定架构):platform-ai → depends-on → platform-metadata(反向不可)。AI 链的部署包生成器 AiAgentService.createDeploymentPackage(taskId,changeSetId) 强绑定 AiTask/AiChangeSet/AiRunRecord,无法从 platform-metadata 调用。因此本节在 platform-metadata 内新建自包含 DeploymentPackageBuilder,产出与 AiDeploymentPackage 同形的 record。这是 DECISION-2「reuse the AI chain generator」在依赖约束下的落地形态——同形复刻而非跨模块调用(见 risksOrGaps follow-up)。

前置(Section 2 产物):platform-metadata 已存在 com.eip4.platform.metadata.web.DesignFeatureController,@RestController @RequestMapping("/api/design"),构造注入 JdbcTemplate,私有 requireAdmin() / currentUserId()(复制自 AdminWriteController 第 665-690 行)。本节向其追加端点与依赖。


Task 10 — GET /api/design/flows:列出实体的 5(+2) 条默认流供人工确认

Files:

  • Create: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DefaultFlowPreviewService.java(合成预览/持久态读取,纯 JdbcTemplate,可单测)
  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java(追加 @GetMapping("/flows") + 构造器追加 DefaultFlowPreviewService 依赖)
  • Test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/publish/DefaultFlowPreviewServiceTest.java

设计:flowName 即 DefaultFlowHelper 里的 Flow id(tableName + "_ADD" 等),在 SYS_SERVICEFLOW 中等于主键 sys_serviceflow_id。persisted=false 时由实体的 tableName + 是否含 STATUS 列合成 5 或 7 个名字(不依赖保真层重型 POInfo,用列存在性 SQL 判断);persisted=true 时从 SYS_SERVICEFLOW WHERE entityid=? 读真实行。

Step 10.1 — 写失败单测(合成预览:无 STATUS 列 → 5 条)

写 DefaultFlowPreviewServiceTest.java:

package com.eip4.platform.metadata.publish;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;

import java.util.List;

import org.junit.jupiter.api.Test;
import org.springframework.jdbc.core.JdbcTemplate;

class DefaultFlowPreviewServiceTest {

    @Test
    void synthesizesFiveFlowsWhenNoServiceflowAndNoStatusColumn() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        // 无持久流
        when(jdbc.queryForObject(
                eq("SELECT COUNT(*) FROM SYS_SERVICEFLOW WHERE entityid=?"),
                eq(Integer.class), eq("ENT-1"))).thenReturn(0);
        // 实体表名
        when(jdbc.queryForObject(
                eq("SELECT TRIM(tablename) FROM SYS_ENTITY WHERE TRIM(sys_entity_id)=?"),
                eq(String.class), eq("ENT-1"))).thenReturn("DEMO_TBL");
        // 无 STATUS 列
        when(jdbc.queryForObject(
                eq("SELECT COUNT(*) FROM SYS_ENTITYATTRIBUTE WHERE entityid=? AND UPPER(TRIM(columnname))='STATUS'"),
                eq(Integer.class), eq("ENT-1"))).thenReturn(0);

        DefaultFlowPreviewService svc = new DefaultFlowPreviewService(jdbc);
        DefaultFlowPreviewService.FlowsPreview preview = svc.preview("ENT-1");

        assertThat(preview.persisted()).isFalse();
        assertThat(preview.tableName()).isEqualTo("DEMO_TBL");
        assertThat(preview.flows()).extracting(DefaultFlowPreviewService.FlowItem::flowName)
                .containsExactly("DEMO_TBL_ADD", "DEMO_TBL_DELETE", "DEMO_TBL_UPDATE",
                        "DEMO_TBL_SEARCH", "DEMO_TBL_LOAD");
        assertThat(preview.flows().get(0).kind()).isEqualTo("ADD");
    }
}

Step 10.2 — 运行,确认 FAIL(类不存在)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=DefaultFlowPreviewServiceTest

预期 FAIL,编译错误:cannot find symbol: class DefaultFlowPreviewService(程序包 com.eip4.platform.metadata.publish 不存在 / 符号: 类 DefaultFlowPreviewService)。

Step 10.3 — 实现 DefaultFlowPreviewService(完整代码)

写 /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DefaultFlowPreviewService.java:

package com.eip4.platform.metadata.publish;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;

/**
 * 默认服务流「预览/持久态」读取(建物 3 · 发布前人工确认)。
 *
 * <p>flowName 与 {@link com.dsasp.server.core.service.flow.model.DefaultFlowHelper}
 * 的 Flow id 完全一致({@code <TABLE>_ADD} 等),在 SYS_SERVICEFLOW 中即主键 sys_serviceflow_id。
 *
 * <ul>
 *   <li>实体尚无流(SYS_SERVICEFLOW 无 entityid 行)→ 返回合成名预览,
 *       含 STATUS 列时 +2(SUBMIT / SAVE_AND_SUBMIT)。</li>
 *   <li>实体已有流 → 从 SYS_SERVICEFLOW 读真实行(sys_serviceflow_id + displayname)。</li>
 * </ul>
 *
 * <p>不引入保真层重型 POInfo:STATUS 列存在性用元数据 SQL 判断,避免预览阶段触发 POInfo 缓存。
 */
@Service
public class DefaultFlowPreviewService {

    /** 5 个基础流 + 2 个 STATUS 提交流的有序后缀 → kind 映射。 */
    private static final String[][] BASE_FLOWS = {
            {"_ADD", "ADD", "新增"},
            {"_DELETE", "DELETE", "删除"},
            {"_UPDATE", "UPDATE", "更新"},
            {"_SEARCH", "SEARCH", "查询"},
            {"_LOAD", "LOAD", "加载"},
    };
    private static final String[][] STATUS_FLOWS = {
            {"_SUBMIT", "SUBMIT", "提交审批"},
            {"_SAVE_AND_SUBMIT", "SAVE_AND_SUBMIT", "保存并提交审批"},
    };

    private final JdbcTemplate jdbcTemplate;

    public DefaultFlowPreviewService(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    public record FlowItem(String flowName, String displayName, String kind) {}

    public record FlowsPreview(String entityId, String tableName, boolean persisted, List<FlowItem> flows) {}

    public FlowsPreview preview(String entityId) {
        Integer existing = jdbcTemplate.queryForObject(
                "SELECT COUNT(*) FROM SYS_SERVICEFLOW WHERE entityid=?", Integer.class, entityId);
        String tableName = jdbcTemplate.queryForObject(
                "SELECT TRIM(tablename) FROM SYS_ENTITY WHERE TRIM(sys_entity_id)=?", String.class, entityId);
        if (existing != null && existing >= 1) {
            return new FlowsPreview(entityId, tableName, true, persistedFlows(entityId));
        }
        return new FlowsPreview(entityId, tableName, false, synthesizedFlows(entityId, tableName));
    }

    private List<FlowItem> synthesizedFlows(String entityId, String tableName) {
        List<FlowItem> out = new ArrayList<>();
        for (String[] f : BASE_FLOWS) {
            out.add(new FlowItem(tableName + f[0], tableName + " " + f[2], f[1]));
        }
        Integer hasStatus = jdbcTemplate.queryForObject(
                "SELECT COUNT(*) FROM SYS_ENTITYATTRIBUTE WHERE entityid=? AND UPPER(TRIM(columnname))='STATUS'",
                Integer.class, entityId);
        if (hasStatus != null && hasStatus >= 1) {
            for (String[] f : STATUS_FLOWS) {
                out.add(new FlowItem(tableName + f[0], tableName + " " + f[2], f[1]));
            }
        }
        return out;
    }

    private List<FlowItem> persistedFlows(String entityId) {
        List<Map<String, Object>> rows = jdbcTemplate.queryForList(
                "SELECT TRIM(sys_serviceflow_id) AS fid, displayname FROM SYS_SERVICEFLOW WHERE entityid=?"
                        + " ORDER BY sys_serviceflow_id", entityId);
        List<FlowItem> out = new ArrayList<>();
        for (Map<String, Object> r : rows) {
            String fid = String.valueOf(r.get("fid"));
            String display = r.get("displayname") == null ? fid : String.valueOf(r.get("displayname"));
            out.add(new FlowItem(fid, display, kindOf(fid)));
        }
        return out;
    }

    private static String kindOf(String flowName) {
        int us = flowName.indexOf('_');
        if (us < 0) {
            return "UNKNOWN";
        }
        return flowName.substring(us + 1);
    }
}

Step 10.4 — 运行,确认 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=DefaultFlowPreviewServiceTest

预期 PASS(BUILD SUCCESS, Tests run: 1, Failures: 0)。

Step 10.5 — 追加第二个单测(含 STATUS → 7 条)

在 DefaultFlowPreviewServiceTest 追加:

    @Test
    void synthesizesSevenFlowsWhenStatusColumnPresent() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        when(jdbc.queryForObject(
                eq("SELECT COUNT(*) FROM SYS_SERVICEFLOW WHERE entityid=?"),
                eq(Integer.class), eq("ENT-2"))).thenReturn(0);
        when(jdbc.queryForObject(
                eq("SELECT TRIM(tablename) FROM SYS_ENTITY WHERE TRIM(sys_entity_id)=?"),
                eq(String.class), eq("ENT-2"))).thenReturn("OA_DOC");
        when(jdbc.queryForObject(
                eq("SELECT COUNT(*) FROM SYS_ENTITYATTRIBUTE WHERE entityid=? AND UPPER(TRIM(columnname))='STATUS'"),
                eq(Integer.class), eq("ENT-2"))).thenReturn(1);

        DefaultFlowPreviewService.FlowsPreview p = new DefaultFlowPreviewService(jdbc).preview("ENT-2");
        assertThat(p.flows()).extracting(DefaultFlowPreviewService.FlowItem::flowName)
                .contains("OA_DOC_SUBMIT", "OA_DOC_SAVE_AND_SUBMIT");
        assertThat(p.flows()).hasSize(7);
    }

运行同命令,预期两个测试均 PASS。

Step 10.6 — 在 DesignFeatureController 追加 GET /flows

先看构造器现状(Section 2 产物):

JAVA_HOME=/opt/homebrew/opt/openjdk@21 grep -n "DesignFeatureController(" /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java

向构造器追加 DefaultFlowPreviewService 字段与赋值(按 Section 2 实际签名定位插入点),并新增端点方法:

    @org.springframework.web.bind.annotation.GetMapping("/flows")
    public Map<String, Object> flows(@org.springframework.web.bind.annotation.RequestParam("entityId") String entityId) {
        requireAdmin();
        DefaultFlowPreviewService.FlowsPreview p = flowPreviewService.preview(entityId);
        java.util.List<Map<String, Object>> flowList = new java.util.ArrayList<>();
        for (DefaultFlowPreviewService.FlowItem f : p.flows()) {
            Map<String, Object> m = new java.util.LinkedHashMap<>();
            m.put("flowName", f.flowName());
            m.put("displayName", f.displayName());
            m.put("kind", f.kind());
            flowList.add(m);
        }
        Map<String, Object> data = new java.util.LinkedHashMap<>();
        data.put("entityId", p.entityId());
        data.put("tableName", p.tableName());
        data.put("persisted", p.persisted());
        data.put("flows", flowList);
        Map<String, Object> resp = new java.util.LinkedHashMap<>();
        resp.put("status", 0);
        resp.put("data", data);
        return resp;
    }

(flowPreviewService 为构造注入的 DefaultFlowPreviewService 字段。)

Step 10.7 — 编译校验

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test-compile

预期 BUILD SUCCESS。

Step 10.8 — 提交

git add platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DefaultFlowPreviewService.java \
        platform-metadata/src/test/java/com/eip4/platform/metadata/publish/DefaultFlowPreviewServiceTest.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java
git commit -m "feat(design): GET /api/design/flows 列出实体默认流预览(建物3-Task10)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 11 — POST /api/design/publish:确保 5(+2) 条默认流落库(幂等)

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java(追加 @PostMapping("/publish") + 构造器追加 FlowServiceWithSynthesis 依赖)
  • Test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/publish/PublishFlowEnsureTest.java

FlowServiceWithSynthesis(@Primary @Component implements FlowService,构造 FlowServiceImpl delegate, SynthesizedFlowRegistry registry)已有 addDefaultFlowService(entityId, ctx),委托 FlowServiceImpl.addDefaultFlowService:已存在则返回 false(幂等),否则按 DefaultFlowHelper.getDefaultFlowService 写 5(+2) 条到 SYS_SERVICEFLOW 并返回 true。本节用 UserSession.getAdmin() 取 ctx(与 MetaController:72 同法)。

Step 11.1 — 写失败单测(验证 publish 调用 addDefaultFlowService 并回传 flowsCreated)

写 PublishFlowEnsureTest.java(对 publish 的「确保流」子逻辑做纯单元 — 抽到一个 package 私有 helper PublishOrchestrator 便于单测;helper 在 Task 12/13 继续承载菜单与部署包):

package com.eip4.platform.metadata.publish;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

import java.util.Properties;

import org.junit.jupiter.api.Test;

import com.eip4.platform.metadata.flow.FlowServiceWithSynthesis;

class PublishFlowEnsureTest {

    @Test
    void ensureFlowsDelegatesToAddDefaultFlowServiceAndReportsCreated() {
        FlowServiceWithSynthesis flowService = mock(FlowServiceWithSynthesis.class);
        when(flowService.addDefaultFlowService(eq("ENT-9"), any(Properties.class))).thenReturn(true);

        PublishOrchestrator orch = new PublishOrchestrator(flowService, null, null);
        boolean created = orch.ensureFlows("ENT-9");

        assertThat(created).isTrue();
        verify(flowService).addDefaultFlowService(eq("ENT-9"), any(Properties.class));
    }

    @Test
    void ensureFlowsReturnsFalseWhenFlowsAlreadyPresent() {
        FlowServiceWithSynthesis flowService = mock(FlowServiceWithSynthesis.class);
        when(flowService.addDefaultFlowService(eq("ENT-9"), any(Properties.class))).thenReturn(false);

        PublishOrchestrator orch = new PublishOrchestrator(flowService, null, null);
        assertThat(orch.ensureFlows("ENT-9")).isFalse();
    }
}

Step 11.2 — 运行,确认 FAIL(PublishOrchestrator 不存在)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=PublishFlowEnsureTest

预期 FAIL:cannot find symbol: class PublishOrchestrator。

Step 11.3 — 创建 PublishOrchestrator(先只实现 ensureFlows)

写 /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/PublishOrchestrator.java:

package com.eip4.platform.metadata.publish;

import java.util.Properties;

import org.springframework.stereotype.Service;

import com.dsasp.server.common.util.UserSession;
import com.eip4.platform.metadata.flow.FlowServiceWithSynthesis;

/**
 * 发布编排(建物 3):发布按钮一次性完成 ①确保默认流落库 ②注册菜单 ③生成 production 部署包。
 *
 * <p>红线:本类只 live-apply 到当前连接库(菜单/流),生产部署包恒人审、不在此执行生产 SQL。
 */
@Service
public class PublishOrchestrator {

    private final FlowServiceWithSynthesis flowService;
    private final MenuRegistrar menuRegistrar;             // Task 12 注入
    private final DeploymentPackageBuilder deploymentPackageBuilder; // Task 13 注入

    public PublishOrchestrator(FlowServiceWithSynthesis flowService,
                               MenuRegistrar menuRegistrar,
                               DeploymentPackageBuilder deploymentPackageBuilder) {
        this.flowService = flowService;
        this.menuRegistrar = menuRegistrar;
        this.deploymentPackageBuilder = deploymentPackageBuilder;
    }

    /**
     * 确保实体的 5(+2) 条默认服务流落库(幂等)。
     *
     * @return true 表示本次新建了默认流;false 表示实体已有流(幂等无操作)。
     */
    public boolean ensureFlows(String entityId) {
        Properties ctx = UserSession.getAdmin();
        return flowService.addDefaultFlowService(entityId, ctx);
    }
}

注意:构造器形参 MenuRegistrar / DeploymentPackageBuilder 在 Task 12/13 才创建。为让 Task 11 单测先编译通过,本步同时创建两个最小空壳类(Task 12/13 会替换其实现):

/Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/MenuRegistrar.java:

package com.eip4.platform.metadata.publish;

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;

/** 平台内菜单注册唯一入口(Task 12 实现)。 */
@Service
public class MenuRegistrar {
    private final JdbcTemplate jdbcTemplate;
    public MenuRegistrar(JdbcTemplate jdbcTemplate) { this.jdbcTemplate = jdbcTemplate; }
}

/Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DeploymentPackageBuilder.java:

package com.eip4.platform.metadata.publish;

import org.springframework.stereotype.Service;

/** 平台内自包含部署包生成器(Task 13 实现)。 */
@Service
public class DeploymentPackageBuilder {
}

Step 11.4 — 运行,确认 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=PublishFlowEnsureTest

预期 PASS(Tests run: 2, Failures: 0)。

Step 11.5 — 在 DesignFeatureController 追加 POST /publish(最小版:仅 ensureFlows)

构造器追加 PublishOrchestrator publishOrchestrator 字段与赋值;追加端点:

    @org.springframework.web.bind.annotation.PostMapping("/publish")
    public Map<String, Object> publish(@org.springframework.web.bind.annotation.RequestBody Map<String, Object> body) {
        requireAdmin();
        String entityId = requireDesignString(body, "entityId");
        String tableName = requireDesignString(body, "tableName");
        String templateId = requireDesignString(body, "templateId");
        String menuName = requireDesignString(body, "menuName");
        String operator = currentUserId();

        boolean flowsCreated = publishOrchestrator.ensureFlows(entityId);

        Map<String, Object> data = new java.util.LinkedHashMap<>();
        data.put("entityId", entityId);
        data.put("tableName", tableName);
        data.put("templateId", templateId);
        data.put("flowsCreated", flowsCreated);
        data.put("flows", publishOrchestrator.flowNames(entityId));
        // menuId / deploymentPackage 由 Task 12 / 13 补齐
        Map<String, Object> resp = new java.util.LinkedHashMap<>();
        resp.put("status", 0);
        resp.put("data", data);
        return resp;
    }

    private String requireDesignString(Map<String, Object> body, String key) {
        Object v = body.get(key);
        if (v == null || v.toString().isBlank()) {
            throw new org.springframework.web.server.ResponseStatusException(
                    org.springframework.http.HttpStatus.BAD_REQUEST, "缺少必填参数: " + key);
        }
        return v.toString().trim();
    }

在 PublishOrchestrator 追加 flowNames 便于响应回填(复用 Task 10 的 DefaultFlowPreviewService 会引入循环,故直接读库):

    /** 返回实体当前持久化的流名列表(发布后读 SYS_SERVICEFLOW)。 */
    public java.util.List<String> flowNames(String entityId) {
        // 用 flowService.delegate 不可达;直接由 PublishOrchestrator 持有的 JdbcTemplate 读。
        return flowNameReader.apply(entityId);
    }

为避免 PublishOrchestrator 直接依赖 JdbcTemplate 与 Task 10 服务循环,改为构造注入 DefaultFlowPreviewService。修订 PublishOrchestrator 构造器与 ensureFlows 单测:构造器签名调整为 (FlowServiceWithSynthesis, MenuRegistrar, DeploymentPackageBuilder, DefaultFlowPreviewService),单测第 4 参数传 mock(DefaultFlowPreviewService.class)(或 null,flowNames 不在本测试触发)。flowNames 实现:

    public java.util.List<String> flowNames(String entityId) {
        java.util.List<String> out = new java.util.ArrayList<>();
        for (DefaultFlowPreviewService.FlowItem f : flowPreviewService.preview(entityId).flows()) {
            out.add(f.flowName());
        }
        return out;
    }

同步把 PublishFlowEnsureTest 两处 new PublishOrchestrator(flowService, null, null) 改为 new PublishOrchestrator(flowService, null, null, null)。

Step 11.6 — 编译 + 重跑单测

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=PublishFlowEnsureTest

预期 PASS。

Step 11.7 — 提交

git add platform-metadata/src/main/java/com/eip4/platform/metadata/publish/PublishOrchestrator.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/publish/MenuRegistrar.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DeploymentPackageBuilder.java \
        platform-metadata/src/test/java/com/eip4/platform/metadata/publish/PublishFlowEnsureTest.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java
git commit -m "feat(design): POST /api/design/publish 确保默认流落库(幂等)(建物3-Task11)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 12 — 菜单注册:MenuRegistrar(dedup by view_templateid + ensure '新功能' 顶级目录)

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/MenuRegistrar.java(实现 register + ensureNewFeatureParent,镜像 AiLocalReleaseExecutor.applyMenu/ensureAiMenuParent 第 162-249 行)
  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/PublishOrchestrator.java(publish 调 menuRegistrar.register,回填 menuId)
  • Modify: DesignFeatureController.java(publish 响应补 menuId)
  • Test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/publish/MenuRegistrarTest.java

镜像 AiLocalReleaseExecutor:dedup 查 SELECT TRIM(sys_menu_id) FROM sys_menu WHERE TRIM(view_templateid)=? AND isactive=1,命中则 UPDATE、否则 INSERT;parentMenuId 为空时 ensure 顶级目录(AI 链用 'AI Agent',本节用 '新功能',与人走五环语义对齐)。ensureNewFeatureParent 缺 sys_menu_root 时抛 409(同款)。

Step 12.1 — 写失败单测(首次 register → INSERT 一行,返回 menuId)

写 MenuRegistrarTest.java:

package com.eip4.platform.metadata.publish;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.times;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

import java.util.List;

import org.junit.jupiter.api.Test;
import org.springframework.jdbc.core.JdbcTemplate;

class MenuRegistrarTest {

    @Test
    void firstRegisterInsertsOneRowUnderNewFeatureParent() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        // dedup 查:无现有菜单
        when(jdbc.queryForList(
                eq("SELECT TRIM(sys_menu_id) FROM sys_menu WHERE TRIM(view_templateid)=? AND isactive=1"),
                eq(String.class), eq("TPL-1"))).thenReturn(List.of());
        // ensure '新功能' 目录:已存在,返回其 id
        when(jdbc.queryForList(
                eq("SELECT TRIM(sys_menu_id) FROM sys_menu WHERE name='新功能' AND parentid IS NULL AND isactive=1 ORDER BY seq LIMIT 1"),
                eq(String.class))).thenReturn(List.of("DIR-NEW"));
        when(jdbc.queryForList(
                eq("SELECT TRIM(menuroot) FROM sys_menu WHERE TRIM(sys_menu_id)=?"),
                eq(String.class), eq("DIR-NEW"))).thenReturn(List.of("ROOT-1"));

        MenuRegistrar reg = new MenuRegistrar(jdbc);
        String menuId = reg.register("TPL-1", "演示功能", null, "admin");

        assertThat(menuId).isNotBlank();
        // 校验 INSERT 被调用一次(参数含 templateId)
        verify(jdbc, times(1)).update(
                anyString(),
                eq(menuId), eq("演示功能"), eq("DIR-NEW"), eq("TPL-1"),
                anyString(), eq("ROOT-1"), any(), any(), any(), any());
    }

    @Test
    void republishDedupsByTemplateIdAndUpdatesInsteadOfInsert() {
        JdbcTemplate jdbc = mock(JdbcTemplate.class);
        when(jdbc.queryForList(
                eq("SELECT TRIM(sys_menu_id) FROM sys_menu WHERE TRIM(view_templateid)=? AND isactive=1"),
                eq(String.class), eq("TPL-1"))).thenReturn(List.of("MENU-EXIST"));

        MenuRegistrar reg = new MenuRegistrar(jdbc);
        String menuId = reg.register("TPL-1", "演示功能改名", null, "admin");

        assertThat(menuId).isEqualTo("MENU-EXIST");
        // 命中 → 不查 '新功能' 目录、不 INSERT,只 UPDATE
        verify(jdbc, times(1)).update(
                org.mockito.ArgumentMatchers.contains("UPDATE sys_menu"),
                eq("演示功能改名"), eq("TPL-1"), any(), any(), eq("MENU-EXIST"));
    }
}

Step 12.2 — 运行,确认 FAIL(register 不存在)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MenuRegistrarTest

预期 FAIL:cannot find symbol: method register(...)。

Step 12.3 — 实现 MenuRegistrar(完整代码)

替换 MenuRegistrar.java:

package com.eip4.platform.metadata.publish;

import java.util.List;
import java.util.UUID;

import org.springframework.http.HttpStatus;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;

/**
 * 平台内菜单注册唯一入口(建物 3 · 发布编排)。
 *
 * <p>镜像 {@code AiLocalReleaseExecutor.applyMenu / ensureAiMenuParent}:
 * dedup by view_templateid(同一页面只挂一条菜单,重复发布走 UPDATE 而非新建),
 * parentMenuId 为空时自动 ensure/复用顶级目录「新功能」(人走五环语义;AI 链用「AI Agent」)。
 */
@Service
public class MenuRegistrar {

    private static final String NEW_FEATURE_DIR = "新功能";

    private final JdbcTemplate jdbcTemplate;

    public MenuRegistrar(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    /**
     * 注册/更新功能菜单。
     *
     * @param templateId   页面标准层 templateId(写入 sys_menu.view_templateid)
     * @param menuName     菜单显示名
     * @param parentMenuId 上级菜单 id;为空则自动挂到「新功能」顶级目录
     * @param operator     操作人(写入 createby/updateby)
     * @return sys_menu_id(新建则为新 UUID,命中则为既有 id)—— 幂等保证
     */
    public String register(String templateId, String menuName, String parentMenuId, String operator) {
        List<String> existing = jdbcTemplate.queryForList(
                "SELECT TRIM(sys_menu_id) FROM sys_menu WHERE TRIM(view_templateid)=? AND isactive=1",
                String.class, templateId);
        long now = System.currentTimeMillis();
        if (!existing.isEmpty()) {
            String menuId = existing.get(0);
            jdbcTemplate.update(
                    "UPDATE sys_menu SET name=?, view_templateid=?, updatetime=?, updateby=?, version=version+1"
                            + " WHERE TRIM(sys_menu_id)=?",
                    menuName, templateId, now, operator, menuId);
            return menuId;
        }

        String parentId = parentMenuId;
        String menuRoot = null;
        if (parentId == null || parentId.isBlank()) {
            ParentMenu parent = ensureNewFeatureParent();
            parentId = parent.parentId();
            menuRoot = parent.menuRoot();
        } else {
            List<String> roots = jdbcTemplate.queryForList(
                    "SELECT TRIM(menuroot) FROM sys_menu WHERE TRIM(sys_menu_id)=?", String.class, parentId);
            menuRoot = roots.isEmpty() ? null : roots.get(0);
        }

        String menuId = UUID.randomUUID().toString();
        jdbcTemplate.update(
                "INSERT INTO sys_menu(sys_menu_id, name, parentid, view_templateid, typename, menuroot, seq,"
                        + " isactive, version, createtime, createby, updatetime, updateby)"
                        + " VALUES(?,?,?,?,?,?,?,1,0,?,?,?,?)",
                menuId, menuName, parentId, templateId, "功能菜单",
                (menuRoot == null || menuRoot.isBlank()) ? null : menuRoot, 0,
                now, operator, now, operator);
        return menuId;
    }

    private ParentMenu ensureNewFeatureParent() {
        List<String> existingDir = jdbcTemplate.queryForList(
                "SELECT TRIM(sys_menu_id) FROM sys_menu WHERE name='" + NEW_FEATURE_DIR
                        + "' AND parentid IS NULL AND isactive=1 ORDER BY seq LIMIT 1",
                String.class);
        if (!existingDir.isEmpty()) {
            List<String> roots = jdbcTemplate.queryForList(
                    "SELECT TRIM(menuroot) FROM sys_menu WHERE TRIM(sys_menu_id)=?",
                    String.class, existingDir.get(0));
            return new ParentMenu(existingDir.get(0), roots.isEmpty() ? "" : roots.get(0));
        }
        List<String> roots = jdbcTemplate.queryForList(
                "SELECT TRIM(sys_menu_root_id) FROM sys_menu_root WHERE isactive=1 ORDER BY seq LIMIT 1",
                String.class);
        if (roots.isEmpty()) {
            throw new ResponseStatusException(HttpStatus.CONFLICT, "缺少 sys_menu_root,不能自动挂载菜单");
        }
        String root = roots.get(0);
        String dirId = UUID.randomUUID().toString();
        long now = System.currentTimeMillis();
        jdbcTemplate.update(
                "INSERT INTO sys_menu(sys_menu_id, name, parentid, view_templateid, typename, menuroot, seq,"
                        + " isactive, version, createtime, createby, updatetime, updateby)"
                        + " VALUES(?,?,NULL,NULL,?,?,?,1,0,?,?,?,?)",
                dirId, NEW_FEATURE_DIR, "目录", root, 9999, now, "DESIGN_PUBLISH", now, "DESIGN_PUBLISH");
        return new ParentMenu(dirId, root);
    }

    private record ParentMenu(String parentId, String menuRoot) {}
}

注意单测 12.1 的 INSERT verify 参数顺序须与实现一致:menuId, menuName, parentId, templateId, "功能菜单", menuRoot, 0, now, operator, now, operator —— 共 11 个占位参数。单测里 update(anyString(), eq(menuId), eq("演示功能"), eq("DIR-NEW"), eq("TPL-1"), anyString()/*typename*/, eq("ROOT-1")/*menuroot*/, any()/*seq*/, any()/*now*/, any()/*operator*/, any()...)。若占位数不符,按实现的 11 参数补齐 verify。UPDATE verify 同理对齐到 5 个绑定参数 name, view_templateid, updatetime, updateby, menuId。

Step 12.4 — 运行,确认 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MenuRegistrarTest

预期 PASS(Tests run: 2, Failures: 0)。若 verify 参数数不符报 Argument(s) are different,按实现实际 11/5 参数修正 verify 后重跑。

Step 12.5 — PublishOrchestrator 接线 menuRegistrar + 在 publish 回填 menuId

在 PublishOrchestrator 追加:

    /** 注册/更新功能菜单,返回 sys_menu_id。 */
    public String registerMenu(String templateId, String menuName, String parentMenuId, String operator) {
        return menuRegistrar.register(templateId, menuName, parentMenuId, operator);
    }

在 DesignFeatureController.publish 的 data.put("flows", ...) 之后补:

        String parentMenuId = body.get("parentMenuId") == null ? null : body.get("parentMenuId").toString().trim();
        String menuId = publishOrchestrator.registerMenu(templateId, menuName, parentMenuId, operator);
        data.put("menuId", menuId);

Step 12.6 — 编译校验

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test-compile

预期 BUILD SUCCESS。

Step 12.7 — 提交

git add platform-metadata/src/main/java/com/eip4/platform/metadata/publish/MenuRegistrar.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/publish/PublishOrchestrator.java \
        platform-metadata/src/test/java/com/eip4/platform/metadata/publish/MenuRegistrarTest.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java
git commit -m "feat(design): publish 菜单注册 MenuRegistrar(dedup+新功能目录)(建物3-Task12)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 13 — production 部署包:DeploymentPackageBuilder(manifest + SQL 草稿 + rollback,requiresHumanApproval=true)

Files:

  • Create: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DeploymentPackage.java(record,与 AiDeploymentPackage 同形精简版)
  • Modify: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DeploymentPackageBuilder.java(实现 build)
  • Modify: PublishOrchestrator.java(generateDeploymentPackage != false 时 build)
  • Modify: DesignFeatureController.java(publish 响应补 deploymentPackage;默认 generate=true)
  • Test: /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/test/java/com/eip4/platform/metadata/publish/DeploymentPackageBuilderTest.java

架构决定(见 risksOrGaps):AI 链 AiAgentService.createDeploymentPackage 强绑 AiTask/AiChangeSet/AiRunRecord 且 platform-metadata 在 platform-ai 之下,不可复用。本节在 platform-metadata 内自包含构建,从 {entityId,templateId,tableName,flows,menuId,parentMenuId} 合成 change-set,产出与 AiDeploymentPackage 同形的 record(status READY_FOR_HUMAN_REVIEW、requiresHumanApproval=true、manifest、sqlStatements、rollbackSqlStatements、warnings)。SQL 含:entity DDL 提示、sys_page_schema upsert、serviceflow inserts、sys_menu insert;rollback 对称。不在 publish 时执行这些生产 SQL——纯草稿。

Step 13.1 — 写失败单测(build 产出 manifest+rollback 且 requiresHumanApproval=true)

写 DeploymentPackageBuilderTest.java:

package com.eip4.platform.metadata.publish;

import static org.assertj.core.api.Assertions.assertThat;

import java.util.List;

import org.junit.jupiter.api.Test;

class DeploymentPackageBuilderTest {

    @Test
    void buildProducesManifestRollbackAndRequiresHumanApproval() {
        DeploymentPackageBuilder builder = new DeploymentPackageBuilder();
        DeploymentPackageBuilder.Input input = new DeploymentPackageBuilder.Input(
                "ENT-1", "DEMO_TBL", "TPL-1", "演示功能", "MENU-1",
                List.of("DEMO_TBL_ADD", "DEMO_TBL_UPDATE", "DEMO_TBL_SEARCH",
                        "DEMO_TBL_DELETE", "DEMO_TBL_LOAD"));

        DeploymentPackage pkg = builder.build(input);

        assertThat(pkg.requiresHumanApproval()).isTrue();
        assertThat(pkg.status()).isEqualTo("READY_FOR_HUMAN_REVIEW");
        assertThat(pkg.manifest()).containsKeys("entityId", "templateId", "tableName", "menuId", "flowCount");
        assertThat(pkg.manifest().get("flowCount")).isEqualTo(5);
        // SQL 草稿覆盖四类工件
        assertThat(pkg.sqlStatements()).anyMatch(s -> s.contains("sys_page_schema"));
        assertThat(pkg.sqlStatements()).anyMatch(s -> s.contains("sys_serviceflow"));
        assertThat(pkg.sqlStatements()).anyMatch(s -> s.contains("sys_menu"));
        // rollback 对称且含 DELETE
        assertThat(pkg.rollbackSqlStatements()).anyMatch(s -> s.contains("DELETE FROM sys_page_schema"));
        assertThat(pkg.rollbackSqlStatements()).anyMatch(s -> s.contains("DELETE FROM sys_serviceflow"));
        assertThat(pkg.rollbackSqlStatements()).anyMatch(s -> s.contains("sys_menu"));
        // 生产 DDL 由人工补全 → warning
        assertThat(pkg.warnings()).isNotEmpty();
    }
}

Step 13.2 — 运行,确认 FAIL(DeploymentPackage / Input / build 不存在)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=DeploymentPackageBuilderTest

预期 FAIL:cannot find symbol: class DeploymentPackage / class Input / method build。

Step 13.3 — 创建 DeploymentPackage record(与 AiDeploymentPackage 同形精简版)

写 /Users/zhengwr/workspace/eip3/eip4-platform/platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DeploymentPackage.java:

package com.eip4.platform.metadata.publish;

import java.util.List;
import java.util.Map;

/**
 * Production 人审部署包(建物 3 · DECISION-2)。
 *
 * <p>与 platform-ai 的 {@code AiDeploymentPackage} 同形精简版:
 * 不含 taskId/changeSetId/runEvidence(人走五环无 AiTask 上下文),其余字段一致。
 * 恒 requiresHumanApproval=true —— 生产上线走既有人审流程,本包不执行任何生产 SQL。
 */
public record DeploymentPackage(
        String status,
        boolean requiresHumanApproval,
        long generatedAt,
        Map<String, Object> manifest,
        List<String> sqlStatements,
        List<String> rollbackSqlStatements,
        List<String> warnings) {
}

Step 13.4 — 实现 DeploymentPackageBuilder(完整代码)

替换 DeploymentPackageBuilder.java:

package com.eip4.platform.metadata.publish;

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

import org.springframework.stereotype.Service;

/**
 * 平台内自包含 production 部署包生成器(建物 3 · DECISION-2)。
 *
 * <p>不依赖 platform-ai(依赖图:platform-ai → platform-metadata,反向不可)。
 * 从发布编排上下文合成 change-set,产出与 AiDeploymentPackage 同形的 {@link DeploymentPackage}。
 * 产物为 production 人审草稿:manifest + 顺序 SQL(page_schema / serviceflow / menu)+ 对称 rollback。
 * 实体 DDL 因不在此处掌握列定义,以占位 + warning 提示人工补全,恒 requiresHumanApproval=true。
 */
@Service
public class DeploymentPackageBuilder {

    /** 发布编排上下文 → 部署包输入。 */
    public record Input(
            String entityId,
            String tableName,
            String templateId,
            String menuName,
            String menuId,
            List<String> flows) {
    }

    public DeploymentPackage build(Input in) {
        long now = System.currentTimeMillis();

        Map<String, Object> manifest = new LinkedHashMap<>();
        manifest.put("entityId", in.entityId());
        manifest.put("templateId", in.templateId());
        manifest.put("tableName", in.tableName());
        manifest.put("menuId", in.menuId());
        manifest.put("menuName", in.menuName());
        manifest.put("flowCount", in.flows() == null ? 0 : in.flows().size());
        manifest.put("flows", in.flows() == null ? List.of() : List.copyOf(in.flows()));
        manifest.put("generatedAt", now);
        manifest.put("source", "design-publish");

        List<String> sql = new ArrayList<>();
        sql.add("-- [1] 实体 DDL:本平台内 net-new 实体由元数据引擎建表,"
                + "生产环境请人工从源库导出 CREATE TABLE " + in.tableName() + " 及索引后置入此处。");
        sql.add("-- [2] 标准层页面 schema(唯一真相 PageSchemaWriter.upsertStandard 的等价 SQL):");
        sql.add("-- 生产请用导出的 schema JSON 替换 :schemaJson 占位");
        // 列名严格对齐唯一写口 PageSchemaWriter.upsertStandard(PageSchemaWriter.java:65-71):
        // (template_id, name, schema_json, schema_etag, version, update_time) + ON CONFLICT(template_id)。
        // sys_page_schema 无 layer/updateby/updatetime 列,勿用(评审 §B.9-6 已核)。
        sql.add("INSERT INTO sys_page_schema(template_id, name, schema_json, schema_etag, version, update_time)"
                + " VALUES(" + sqlString(in.templateId()) + ", " + sqlString(in.menuName())
                + ", :schemaJson, :schemaEtag, 1, " + now + ")"
                + " ON CONFLICT (template_id) DO UPDATE SET schema_json=EXCLUDED.schema_json,"
                + " schema_etag=EXCLUDED.schema_etag, version=sys_page_schema.version+1,"
                + " update_time=EXCLUDED.update_time;");
        sql.add("-- [3] 默认服务流:生产请用导出的 contentxml 替换 :contentxml 占位");
        if (in.flows() != null) {
            for (String flow : in.flows()) {
                sql.add("INSERT INTO sys_serviceflow(sys_serviceflow_id, displayname, contentxml, entityid)"
                        + " VALUES(" + sqlString(flow) + ", " + sqlString(flow) + ", :contentxml, "
                        + sqlString(in.entityId()) + ")"
                        + " ON CONFLICT (sys_serviceflow_id) DO NOTHING;");
            }
        }
        sql.add("-- [4] 功能菜单:生产请替换 ${parentMenuId}/${menuRoot} 为目标环境的菜单父节点");
        sql.add("INSERT INTO sys_menu(sys_menu_id, name, parentid, view_templateid, typename, menuroot, seq,"
                + " isactive, version, createtime, createby, updatetime, updateby)"
                + " VALUES(" + sqlString(in.menuId()) + ", " + sqlString(in.menuName())
                + ", ${parentMenuId}, " + sqlString(in.templateId()) + ", '功能菜单', ${menuRoot}, 0,"
                + " 1, 0, " + now + ", 'DESIGN_PUBLISH', " + now + ", 'DESIGN_PUBLISH')"
                + " ON CONFLICT (sys_menu_id) DO NOTHING;");

        List<String> rollback = new ArrayList<>();
        rollback.add("UPDATE sys_menu SET isactive=0, updatetime=" + now
                + ", updateby='DESIGN_PUBLISH_ROLLBACK', version=version+1"
                + " WHERE TRIM(view_templateid)=" + sqlString(in.templateId()) + ";");
        rollback.add("DELETE FROM sys_page_schema WHERE template_id=" + sqlString(in.templateId()) + ";");
        if (in.flows() != null && !in.flows().isEmpty()) {
            List<String> quoted = new ArrayList<>();
            for (String flow : in.flows()) {
                quoted.add(sqlString(flow));
            }
            rollback.add("DELETE FROM sys_serviceflow WHERE sys_serviceflow_id IN ("
                    + String.join(", ", quoted) + ");");
        }
        rollback.add("-- 实体 DELETE:人工确认后 DELETE /api/meta/entity/" + in.tableName()
                + "(含物理表 DROP),并清理 SYS_ENTITY/SYS_ENTITYATTRIBUTE 元数据。");

        List<String> warnings = new ArrayList<>();
        warnings.add("实体 DDL 与 schema_json/contentxml 为占位,生产部署前须由人工从本地库导出真实定义置入。");
        warnings.add("sys_menu 的 ${parentMenuId}/${menuRoot} 须替换为生产环境目标菜单父节点。");
        warnings.add("本部署包恒人审:生产上线走既有人工审核流程,平台不自动在生产执行任何 SQL。");

        return new DeploymentPackage(
                "READY_FOR_HUMAN_REVIEW",
                true,
                now,
                manifest,
                List.copyOf(sql),
                List.copyOf(rollback),
                List.copyOf(warnings));
    }

    private static String sqlString(String value) {
        String text = value == null ? "" : value;
        return "'" + text.replace("'", "''") + "'";
    }
}

Step 13.5 — 运行,确认 PASS

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=DeploymentPackageBuilderTest

预期 PASS(Tests run: 1, Failures: 0)。

Step 13.6 — PublishOrchestrator 接线部署包 + DesignFeatureController 回填

在 PublishOrchestrator 追加:

    /** generateDeploymentPackage != false 时生成 production 人审部署包;否则返回 null。 */
    public DeploymentPackage buildDeploymentPackage(String entityId, String tableName, String templateId,
                                                    String menuName, String menuId,
                                                    java.util.List<String> flows, boolean generate) {
        if (!generate) {
            return null;
        }
        return deploymentPackageBuilder.build(new DeploymentPackageBuilder.Input(
                entityId, tableName, templateId, menuName, menuId, flows));
    }

在 DesignFeatureController.publish(menuId 之后)补:

        boolean generatePkg = !(Boolean.FALSE.equals(body.get("generateDeploymentPackage")));
        @SuppressWarnings("unchecked")
        java.util.List<String> flowsForPkg = (java.util.List<String>) data.get("flows");
        DeploymentPackage pkg = publishOrchestrator.buildDeploymentPackage(
                entityId, tableName, templateId, menuName, menuId, flowsForPkg, generatePkg);
        if (pkg != null) {
            Map<String, Object> pkgMap = new java.util.LinkedHashMap<>();
            pkgMap.put("status", pkg.status());
            pkgMap.put("requiresHumanApproval", pkg.requiresHumanApproval());
            pkgMap.put("generatedAt", pkg.generatedAt());
            pkgMap.put("manifest", pkg.manifest());
            pkgMap.put("sqlStatements", pkg.sqlStatements());
            pkgMap.put("rollbackSqlStatements", pkg.rollbackSqlStatements());
            pkgMap.put("warnings", pkg.warnings());
            data.put("deploymentPackage", pkgMap);
        }

import:import com.eip4.platform.metadata.publish.DeploymentPackage;(若控制器与 publish 包不同包则需此 import;同包则免)。

Step 13.7 — 全包单测 + 编译校验

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest='DefaultFlowPreviewServiceTest,PublishFlowEnsureTest,MenuRegistrarTest,DeploymentPackageBuilderTest'

预期全部 PASS(Tests run: 7, Failures: 0),BUILD SUCCESS。

Step 13.8 — 手动验证(可选,需起后端)

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTests && /opt/homebrew/opt/openjdk@21/bin/java -jar platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=dev

另开终端(先用 admin 登录拿 token,再带 Bearer):

# 预览流
curl -s 'http://localhost:8093/api/design/flows?entityId=<ENTITY_ID>' -H "Authorization: Bearer <TOKEN>"
# 发布
curl -s -X POST 'http://localhost:8093/api/design/publish' -H "Authorization: Bearer <TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{"entityId":"<ENTITY_ID>","tableName":"<TABLE>","templateId":"<TPL>","menuName":"演示功能"}'

预期:flows 含 <TABLE>_ADD/_UPDATE/_SEARCH/_DELETE/_LOAD,menuId 非空,deploymentPackage.requiresHumanApproval=true、status=READY_FOR_HUMAN_REVIEW。重复 publish:flowsCreated=false 且 menuId 不变(幂等)。

Step 13.9 — 提交

git add platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DeploymentPackage.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/publish/DeploymentPackageBuilder.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/publish/PublishOrchestrator.java \
        platform-metadata/src/test/java/com/eip4/platform/metadata/publish/DeploymentPackageBuilderTest.java \
        platform-metadata/src/main/java/com/eip4/platform/metadata/web/DesignFeatureController.java
git commit -m "feat(design): publish 生成 production 人审部署包(DECISION-2,manifest+rollback)(建物3-Task13)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

本节交付物汇总:GET /api/design/flows + POST /api/design/publish(发布编排:确保 5(+2) 流落库 → 注册菜单使页面在当前库立即可用 → 生成 production 人审部署包),新增 DefaultFlowPreviewService / PublishOrchestrator / MenuRegistrar / DeploymentPackageBuilder / DeploymentPackage(均在 com.eip4.platform.metadata.publish),全部红线守住(发布恒人审、部署包 requiresHumanApproval=true、不在 publish 执行生产 SQL、不碰 sys_page_schema 单一真相、平台进程内无 LLM)。

第 4 节 · 前端 api 模块 + 建模器 UI(建物 1 前端)

范围:Tasks 14–17。在 /Users/zhengwr/workspace/eip3/eip4-web 下新增三个 api 模块(meta/recipe/publish)+ 建模器页 ModelerPage(实体清单、新建实体 Dialog、字段表、引用列选择器)。全部 TDD,vitest 单测,频繁提交。

测试运行约定:cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- <file>(npm test == vitest run,jsdom 环境,globals 开启)。 提交前置:本仓 eip4-web 是独立 git 仓(顶层 eip3 非 git)。所有 git 命令在 /Users/zhengwr/workspace/eip3/eip4-web 内执行。若当前在默认分支,先 git checkout -b feat/modeler-frontend(仅首个 commit 前做一次)。

相关技能:测试先行用 @superpowers:test-driven-development;完工自检用 @superpowers:verification-before-completion。


Task 14 — 三个 api 模块(meta/recipe/publish)+ vitest 组件测试基建

建立 src/setupTests.ts(jest-dom + cleanup,后续所有 *.test.tsx 依赖它),再 TDD 写三个 api 模块。所有模块镜像 src/api/auth.ts:import { http } from './http',解包后端 {status:0,data:...} 信封返回内层 data。

Files:

  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/setupTests.ts
  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/vitest.config.ts(在 test: 内加 setupFiles)
  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/api/meta.ts
  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/api/recipe.ts
  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/api/publish.ts
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/api/meta.test.ts
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/api/recipe.test.ts
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/api/publish.test.ts

Step 14.1 — 写 vitest 组件测试基建(setupFiles)

本仓有 @testing-library/jest-dom 与 @testing-library/react 已装,但无 setupFiles、无任何 *.test.tsx。先补 setup(Task 16/17 与 Section 5 的组件测试全部依赖)。

写 src/setupTests.ts(COMPLETE):

// vitest 全局测试基建:注册 jest-dom 断言匹配器 + 每个用例后自动卸载组件树。
// 在 vitest.config.ts 的 test.setupFiles 里登记,所有 *.test.tsx 共享。
import '@testing-library/jest-dom/vitest';
import { afterEach } from 'vitest';
import { cleanup } from '@testing-library/react';

afterEach(() => {
  cleanup();
});

在 vitest.config.ts 的 test: 块内,把现有

  test: {
    environment: 'jsdom',
    globals: true,
    include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
  },

改为(加一行 setupFiles):

  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/setupTests.ts'],
    include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
  },

Step 14.2 — meta.ts 失败测试

写 src/api/meta.test.ts(COMPLETE):

import { describe, expect, it, vi, beforeEach } from 'vitest';
import { http } from './http';
import { createEntity, listEntities, listEntityColumns } from './meta';

vi.mock('./http', () => ({
  http: { get: vi.fn(), post: vi.fn() },
}));

const mGet = vi.mocked(http.get);
const mPost = vi.mocked(http.post);

beforeEach(() => {
  mGet.mockReset();
  mPost.mockReset();
});

describe('meta api', () => {
  it('createEntity POST /api/meta/entity 并解包 data', async () => {
    mPost.mockResolvedValue({
      data: { status: 0, data: { entityId: 'E1', tablename: 'OA_DEMO', attributeCount: 4, indexCount: 1, listApi: '/api/entity/OA_DEMO/list' } },
    } as never);
    const r = await createEntity({ tablename: 'OA_DEMO', name: '演示', attributes: [{ column: 'TITLE', type: 'string', length: 200, mandatory: true }] });
    expect(mPost).toHaveBeenCalledWith('/api/meta/entity', {
      tablename: 'OA_DEMO',
      name: '演示',
      attributes: [{ column: 'TITLE', type: 'string', length: 200, mandatory: true }],
    });
    expect(r.entityId).toBe('E1');
    expect(r.listApi).toBe('/api/entity/OA_DEMO/list');
  });

  it('listEntities GET /api/meta/entities 并解包数组', async () => {
    mGet.mockResolvedValue({ data: { status: 0, data: [{ entityId: 'E1', tablename: 'OA_DEMO', name: '演示' }] } } as never);
    const r = await listEntities();
    expect(mGet).toHaveBeenCalledWith('/api/meta/entities');
    expect(r).toHaveLength(1);
    expect(r[0].tablename).toBe('OA_DEMO');
  });

  it('listEntityColumns GET /api/meta/entity/{table}/attributes 并解包', async () => {
    mGet.mockResolvedValue({
      data: { status: 0, data: { tablename: 'SYS_DEPART', displayColumn: 'DEPARTNAME', columns: [{ column: 'DEPARTNAME', display: '部门名', type: 'string' }] } },
    } as never);
    const r = await listEntityColumns('SYS_DEPART');
    expect(mGet).toHaveBeenCalledWith('/api/meta/entity/SYS_DEPART/attributes');
    expect(r.displayColumn).toBe('DEPARTNAME');
    expect(r.columns[0].column).toBe('DEPARTNAME');
  });
});

Step 14.3 — 跑 meta 测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/api/meta.test.ts

期望失败信息含:Failed to resolve import "./meta" 或 Cannot find module './meta'(文件尚不存在)。

Step 14.4 — 写 meta.ts(最小实现)

写 src/api/meta.ts(COMPLETE):

// 元数据建模 API —— 实体目录 / 实体属性 / 建表。
// 后端信封统一 {status:0,data:...},本模块解包返回内层 data(镜像 auth.ts 用法)。
import { http } from './http';

export type AttrType = 'string' | 'integer' | 'number' | 'date' | 'datetime' | 'boolean' | 'reference';

export interface EntityAttr {
  column: string;
  type: AttrType;
  length?: number;
  display?: string;
  mandatory?: boolean;
  /** type==='reference' 时必填:外键目标表名(DECISION-1)。 */
  referenceTable?: string;
}

export interface CreateEntityBody {
  tablename: string;
  name?: string;
  attributes: EntityAttr[];
}

export interface CreateEntityResult {
  entityId: string;
  tablename: string;
  attributeCount: number;
  indexCount: number;
  listApi: string;
}

export interface EntitySummary {
  entityId: string;
  tablename: string;
  name: string;
}

export interface EntityColumn {
  column: string;
  display: string;
  type: string;
  referenceTable?: string;
}

export interface EntityColumns {
  tablename: string;
  displayColumn: string;
  columns: EntityColumn[];
}

interface Envelope<T> {
  status: number;
  data: T;
}

/** POST /api/meta/entity —— 建表(标准列由后端自动追加)。 */
export async function createEntity(body: CreateEntityBody): Promise<CreateEntityResult> {
  const resp = await http.post<Envelope<CreateEntityResult>>('/api/meta/entity', body);
  return resp.data.data;
}

/** GET /api/meta/entities —— 实体目录(供引用列选择器)。 */
export async function listEntities(): Promise<EntitySummary[]> {
  const resp = await http.get<Envelope<EntitySummary[]>>('/api/meta/entities');
  return resp.data.data;
}

/** GET /api/meta/entity/{table}/attributes —— 某表的列定义(含 displayColumn)。 */
export async function listEntityColumns(table: string): Promise<EntityColumns> {
  const resp = await http.get<Envelope<EntityColumns>>(`/api/meta/entity/${encodeURIComponent(table)}/attributes`);
  return resp.data.data;
}

Step 14.5 — 跑 meta 测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/api/meta.test.ts

期望:3 passed。

Step 14.6 — recipe.ts 失败测试

写 src/api/recipe.test.ts(COMPLETE):

import { describe, expect, it, vi, beforeEach } from 'vitest';
import { http } from './http';
import { compileRecipe, listRecipes } from './recipe';

vi.mock('./http', () => ({ http: { get: vi.fn(), post: vi.fn() } }));
const mGet = vi.mocked(http.get);
const mPost = vi.mocked(http.post);
beforeEach(() => { mGet.mockReset(); mPost.mockReset(); });

describe('recipe api', () => {
  it('compileRecipe POST /api/design/recipe/compile 并解包', async () => {
    mPost.mockResolvedValue({ data: { status: 0, data: { templateId: 'tpl-uuid', etag: 'W/"1"' } } } as never);
    const r = await compileRecipe({ tableName: 'OA_DEMO', recipe: 'maintenance-crud-v1', title: '演示维护', displayField: 'TITLE' });
    expect(mPost).toHaveBeenCalledWith('/api/design/recipe/compile', {
      tableName: 'OA_DEMO', recipe: 'maintenance-crud-v1', title: '演示维护', displayField: 'TITLE',
    });
    expect(r.templateId).toBe('tpl-uuid');
    expect(r.etag).toBe('W/"1"');
  });

  it('listRecipes GET /api/ai/page-recipes 并解包数组', async () => {
    mGet.mockResolvedValue({ data: { status: 0, data: [{ id: 'maintenance-crud-v1', name: '维护型 CRUD' }] } } as never);
    const r = await listRecipes();
    expect(mGet).toHaveBeenCalledWith('/api/ai/page-recipes');
    expect(r[0].id).toBe('maintenance-crud-v1');
  });
});

Step 14.7 — 跑 recipe 测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/api/recipe.test.ts

期望失败:Failed to resolve import "./recipe"。

Step 14.8 — 写 recipe.ts

写 src/api/recipe.ts(COMPLETE):

// recipe 编译 API —— 把实体 + recipe 编译为标准页(templateId 由服务端生成)。
// listRecipes 取 AI ①面的 recipe 目录(/api/ai/page-recipes)。
import { http } from './http';

export type RecipeId = 'maintenance-crud-v1' | 'tree-crud-v1';

export interface CompileRecipeBody {
  tableName: string;
  recipe: RecipeId;
  title: string;
  displayField?: string;
  pageSize?: number;
}

export interface CompileRecipeResult {
  templateId: string;
  etag: string;
}

export interface RecipeOption {
  id: string;
  name: string;
}

interface Envelope<T> { status: number; data: T; }

/** POST /api/design/recipe/compile —— 服务端建蓝图→编译→校验→PageSchemaWriter.upsertStandard。 */
export async function compileRecipe(body: CompileRecipeBody): Promise<CompileRecipeResult> {
  const resp = await http.post<Envelope<CompileRecipeResult>>('/api/design/recipe/compile', body);
  return resp.data.data;
}

/** GET /api/ai/page-recipes —— recipe 目录(下拉用)。 */
export async function listRecipes(): Promise<RecipeOption[]> {
  const resp = await http.get<Envelope<RecipeOption[]>>('/api/ai/page-recipes');
  return resp.data.data;
}

Step 14.9 — 跑 recipe 测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/api/recipe.test.ts

期望:2 passed。

Step 14.10 — publish.ts 失败测试

写 src/api/publish.test.ts(COMPLETE):

import { describe, expect, it, vi, beforeEach } from 'vitest';
import { http } from './http';
import { publishFeature } from './publish';

vi.mock('./http', () => ({ http: { get: vi.fn(), post: vi.fn() } }));
const mPost = vi.mocked(http.post);
beforeEach(() => { mPost.mockReset(); });

describe('publish api', () => {
  it('publishFeature POST /api/design/publish 并解包', async () => {
    mPost.mockResolvedValue({ data: { status: 0, data: { menuId: 'M1', flows: ['OA_DEMO_ADD'], deploymentPackage: { id: 'pkg-1' } } } } as never);
    const r = await publishFeature({ entityId: 'E1', tableName: 'OA_DEMO', templateId: 'tpl-uuid', menuName: '演示', generateDeploymentPackage: true });
    expect(mPost).toHaveBeenCalledWith('/api/design/publish', {
      entityId: 'E1', tableName: 'OA_DEMO', templateId: 'tpl-uuid', menuName: '演示', generateDeploymentPackage: true,
    });
    expect(r.menuId).toBe('M1');
    expect(r.flows).toContain('OA_DEMO_ADD');
  });
});

Step 14.11 — 跑 publish 测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/api/publish.test.ts

期望失败:Failed to resolve import "./publish"。

Step 14.12 — 写 publish.ts

写 src/api/publish.ts(COMPLETE):

// 发布 API —— 五环终点:触发 5 条默认流 + 注册菜单 + 可选生产部署包(DECISION-2)。
// 发布恒人审:本端点只做「本环境即用 + 生产部署包生成」,生产上线仍走人工人审流程。
import { http } from './http';

export interface PublishFeatureBody {
  entityId: string;
  tableName: string;
  templateId: string;
  menuName: string;
  parentMenuId?: string;
  generateDeploymentPackage?: boolean;
}

export interface PublishFeatureResult {
  menuId: string;
  flows: string[];
  deploymentPackage?: unknown;
}

interface Envelope<T> { status: number; data: T; }

/** POST /api/design/publish。 */
export async function publishFeature(body: PublishFeatureBody): Promise<PublishFeatureResult> {
  const resp = await http.post<Envelope<PublishFeatureResult>>('/api/design/publish', body);
  return resp.data.data;
}

Step 14.13 — 跑 publish 测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/api/publish.test.ts

期望:1 passed。

Step 14.14 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/setupTests.ts vitest.config.ts src/api/meta.ts src/api/recipe.ts src/api/publish.ts src/api/meta.test.ts src/api/recipe.test.ts src/api/publish.test.ts && git commit -m "feat(modeler): meta/recipe/publish api modules + vitest jest-dom setup

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 15 — ModelerPage 骨架 + 路由 + 实体清单 + 新建实体 Dialog 壳

页面挂 /modeler,管理员早返回。加载并展示已有实体(listEntities),「新建实体」按钮打开 Dialog(含表名校验 /^[A-Z][A-Z0-9_]{2,40}$/、显示名)。字段表与提交在 Task 16/17 补全;本 Task 先把 Dialog 壳 + 表名/显示名 + 提交占位(暂调 createEntity({tablename,name,attributes:[]}))跑通。

Files:

  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/ModelerPage.tsx
  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/src/App.tsx(import + <Route path="/modeler" .../>,第 10、42 行附近)
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/ModelerPage.test.tsx

Step 15.1 — 失败测试(清单渲染 + 非管理员早返回 + 表名校验)

写 src/pages/ModelerPage.test.tsx(COMPLETE):

import { describe, expect, it, vi, beforeEach } from 'vitest';
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { ModelerPage, validateTableName } from './ModelerPage';

vi.mock('../api/meta', () => ({
  listEntities: vi.fn(),
  listEntityColumns: vi.fn(),
  createEntity: vi.fn(),
}));
vi.mock('../auth/token', () => ({ getProfile: vi.fn() }));

import { listEntities, createEntity } from '../api/meta';
import { getProfile } from '../auth/token';

const mList = vi.mocked(listEntities);
const mCreate = vi.mocked(createEntity);
const mProfile = vi.mocked(getProfile);

beforeEach(() => {
  mList.mockReset();
  mCreate.mockReset();
  mProfile.mockReset();
  mProfile.mockReturnValue({ userId: 'ADMIN', account: 'admin', name: '管理员', roles: [] });
  mList.mockResolvedValue([{ entityId: 'E1', tablename: 'OA_DEMO', name: '演示' }]);
});

describe('validateTableName', () => {
  it('合法表名通过', () => {
    expect(validateTableName('OA_DEMO')).toBe(true);
    expect(validateTableName('ABC')).toBe(true);
  });
  it('非法表名拒绝', () => {
    expect(validateTableName('ab')).toBe(false);        // 太短 + 小写
    expect(validateTableName('1ABC')).toBe(false);      // 数字开头
    expect(validateTableName('OA-DEMO')).toBe(false);   // 含非法字符
  });
});

describe('ModelerPage', () => {
  it('非管理员显示无权访问', () => {
    mProfile.mockReturnValue({ userId: 'U9', account: 'zhang', name: '张三', roles: [] });
    render(<ModelerPage />);
    expect(screen.getByText(/仅管理员可用/)).toBeInTheDocument();
  });

  it('管理员加载并展示已有实体', async () => {
    render(<ModelerPage />);
    await waitFor(() => expect(screen.getByText('OA_DEMO')).toBeInTheDocument());
    expect(mList).toHaveBeenCalled();
  });

  it('点新建实体打开 Dialog,非法表名禁用提交', async () => {
    render(<ModelerPage />);
    fireEvent.click(screen.getByTestId('modeler-new-entity'));
    expect(screen.getByTestId('modeler-tablename')).toBeInTheDocument();
    fireEvent.change(screen.getByTestId('modeler-tablename'), { target: { value: 'ab' } });
    expect(screen.getByTestId('modeler-submit')).toBeDisabled();
    fireEvent.change(screen.getByTestId('modeler-tablename'), { target: { value: 'OA_NEW' } });
    expect(screen.getByTestId('modeler-submit')).not.toBeDisabled();
  });
});

Step 15.2 — 跑测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ModelerPage.test.tsx

期望失败:Failed to resolve import "./ModelerPage"。

Step 15.3 — 写 ModelerPage.tsx(本 Task 版,字段表/引用器为 Task 16/17 留接缝)

写 src/pages/ModelerPage.tsx(COMPLETE;Task 16/17 将就地扩展同一文件,本版已含字段表与 buildAttribute 的最小形态以便后续无缝增补):

// 建模器 —— NocoBase 式实体建模入口(五环第①环:元数据→表)。
// 仅管理员可用。展示已有实体清单 + 「新建实体」Dialog(表名/显示名/字段表)。
// v1 只建新不改表(DECISION:no ALTER)。字段表与引用列选择器见同文件下方组件。
import { useEffect, useState } from 'react';
import { Dialog } from '../components/ui/Dialog';
import { getProfile } from '../auth/token';
import {
  listEntities,
  createEntity,
  type EntitySummary,
  type EntityAttr,
} from '../api/meta';
import { FieldTable, buildAttribute, type FieldRow } from './ModelerFields';

export function validateTableName(t: string): boolean {
  return /^[A-Z][A-Z0-9_]{2,40}$/.test(t);
}

export function ModelerPage() {
  const profile = getProfile();
  const isAdmin = profile?.account === 'admin' || profile?.userId === 'ADMIN';

  const [entities, setEntities] = useState<EntitySummary[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState('');
  const [open, setOpen] = useState(false);

  // 新建表单态
  const [tablename, setTablename] = useState('');
  const [name, setName] = useState('');
  const [rows, setRows] = useState<FieldRow[]>([]);
  const [submitting, setSubmitting] = useState(false);
  const [submitErr, setSubmitErr] = useState('');

  function reload() {
    setLoading(true);
    listEntities()
      .then((es) => setEntities(es))
      .catch((e: Error) => setError(e.message ?? '实体加载失败'))
      .finally(() => setLoading(false));
  }

  useEffect(() => {
    if (!isAdmin) return;
    reload();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [isAdmin]);

  if (!isAdmin) {
    return <div style={{ padding: 24, color: 'var(--text-3)' }}>建模器仅管理员可用。</div>;
  }

  const tableValid = validateTableName(tablename);
  // 引用行必须选了目标表才合法(Task 17 填充 referenceTable)
  const rowsValid = rows.every((r) => r.type !== '引用' || !!r.referenceTable);
  const canSubmit = tableValid && rows.length > 0 && rowsValid && !submitting;

  function openDialog() {
    setTablename('');
    setName('');
    setRows([]);
    setSubmitErr('');
    setOpen(true);
  }

  async function submit() {
    setSubmitting(true);
    setSubmitErr('');
    try {
      const attributes: EntityAttr[] = rows.map(buildAttribute);
      await createEntity({ tablename, name: name || undefined, attributes });
      setOpen(false);
      reload();
    } catch (e) {
      setSubmitErr((e as Error).message ?? '建表失败');
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <div style={{ height: '100%', overflow: 'auto', padding: 'var(--pad-lg)' }} data-testid="modeler">
      <div style={{ display: 'flex', alignItems: 'center', gap: 16, marginBottom: 16, flexWrap: 'wrap' }}>
        <div>
          <h2 style={{ margin: 0, fontSize: 18, fontWeight: 600, color: 'var(--text)' }}>建模器</h2>
          <div className="sub-text" style={{ marginTop: 4 }}>
            新建实体(建表)。v1 只建新不改表 · 标准列由后端自动追加
          </div>
        </div>
        <div style={{ flex: 1 }} />
        <button className="btn btn-primary" data-testid="modeler-new-entity" onClick={openDialog}>
          新建实体
        </button>
      </div>

      {loading ? (
        <div style={{ padding: 24, color: 'var(--text-3)' }}>加载中…</div>
      ) : error ? (
        <div style={{ padding: 16, color: 'var(--err)' }}>实体加载失败:{error}</div>
      ) : entities.length === 0 ? (
        <div className="empty">尚无实体,点「新建实体」开始</div>
      ) : (
        <div className="card" style={{ padding: 0 }}>
          <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 'var(--fs)' }}>
            <thead>
              <tr style={{ textAlign: 'left', color: 'var(--text-3)' }}>
                <th style={{ padding: '8px 14px', borderBottom: '1px solid var(--line)' }}>表名</th>
                <th style={{ padding: '8px 14px', borderBottom: '1px solid var(--line)' }}>显示名</th>
                <th style={{ padding: '8px 14px', borderBottom: '1px solid var(--line)' }}>实体ID</th>
              </tr>
            </thead>
            <tbody>
              {entities.map((e) => (
                <tr key={e.entityId} data-testid="modeler-entity-row">
                  <td style={{ padding: '8px 14px', borderBottom: '1px solid var(--line)' }}>{e.tablename}</td>
                  <td style={{ padding: '8px 14px', borderBottom: '1px solid var(--line)' }}>{e.name}</td>
                  <td style={{ padding: '8px 14px', borderBottom: '1px solid var(--line)', color: 'var(--text-3)' }}>{e.entityId}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      )}

      {open ? (
        <Dialog
          title="新建实体"
          width={720}
          onClose={() => setOpen(false)}
          foot={
            <>
              <button className="btn" onClick={() => setOpen(false)}>取消</button>
              <button className="btn btn-primary" data-testid="modeler-submit" disabled={!canSubmit} onClick={submit}>
                {submitting ? '建表中…' : '建表'}
              </button>
            </>
          }
        >
          <div style={{ display: 'grid', gap: 12 }}>
            <label style={{ display: 'grid', gap: 4 }}>
              <span className="sub-text">表名(大写字母开头,仅大写字母/数字/下划线,3–41 位)</span>
              <input
                data-testid="modeler-tablename"
                value={tablename}
                onChange={(ev) => setTablename(ev.target.value.toUpperCase())}
                placeholder="OA_DEMO"
              />
              {tablename && !tableValid ? (
                <span style={{ color: 'var(--err)', fontSize: 11 }}>表名格式不合法</span>
              ) : null}
            </label>
            <label style={{ display: 'grid', gap: 4 }}>
              <span className="sub-text">显示名(可选)</span>
              <input value={name} onChange={(ev) => setName(ev.target.value)} placeholder="演示维护" />
            </label>

            <FieldTable rows={rows} onChange={setRows} />

            {submitErr ? <div style={{ color: 'var(--err)', fontSize: 12 }}>{submitErr}</div> : null}
          </div>
        </Dialog>
      ) : null}
    </div>
  );
}

注:本文件 import 了 ./ModelerFields(FieldTable/buildAttribute/FieldRow)——该文件在 Task 16 创建。为让本 Task 的测试先过,Task 15 同时创建一个临时最小 ModelerFields.tsx(Task 16 用 TDD 替换其实现)。

写临时 src/pages/ModelerFields.tsx(最小占位,Task 16 替换):

// 占位(Task 16 用 TDD 实现字段表 + buildAttribute + 引用列选择器)。
import type { Dispatch, SetStateAction } from 'react';
import type { EntityAttr } from '../api/meta';

export type UiType = '文本' | '整数' | '小数' | '日期' | '日期时间' | '布尔' | '引用';

export interface FieldRow {
  column: string;
  display: string;
  type: UiType;
  length?: number;
  mandatory?: boolean;
  referenceTable?: string;
}

export function buildAttribute(_row: FieldRow): EntityAttr {
  throw new Error('not implemented (Task 16)');
}

export function FieldTable(_props: { rows: FieldRow[]; onChange: Dispatch<SetStateAction<FieldRow[]>> }) {
  return null;
}

Step 15.4 — 接路由

在 src/App.tsx:

  • 第 10 行 import { DesignCenterPage } from './pages/DesignCenterPage'; 之后加:
    import { ModelerPage } from './pages/ModelerPage';
    
  • 第 42 行 <Route path="/design-center" element={<DesignCenterPage />} /> 之后加:
    {/* 建模器(五环第①环·元数据→表,仅管理员)*/}
    <Route path="/modeler" element={<ModelerPage />} />
    

Step 15.5 — 跑测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ModelerPage.test.tsx

期望:5 passed(validateTableName 2 + ModelerPage 3)。

Step 15.6 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/pages/ModelerPage.tsx src/pages/ModelerFields.tsx src/pages/ModelerPage.test.tsx src/App.tsx && git commit -m "feat(modeler): ModelerPage shell + /modeler route + entity list + new-entity dialog

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 16 — 字段表 + 加字段 Dialog + UI 类型→api 类型映射(buildAttribute)

用纯 HTML <table> 渲染字段行 {column,display,type,length,mandatory},加字段用 components/ui/Dialog。核心是 buildAttribute(row) 把 UI 类型映射成 api 类型并落 length/mandatory。本 Task 不含引用列(type=引用的 referenceTable 在 Task 17)。

Files:

  • Modify (替换占位): /Users/zhengwr/workspace/eip3/eip4-web/src/pages/ModelerFields.tsx
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/ModelerFields.test.tsx

Step 16.1 — 失败测试(buildAttribute 映射 + 字段表交互)

写 src/pages/ModelerFields.test.tsx(COMPLETE):

import { describe, expect, it, vi, beforeEach } from 'vitest';
import { render, screen, fireEvent } from '@testing-library/react';
import { useState } from 'react';
import { buildAttribute, FieldTable, type FieldRow } from './ModelerFields';

vi.mock('../api/meta', () => ({ listEntities: vi.fn(), listEntityColumns: vi.fn() }));

describe('buildAttribute 映射', () => {
  it('文本→string,带 length/display/mandatory', () => {
    const r: FieldRow = { column: 'TITLE', display: '标题', type: '文本', length: 200, mandatory: true };
    expect(buildAttribute(r)).toEqual({ column: 'TITLE', type: 'string', length: 200, display: '标题', mandatory: true });
  });
  it('整数→integer,无 length', () => {
    const r: FieldRow = { column: 'QTY', display: '数量', type: '整数' };
    expect(buildAttribute(r)).toEqual({ column: 'QTY', type: 'integer', display: '数量' });
  });
  it('小数→number / 日期→date / 日期时间→datetime / 布尔→boolean', () => {
    expect(buildAttribute({ column: 'A', display: 'a', type: '小数' }).type).toBe('number');
    expect(buildAttribute({ column: 'B', display: 'b', type: '日期' }).type).toBe('date');
    expect(buildAttribute({ column: 'C', display: 'c', type: '日期时间' }).type).toBe('datetime');
    expect(buildAttribute({ column: 'D', display: 'd', type: '布尔' }).type).toBe('boolean');
  });
  it('引用→reference,带 referenceTable', () => {
    const r: FieldRow = { column: 'DEPARTID', display: '部门', type: '引用', referenceTable: 'SYS_DEPART' };
    expect(buildAttribute(r)).toEqual({ column: 'DEPARTID', type: 'reference', display: '部门', referenceTable: 'SYS_DEPART' });
  });
  it('mandatory=false 不输出该键', () => {
    const r: FieldRow = { column: 'X', display: 'x', type: '文本', length: 50, mandatory: false };
    expect('mandatory' in buildAttribute(r)).toBe(false);
  });
});

function Harness() {
  const [rows, setRows] = useState<FieldRow[]>([]);
  return (
    <div>
      <FieldTable rows={rows} onChange={setRows} />
      <div data-testid="count">{rows.length}</div>
    </div>
  );
}

describe('FieldTable 交互', () => {
  beforeEach(() => { /* no-op */ });

  it('加字段:填列名/显示名/选类型→提交→出现在表里', () => {
    render(<Harness />);
    fireEvent.click(screen.getByTestId('field-add'));
    fireEvent.change(screen.getByTestId('field-column'), { target: { value: 'TITLE' } });
    fireEvent.change(screen.getByTestId('field-display'), { target: { value: '标题' } });
    fireEvent.change(screen.getByTestId('field-type'), { target: { value: '文本' } });
    fireEvent.change(screen.getByTestId('field-length'), { target: { value: '200' } });
    fireEvent.click(screen.getByTestId('field-submit'));
    expect(screen.getByText('TITLE')).toBeInTheDocument();
    expect(screen.getByTestId('count').textContent).toBe('1');
  });

  it('文本类型显示 length 输入,整数类型隐藏', () => {
    render(<Harness />);
    fireEvent.click(screen.getByTestId('field-add'));
    fireEvent.change(screen.getByTestId('field-type'), { target: { value: '文本' } });
    expect(screen.getByTestId('field-length')).toBeInTheDocument();
    fireEvent.change(screen.getByTestId('field-type'), { target: { value: '整数' } });
    expect(screen.queryByTestId('field-length')).not.toBeInTheDocument();
  });
});

Step 16.2 — 跑测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ModelerFields.test.tsx

期望失败:not implemented (Task 16)(buildAttribute 占位抛错)以及 field-add 找不到(FieldTable 占位返回 null)。

Step 16.3 — 实现 ModelerFields.tsx(字段表 + 加字段 Dialog + buildAttribute;引用分支为 Task 17 留 import 接缝)

替换 src/pages/ModelerFields.tsx 全文(COMPLETE;注意:本版的「引用」类型分支已渲染由 Task 17 提供的 ReferencePicker——为让 Task 16 测试先过,Task 16 同时创建最小 ReferencePicker 占位,Task 17 用 TDD 替换它):

// 字段表 + 加字段 Dialog + UI 类型↔api 类型映射。
// 纯 HTML <table>(本仓无可复用表格组件)+ components/ui/Dialog。
import { useState } from 'react';
import type { Dispatch, SetStateAction } from 'react';
import { Dialog } from '../components/ui/Dialog';
import type { EntityAttr, AttrType } from '../api/meta';
import { ReferencePicker } from './ReferencePicker';

export type UiType = '文本' | '整数' | '小数' | '日期' | '日期时间' | '布尔' | '引用';

export interface FieldRow {
  column: string;
  display: string;
  type: UiType;
  length?: number;
  mandatory?: boolean;
  referenceTable?: string;
}

const UI_TYPES: UiType[] = ['文本', '整数', '小数', '日期', '日期时间', '布尔', '引用'];

const TYPE_MAP: Record<UiType, AttrType> = {
  文本: 'string',
  整数: 'integer',
  小数: 'number',
  日期: 'date',
  日期时间: 'datetime',
  布尔: 'boolean',
  引用: 'reference',
};

/** UI 行 → api EntityAttr。length 仅文本有意义;mandatory=false 不输出;引用带 referenceTable。 */
export function buildAttribute(row: FieldRow): EntityAttr {
  const attr: EntityAttr = { column: row.column, type: TYPE_MAP[row.type] };
  if (row.display) attr.display = row.display;
  if (row.type === '文本' && typeof row.length === 'number') attr.length = row.length;
  if (row.mandatory) attr.mandatory = true;
  if (row.type === '引用' && row.referenceTable) attr.referenceTable = row.referenceTable;
  return attr;
}

interface FieldTableProps {
  rows: FieldRow[];
  onChange: Dispatch<SetStateAction<FieldRow[]>>;
}

export function FieldTable({ rows, onChange }: FieldTableProps) {
  const [adding, setAdding] = useState(false);
  // 加字段草稿
  const [column, setColumn] = useState('');
  const [display, setDisplay] = useState('');
  const [type, setType] = useState<UiType>('文本');
  const [length, setLength] = useState('200');
  const [mandatory, setMandatory] = useState(false);
  const [refTable, setRefTable] = useState('');

  function openAdd() {
    setColumn('');
    setDisplay('');
    setType('文本');
    setLength('200');
    setMandatory(false);
    setRefTable('');
    setAdding(true);
  }

  const columnValid = /^[A-Z][A-Z0-9_]{0,40}$/.test(column);
  const refOk = type !== '引用' || !!refTable;
  const canAdd = columnValid && !!display && refOk;

  function submitField() {
    const row: FieldRow = { column, display, type };
    if (type === '文本') row.length = Number(length) || undefined;
    if (mandatory) row.mandatory = true;
    if (type === '引用') row.referenceTable = refTable;
    onChange((prev) => [...prev, row]);
    setAdding(false);
  }

  function removeRow(i: number) {
    onChange((prev) => prev.filter((_, idx) => idx !== i));
  }

  return (
    <div>
      <div style={{ display: 'flex', alignItems: 'center', marginBottom: 6 }}>
        <span className="sub-text" style={{ flex: 1 }}>字段(标准列由后端自动追加,无需在此添加 ID/创建人等)</span>
        <button className="btn btn-sm" type="button" data-testid="field-add" onClick={openAdd}>加字段</button>
      </div>
      <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 'var(--fs)' }}>
        <thead>
          <tr style={{ textAlign: 'left', color: 'var(--text-3)' }}>
            <th style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>列名</th>
            <th style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>显示名</th>
            <th style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>类型</th>
            <th style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>必填</th>
            <th style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }} />
          </tr>
        </thead>
        <tbody>
          {rows.length === 0 ? (
            <tr><td colSpan={5} style={{ padding: '10px', color: 'var(--text-3)' }}>尚无字段</td></tr>
          ) : (
            rows.map((r, i) => (
              <tr key={i} data-testid="field-row">
                <td style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>{r.column}</td>
                <td style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>{r.display}</td>
                <td style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>
                  {r.type}{r.type === '引用' && r.referenceTable ? `→${r.referenceTable}` : ''}
                </td>
                <td style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>{r.mandatory ? '是' : ''}</td>
                <td style={{ padding: '6px 10px', borderBottom: '1px solid var(--line)' }}>
                  <span className="link" style={{ fontSize: 11 }} onClick={() => removeRow(i)}>删除</span>
                </td>
              </tr>
            ))
          )}
        </tbody>
      </table>

      {adding ? (
        <Dialog
          title="加字段"
          width={520}
          onClose={() => setAdding(false)}
          foot={
            <>
              <button className="btn" type="button" onClick={() => setAdding(false)}>取消</button>
              <button className="btn btn-primary" type="button" data-testid="field-submit" disabled={!canAdd} onClick={submitField}>添加</button>
            </>
          }
        >
          <div style={{ display: 'grid', gap: 10 }}>
            <label style={{ display: 'grid', gap: 4 }}>
              <span className="sub-text">列名(大写字母开头)</span>
              <input data-testid="field-column" value={column} onChange={(e) => setColumn(e.target.value.toUpperCase())} placeholder="TITLE" />
            </label>
            <label style={{ display: 'grid', gap: 4 }}>
              <span className="sub-text">显示名</span>
              <input data-testid="field-display" value={display} onChange={(e) => setDisplay(e.target.value)} placeholder="标题" />
            </label>
            <label style={{ display: 'grid', gap: 4 }}>
              <span className="sub-text">类型</span>
              <select data-testid="field-type" value={type} onChange={(e) => setType(e.target.value as UiType)}>
                {UI_TYPES.map((t) => <option key={t} value={t}>{t}</option>)}
              </select>
            </label>
            {type === '文本' ? (
              <label style={{ display: 'grid', gap: 4 }}>
                <span className="sub-text">长度</span>
                <input data-testid="field-length" type="number" value={length} onChange={(e) => setLength(e.target.value)} />
              </label>
            ) : null}
            {type === '引用' ? (
              <ReferencePicker value={refTable} onChange={setRefTable} />
            ) : null}
            <label style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
              <input data-testid="field-mandatory" type="checkbox" checked={mandatory} onChange={(e) => setMandatory(e.target.checked)} />
              <span className="sub-text">必填</span>
            </label>
          </div>
        </Dialog>
      ) : null}
    </div>
  );
}

同时创建最小 src/pages/ReferencePicker.tsx(占位;Task 17 用 TDD 替换):

// 占位(Task 17 实现引用列选择器)。
export function ReferencePicker(props: { value: string; onChange: (t: string) => void }) {
  return (
    <input
      data-testid="field-ref-table"
      value={props.value}
      onChange={(e) => props.onChange(e.target.value)}
      placeholder="目标表(Task 17 改为下拉)"
    />
  );
}

Step 16.4 — 跑测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ModelerFields.test.tsx

期望:7 passed(buildAttribute 5 + FieldTable 2)。

Step 16.5 — 回归 ModelerPage 测试仍绿

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ModelerPage.test.tsx

期望:5 passed(FieldTable 真实现后清单/Dialog 仍正常)。

Step 16.6 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/pages/ModelerFields.tsx src/pages/ModelerFields.test.tsx src/pages/ReferencePicker.tsx && git commit -m "feat(modeler): field table + add-field dialog + ui-type to api-type mapping (buildAttribute)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 17 — 引用列选择器(目标实体 + 显示列)

替换占位 ReferencePicker:type=引用时,目标实体 <select>(listEntities 填充)+ 显示列 <select>(选中目标后 listEntityColumns(targetTable) 填充)。提交时只把 referenceTable 回写父级(DECISION-1:显示列由 recipe 渲染时按目标表 displayColumn 解析,前端选显示列仅用于预览/可选携带,本 v1 payload 仅需 referenceTable)。

Files:

  • Modify (替换占位): /Users/zhengwr/workspace/eip3/eip4-web/src/pages/ReferencePicker.tsx
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/ReferencePicker.test.tsx

Step 17.1 — 失败测试(选目标→加载列→回写 referenceTable)

写 src/pages/ReferencePicker.test.tsx(COMPLETE):

import { describe, expect, it, vi, beforeEach } from 'vitest';
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { ReferencePicker } from './ReferencePicker';

vi.mock('../api/meta', () => ({ listEntities: vi.fn(), listEntityColumns: vi.fn() }));
import { listEntities, listEntityColumns } from '../api/meta';
const mList = vi.mocked(listEntities);
const mCols = vi.mocked(listEntityColumns);

beforeEach(() => {
  mList.mockReset();
  mCols.mockReset();
  mList.mockResolvedValue([
    { entityId: 'E1', tablename: 'SYS_DEPART', name: '部门' },
    { entityId: 'E2', tablename: 'SYS_ORG', name: '组织' },
  ]);
  mCols.mockResolvedValue({
    tablename: 'SYS_DEPART',
    displayColumn: 'DEPARTNAME',
    columns: [
      { column: 'DEPARTNAME', display: '部门名', type: 'string' },
      { column: 'DEPARTCODE', display: '部门编码', type: 'string' },
    ],
  });
});

describe('ReferencePicker', () => {
  it('加载目标实体清单', async () => {
    render(<ReferencePicker value="" onChange={() => {}} />);
    await waitFor(() => expect(screen.getByTestId('ref-target')).toBeInTheDocument());
    expect(mList).toHaveBeenCalled();
    // 选项含 SYS_DEPART
    expect(screen.getByRole('option', { name: /SYS_DEPART/ })).toBeInTheDocument();
  });

  it('选目标实体→回写 referenceTable + 加载其列', async () => {
    const onChange = vi.fn();
    render(<ReferencePicker value="" onChange={onChange} />);
    await waitFor(() => expect(screen.getByTestId('ref-target')).toBeInTheDocument());
    fireEvent.change(screen.getByTestId('ref-target'), { target: { value: 'SYS_DEPART' } });
    expect(onChange).toHaveBeenCalledWith('SYS_DEPART');
    await waitFor(() => expect(mCols).toHaveBeenCalledWith('SYS_DEPART'));
    // 显示列下拉默认选中 displayColumn
    await waitFor(() => expect(screen.getByTestId('ref-display-col')).toBeInTheDocument());
    expect((screen.getByTestId('ref-display-col') as HTMLSelectElement).value).toBe('DEPARTNAME');
  });
});

Step 17.2 — 跑测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ReferencePicker.test.tsx

期望失败:占位无 ref-target(Unable to find an element by: [data-testid="ref-target"])。

Step 17.3 — 实现 ReferencePicker.tsx

替换 src/pages/ReferencePicker.tsx 全文(COMPLETE):

// 引用列选择器(DECISION-1)。type=引用时选目标实体 + 显示列。
// 父级只需 referenceTable;显示列默认取目标表 displayColumn,仅做预览,
// 实际渲染时由 recipe 按目标表 displayColumn 解析显示名(非裸 id)。
import { useEffect, useState } from 'react';
import { listEntities, listEntityColumns, type EntitySummary, type EntityColumn } from '../api/meta';

interface ReferencePickerProps {
  value: string; // 已选目标表名
  onChange: (referenceTable: string) => void;
}

export function ReferencePicker({ value, onChange }: ReferencePickerProps) {
  const [entities, setEntities] = useState<EntitySummary[]>([]);
  const [cols, setCols] = useState<EntityColumn[]>([]);
  const [displayCol, setDisplayCol] = useState('');
  const [err, setErr] = useState('');

  useEffect(() => {
    let alive = true;
    listEntities()
      .then((es) => alive && setEntities(es))
      .catch((e: Error) => alive && setErr(e.message ?? '实体清单加载失败'));
    return () => { alive = false; };
  }, []);

  useEffect(() => {
    if (!value) {
      setCols([]);
      setDisplayCol('');
      return;
    }
    let alive = true;
    listEntityColumns(value)
      .then((c) => {
        if (!alive) return;
        setCols(c.columns);
        setDisplayCol(c.displayColumn || c.columns[0]?.column || '');
      })
      .catch((e: Error) => alive && setErr(e.message ?? '目标列加载失败'));
    return () => { alive = false; };
  }, [value]);

  return (
    <div style={{ display: 'grid', gap: 8, padding: 8, border: '1px solid var(--line)', borderRadius: 6 }}>
      <label style={{ display: 'grid', gap: 4 }}>
        <span className="sub-text">引用目标实体</span>
        <select data-testid="ref-target" value={value} onChange={(e) => onChange(e.target.value)}>
          <option value="">请选择…</option>
          {entities.map((en) => (
            <option key={en.entityId} value={en.tablename}>
              {en.tablename}({en.name})
            </option>
          ))}
        </select>
      </label>
      {value ? (
        <label style={{ display: 'grid', gap: 4 }}>
          <span className="sub-text">显示列(渲染时显示该列而非 id)</span>
          <select data-testid="ref-display-col" value={displayCol} onChange={(e) => setDisplayCol(e.target.value)}>
            {cols.map((c) => (
              <option key={c.column} value={c.column}>
                {c.display || c.column}
              </option>
            ))}
          </select>
        </label>
      ) : null}
      {err ? <div style={{ color: 'var(--err)', fontSize: 11 }}>{err}</div> : null}
    </div>
  );
}

Step 17.4 — 跑测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ReferencePicker.test.tsx

期望:2 passed。

Step 17.5 — 回归字段表测试(引用分支真实现后 buildAttribute 仍生成 {type:'reference',referenceTable})

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test -- src/pages/ModelerFields.test.tsx

期望:7 passed(FieldTable 内引用 picker 替换后仍绿——buildAttribute 引用用例在 Task 16 已覆盖,picker 回写 refTable 不改其逻辑)。

Step 17.6 — 全量回归 + typecheck/build

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test && npm run build

期望:全部测试 passed;npm run build 成功(tsc 无类型错 + vite 产物)。若 build 报 ModelerFields/ReferencePicker 未用变量等 lint/类型错,按报错修齐再提交(参见 @superpowers:verification-before-completion)。

Step 17.7 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/pages/ReferencePicker.tsx src/pages/ReferencePicker.test.tsx && git commit -m "feat(modeler): reference-column picker (target entity + display column) per DECISION-1

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

第 4 节产出汇总(供后续节消费)

  • api:meta.ts(createEntity/listEntities/listEntityColumns)、recipe.ts(compileRecipe/listRecipes)、publish.ts(publishFeature)——签名见 providesContracts。Section 5 编排壳直接 import 这三个模块。
  • UI:/modeler 路由 + ModelerPage(实体清单 + 新建实体 Dialog);FieldTable/buildAttribute/ReferencePicker 可被 Section 5 复用为「第①环」步骤面板。
  • 测试基建:src/setupTests.ts + vitest.config.ts setupFiles 已就绪,Section 5/6 的 *.test.tsx 直接受益(jest-dom 匹配器 + 自动 cleanup)。

第 5 节 · 前端 编排壳「+新建功能」+ AI 入口「⚡AI建功能」(建物 3 前端 + 建物 4)

本节在「设计中心」里加两条入口:人走五环的编排壳 /new-feature,以及 AI ①面加速器 /ai-feature。两者都 admin-gated、都最终落到既有 editor.html 设计器(edit-only,模板须先存在)。消费 Section 4 的 src/api/meta.ts、src/api/recipe.ts、src/api/publish.ts(假定已存在)。

前置约定:所有 vitest 用 cd /Users/zhengwr/workspace/eip3/eip4-web && npm test(vitest run,跑全量);定向单文件用 cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/<path>.test.tsx。无全局 jsdom setup,故每个 .test.tsx 首行 import '@testing-library/jest-dom'。TDD:先写失败测试→跑出 FAIL→最小实现→跑出 PASS→提交。相关技能:@superpowers:test-driven-development。


Task 18 · 设计中心头部加两枚入口按钮(admin-gated)

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/DesignCenterPage.tsx(import 段第 1-6 行加 useNavigate;header flex row 第 73-74 行之间,搜索框前插两枚按钮)
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/DesignCenterPage.entrances.test.tsx(新建)

Step 18.1 — 写失败测试(admin 可见两按钮)

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/pages/DesignCenterPage.entrances.test.tsx:

import '@testing-library/jest-dom';
import { render, screen, waitFor } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
import { vi, describe, it, expect, beforeEach } from 'vitest';
import { DesignCenterPage } from './DesignCenterPage';

// menu 走真实 http → mock 掉,避免网络
vi.mock('../api/menu', () => ({
  fetchMenu: vi.fn().mockResolvedValue({ roots: [] }),
  collectLeaves: vi.fn().mockReturnValue([]),
}));

// 受控 profile:默认 admin
const profileMock = vi.fn();
vi.mock('../auth/token', () => ({
  getProfile: () => profileMock(),
}));

function renderPage() {
  return render(
    <MemoryRouter>
      <DesignCenterPage />
    </MemoryRouter>,
  );
}

describe('DesignCenterPage 入口按钮', () => {
  beforeEach(() => {
    profileMock.mockReset();
  });

  it('admin 看到 [+ 新建功能] 与 [⚡ AI 建功能]', async () => {
    profileMock.mockReturnValue({ account: 'admin', userId: 'ADMIN' });
    renderPage();
    await waitFor(() => {
      expect(screen.getByTestId('dc-new-feature')).toBeInTheDocument();
      expect(screen.getByTestId('dc-ai-feature')).toBeInTheDocument();
    });
  });

  it('非 admin 不渲染入口(整页降级)', () => {
    profileMock.mockReturnValue({ account: 'zhangsan', userId: 'U1' });
    renderPage();
    expect(screen.queryByTestId('dc-new-feature')).not.toBeInTheDocument();
    expect(screen.queryByTestId('dc-ai-feature')).not.toBeInTheDocument();
  });
});

Step 18.2 — 跑测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/pages/DesignCenterPage.entrances.test.tsx

期望 FAIL,报错形如:Unable to find an element by: [data-testid="dc-new-feature"]。

Step 18.3 — 最小实现:加 useNavigate import

把 /Users/zhengwr/workspace/eip3/eip4-web/src/pages/DesignCenterPage.tsx 第 4 行:

import { useEffect, useMemo, useState } from 'react';

改为:

import { useEffect, useMemo, useState } from 'react';
import { useNavigate } from 'react-router-dom';

在组件函数体内(第 21 行 const [q, setQ] = useState(''); 之后)加:

  const navigate = useNavigate();

Step 18.4 — 最小实现:header flex row 插两枚按钮

把第 73 行的 <div style={{ flex: 1 }} /> 替换为以下三段(弹簧 + 两按钮):

        <div style={{ flex: 1 }} />
        <button
          className="btn btn-sm"
          data-testid="dc-new-feature"
          onClick={() => navigate('/new-feature')}
          title="人走五环,从零搭建一个新功能"
        >
          + 新建功能
        </button>
        <button
          className="btn btn-sm"
          data-testid="dc-ai-feature"
          onClick={() => navigate('/ai-feature')}
          title="AI 加速器:外部 agent 起草,人审后进设计器"
        >
          ⚡ AI 建功能
        </button>

非 admin 早返回(第 59-61 行 if (!isAdmin) return ...)已在按钮渲染之前,故两按钮天然 admin-gated,第二个测试自动满足。

Step 18.5 — 跑测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/pages/DesignCenterPage.entrances.test.tsx

期望两条 it 全绿。

Step 18.6 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/pages/DesignCenterPage.tsx src/pages/DesignCenterPage.entrances.test.tsx && git commit -m "feat(design-center): admin 入口按钮 +新建功能 / ⚡AI建功能

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 19 · NewFeatureShell 编排壳页 /new-feature

状态机:entity(建模/选已有实体)→ recipe(选 recipe + 标题/显示字段/页大小)→ designed(compileRecipe 拿到 templateId,可进设计器)→ 发布。每步前进有守护:未选实体不能进 recipe 步;未 compile 出 templateId 不能进设计器 / 不能发布。

Files:

  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/NewFeatureShell.tsx
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/NewFeatureShell.test.tsx

Step 19.1 — 写失败测试(happy-path 步进 + compile + publish)

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/pages/NewFeatureShell.test.tsx:

import '@testing-library/jest-dom';
import { render, screen, waitFor, fireEvent } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
import { vi, describe, it, expect, beforeEach } from 'vitest';
import { NewFeatureShell } from './NewFeatureShell';

vi.mock('../auth/token', () => ({ getProfile: () => ({ account: 'admin', userId: 'ADMIN' }) }));

const listEntities = vi.fn();
const createEntity = vi.fn();
vi.mock('../api/meta', () => ({
  listEntities: (...a: unknown[]) => listEntities(...a),
  createEntity: (...a: unknown[]) => createEntity(...a),
}));

const listRecipes = vi.fn();
const compileRecipe = vi.fn();
vi.mock('../api/recipe', () => ({
  listRecipes: (...a: unknown[]) => listRecipes(...a),
  compileRecipe: (...a: unknown[]) => compileRecipe(...a),
}));

const publishFeature = vi.fn();
vi.mock('../api/publish', () => ({ publishFeature: (...a: unknown[]) => publishFeature(...a) }));

const fetchMenu = vi.fn();
vi.mock('../api/menu', () => ({ fetchMenu: (...a: unknown[]) => fetchMenu(...a), collectLeaves: vi.fn() }));

function renderShell() {
  return render(
    <MemoryRouter>
      <NewFeatureShell />
    </MemoryRouter>,
  );
}

describe('NewFeatureShell happy path', () => {
  beforeEach(() => {
    listEntities.mockReset().mockResolvedValue([
      { entityId: 'E1', tablename: 'OA_DEMO', name: '演示表' },
    ]);
    listRecipes.mockReset().mockReturnValue([
      { id: 'maintenance-crud-v1', label: '维护型 CRUD' },
      { id: 'tree-crud-v1', label: '树型 CRUD' },
    ]);
    compileRecipe.mockReset().mockResolvedValue({ templateId: 'TPL-NEW-1', etag: 'e1' });
    publishFeature.mockReset().mockResolvedValue({ menuId: 'M9', flows: ['OA_DEMO_ADD'] });
    fetchMenu.mockReset().mockResolvedValue({ roots: [] });
  });

  it('选实体→选 recipe→compile→进设计器按钮可用→发布', async () => {
    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
    renderShell();

    // step entity:等实体列表加载,选中第一个
    await waitFor(() => expect(screen.getByTestId('nf-entity-OA_DEMO')).toBeInTheDocument());
    fireEvent.click(screen.getByTestId('nf-entity-OA_DEMO'));
    fireEvent.click(screen.getByTestId('nf-next-entity'));

    // step recipe:默认选了第一个 recipe;填标题;compile
    await waitFor(() => expect(screen.getByTestId('nf-recipe-maintenance-crud-v1')).toBeInTheDocument());
    fireEvent.change(screen.getByTestId('nf-title'), { target: { value: '演示功能' } });
    fireEvent.click(screen.getByTestId('nf-compile'));

    await waitFor(() => expect(compileRecipe).toHaveBeenCalledWith({
      tableName: 'OA_DEMO',
      recipe: 'maintenance-crud-v1',
      title: '演示功能',
    }));

    // compile 成功 → 进设计器按钮出现且可用
    const designBtn = await screen.findByTestId('nf-open-designer');
    expect(designBtn).not.toBeDisabled();
    fireEvent.click(designBtn);
    expect(openSpy).toHaveBeenCalledWith('/editor.html?templateId=TPL-NEW-1', '_blank');

    // 发布
    fireEvent.change(screen.getByTestId('nf-menu-name'), { target: { value: '演示功能' } });
    fireEvent.click(screen.getByTestId('nf-publish'));
    await waitFor(() => expect(publishFeature).toHaveBeenCalledWith(expect.objectContaining({
      entityId: 'E1',
      tableName: 'OA_DEMO',
      templateId: 'TPL-NEW-1',
      menuName: '演示功能',
    })));
    await waitFor(() => expect(fetchMenu).toHaveBeenCalled());

    openSpy.mockRestore();
  });

  it('compile 之前进设计器按钮不存在/禁用', async () => {
    renderShell();
    await waitFor(() => expect(screen.getByTestId('nf-entity-OA_DEMO')).toBeInTheDocument());
    fireEvent.click(screen.getByTestId('nf-entity-OA_DEMO'));
    fireEvent.click(screen.getByTestId('nf-next-entity'));
    await waitFor(() => expect(screen.getByTestId('nf-recipe-maintenance-crud-v1')).toBeInTheDocument());
    // 还没 compile:进设计器按钮要么不存在要么 disabled
    const btn = screen.queryByTestId('nf-open-designer');
    expect(btn === null || (btn as HTMLButtonElement).disabled).toBe(true);
  });
});

Step 19.2 — 跑测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/pages/NewFeatureShell.test.tsx

期望 FAIL:Failed to resolve import "./NewFeatureShell" 或 Cannot find module(文件未建)。

Step 19.3 — 最小实现:建 NewFeatureShell.tsx

假定 Section 4 已导出:listEntities(): Promise<{entityId:string;tablename:string;name:string}[]>、listRecipes(): {id:string;label:string}[]、compileRecipe(body:{tableName;recipe;title;displayField?;pageSize?}): Promise<{templateId:string;etag:string}>、publishFeature(body): Promise<{menuId:string;flows:string[];deploymentPackage?:unknown}>。

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/pages/NewFeatureShell.tsx:

// 人走五环 · 编排壳 —— 从零搭建一个新功能页。
// 步骤:① 选/建实体(元数据+表)→ ② 选 recipe + 填页面参数 → compileRecipe 写 standard 层拿 templateId
//      → ③ 可选「进设计器微调」(editor.html 是 edit-only,模板已存在才允许) → ④ 发布(menu+5默认流)。
// 红线:发布恒人审;standard 写入恒走后端 PageSchemaWriter.upsertStandard(前端只调 compileRecipe)。
import { useEffect, useState } from 'react';
import { useNavigate } from 'react-router-dom';
import { getProfile } from '../auth/token';
import { listEntities } from '../api/meta';
import { listRecipes, compileRecipe } from '../api/recipe';
import { publishFeature } from '../api/publish';
import { fetchMenu } from '../api/menu';
import { toast } from '../components/ui/Toast';

interface EntityRow {
  entityId: string;
  tablename: string;
  name: string;
}

type Step = 'entity' | 'recipe';

const RECIPES = listRecipes(); // 静态清单(maintenance-crud-v1 / tree-crud-v1)

export function NewFeatureShell() {
  const navigate = useNavigate();
  const profile = getProfile();
  const isAdmin = profile?.account === 'admin' || profile?.userId === 'ADMIN';

  const [step, setStep] = useState<Step>('entity');
  const [entities, setEntities] = useState<EntityRow[]>([]);
  const [loadErr, setLoadErr] = useState('');
  const [selectedEntity, setSelectedEntity] = useState<EntityRow | null>(null);

  const [recipe, setRecipe] = useState<string>(RECIPES[0]?.id ?? 'maintenance-crud-v1');
  const [title, setTitle] = useState('');
  const [displayField, setDisplayField] = useState('');
  const [pageSize, setPageSize] = useState<number | ''>('');

  const [templateId, setTemplateId] = useState('');
  const [compiling, setCompiling] = useState(false);
  const [menuName, setMenuName] = useState('');
  const [publishing, setPublishing] = useState(false);

  useEffect(() => {
    if (!isAdmin) return;
    let alive = true;
    listEntities()
      .then((rows) => alive && setEntities(rows))
      .catch((e: Error) => alive && setLoadErr(e.message ?? '实体加载失败'));
    return () => {
      alive = false;
    };
  }, [isAdmin]);

  if (!isAdmin) {
    return <div style={{ padding: 24, color: 'var(--text-3)' }}>新建功能仅管理员可用。</div>;
  }

  async function doCompile() {
    if (!selectedEntity || !title.trim()) {
      toast('请先选实体并填写页面标题', 'warn');
      return;
    }
    setCompiling(true);
    try {
      const body: { tableName: string; recipe: string; title: string; displayField?: string; pageSize?: number } = {
        tableName: selectedEntity.tablename,
        recipe,
        title: title.trim(),
      };
      if (displayField.trim()) body.displayField = displayField.trim();
      if (pageSize !== '') body.pageSize = Number(pageSize);
      const res = await compileRecipe(body);
      setTemplateId(res.templateId);
      if (!menuName.trim()) setMenuName(title.trim());
      toast('已生成页面,可进设计器微调或直接发布', 'ok');
    } catch (e) {
      toast((e as Error).message ?? '生成失败', 'err');
    } finally {
      setCompiling(false);
    }
  }

  function openDesigner() {
    if (!templateId) return;
    window.open(`/editor.html?templateId=${encodeURIComponent(templateId)}`, '_blank');
  }

  async function doPublish() {
    if (!selectedEntity || !templateId || !menuName.trim()) {
      toast('发布需先生成页面并填写菜单名', 'warn');
      return;
    }
    setPublishing(true);
    try {
      const res = await publishFeature({
        entityId: selectedEntity.entityId,
        tableName: selectedEntity.tablename,
        templateId,
        menuName: menuName.trim(),
        generateDeploymentPackage: true,
      });
      await fetchMenu(); // 刷新左侧菜单缓存(新节点)
      toast(`已发布:菜单 ${res.menuId},默认流 ${res.flows.join('、')}`, 'ok');
    } catch (e) {
      toast((e as Error).message ?? '发布失败', 'err');
    } finally {
      setPublishing(false);
    }
  }

  return (
    <div style={{ height: '100%', overflow: 'auto', padding: 'var(--pad-lg)' }} data-testid="new-feature-shell">
      <div style={{ display: 'flex', alignItems: 'center', gap: 12, marginBottom: 16 }}>
        <button className="btn btn-sm" onClick={() => navigate('/design-center')}>
          ← 返回设计中心
        </button>
        <h2 style={{ margin: 0, fontSize: 18, fontWeight: 600 }}>新建功能 · 人走五环</h2>
      </div>

      {/* 步骤指示 */}
      <div className="sub-text" style={{ marginBottom: 16 }}>
        {step === 'entity' ? '步骤 1 / 2 :选择实体(元数据+表)' : '步骤 2 / 2 :选 recipe、生成页面、发布'}
      </div>

      {loadErr ? <div style={{ padding: 12, color: 'var(--err)' }}>实体加载失败:{loadErr}</div> : null}

      {step === 'entity' ? (
        <div className="card" style={{ padding: 16 }}>
          <div style={{ marginBottom: 10, fontWeight: 600 }}>选择已有实体</div>
          <table style={{ width: '100%', borderCollapse: 'collapse' }}>
            <thead>
              <tr style={{ textAlign: 'left', color: 'var(--text-3)' }}>
                <th style={{ padding: '6px 8px' }}>名称</th>
                <th style={{ padding: '6px 8px' }}>表名</th>
                <th style={{ padding: '6px 8px', width: 80 }} />
              </tr>
            </thead>
            <tbody>
              {entities.map((en) => (
                <tr
                  key={en.entityId}
                  style={{
                    borderTop: '1px solid var(--line)',
                    background: selectedEntity?.entityId === en.entityId ? 'var(--hover)' : undefined,
                  }}
                >
                  <td style={{ padding: '6px 8px' }}>{en.name}</td>
                  <td style={{ padding: '6px 8px' }} className="muted">{en.tablename}</td>
                  <td style={{ padding: '6px 8px' }}>
                    <button
                      className="btn btn-sm"
                      data-testid={`nf-entity-${en.tablename}`}
                      onClick={() => setSelectedEntity(en)}
                    >
                      {selectedEntity?.entityId === en.entityId ? '已选' : '选择'}
                    </button>
                  </td>
                </tr>
              ))}
            </tbody>
          </table>
          <div style={{ marginTop: 16, display: 'flex', gap: 8 }}>
            <button
              className="btn"
              data-testid="nf-next-entity"
              disabled={!selectedEntity}
              onClick={() => setStep('recipe')}
            >
              下一步:选 recipe
            </button>
          </div>
        </div>
      ) : (
        <div className="card" style={{ padding: 16 }}>
          <div style={{ marginBottom: 10 }}>
            实体:<b>{selectedEntity?.name}</b>{' '}
            <span className="muted">({selectedEntity?.tablename})</span>{' '}
            <span className="link" onClick={() => setStep('entity')}>更换</span>
          </div>

          <div style={{ marginBottom: 12 }}>
            <div style={{ marginBottom: 6, fontWeight: 600 }}>页面模板 recipe</div>
            {RECIPES.map((r) => (
              <label key={r.id} style={{ marginRight: 16, cursor: 'pointer' }} data-testid={`nf-recipe-${r.id}`}>
                <input
                  type="radio"
                  name="recipe"
                  checked={recipe === r.id}
                  onChange={() => setRecipe(r.id)}
                />{' '}
                {r.label}
              </label>
            ))}
          </div>

          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, marginBottom: 12 }}>
            <label>
              <div className="muted">页面标题 *</div>
              <input data-testid="nf-title" value={title} onChange={(e) => setTitle(e.target.value)} />
            </label>
            <label>
              <div className="muted">显示字段(可选)</div>
              <input
                data-testid="nf-display-field"
                value={displayField}
                onChange={(e) => setDisplayField(e.target.value)}
              />
            </label>
            <label>
              <div className="muted">页大小(可选)</div>
              <input
                data-testid="nf-page-size"
                type="number"
                value={pageSize}
                onChange={(e) => setPageSize(e.target.value === '' ? '' : Number(e.target.value))}
              />
            </label>
          </div>

          <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
            <button className="btn" data-testid="nf-compile" disabled={compiling || !title.trim()} onClick={doCompile}>
              {compiling ? '生成中…' : templateId ? '重新生成页面' : '生成页面'}
            </button>
            <button
              className="btn"
              data-testid="nf-open-designer"
              disabled={!templateId}
              onClick={openDesigner}
              title={templateId ? '在新标签页打开设计器微调' : '先生成页面才能进设计器'}
            >
              进设计器微调
            </button>
          </div>

          {templateId ? (
            <div className="card" style={{ padding: 12, background: 'var(--surface-2)' }}>
              <div style={{ marginBottom: 8 }}>
                已生成模板:<code data-testid="nf-template-id">{templateId}</code>
              </div>
              <div style={{ display: 'flex', alignItems: 'flex-end', gap: 8 }}>
                <label>
                  <div className="muted">菜单名 *</div>
                  <input data-testid="nf-menu-name" value={menuName} onChange={(e) => setMenuName(e.target.value)} />
                </label>
                <button
                  className="btn btn-primary"
                  data-testid="nf-publish"
                  disabled={publishing || !menuName.trim()}
                  onClick={doPublish}
                >
                  {publishing ? '发布中…' : '发布'}
                </button>
              </div>
              <div className="sub-text" style={{ marginTop: 8 }}>
                发布 = 写标准页 + 触发 5 条默认流 + 注册菜单(当前后端立即可用);并生成生产部署包供人审上线。
              </div>
            </div>
          ) : null}
        </div>
      )}
    </div>
  );
}

Step 19.4 — 跑测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/pages/NewFeatureShell.test.tsx

期望两条 it 全绿。若 RECIPES = listRecipes() 在模块加载期调用导致 mock 时序问题,测试已用 vi.mock 工厂提前注入,模块 import 时 mock 已生效,安全。

Step 19.5 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/pages/NewFeatureShell.tsx src/pages/NewFeatureShell.test.tsx && git commit -m "feat(new-feature): 人走五环编排壳页 NewFeatureShell(建模→recipe→compile→设计器→发布)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 20 · AI 入口 api 模块 + AiFeatureForm 页 /ai-feature

红线:AI ①面产物 status 恒 READY_FOR_HUMAN_REVIEW,永不自动发布;人审动作 = 点「审阅草稿(进设计器)」打开 editor.html。

Files:

  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/api/ai.ts
  • Create: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/AiFeatureForm.tsx
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/api/ai.test.ts(提取契约单测)
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/pages/AiFeatureForm.test.tsx(组件测试)

Step 20.1 — 写失败测试:提取契约(纯函数)

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/api/ai.test.ts:

import { describe, it, expect } from 'vitest';
import { extractPageSchemaTemplateId } from './ai';
import type { AiAutoDevelopRun } from './ai';

describe('extractPageSchemaTemplateId', () => {
  it('从 PAGE_SCHEMA draft 取 targetId', () => {
    const run: AiAutoDevelopRun = {
      taskId: 't1',
      status: 'READY_FOR_HUMAN_REVIEW',
      development: {
        drafts: [
          { artifactType: 'FLOW', targetId: 'OA_X_ADD' },
          { artifactType: 'PAGE_SCHEMA', targetId: 'TPL-AI-9' },
        ],
      },
    };
    expect(extractPageSchemaTemplateId(run)).toBe('TPL-AI-9');
  });

  it('无 PAGE_SCHEMA draft 时返回 undefined', () => {
    const run: AiAutoDevelopRun = {
      taskId: 't2',
      status: 'READY_FOR_HUMAN_REVIEW',
      development: { drafts: [{ artifactType: 'FLOW', targetId: 'X' }] },
    };
    expect(extractPageSchemaTemplateId(run)).toBeUndefined();
  });

  it('development 缺失时安全返回 undefined', () => {
    const run: AiAutoDevelopRun = { taskId: 't3', status: 'FAILED' };
    expect(extractPageSchemaTemplateId(run)).toBeUndefined();
  });
});

Step 20.2 — 跑测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/api/ai.test.ts

期望 FAIL:Failed to resolve import "./ai"。

Step 20.3 — 最小实现:建 src/api/ai.ts

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/api/ai.ts:

// AI ①面加速器入口 —— POST /api/ai/features/auto-develop(admin)。
// 平台进程内不内置生成 LLM:实际起草由外部 agent + Skills 完成,本接口只是确定性编排+人审门禁。
// 终端良态 status === 'READY_FOR_HUMAN_REVIEW'(红线:永不自动发布)。
//
// ⚠️ 端口约束:后端 auto-develop 会以 baseUrl 回调写后端。dev 默认 8084 已死,
//    本前端透传 baseUrl = window.location.origin(经 vite 代理 /api → 8093)。
//    若省略 baseUrl,则要求后端 dev profile 自身的 baseUrl 指向 8093(根因修在后端 Section)。
import { http } from './http';

export interface AiFeatureField {
  column: string;
  label: string;
  type: string;
  length?: number;
  required?: boolean;
}

export interface AiAutoDevelopBody {
  feature: {
    objective: string;
    featureName: string;
    tableName: string;
    entityName: string;
    templateId?: string;
    menuName?: string;
    fields: AiFeatureField[];
    pageRecipe: 'maintenance-crud-v1' | 'tree-crud-v1';
  };
  baseUrl?: string;
  generateDeploymentPackage?: boolean;
  maxRepairAttempts?: number;
}

export interface AiDraft {
  artifactType: string; // 'PAGE_SCHEMA' | 'FLOW' | ...
  targetId: string;
  payload?: unknown;
}

export interface AiAutoDevelopRun {
  taskId: string;
  status: string; // 'READY_FOR_HUMAN_REVIEW' = 终端良态
  development?: { drafts?: AiDraft[] };
  applyRun?: unknown;
  deploymentPackage?: unknown;
  messages?: string[];
}

/** 终端良态判定(红线:AI 入口产物恒此状态才可人审进设计器)。 */
export const READY_STATUS = 'READY_FOR_HUMAN_REVIEW';

/** 从 run 提取 PAGE_SCHEMA draft 的 targetId(即写入 standard 层的 templateId)。 */
export function extractPageSchemaTemplateId(run: AiAutoDevelopRun): string | undefined {
  return run.development?.drafts?.find((d) => d.artifactType === 'PAGE_SCHEMA')?.targetId;
}

export async function autoDevelop(body: AiAutoDevelopBody): Promise<AiAutoDevelopRun> {
  // 透传 baseUrl=当前前端 origin,让后端回调经 vite 代理打到正在跑的 8093(而非死的 8084)。
  const payload: AiAutoDevelopBody = {
    baseUrl: window.location.origin,
    generateDeploymentPackage: true,
    ...body,
  };
  const { data } = await http.post<AiAutoDevelopRun>('/api/ai/features/auto-develop', payload);
  return data;
}

Step 20.4 — 跑测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/api/ai.test.ts

期望 3 条全绿。

Step 20.5 — 写失败测试:AiFeatureForm 组件(mocked READY run → 审阅按钮开正确 templateId)

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/pages/AiFeatureForm.test.tsx:

import '@testing-library/jest-dom';
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
import { vi, describe, it, expect, beforeEach } from 'vitest';
import { AiFeatureForm } from './AiFeatureForm';

vi.mock('../auth/token', () => ({ getProfile: () => ({ account: 'admin', userId: 'ADMIN' }) }));

const autoDevelop = vi.fn();
vi.mock('../api/ai', async (importOriginal) => {
  const actual = await importOriginal<typeof import('../api/ai')>();
  return { ...actual, autoDevelop: (...a: unknown[]) => autoDevelop(...a) };
});

function renderForm() {
  return render(
    <MemoryRouter>
      <AiFeatureForm />
    </MemoryRouter>,
  );
}

describe('AiFeatureForm', () => {
  beforeEach(() => autoDevelop.mockReset());

  it('READY_FOR_HUMAN_REVIEW 后审阅按钮打开正确 templateId', async () => {
    autoDevelop.mockResolvedValue({
      taskId: 't1',
      status: 'READY_FOR_HUMAN_REVIEW',
      development: { drafts: [{ artifactType: 'PAGE_SCHEMA', targetId: 'TPL-AI-9' }] },
      messages: ['ok'],
    });
    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
    renderForm();

    fireEvent.change(screen.getByTestId('ai-objective'), { target: { value: '做个登记表' } });
    fireEvent.change(screen.getByTestId('ai-feature-name'), { target: { value: '登记' } });
    fireEvent.change(screen.getByTestId('ai-table-name'), { target: { value: 'OA_REG' } });
    fireEvent.change(screen.getByTestId('ai-entity-name'), { target: { value: '登记表' } });
    fireEvent.click(screen.getByTestId('ai-submit'));

    const reviewBtn = await screen.findByTestId('ai-review');
    fireEvent.click(reviewBtn);
    expect(openSpy).toHaveBeenCalledWith('/editor.html?templateId=TPL-AI-9', '_blank');
    openSpy.mockRestore();
  });

  it('非 READY 状态展示 messages,不出审阅按钮', async () => {
    autoDevelop.mockResolvedValue({
      taskId: 't2',
      status: 'FAILED',
      messages: ['校验未通过:字段缺失'],
    });
    renderForm();
    fireEvent.change(screen.getByTestId('ai-objective'), { target: { value: 'x' } });
    fireEvent.change(screen.getByTestId('ai-feature-name'), { target: { value: 'x' } });
    fireEvent.change(screen.getByTestId('ai-table-name'), { target: { value: 'OA_X' } });
    fireEvent.change(screen.getByTestId('ai-entity-name'), { target: { value: 'x' } });
    fireEvent.click(screen.getByTestId('ai-submit'));
    await waitFor(() => expect(screen.getByText(/校验未通过/)).toBeInTheDocument());
    expect(screen.queryByTestId('ai-review')).not.toBeInTheDocument();
  });
});

Step 20.6 — 跑测试,期望 FAIL

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/pages/AiFeatureForm.test.tsx

期望 FAIL:Failed to resolve import "./AiFeatureForm"。

Step 20.7 — 最小实现:建 AiFeatureForm.tsx

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/pages/AiFeatureForm.tsx:

// AI ①面加速器入口页 —— 填需求,调外部 agent 起草,产物恒 READY_FOR_HUMAN_REVIEW,
// 人点「审阅草稿」进 editor.html(edit-only,模板已由 auto-develop 写入 standard 层)。
// 红线:永不自动发布;平台进程内不内置生成 LLM。
import { useState } from 'react';
import { useNavigate } from 'react-router-dom';
import { getProfile } from '../auth/token';
import {
  autoDevelop,
  extractPageSchemaTemplateId,
  READY_STATUS,
  type AiAutoDevelopRun,
  type AiFeatureField,
} from '../api/ai';
import { toast } from '../components/ui/Toast';

export function AiFeatureForm() {
  const navigate = useNavigate();
  const profile = getProfile();
  const isAdmin = profile?.account === 'admin' || profile?.userId === 'ADMIN';

  const [objective, setObjective] = useState('');
  const [featureName, setFeatureName] = useState('');
  const [tableName, setTableName] = useState('');
  const [entityName, setEntityName] = useState('');
  const [pageRecipe, setPageRecipe] = useState<'maintenance-crud-v1' | 'tree-crud-v1'>('maintenance-crud-v1');
  const [fields, setFields] = useState<AiFeatureField[]>([{ column: '', label: '', type: 'string' }]);

  const [running, setRunning] = useState(false);
  const [run, setRun] = useState<AiAutoDevelopRun | null>(null);

  if (!isAdmin) {
    return <div style={{ padding: 24, color: 'var(--text-3)' }}>AI 建功能仅管理员可用。</div>;
  }

  const reviewTemplateId = run && run.status === READY_STATUS ? extractPageSchemaTemplateId(run) : undefined;

  function setField(i: number, patch: Partial<AiFeatureField>) {
    setFields((fs) => fs.map((f, idx) => (idx === i ? { ...f, ...patch } : f)));
  }
  function addField() {
    setFields((fs) => [...fs, { column: '', label: '', type: 'string' }]);
  }
  function removeField(i: number) {
    setFields((fs) => fs.filter((_, idx) => idx !== i));
  }

  async function submit() {
    if (!objective.trim() || !featureName.trim() || !tableName.trim() || !entityName.trim()) {
      toast('请填写需求、功能名、表名、实体名', 'warn');
      return;
    }
    setRunning(true);
    setRun(null);
    try {
      const res = await autoDevelop({
        feature: {
          objective: objective.trim(),
          featureName: featureName.trim(),
          tableName: tableName.trim(),
          entityName: entityName.trim(),
          fields: fields.filter((f) => f.column.trim()),
          pageRecipe,
        },
      });
      setRun(res);
      if (res.status === READY_STATUS) {
        toast('草稿已就绪,请审阅后进设计器', 'ok');
      } else {
        toast(`未达人审就绪状态:${res.status}`, 'warn');
      }
    } catch (e) {
      toast((e as Error).message ?? 'AI 起草失败', 'err');
    } finally {
      setRunning(false);
    }
  }

  function openReview() {
    if (!reviewTemplateId) return;
    window.open(`/editor.html?templateId=${encodeURIComponent(reviewTemplateId)}`, '_blank');
  }

  return (
    <div style={{ height: '100%', overflow: 'auto', padding: 'var(--pad-lg)' }} data-testid="ai-feature-form">
      <div style={{ display: 'flex', alignItems: 'center', gap: 12, marginBottom: 16 }}>
        <button className="btn btn-sm" onClick={() => navigate('/design-center')}>← 返回设计中心</button>
        <h2 style={{ margin: 0, fontSize: 18, fontWeight: 600 }}>⚡ AI 建功能</h2>
      </div>
      <div className="sub-text" style={{ marginBottom: 16 }}>
        外部 AI agent 起草,产物恒人审;点「审阅草稿」进设计器,平台不自动发布。
      </div>

      <div className="card" style={{ padding: 16, maxWidth: 720 }}>
        <div style={{ display: 'flex', flexDirection: 'column', gap: 10 }}>
          <label>
            <div className="muted">需求目标 objective *</div>
            <textarea data-testid="ai-objective" rows={2} style={{ width: '100%' }}
              value={objective} onChange={(e) => setObjective(e.target.value)} />
          </label>
          <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
            <label>
              <div className="muted">功能名 featureName *</div>
              <input data-testid="ai-feature-name" value={featureName} onChange={(e) => setFeatureName(e.target.value)} />
            </label>
            <label>
              <div className="muted">表名 tableName *</div>
              <input data-testid="ai-table-name" value={tableName} onChange={(e) => setTableName(e.target.value)} />
            </label>
            <label>
              <div className="muted">实体名 entityName *</div>
              <input data-testid="ai-entity-name" value={entityName} onChange={(e) => setEntityName(e.target.value)} />
            </label>
            <label>
              <div className="muted">页面模板</div>
              <select data-testid="ai-recipe" value={pageRecipe}
                onChange={(e) => setPageRecipe(e.target.value as 'maintenance-crud-v1' | 'tree-crud-v1')}>
                <option value="maintenance-crud-v1">维护型 CRUD</option>
                <option value="tree-crud-v1">树型 CRUD</option>
              </select>
            </label>
          </div>

          <div>
            <div className="muted" style={{ marginBottom: 6 }}>字段(column 留空的行忽略)</div>
            {fields.map((f, i) => (
              <div key={i} style={{ display: 'flex', gap: 6, marginBottom: 6 }}>
                <input placeholder="column" data-testid={`ai-field-col-${i}`}
                  value={f.column} onChange={(e) => setField(i, { column: e.target.value })} />
                <input placeholder="label"
                  value={f.label} onChange={(e) => setField(i, { label: e.target.value })} />
                <select value={f.type} onChange={(e) => setField(i, { type: e.target.value })}>
                  <option value="string">string</option>
                  <option value="integer">integer</option>
                  <option value="number">number</option>
                  <option value="date">date</option>
                  <option value="datetime">datetime</option>
                  <option value="boolean">boolean</option>
                </select>
                <label style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
                  <input type="checkbox" checked={!!f.required}
                    onChange={(e) => setField(i, { required: e.target.checked })} /> 必填
                </label>
                <button className="btn btn-sm" onClick={() => removeField(i)}>删</button>
              </div>
            ))}
            <button className="btn btn-sm" onClick={addField}>+ 加字段</button>
          </div>

          <div style={{ marginTop: 8 }}>
            <button className="btn btn-primary" data-testid="ai-submit" disabled={running} onClick={submit}>
              {running ? 'AI 起草中…' : '开始 AI 起草'}
            </button>
          </div>
        </div>
      </div>

      {run ? (
        <div className="card" style={{ padding: 16, maxWidth: 720, marginTop: 16 }}>
          <div style={{ marginBottom: 8 }}>
            状态:<b data-testid="ai-status">{run.status}</b>{' '}
            <span className="muted">taskId={run.taskId}</span>
          </div>
          {reviewTemplateId ? (
            <button className="btn btn-primary" data-testid="ai-review" onClick={openReview}>
              审阅草稿(进设计器)
            </button>
          ) : (
            <div>
              <div className="sub-text" style={{ marginBottom: 6 }}>未生成可审阅的页面草稿,运行信息:</div>
              <ul>
                {(run.messages ?? ['(无消息)']).map((m, i) => (
                  <li key={i} style={{ color: 'var(--text-3)' }}>{m}</li>
                ))}
              </ul>
            </div>
          )}
        </div>
      ) : null}
    </div>
  );
}

Step 20.8 — 跑测试,期望 PASS

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/pages/AiFeatureForm.test.tsx src/api/ai.test.ts

期望 ai.test.ts 3 条 + AiFeatureForm.test.tsx 2 条全绿。

Step 20.9 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/api/ai.ts src/api/ai.test.ts src/pages/AiFeatureForm.tsx src/pages/AiFeatureForm.test.tsx && git commit -m "feat(ai-feature): AI ①面入口页 + api/ai.ts(auto-develop,恒 READY_FOR_HUMAN_REVIEW 人审)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 21 · 路由接线 + 守护 + 构建校验

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/src/App.tsx(imports 第 10 行后加两条 import;<Route> 第 42 行后加两条路由)
  • Test: /Users/zhengwr/workspace/eip3/eip4-web/src/App.routes.test.tsx(新建)

Step 21.1 — 写失败测试:两条路由渲染对应页

新建 /Users/zhengwr/workspace/eip3/eip4-web/src/App.routes.test.tsx:

import '@testing-library/jest-dom';
import { render, screen, waitFor } from '@testing-library/react';
import { MemoryRouter, Routes, Route } from 'react-router-dom';
import { vi, describe, it, expect } from 'vitest';
import { NewFeatureShell } from './pages/NewFeatureShell';
import { AiFeatureForm } from './pages/AiFeatureForm';

vi.mock('./auth/token', () => ({ getProfile: () => ({ account: 'admin', userId: 'ADMIN' }) }));
vi.mock('./api/meta', () => ({ listEntities: vi.fn().mockResolvedValue([]), createEntity: vi.fn() }));
vi.mock('./api/recipe', () => ({ listRecipes: () => [{ id: 'maintenance-crud-v1', label: '维护型 CRUD' }], compileRecipe: vi.fn() }));
vi.mock('./api/publish', () => ({ publishFeature: vi.fn() }));
vi.mock('./api/menu', () => ({ fetchMenu: vi.fn().mockResolvedValue({ roots: [] }), collectLeaves: vi.fn() }));
vi.mock('./api/ai', async (io) => {
  const actual = await io<typeof import('./api/ai')>();
  return { ...actual, autoDevelop: vi.fn() };
});

describe('新路由可达', () => {
  it('/new-feature 渲染 NewFeatureShell', async () => {
    render(
      <MemoryRouter initialEntries={['/new-feature']}>
        <Routes>
          <Route path="/new-feature" element={<NewFeatureShell />} />
          <Route path="/ai-feature" element={<AiFeatureForm />} />
        </Routes>
      </MemoryRouter>,
    );
    await waitFor(() => expect(screen.getByTestId('new-feature-shell')).toBeInTheDocument());
  });

  it('/ai-feature 渲染 AiFeatureForm', () => {
    render(
      <MemoryRouter initialEntries={['/ai-feature']}>
        <Routes>
          <Route path="/new-feature" element={<NewFeatureShell />} />
          <Route path="/ai-feature" element={<AiFeatureForm />} />
        </Routes>
      </MemoryRouter>,
    );
    expect(screen.getByTestId('ai-feature-form')).toBeInTheDocument();
  });
});

此测试用本地 <Routes> 验证两页可被路由挂载(不引整个 App 以避开 BrowserRouter/AppShell 依赖)。它会在 Step 21.2 直接 PASS(页面已建),但作为接线锚点保留;若两页 import 路径错则 FAIL。先确认它本身能跑过:

cd /Users/zhengwr/workspace/eip3/eip4-web && npx vitest run src/App.routes.test.tsx

期望 2 条全绿(两页已在 Task 19/20 建好)。若 FAIL 多半是 mock 路径写错,修正后再继续。

Step 21.2 — 接线 App.tsx:加 import

把 /Users/zhengwr/workspace/eip3/eip4-web/src/App.tsx 第 10 行:

import { DesignCenterPage } from './pages/DesignCenterPage';

改为:

import { DesignCenterPage } from './pages/DesignCenterPage';
import { NewFeatureShell } from './pages/NewFeatureShell';
import { AiFeatureForm } from './pages/AiFeatureForm';

Step 21.3 — 接线 App.tsx:加两条 Route

把第 41-42 行:

          {/* 设计中心(管理员集中式低代码设计入口,替代每页设计按钮)*/}
          <Route path="/design-center" element={<DesignCenterPage />} />

改为:

          {/* 设计中心(管理员集中式低代码设计入口,替代每页设计按钮)*/}
          <Route path="/design-center" element={<DesignCenterPage />} />
          {/* 人走五环编排壳 + AI ①面入口(admin-gated,页内早返回守护)*/}
          <Route path="/new-feature" element={<NewFeatureShell />} />
          <Route path="/ai-feature" element={<AiFeatureForm />} />

守护:两页组件内部已 if (!isAdmin) return <降级提示>(Task 19/20 已实现),无需额外路由守卫。最终 App.tsx 的 import 段与 Route 段 diff 如上两块。

Step 21.4 — 全量单测 + 类型构建校验

cd /Users/zhengwr/workspace/eip3/eip4-web && npm test

期望全绿(含本节 4 个新测试文件)。再跑生产构建(含 tsc -b 类型检查),证明接线无类型/编译错:

cd /Users/zhengwr/workspace/eip3/eip4-web && npm run build

期望构建成功、无 TS 报错。若报 src/api/meta/recipe/publish 模块缺失,说明 Section 4 尚未合入——此时该构建在本节单独验证时可能失败,属预期跨节依赖:本节 PR 须在 Section 4 之后落地,或临时桩接(见 risksOrGaps)。

Step 21.5 — 提交

cd /Users/zhengwr/workspace/eip3/eip4-web && git add src/App.tsx src/App.routes.test.tsx && git commit -m "feat(routes): 接线 /new-feature 与 /ai-feature(admin-gated 页内守护)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Step 21.6 — 手验(文档化,依赖后端 8093 在跑 + Section 1-4 已合)

  1. 起后端:JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTests && /opt/homebrew/opt/openjdk@21/bin/java -jar platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=dev(8093)。
  2. 起前端:cd /Users/zhengwr/workspace/eip3/eip4-web && npm run dev(5173,.env.local 代理 /api → 8093)。
  3. 浏览器 admin 登录 → /design-center → 看到 [+ 新建功能] / [⚡ AI 建功能]。
  4. 走 /new-feature:选实体 → 选 recipe → 生成页面(compileRecipe 写 standard)→ 进设计器(新标签打开 editor.html?templateId=...,能加载即证明模板已存在)→ 填菜单名 → 发布 → 回工作台刷新看新菜单节点。
  5. 走 /ai-feature:填需求提交 → 若返回 READY_FOR_HUMAN_REVIEW 出「审阅草稿」→ 打开 editor.html 加载 PAGE_SCHEMA draft 的 targetId 模板。
    • ⚠️ 若 auto-develop 的 applyRun 落空 / editor 404:检查后端 dev profile 的 auto-develop baseUrl 是否打到 8093(非死的 8084)——根因修在后端 Section,本节前端已透传 baseUrl=window.location.origin。

第 6 节 · serving/门禁修复 + 端到端 dev 演示验收(横向)

本节横向收尾:让 fresh checkout 的 dev 环境开箱即通、修掉 editor.html 生产构建样式 404、并给出一份「四环建新功能」端到端验收脚本(证据先行)。 本节不新增后端契约。Task 22/23 是配置与构建产物修复(无 vitest 单测,验证以 build/preview/浏览器 network 证据为准,遵循 @superpowers:verification-before-completion);Task 24 是验收脚本本身。 前置:Section 1(GET /api/meta/entities、GET /api/meta/entity/{table}/attributes、reference 列支持)、Section 2(POST /api/design/recipe/compile)、Section 3(GET /api/design/flows、POST /api/design/publish、菜单注册)、Section 4/5(设计中心页与 + 新建功能 / ⚡ AI 建功能 入口)必须已合入并可用。


Task 22 · 把 dev 后端反代目标改为可复现(8084 → 8093)

问题:.env.local(指向 8093)被 .gitignore 排除(.gitignore 含 .env.local),fresh checkout 拿不到它;此时 vite 退回 .env(VITE_BACKEND_TARGET=http://localhost:8084)与 vite.config.ts 第 19 行默认 'http://localhost:8084',而 8084 是 local profile、当前 dev 跑在 8093 → 新克隆者 dev server 反代到死端口,所有 /api 失败。修复:把这两处提交进库的默认值统一改为 8093。

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/.env(第 1-2 行)
  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/vite.config.ts(第 5-6 行注释 + 第 19 行默认值)
  • 无新增测试文件(纯配置;验证为文档化 manual 检查)

Step 22.1 — 改 .env 默认目标为 8093

把 /Users/zhengwr/workspace/eip3/eip4-web/.env 整文件替换为:

# 后端反代目标。dev profile 默认 8093(本机联调跑这个口)。
# 若端口冲突,复制本文件为 .env.local 并改 VITE_BACKEND_TARGET(.env.local 已 gitignore,不入库)。
VITE_BACKEND_TARGET=http://localhost:8093

确切 diff:

--- a/eip4-web/.env
+++ b/eip4-web/.env
-# 后端反代目标。后端默认 8084(local profile);若 8084 被占改为 8090,此处同步改。
-VITE_BACKEND_TARGET=http://localhost:8084
+# 后端反代目标。dev profile 默认 8093(本机联调跑这个口)。
+# 若端口冲突,复制本文件为 .env.local 并改 VITE_BACKEND_TARGET(.env.local 已 gitignore,不入库)。
+VITE_BACKEND_TARGET=http://localhost:8093

Step 22.2 — 改 vite.config.ts 默认 fallback 与注释为 8093

在 /Users/zhengwr/workspace/eip3/eip4-web/vite.config.ts 改第 5-6 行注释与第 19 行默认值。

第 5-6 行注释替换:

--- a/eip4-web/vite.config.ts
+++ b/eip4-web/vite.config.ts
-// 开发期 dev server 把 /api 反代到后端(默认 8084,端口被占时改 8090)。
-// 后端地址经 .env 的 VITE_BACKEND_TARGET 配置;生产由 Nginx 反代,前端只发相对 /api。
+// 开发期 dev server 把 /api 反代到后端(dev profile 默认 8093,端口被占时用 .env.local 覆盖)。
+// 后端地址经 .env 的 VITE_BACKEND_TARGET 配置;生产由 Nginx 反代,前端只发相对 /api。

第 19 行默认值替换:

-  const backendTarget = env.VITE_BACKEND_TARGET || 'http://localhost:8084';
+  const backendTarget = env.VITE_BACKEND_TARGET || 'http://localhost:8093';

Step 22.3 — 文档化 manual 验证(无单测)

这是反代配置,正确做法是跑真后端验证,不写 vitest(YAGNI:单测无法验证代理真连)。按序执行并记录证据:

  1. 起 dev profile 后端(8093):
cd /Users/zhengwr/workspace/eip3 && JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTests && /opt/homebrew/opt/openjdk@21/bin/java -jar eip4-platform/platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=dev

预期:日志含 Tomcat started on port(s): 8093。

  1. 临时移走 .env.local 模拟 fresh checkout(验证默认值生效),起 dev server:
cd /Users/zhengwr/workspace/eip3/eip4-web && mv .env.local .env.local.bak 2>/dev/null; npm run dev

预期:vite 打印 Local: http://localhost:5173/。

  1. 通过 dev server 代理打后端(另开终端):
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5173/api/menu

预期输出:401(未带 token 的受保护端口;关键是非 502/ECONNREFUSED——证明代理打到了活后端 8093,而不是死的 8084)。若得 502 或连接拒绝,说明默认目标仍错。

  1. 恢复 .env.local:
cd /Users/zhengwr/workspace/eip3/eip4-web && mv .env.local.bak .env.local 2>/dev/null || true

Step 22.4 — commit

cd /Users/zhengwr/workspace/eip3 && git add eip4-web/.env eip4-web/vite.config.ts && git commit -m "fix(web): dev 反代默认目标 8084→8093,fresh checkout 开箱即通

.env.local(8093) 被 gitignore 排除,新克隆退回 .env/vite.config 的 8084(local profile)死口。
统一提交进库的默认值为 8093(dev profile),无需手建 .env.local 即可联调。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 23 · 修 editor.html 生产构建 CSS 404(架构 §7 已知阻塞)

问题:editor.html 第 9-11 行用绝对路径 <link href="/node_modules/amis-editor-core/lib/style.css"> 等三条引 CSS。dev 期 vite server.fs.allow:['..'] 放开 node_modules 故有样式;但 vite build 不会把 /node_modules/* 拷进 dist/,vite preview(及任何静态托管)打开 dist/editor.html 时这三条 link 404 → 设计器裸样式不可用。修复:把三条 CSS 改为在 JS 入口 src/editor/main.tsx 里 import,让 rollup 收集进 dist 的 css 产物,再从 HTML 删掉绝对 link。三条 CSS 磁盘文件已确认存在:node_modules/amis-editor-core/lib/style.css、node_modules/amis-ui/lib/themes/default.css、node_modules/amis-ui/lib/helper.css。

REQUIRED-before-any-hosted-demo(preview / Nginx / 任何静态托管都必须先修)。 OPTIONAL-for-pure-dev(npm run dev 下 vite 直接伺服 node_modules,dev 期不修也有样式)。

Files:

  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/src/editor/main.tsx(第 9 行 import 块顶部加三条 CSS import)
  • Modify: /Users/zhengwr/workspace/eip3/eip4-web/editor.html(删第 8-11 行三条绝对 link,保留第 7 行业务注释与第 12-20 行 <style>)
  • 无新增单测(构建产物样式,验证以 build+preview+浏览器 network 为准)

Step 23.1 — 在 main.tsx 顶部 import 三条 amis CSS

在 /Users/zhengwr/workspace/eip3/eip4-web/src/editor/main.tsx 第 9 行 import { createRoot } 之前插入三条 CSS import(用包名而非绝对路径,vite/rollup 解析到 node_modules 并打包)。

--- a/eip4-web/src/editor/main.tsx
+++ b/eip4-web/src/editor/main.tsx
 // 主应用 main.tsx 跑 amis SDK(运行时渲染器,容忍 StrictMode),唯独 amis-editor 不行。
+//
+// CSS 由此处 import 引入(不再用 editor.html 的 /node_modules 绝对 link):
+// vite dev 直接转译、vite build 由 rollup 收集进 dist 的 css 产物,
+// 修掉「dist/editor.html 三条 /node_modules link 在 preview/静态托管下 404」。
+import 'amis-editor-core/lib/style.css';
+import 'amis-ui/lib/themes/default.css';
+import 'amis-ui/lib/helper.css';
 import { createRoot } from 'react-dom/client';
 import { DesignerPage } from './DesignerPage';

Step 23.2 — 从 editor.html 删三条绝对 link

在 /Users/zhengwr/workspace/eip3/eip4-web/editor.html 删第 8-11 行(CSS 注释 + 三条 link),保留第 7 行隔离说明与第 12 行起的 <style>。

--- a/eip4-web/editor.html
+++ b/eip4-web/editor.html
   <!-- amis-editor 独立入口:用 npm 包版 amis,与主应用 sdk-local 完全隔离 -->
-  <!-- CSS 在 HTML 里直接引用,绕开 vite esbuild 对 amis-ui 包路径的解析 -->
-  <link rel="stylesheet" href="/node_modules/amis-editor-core/lib/style.css" />
-  <link rel="stylesheet" href="/node_modules/amis-ui/lib/themes/default.css" />
-  <link rel="stylesheet" href="/node_modules/amis-ui/lib/helper.css" />
+  <!-- CSS 由 src/editor/main.tsx import 引入(vite build 收集进 dist,避免 /node_modules 绝对路径在生产构建 404)-->
   <style>

Step 23.3 — 跑 build,expect 通过 + dist 产出 css

cd /Users/zhengwr/workspace/eip3/eip4-web && npm run build

预期:tsc -b 与 vite build 均成功,结尾打印 dist/editor.html 与 dist/assets/*.css。确认 css 产物存在:

ls /Users/zhengwr/workspace/eip3/eip4-web/dist/assets/*.css

预期:至少一个 .css 文件(amis 样式已 bundle)。再确认 dist/editor.html 已不含 /node_modules:

grep -c "/node_modules" /Users/zhengwr/workspace/eip3/eip4-web/dist/editor.html

预期输出:0。

Step 23.4 — preview 起服,浏览器验证设计器有样式 + 无 404

需要一个标准层已存在的 templateId(用 Section 2 compile 出来的,或任意现存 sys_page_schema 的 templateId;设计器是 EDIT-ONLY,页面必须先存在)。

cd /Users/zhengwr/workspace/eip3/eip4-web && npm run preview

预期:Local: http://localhost:4173/(preview 默认 4173;需后端 8093 在跑以反代 /api)。

浏览器打开 http://localhost:4173/editor.html?templateId=<已存在的templateId>,在 DevTools → Network 面板验证:

  • 期望:三栏设计器有完整样式(左组件面板/中画布/右属性面板带边框配色,非裸 HTML)。
  • 期望:Network 中无任何 /node_modules/*.css 的 404;amis css 来自 dist/assets/*.css(200)。

若样式重复或冲突(plan B 回退):改用 vite 静态拷贝——npm i -D vite-plugin-static-copy,在 vite.config.ts plugins 加:

import { viteStaticCopy } from 'vite-plugin-static-copy';
// plugins: [react(), viteStaticCopy({ targets: [
//   { src: 'node_modules/amis-editor-core/lib/style.css', dest: 'node_modules/amis-editor-core/lib' },
//   { src: 'node_modules/amis-ui/lib/themes/default.css', dest: 'node_modules/amis-ui/lib/themes' },
//   { src: 'node_modules/amis-ui/lib/helper.css', dest: 'node_modules/amis-ui/lib' },
// ]})]

保留 editor.html 原绝对 link 不删。本任务默认走 import 方案;仅当观察到样式冲突才切 plan B。

Step 23.5 — commit

cd /Users/zhengwr/workspace/eip3 && git add eip4-web/src/editor/main.tsx eip4-web/editor.html && git commit -m "fix(web): editor.html CSS 改 import 进 bundle,修生产构建 404

editor.html 三条 /node_modules/*.css 绝对 link 在 vite build 后不入 dist,
preview/静态托管下 404 → 设计器裸样式。改由 src/editor/main.tsx import,
rollup 收集进 dist/assets/*.css。dev 不受影响(vite 转译同源)。
REQUIRED-before-any-hosted-demo, OPTIONAL-for-pure-dev。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

Task 24 · 端到端 dev 验收脚本(四环建新功能演示)

目标:一份有序、可复跑的 manual + 可选 Playwright 验收,逐项给出确切 URL/endpoint 与预期结果,证明「人走四环建新功能 + AI 加速器入口」闭环。遵循 @superpowers:verification-before-completion:先有证据再宣称 done,每步未达预期即停、不放过。

Files:

  • Create: /Users/zhengwr/workspace/eip3/eip4-web/docs/acceptance/2026-06-20-五环建新功能-端到端验收.md(验收清单文档)
  • Create(可选): /Users/zhengwr/workspace/eip3/eip4-web/e2e/five-ring-new-feature.spec.ts(Playwright,可选自动化)

Step 24.1 — 写验收清单文档

把以下内容写入 /Users/zhengwr/workspace/eip3/eip4-web/docs/acceptance/2026-06-20-五环建新功能-端到端验收.md:

# 端到端验收 · 人走四环建新功能(NocoBase 式建模器 + 实时设计器)

> 证据先行(@superpowers:verification-before-completion):每项给确切 URL/endpoint 与预期;
> 任一项未达预期即停、记录实况、不宣称 done。
> 红线复核:发布恒人审;AI 入口 status 恒 READY_FOR_HUMAN_REVIEW;标准层写入恒走
> PageSchemaWriter.upsertStandard;平台进程内不内置生成 LLM。

## 前置环境(缺一不可)
1. 后端 dev profile 跑在 8093,连到目标库:
   `JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTests \
    && /opt/homebrew/opt/openjdk@21/bin/java -jar eip4-platform/platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=dev`
   预期:`Tomcat started on port(s): 8093`。
2. 前端 dev:`cd eip4-web && npm run dev` → `http://localhost:5173`(.env 默认已 8093,见 Task 22)。
3. 凭据:admin / 111111。
4. 取 token(后续 curl 复核用):
   `curl -s -X POST http://localhost:8093/api/auth/login -H 'Content-Type: application/json' -d '{"account":"admin","password":"111111"}'`
   预期:JSON 顶层 `d.token` 非空。导出:`export TK=<token>`。

## 检查项

### (1) 登录 admin/111111
- URL: `http://localhost:5173/`,输入 admin/111111 登录。
- 预期:进入 AppShell;右上角显示 admin;`getProfile().account==='admin'`(管理员闸通过)。

### (2) 设计中心 → `+ 新建功能` → 建实体 EIP4PT_DEMO(标量列 + reference 列)
- 入口: 设计中心页 → 点 `+ 新建功能` → 建模器。
- 第一环(元数据/表):tablename=`EIP4PT_DEMO`,name=`演示功能`;加一个标量字段(如 column=`TITLE`,type=`string`,length=200,display=`标题`,mandatory=true);加一个 reference 字段:type=`reference`,referenceTable 选一个已存在实体(从 ref picker 下拉,数据来自 `GET /api/meta/entities`),display=`关联对象`。
- 提交后端: `POST /api/meta/entity`。
- curl 复核:
  `curl -s -X POST http://localhost:8093/api/meta/entity -H "Authorization: Bearer $TK" -H 'Content-Type: application/json' \
   -d '{"tablename":"EIP4PT_DEMO","name":"演示功能","attributes":[{"column":"TITLE","type":"string","length":200,"display":"标题","mandatory":true},{"column":"REFOBJ","type":"reference","referenceTable":"<已存在表>","display":"关联对象"}]}'`
- 预期:`{"status":0,"data":{"entityId":...,"tablename":"EIP4PT_DEMO","attributeCount":>=2,"indexCount":>=1,"listApi":"/api/entity/EIP4PT_DEMO/list"}}`。
- reference 列建对的证据(DECISION-1):
  `curl -s "http://localhost:8093/api/meta/entity/EIP4PT_DEMO/attributes" -H "Authorization: Bearer $TK"`
  预期:`columns` 中 `REFOBJ` 带 `referenceTable:"<已存在表>"`(即外键指向 TARGET 表,非自指)。

### (3) 选 maintenance-crud-v1 → compile → 拿到 templateId
- 第三环(设计):建模器选 recipe=`maintenance-crud-v1`,填 title=`演示功能`,displayField=`TITLE`。
- 提交后端: `POST /api/design/recipe/compile`。
- curl 复核:
  `curl -s -X POST http://localhost:8093/api/design/recipe/compile -H "Authorization: Bearer $TK" -H 'Content-Type: application/json' \
   -d '{"tableName":"EIP4PT_DEMO","recipe":"maintenance-crud-v1","title":"演示功能","displayField":"TITLE"}'`
- 预期:`{"status":0,"data":{"templateId":"<server生成UUID>","etag":"<非空>"}}`。
- 红线证据:templateId 由**服务端生成**(非调用方指定);标准层写入走 `PageSchemaWriter.upsertStandard`(代码路径,无裸 INSERT)。导出 `export TID=<templateId>`。

### (4) 进设计器微调(editor 打开且有样式)
- 前端: `window.open('/editor.html?templateId='+encodeURIComponent(TID),'_blank')`。
- 直接 URL: `http://localhost:5173/editor.html?templateId=$TID`。
- 预期:三栏设计器加载、**有完整样式**(Task 23 已修)、画布渲染出 maintenance-crud 页面(列表+表单);EDIT-ONLY 故页面已存在不会空白。
- 网络证据:DevTools Network 无 `/node_modules/*.css` 404。

### (5) 发布 → 菜单出现在「新功能」下 → 页面可访问并经 _SEARCH 出列表
- 第四环(发布):建模器点 发布。
- 流预览先看: `curl -s "http://localhost:8093/api/design/flows?entityId=<entityId>" -H "Authorization: Bearer $TK"`
  预期:`data` 含 5 条,flowName 形如 `EIP4PT_DEMO_ADD/_UPDATE/_DELETE/_SEARCH/_LOAD`(至少含 `EIP4PT_DEMO_SEARCH`)。
- 发布提交: `POST /api/design/publish`:
  `curl -s -X POST http://localhost:8093/api/design/publish -H "Authorization: Bearer $TK" -H 'Content-Type: application/json' \
   -d '{"entityId":<entityId>,"tableName":"EIP4PT_DEMO","templateId":"'"$TID"'","menuName":"演示功能","generateDeploymentPackage":true}'`
- 预期:`{"status":0,"data":{"menuId":...,"flows":[...含 EIP4PT_DEMO_SEARCH...],"deploymentPackage":{...}}}`。
- 红线证据(DECISION-2):本环境 live 生效(菜单注册+五流 TRIGGER) **且** `deploymentPackage` 非空(生产人工部署包,生产上线仍走既有人审)。
- 前端验证:刷新左侧菜单 → 「新功能」目录下出现「演示功能」节点 → 点开 → 路由 `http://localhost:5173/page/$TID`。
- 列表证据:DevTools Network 见请求 `/api/flow/EIP4PT_DEMO_SEARCH`(200),页面渲染出列表(空数据也算通过,关键是 _SEARCH 流被触发且 200)。

### (6) reference 列显示「显名」非 id(DECISION-1 末环)
- 在 (5) 的列表页(`/page/$TID`)看「关联对象」列。
- 先造一行带 REFOBJ 的数据(经页面新增或直接 _ADD 流),使 REFOBJ 指向 TARGET 表某行。
- 预期:列表「关联对象」列显示 TARGET 行的**显名**(displayColumn 值),**不是裸 id**。
- 证据:Network 中列表响应该列值为可读名称;若仍是 id,recipe 渲染的 reference 显名链路有缺(回 Section 1/2 排查)。

### (7) `⚡ AI 建功能` 路径 → READY_FOR_HUMAN_REVIEW → 评审按钮打开草稿
- 入口:设计中心 → `⚡ AI 建功能`(外部 agent 加速器;平台进程内**不**内置生成 LLM)。
- 前端触发须传 `baseUrl=http://localhost:8093`(运行中的后端,**非**死的默认 8084)。
- 提交后端: `POST /api/ai/features/auto-develop`,body 见 AiAutoDevelopmentRequest。
- curl 复核(示例):
  `curl -s -X POST http://localhost:8093/api/ai/features/auto-develop -H "Authorization: Bearer $TK" -H 'Content-Type: application/json' \
   -d '{"feature":{"objective":"演示AI建功能","featureName":"AI演示","tableName":"EIP4PT_AIDEMO","entityName":"AI演示","menuName":"AI演示","fields":[{"column":"NAME","label":"名称","type":"string","length":100,"required":true}],"pageRecipe":"maintenance-crud-v1"},"baseUrl":"http://localhost:8093","generateDeploymentPackage":true}'`
- 预期:`{"taskId":...,"status":"READY_FOR_HUMAN_REVIEW","development":{"drafts":[{"artifactType":"PAGE_SCHEMA","targetId":"<templateId>",...}]},...}`。
- 红线证据:status **恒** `READY_FOR_HUMAN_REVIEW`(终点恒人审,非自动上线)。
- 前端验证:AI 运行结果页出现「评审」按钮 → 点它从 drafts 中取 `artifactType==='PAGE_SCHEMA'` 的 `targetId` → `window.open('/editor.html?templateId='+encodeURIComponent(targetId),'_blank')` → 设计器打开该草稿(有样式)。

## 通过判据
全部 (1)~(7) 达预期 = 端到端闭环成立。任一项失败:记录实况(curl 原始响应 + Network 截图),定位到对应 Section 修复后重跑,**不跳过、不宣称 done**。

## 范围声明
- 本验收覆盖 dev 双源(5173 前端 + 8093 后端,vite 反代 /api)。
- 生产单源托管(Nginx / Spring static 同源伴服 dist + /api)**out-of-scope**,需另立部署任务;此处仅 flag。

Step 24.2 — 跑前置环境冒烟(验证脚本本身可执行)

按文档「前置环境」起后端 8093 + 前端 5173,取 token:

curl -s -X POST http://localhost:8093/api/auth/login -H 'Content-Type: application/json' -d '{"account":"admin","password":"111111"}'

预期:返回 JSON,顶层 d.token 非空(证明凭据与后端可用,验收脚本前置成立)。

Step 24.3 — (可选)Playwright 自动化骨架

可选写 /Users/zhengwr/workspace/eip3/eip4-web/e2e/five-ring-new-feature.spec.ts(自动化 (1)~(5);(6)(7) 涉及外部 agent 与造数据,建议 manual):

import { test, expect } from '@playwright/test';

const TABLE = 'EIP4PT_DEMO_E2E';

test('五环建新功能 端到端(maintenance-crud-v1)', async ({ page, request }) => {
  // (1) 登录
  await page.goto('http://localhost:5173/');
  await page.getByPlaceholder(/账号|account/i).fill('admin');
  await page.getByPlaceholder(/密码|password/i).fill('111111');
  await page.getByRole('button', { name: /登录|login/i }).click();
  await expect(page.getByText('admin')).toBeVisible();

  // 取 token 复用后端断言
  const login = await request.post('http://localhost:8093/api/auth/login', {
    data: { account: 'admin', password: '111111' },
  });
  const token = (await login.json()).d.token as string;
  const auth = { Authorization: `Bearer ${token}` };

  // (2) 建实体(含 reference 列)
  const ents = await (await request.get('http://localhost:8093/api/meta/entities', { headers: auth })).json();
  const refTable = ents.data[0].tablename as string;
  const ent = await request.post('http://localhost:8093/api/meta/entity', {
    headers: auth,
    data: { tablename: TABLE, name: '演示E2E', attributes: [
      { column: 'TITLE', type: 'string', length: 200, display: '标题', mandatory: true },
      { column: 'REFOBJ', type: 'reference', referenceTable: refTable, display: '关联对象' },
    ] },
  });
  const entBody = await ent.json();
  expect(entBody.status).toBe(0);
  const entityId = entBody.data.entityId;

  // (3) compile
  const comp = await request.post('http://localhost:8093/api/design/recipe/compile', {
    headers: auth,
    data: { tableName: TABLE, recipe: 'maintenance-crud-v1', title: '演示E2E', displayField: 'TITLE' },
  });
  const compBody = await comp.json();
  expect(compBody.status).toBe(0);
  const templateId = compBody.data.templateId as string;
  expect(templateId).toBeTruthy();

  // (4) 设计器打开且有样式(无 /node_modules css 404)
  const css404: string[] = [];
  page.on('response', (r) => { if (r.url().includes('/node_modules') && r.url().endsWith('.css') && r.status() === 404) css404.push(r.url()); });
  const editor = await page.context().newPage();
  await editor.goto(`http://localhost:5173/editor.html?templateId=${encodeURIComponent(templateId)}`);
  await expect(editor.locator('.ae-Editor')).toBeVisible({ timeout: 15000 });
  expect(css404).toEqual([]);

  // (5) 发布 → 五流含 _SEARCH
  const pub = await request.post('http://localhost:8093/api/design/publish', {
    headers: auth,
    data: { entityId, tableName: TABLE, templateId, menuName: '演示E2E', generateDeploymentPackage: true },
  });
  const pubBody = await pub.json();
  expect(pubBody.status).toBe(0);
  expect(pubBody.data.flows.some((f: any) => String(f.flowName ?? f).includes(`${TABLE}_SEARCH`))).toBe(true);
  expect(pubBody.data.deploymentPackage).toBeTruthy(); // DECISION-2: 生产部署包
});

跑:

cd /Users/zhengwr/workspace/eip3/eip4-web && npx playwright test e2e/five-ring-new-feature.spec.ts

预期:1 passed(需 8093+5173 在跑;首跑可能要 npx playwright install chromium)。注意此 spec 会建真表,跑前确认 EIP4PT_DEMO_E2E 可建(或换唯一表名)。

Step 24.4 — commit

cd /Users/zhengwr/workspace/eip3 && git add eip4-web/docs/acceptance/2026-06-20-五环建新功能-端到端验收.md eip4-web/e2e/five-ring-new-feature.spec.ts && git commit -m "test(web): 五环建新功能 端到端验收脚本(manual清单 + 可选Playwright)

逐项 URL/endpoint+预期证明四环闭环:建实体(含ref列)→compile→设计器→发布(五流+菜单+部署包)→ref显名→AI入口 READY_FOR_HUMAN_REVIEW。
红线复核:发布恒人审/AI status恒 READY_FOR_HUMAN_REVIEW/标准层走 upsertStandard/进程内无生成LLM。
生产单源托管 out-of-scope 已 flag。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

E. 全局验收(所有 Task 完成后)

用 @superpowers:verification-before-completion:先跑命令、贴输出,再断言「完成」。

后端(自主可证,无需 env):

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata,platform-ai -am test

预期:全部新增测试 + 既有回归绿(重点 MetaCatalogControllerTest / MetaControllerDdlTest(引用列 case)/ DesignFeatureControllerTest / RecipePageComposerTest / MenuRegistrarTest / DeploymentPackageBuilderTest)。

前端(自主可证):

cd eip4-web && npm test && npm run build

预期:Vitest 全绿;npm run build 产 dist/(含 index.html + editor.html + 样式齐全、无 /node_modules/*.css 残链)。

端到端 dev 演示(需 env:dev profile 后端 8093 + 前端 5173 + 登录 admin/111111): 按第 6 节 Task 24 的有序清单逐项核验,关键证据:

  1. 设计中心 [+ 新建功能] → 建实体(含 1 个标量字段 + 1 个引用字段指向既有实体)→ 选 maintenance-crud-v1 → compile 返回 templateId。
  2. 进设计器微调 打开 /editor.html?templateId=…,样式正常、可存 overlay。
  3. 发布 → /api/design/publish 返回 flows(含 _SEARCH)+ menuId + deploymentPackage(requiresHumanApproval:true);菜单「新功能」目录下出现新节点;/page/<templateId> 列表经 /api/flow/<TABLE>_SEARCH 出数据。
  4. 引用列显示目标显名而非裸 id(红线 DECISION-1)。
  5. [⚡ AI 建功能] 走 auto-develop → status==READY_FOR_HUMAN_REVIEW → 审阅按钮打开 PAGE_SCHEMA 草稿的 templateId(红线:恒人审)。

红线复核(贴证据): 发布未执行任何生产 SQL(仅 live-apply 当前库 + 产部署包);AI 产物 status==READY_FOR_HUMAN_REVIEW;sys_page_schema 写入只经 PageSchemaWriter.upsertStandard(grep 新增代码无裸 INSERT ... sys_page_schema);无新增进程内生成 LLM 调用。

F. 不做 / 推迟(v1 边界与 follow-up)

  • ALTER / 改已有表(路线图 M4,v2)。
  • recipe 扩面:主子表 / EditGrid / 审批 / 组合 tabs(M7)。
  • ②面 in-app AI employees / 平台内置生成 LLM。
  • 纯 NocoBase「空白页拖组件现绑实体」(v1 用 recipe 预接好页规避)。
  • 净新标准页运行时 DELETE/回滚端点(当前仅 overlay 删除 + 离线部署包 SQL)——follow-up。
  • 普通用户可见性:publish 仅 INSERT sys_menu,未写角色菜单授权;非超管可见需另调 set-menus(AdminWriteController)——follow-up。
  • AI 链与人工链部署包统一:第 3 节 DeploymentPackageBuilder 与 platform-ai 各一份,统一须把生成器下沉到 platform-metadata——follow-up。
  • 生产单源托管(Nginx / Spring 静态同源伴服 dist + /api)out-of-scope;v1 以 npm run dev(5173) + dev 后端(8093) 作为 M1「serving 绿」基线。

G. 执行交接

计划完成。两种执行方式:

1. Subagent 驱动(本会话) — 每个 Task 派一个 fresh subagent,Task 间做 code review,快速迭代。REQUIRED SUB-SKILL: superpowers:subagent-driven-development。

2. 并行会话(独立) — 在 worktree 新开会话用 superpowers:executing-plans,按批次执行 + 检查点。

建议:后端三节(第 1-3 节)数据依赖强、引擎语义敏感,宜 subagent 驱动 + 每节后 code-reviewer/verifier 过审;前端两节可并行批次执行;第 6 节 T24 收尾人工 + Playwright。