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

5651 lines
266 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 人走五环建新功能 · 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` 改为:
```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`:
```java
@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):
```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.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 — 跑测试,预期编译失败(方法不存在)**
```bash
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 = "删除实体...` 之前插入:
```java
@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;` 附近)补一行:
```java
import org.springframework.web.bind.annotation.GetMapping;
```
**Step 1.4 — 跑测试,预期 PASS**
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest
```
预期:`BUILD SUCCESS`,2 个用例绿。
**Step 1.5 — 提交**
```bash
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 引入):
```java
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 — 跑测试,预期编译失败**
```bash
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:
```java
@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**
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest
```
预期:3 个用例全绿。
**Step 2.5 — 提交**
```bash
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):
```java
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 — 跑测试,预期编译失败**
```bash
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 区补:
```java
import java.util.UUID;
```
新增 helper(放在 `saveAttr` 方法第247行 `}` 之后):
```java
/**
* 为引用列 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行整段替换):
```java
// 业务列
@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**
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest
```
预期:2 个用例绿。再跑一次全 `platform-metadata` 编译保障没破坏 `createEntity`:
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test-compile
```
预期:`BUILD SUCCESS`。
**Step 3.5 — 提交**
```bash
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 用例):
```java
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 — 跑测试,预期编译失败**
```bash
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` 透传:
```java
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行):
```java
private static void appendColumnDdl(String table, GeneralPOJO attr, StringBuilder sql,
StringBuilder unique, StringBuilder combUnique,
Map<String, String> refTargets) {
```
把第296-298行的 else 分支:
```java
} else {
sql.append(col).append(" character(36) REFERENCES ").append(table);
}
```
改成(指向 refTargets 里的目标表;没有则退回自表以保持旧行为不破坏):
```java
} 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行下声明该局部变量):
```java
String ddl = createTableDdl(table, created, refTargets);
```
**Step 4.4 — 跑测试,预期 PASS**
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerDdlTest
```
预期:2 个用例绿,含新 `referenceColumnPointsAtTargetTable`。再跑 Task 3 测试确保未回归:
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest,MetaCatalogControllerTest,MetaControllerDdlTest
```
预期:全绿。
**Step 4.5 — 提交**
```bash
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)**
```java
@Test
@DisplayName("resolveDescription: 无 description → 中性默认; 有则原样")
void resolveDescriptionNeutralDefault() {
assertEquals("设计中心创建", MetaController.resolveDescription(java.util.Map.of()));
assertEquals("我的订单实体",
MetaController.resolveDescription(java.util.Map.of("description", "我的订单实体")));
}
```
**Step 5.2 — 跑测试,预期编译失败**
```bash
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行附近):
```java
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行:
```java
entityMap.put("DESCRIPTION", "AI 闭环创建 (eip4-poc WS5)");
```
改为:
```java
entityMap.put("DESCRIPTION", resolveDescription(req));
```
**Step 5.4 — 跑测试,预期 PASS**
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaControllerReferenceTest
```
预期:含新 `resolveDescriptionNeutralDefault` 在内全绿。最后跑本节全部新增/改动测试一把总验:
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=MetaCatalogControllerTest,MetaControllerReferenceTest,MetaControllerDdlTest
```
预期:`BUILD SUCCESS`,三个测试类全绿。
**Step 5.5 — 提交**
```bash
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`:
```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`(完整文件):
```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` 替换为:
```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`:
```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`:
```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`:
```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` 末尾(最后一个 `}` 之前)追加:
```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),把:
```java
ObjectNode column = columns.addObject();
column.put("name", field.name());
column.put("label", field.label());
applyColumnRender(column, field.type());
```
替换为:
```java
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());`)替换为:
```java
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` 分支:
```java
case "reference" -> {
// 引用列:列 name 已在 listColumnName 改指 <COL>_DISPLAY__(运行时 _SEARCH 流
// 经 UserColumnResolver.resolveRows 注入显名)。此处保持纯文本渲染即可,
// 不引入新 amis 组件类型 → TypedPageSchemaValidator 白名单平凡通过。
}
```
在类内(紧邻 `applyColumnRender` 之后)新增私有方法 `listColumnName`:
```java
/**
* 列表列 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` 末尾(最后一个 `}` 之前)追加:
```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`:
```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`:
```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` 追加:
```java
@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 实际签名定位插入点),并新增端点方法:
```java
@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 继续承载菜单与部署包):
```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.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`:
```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`:
> ```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`:
> ```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` 字段与赋值;追加端点:
```java
@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` 会引入循环,故直接读库):
```java
/** 返回实体当前持久化的流名列表(发布后读 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` 实现:
> ```java
> 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`:
```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`:
```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` 追加:
```java
/** 注册/更新功能菜单,返回 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", ...)` 之后补:
```java
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`:
```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`:
```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`:
```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` 追加:
```java
/** 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 之后)补:
```java
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):
```ts
// 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:` 块内,把现有
```ts
test: {
environment: 'jsdom',
globals: true,
include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
},
```
改为(加一行 `setupFiles`):
```ts
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):
```ts
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):
```ts
// 元数据建模 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):
```ts
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):
```ts
// 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):
```ts
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):
```ts
// 发布 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):
```tsx
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 的最小形态以便后续无缝增补):
```tsx
// 建模器 —— 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 替换):
```tsx
// 占位(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';` 之后加:
```tsx
import { ModelerPage } from './pages/ModelerPage';
```
- 第 42 行 `<Route path="/design-center" element={<DesignCenterPage />} />` 之后加:
```tsx
{/* 建模器(五环第①环·元数据→表,仅管理员)*/}
<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):
```tsx
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 替换它):
```tsx
// 字段表 + 加字段 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 替换):
```tsx
// 占位(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):
```tsx
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):
```tsx
// 引用列选择器(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`:
```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 行:
```tsx
import { useEffect, useMemo, useState } from 'react';
```
改为:
```tsx
import { useEffect, useMemo, useState } from 'react';
import { useNavigate } from 'react-router-dom';
```
在组件函数体内(第 21 行 `const [q, setQ] = useState('');` 之后)加:
```tsx
const navigate = useNavigate();
```
**Step 18.4 — 最小实现:header flex row 插两枚按钮**
把第 73 行的 `<div style={{ flex: 1 }} />` 替换为以下三段(弹簧 + 两按钮):
```tsx
<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`:
```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`:
```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`:
```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`:
```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`:
```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`:
```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`:
```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 行:
```tsx
import { DesignCenterPage } from './pages/DesignCenterPage';
```
改为:
```tsx
import { DesignCenterPage } from './pages/DesignCenterPage';
import { NewFeatureShell } from './pages/NewFeatureShell';
import { AiFeatureForm } from './pages/AiFeatureForm';
```
**Step 21.3 — 接线 App.tsx:加两条 Route**
把第 41-42 行:
```tsx
{/* 设计中心(管理员集中式低代码设计入口,替代每页设计按钮)*/}
<Route path="/design-center" element={<DesignCenterPage />} />
```
改为:
```tsx
{/* 设计中心(管理员集中式低代码设计入口,替代每页设计按钮)*/}
<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:
```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 行注释替换:
```diff
--- 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 行默认值替换:
```diff
- 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):
```bash
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`。
2) 临时移走 `.env.local` 模拟 fresh checkout(验证默认值生效),起 dev server:
```bash
cd /Users/zhengwr/workspace/eip3/eip4-web && mv .env.local .env.local.bak 2>/dev/null; npm run dev
```
预期:vite 打印 `Local: http://localhost:5173/`。
3) 通过 dev server 代理打后端(另开终端):
```bash
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5173/api/menu
```
预期输出:`401`(未带 token 的受保护端口;关键是**非 502/ECONNREFUSED**——证明代理打到了活后端 8093,而不是死的 8084)。若得 `502` 或连接拒绝,说明默认目标仍错。
4) 恢复 `.env.local`:
```bash
cd /Users/zhengwr/workspace/eip3/eip4-web && mv .env.local.bak .env.local 2>/dev/null || true
```
**Step 22.4 — commit**
```bash
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 并打包)。
```diff
--- 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>`。
```diff
--- 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**
```bash
cd /Users/zhengwr/workspace/eip3/eip4-web && npm run build
```
预期:`tsc -b` 与 `vite build` 均成功,结尾打印 `dist/editor.html` 与 `dist/assets/*.css`。确认 css 产物存在:
```bash
ls /Users/zhengwr/workspace/eip3/eip4-web/dist/assets/*.css
```
预期:至少一个 `.css` 文件(amis 样式已 bundle)。再确认 `dist/editor.html` 已不含 `/node_modules`:
```bash
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,页面必须先存在)。
```bash
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` 加:
```ts
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**
```bash
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`:
```markdown
# 端到端验收 · 人走四环建新功能(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:
```bash
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):
```ts
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: 生产部署包
});
```
跑:
```bash
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**
```bash
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):**
```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata,platform-ai -am test
```
预期:全部新增测试 + 既有回归绿(重点 `MetaCatalogControllerTest` / `MetaControllerDdlTest`(引用列 case)/ `DesignFeatureControllerTest` / `RecipePageComposerTest` / `MenuRegistrarTest` / `DeploymentPackageBuilderTest`)。
**前端(自主可证):**
```bash
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。