diff --git a/README.md b/README.md index cf16d28..32d5139 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ EIP4 平台正式工程(路线 A'):双层制模块化单体——**保真层供 | platform-auth | 数据权限真实现(C2 已替换桩)+ P2 组织/权限 | | | platform-converter | 模板转换器(P4) | 可独立 CLI 跑批 | | platform-flow-gateway | P3 占位:Flowable 网关 | | -| platform-ai | P5 占位:MCP Server | | +| platform-ai | P5 AI Agent 开发底座:草稿/变更包/本地门禁/自动修复/人工部署包 | Agent 不直连线上执行生产变更 | +| platform-cli | EIP4 Agent 受控命令入口:环境探测、AI 自动开发、后续发布编排 | Agent 优先通过 CLI/API 操作 | | platform-parity | C1 对拍框架:录制/重放/RowDiff/自对拍 CLI | P1 一级交付物 | | platform-app | Boot 启动器,组装全部模块 | ArchUnit 规则在此模块测试里 | @@ -75,6 +76,30 @@ java -cp "$CP" com.eip4.platform.parity.selfcheck.ParityCli --privilege # C # 指向 eip4dev 自对拍: mvn -pl platform-parity exec:java -Dexec.mainClass="com.eip4.platform.parity.selfcheck.ParityCli" \ "-Dexec.args=--discover --jdbc=jdbc:postgresql://localhost:5433/eip4dev?currentSchema=eip3 --engine=http://localhost:8093 --out=parity-reports/eip4dev" + +# EIP4 Agent CLI +mvn -pl platform-cli package +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env add --name local --base-url http://localhost:8084 --use +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env status --base-url http://localhost:8084 +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package --task-id ait-xxx --change-set-id aics-xxx --output target/ai-runs/package.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release verify --package-file target/ai-runs/package.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release export --package-file target/ai-runs/package.json --output target/ai-runs/package.eip4pkg.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-preview --package-file target/ai-runs/package.eip4pkg.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release diff --left target/ai-runs/package-old.json --right target/ai-runs/package.json +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release rollback-plan --package-file target/ai-runs/package.eip4pkg.json --output target/ai-runs/rollback-plan.json + +# Typed page schema +curl http://localhost:8084/api/page/schema/components +curl -X POST http://localhost:8084/api/page/schema/validate \ + -H "Content-Type: application/json" \ + --data-binary @target/ai-runs/page-schema.json + +# AI tools / employees / ACL +curl http://localhost:8084/api/ai/tools +curl http://localhost:8084/api/ai/employees +curl -X POST http://localhost:8084/api/ai/tools/access-check \ + -H "Content-Type: application/json" \ + -d '{"employeeId":"agent-developer","toolName":"local.apply","grantedScopes":["ai:local:apply"],"targetEnv":"local","productionWrite":false}' ``` ## tools/ diff --git a/docs/AI_AGENT_AUTO_DEVELOPMENT.md b/docs/AI_AGENT_AUTO_DEVELOPMENT.md new file mode 100644 index 0000000..4131f6b --- /dev/null +++ b/docs/AI_AGENT_AUTO_DEVELOPMENT.md @@ -0,0 +1,182 @@ +# AI Agent 辅助开发运行说明(生成草稿 + 本地验证 + 人工复核发布) + +> **能力边界(对外口径,红线)**:本能力是「**AI 辅助生成草稿 + 人工复核发布**」,**不是** AI 全自动开发。当前只覆盖最简单的 CRUD recipe,存量复杂场景未取得数据;按《EIP3架构决策会纪要》红线,**严禁在报价/合同中承诺「AI 全自动开发 / 人力大幅下降」**。线上变更一律输出人工部署包、由人工复核后发布。 + +`platform-ai` 的辅助开发入口是 `POST /api/ai/features/auto-develop`。它只在本地环境执行草稿生成、本地落库、smoke 和自动修复;线上变更只输出人工部署包,不连接线上环境执行,须人工复核后发布。 + +## 本地运行配置 + +`local` 和 `dev` profile 已开启: + +```yaml +spring: + sql: + init: + mode: always + schema-locations: classpath:bootstrap/bootstrap-ai-agent.sql + +eip4: + ai: + store: jdbc +``` + +因此本地启动时会幂等创建 `sys_ai_task`、`sys_ai_draft`、`sys_ai_change_set`、`sys_ai_run`、`sys_ai_audit_log`,并用 JDBC 持久化开发证据。默认 profile 不强制写远端验证库,避免误把开发证据写到共享环境。 + +建议使用独立 worktree 做 Agent 功能开发,避免占用当前任务目录: + +```bash +git worktree add ../eip4-platform-ai-agent -b ai/agent-dev +cd ../eip4-platform-ai-agent +``` + +运行态验证要先构建依赖模块并启动重新打包后的 jar,避免 `spring-boot:run -pl platform-app` 读取本地 Maven 仓库里的旧 `platform-ai`: + +```bash +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=local +``` + +## 请求示例 + +推荐优先使用 `platform-cli`,让 Agent 通过稳定命令入口操作自动开发链路: + +```bash +mvn -pl platform-cli package +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \ + --base-url http://localhost:8093 \ + --objective "新增客户等级维护功能" \ + --feature-name "客户等级维护" \ + --table-name EIP4AI_CUSTOMER_LEVEL \ + --entity-name "客户等级" \ + --template-id eip4ai-customer-level \ + --menu-name "客户等级维护" \ + --field NAME:名称:string:100:true \ + --field CODE:编码:string:64:true \ + --field ENABLED:启用:boolean::false \ + --page-recipe maintenance-crud-v1 \ + --max-repair-attempts 2 \ + --output target/ai-runs/customer-level.json +``` + +树形维护页使用 `tree-crud-v1`。如果字段列表没有显式提供 `PARENTID`,生成器会自动补一个父级字段, +页面使用 `/api/entity/{table}/tree?parentKey=PARENTID&idKey={table}_ID&perPage=2000` +作为树数据接口,并把 `PARENTID` 从树列表列中隐藏: + +```bash +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \ + --base-url http://localhost:8093 \ + --objective "新增组织分类树形维护功能" \ + --feature-name "组织分类维护" \ + --table-name EIP4AI_ORG_CATEGORY \ + --entity-name "组织分类" \ + --template-id eip4ai-org-category \ + --menu-name "组织分类维护" \ + --field NAME:名称:string:100:true \ + --field CODE:编码:string:64:true \ + --page-recipe tree-crud-v1 \ + --max-repair-attempts 2 \ + --output target/ai-runs/org-category-tree.json +``` + +本地门禁通过后,可以把最终变更包封装成功能包快照,并保存一个里程碑 revision: + +```bash +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package \ + --base-url http://localhost:8093 \ + --task-id ait-xxx \ + --change-set-id aics-xxx \ + --output target/ai-runs/customer-level-package.json + +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai revision \ + --base-url http://localhost:8093 \ + --task-id ait-xxx \ + --package-id aipkg-xxx \ + --note "本地门禁通过,待人工部署" \ + --output target/ai-runs/customer-level-revision.json +``` + +底层 REST API 仍可直接调用: + +```bash +curl -X POST http://localhost:8093/api/ai/features/auto-develop \ + -H 'Content-Type: application/json' \ + -d '{ + "baseUrl": "http://localhost:8093", + "generateDeploymentPackage": true, + "maxRepairAttempts": 2, + "feature": { + "objective": "新增客户等级维护功能", + "featureName": "客户等级维护", + "tableName": "EIP4AI_CUSTOMER_LEVEL", + "entityName": "客户等级", + "templateId": "eip4ai-customer-level", + "menuName": "客户等级维护", + "pageRecipe": "maintenance-crud-v1", + "fields": [ + {"column": "NAME", "label": "名称", "type": "string", "length": 100, "required": true}, + {"column": "CODE", "label": "编码", "type": "string", "length": 64, "required": true}, + {"column": "ENABLED", "label": "启用", "type": "boolean", "required": false} + ] + } + }' +``` + +`maxRepairAttempts` 可省略,默认 2;设为 0 时只跑首轮开发和本地门禁,失败后由调用方手动调用 repair 接口。 + +## 自动链路 + +1. 创建 `AiTask`。 +2. 读取 `/api/ai/page-recipes` 中的 EIP4 页面 recipe,确认当前页面类型的 UI/UE 约束。 +3. 生成 `ENTITY`、`PAGE_SCHEMA`、`SERVICEFLOW`、`MENU`、`TEST` 草稿。`PAGE_SCHEMA` + 先生成 EIP4 PageBlueprint,再由平台编译器输出 amis schema;草稿 metadata 保留 blueprint 证据。 + 未指定 `feature.pageRecipe` 时默认使用 `maintenance-crud-v1`;树形维护页应指定 `tree-crud-v1`。 +4. 对草稿执行基础门禁,包括 page-recipe、amis schema、typed page schema、服务流 XML、实体字段、smoke 计划和 render plan。 +5. 生成待人审 `AiChangeSet`。 +6. 生成 release plan。 +7. 本地 apply:实体走本机 `/api/meta/entity`,页面/服务流写本地库;如果本地最小库缺少 `sys_menu`,菜单发布标记为 `SKIPPED`,不阻断本地 gate,部署包仍保留菜单 SQL 供线上人审。 +8. 本地 smoke:只允许 `localhost`、`127.0.0.1`、`::1` baseUrl;HTTP 状态必须匹配,且 JSON 响应体存在 `status` 时必须为 0。 + `TEST` 草稿同时包含 `renderTests`,给 Playwright 渲染验收提供 recipe、schemaUrl、previewUrl、预期组件、CRUD 名、数据 API、列、动作和关键文本。 +9. 若失败,自动生成 repair plan 并执行修复重试。 +10. 生成线上人工部署包,包含 manifest、SQL 草案、回滚 SQL 和本地执行证据。 +11. 可选:生成功能包快照并保存 revision,用于后续导出、差异比较和回滚扩展。 + +返回体中的关键字段: + +- `originalChangeSetId`: 首轮自动生成的变更包。 +- `changeSetId`: 最终用于部署包的变更包;如果修复生成了替代草稿,可能不同于 `originalChangeSetId`。 +- `repairExecutions`: 每轮自动修复证据。 +- `deploymentPackage.requiresHumanApproval`: 固定为 `true`,线上发布必须人工审批。 + +## 功能包和 revision + +P2 第一版新增功能包快照和里程碑版本: + +- `POST /api/ai/tasks/{taskId}/change-sets/{changeSetId}/feature-package` +- `GET /api/ai/tasks/{taskId}/feature-packages` +- `POST /api/ai/tasks/{taskId}/feature-packages/{packageId}/revisions` +- `GET /api/ai/tasks/{taskId}/revisions` + +功能包封装部署包、manifest、本地 evidence、SQL 草案和回滚 SQL。revision 当前保存功能包 JSON 快照,作为后续差异比较和回滚执行的基础。生产执行仍不自动化,必须人审。 + +## LLM 修复 + +默认使用确定性修复规则。需要外部 LLM 参与时设置: + +```properties +EIP4_AI_LLM_REPAIR_ENABLED=true +EIP4_AI_LLM_REPAIR_ENDPOINT=http://127.0.0.1:18081/ai-agent/repair +EIP4_AI_LLM_REPAIR_API_KEY=... +EIP4_AI_LLM_REPAIR_MODEL=... +``` + +外部服务契约见 `docs/AI_AGENT_REPAIR_CONTRACT.md`。LLM 只能返回草稿补丁,不能要求平台执行生产命令。 + +## 线上边界 + +可靠路径是:本地 `auto-develop` 通过后,人工检查部署包,再由现有发布流程上线。功能上线后如果发现 bug,Agent 可以基于线上错误日志、导出的 run evidence 或人工复现结果生成新的本地任务并修复,但仍应先在本地验证,再输出人工部署包。 + +## 当前验证结论与遗留项 + +已在 `local` profile 验证完整自动开发链路:实体创建、默认服务流发布、页面 schema 发布、实体列表/树列表、默认搜索流和新增数据 smoke 均通过,最终状态为 `READY_FOR_HUMAN_REVIEW`。`local` 最小库没有菜单表,因此菜单 apply 为 `SKIPPED`,这是预期的本地边界。 + +遗留项是全局 metadata 辅助读路径仍有部分 SQL 写死 `eip3.` schema;在 `local/eip4m0` 下会出现非阻断 warning。AI 主链路已规避/修正必要路径,后续如果要让所有后台辅助解析在 `local` 最小库完全无噪声,需要单独做一次 schema 兼容清理。 diff --git a/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md b/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md new file mode 100644 index 0000000..d3bf124 --- /dev/null +++ b/docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md @@ -0,0 +1,215 @@ +# AI Agent 借鉴 NocoBase 的落地路线 + +日期:2026-06-17 + +本文记录 EIP4 对 NocoBase AI + no-code 体系的可借鉴点和落地顺序。目标不是照搬 NocoBase 的 TypeScript 插件运行时,而是吸收它的工程边界:核心平台稳定、业务能力包化、AI 通过受控 CLI/API 操作、所有变更可审计、可验证、可回滚。 + +参考: + +- NocoBase README: https://github.com/nocobase/nocobase +- NocoBase Plugin Development: https://docs.nocobase.com/plugin-development/ +- NocoBase Project Structure: https://docs.nocobase.com/plugin-development/project-structure +- NocoBase AI Builder: https://docs.nocobase.com/ai-builder/ +- NocoBase AI Plugin Development: https://docs.nocobase.com/ai-dev/ +- NocoBase CLI: https://docs.nocobase.com/api/cli/ +- NocoBase Skills: https://github.com/nocobase/skills + +## 一、判断 + +NocoBase 最核心的启发是:AI 不应该默认直接写一堆业务代码,而是基于平台已有的可配置能力工作。AI 负责把自然语言需求转换为数据模型、页面配置、工作流、权限和发布包,人负责审核关键边界。 + +EIP4 当前已经有实体、页面 schema、服务流、菜单、smoke、部署包这些受控对象,因此更适合走“AI 操作元数据和发布包”的路线,而不是引入一套新的插件运行时。 + +## 二、可借鉴点 + +| NocoBase 做法 | EIP4 对应落点 | 处理方式 | +|---|---|---| +| AI 基于 no-code 基础设施工作 | `platform-ai` 生成实体/页面/服务流/菜单草稿 | 已落地,继续收敛到受控接口 | +| CLI 作为 Agent 操作入口 | `platform-cli` | P1 建立,后续扩展环境/发布/回滚 | +| Skills 让 Agent 理解平台 | `docs/skills/` | P1 建立规范骨架 | +| 插件生命周期 | EIP4 `FeaturePackage` 生命周期 | P2 设计和持久化 | +| 版本控制/里程碑回滚 | `SYS_AI_REVISION` / release evidence | P2-P3 | +| FlowEngine 的可配置模型 | EIP4 typed page schema + component registry | P4 借鉴思想,不照搬实现 | + +## 三、落地顺序 + +### P0:AI 辅助开发主链路(人工复核发布) + +状态:已完成。 + +完成内容: + +- `POST /api/ai/features/auto-develop` +- 草稿生成、变更包、release plan、本地 apply、smoke、自动修复、人工部署包 +- JDBC 审计和运行证据 +- 本地 jar 验证通过 + +验收标准: + +- 本地可从一段功能需求生成可审核部署包 +- 线上执行仍停在人审边界 + +### P1:受控入口和 Agent 知识包 + +状态:第一版完成。 + +目标: + +- 建立 `platform-cli`,让 Agent 通过命令调用 EIP4,而不是直接猜 HTTP 接口或直连数据库。 +- 建立 `docs/skills/`,把 EIP4 的环境管理、自动开发、发布管理写成 Agent 可复用的操作规程。 + +本阶段交付: + +- `eip4 env status` +- `eip4 ai auto-develop` +- `docs/skills/eip4-env-manage.md` +- `docs/skills/eip4-ai-feature-development.md` +- `docs/skills/eip4-release-manage.md` + +验收标准: + +- CLI 单测覆盖命令解析和请求组装 +- README 和自动开发文档给出 CLI 用法 +- Agent 后续操作优先引用 Skills 和 CLI + +### P2:FeaturePackage 和里程碑版本 + +状态:第一版完成。 + +目标: + +- 把 AI 生成结果从松散的 draft/change-set 升级为稳定的 `FeaturePackage`。 +- 保存里程碑版本,支持本地回滚和线上部署前差异确认。 + +建议对象: + +- `FeaturePackage`: manifest、entity、serviceflow、page schema、menu、acl、sql、rollback、smoke、evidence +- `SYS_AI_FEATURE_PACKAGE` +- `SYS_AI_REVISION` + +验收标准: + +- 一个功能包可以导出、导入、重复校验 +- 每个通过 smoke 的里程碑都能追溯输入、输出、测试证据和回滚脚本 + +第一版已落地: + +- `POST /api/ai/tasks/{taskId}/change-sets/{changeSetId}/feature-package` +- `GET /api/ai/tasks/{taskId}/feature-packages` +- `POST /api/ai/tasks/{taskId}/feature-packages/{packageId}/revisions` +- `GET /api/ai/tasks/{taskId}/revisions` +- `eip4 ai feature-package` +- `eip4 ai revision` +- `sys_ai_feature_package` +- `sys_ai_revision` + +未完成项: + +- 功能包导出/导入文件格式 +- revision 差异比较 +- 回滚执行编排 + +### P3:发布、回滚和环境治理 + +状态:进行中。 + +目标: + +- CLI 扩展为环境管理和发布编排入口。 +- 建立本地、测试、生产环境的只读探测、部署前检查和人工批准边界。 + +建议命令: + +- `eip4 env list/use/status` +- `eip4 release package` +- `eip4 release verify` +- `eip4 release apply --require-approval` +- `eip4 release rollback-plan --package-file FILE --output FILE` + +验收标准: + +- 默认不能连接线上执行写操作 +- 生产写操作必须有显式环境、审批标记和部署包 +- 发布失败能用结构化 evidence 回到本地修复链路 + +源码级修订: + +- 参考 NocoBase `env/status.ts` 和 `env-guard.ts`,`platform-cli` 新增本地 env registry/current env。 +- 参考 NocoBase revision 创建前检查版本控制插件的思路,EIP4 后续 revision restore/diff 不能只依赖 JSON 快照,必须有发布系统能力检查。 +- 新增 `eip4 release verify --package-file FILE`,先做离线发布前门禁,阻断未替换占位符和缺失本地 evidence 的功能包。 +- 新增 `eip4 release export/import-preview`,形成 `.eip4pkg.json` 文件格式和 checksum 门禁;导入预览不写环境、不启用功能。 +- 新增 `eip4 release diff/rollback-plan`,先落地离线差异检查和计划型回滚;回滚计划不执行生产 SQL。 +- 详细源码对照见 `docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md`。 + +### P4:Typed Page Schema 和组件注册表 + +状态:第一版完成。 + +目标: + +- 借鉴 NocoBase FlowEngine 的“可配置模型”思想,把页面 block、field、action、linkage 抽象为 typed schema。 +- 让 AI 和人工设计器操作同一份 schema。 + +验收标准: + +- 页面 schema 有版本、类型、组件能力表和校验器 +- AI 只能选择注册过的组件和动作 +- 设计器变更和 AI 变更能互相接续 + +第一版已落地: + +- `GET /api/page/schema/components` 下发组件能力表。 +- `POST /api/page/schema/validate` 做 typed page schema 离线校验。 +- `PUT /api/page/schema/{templateId}/overlay` 保存 overlay 前强制校验组件和 actionType。 +- 当前仍是第一版 registry;后续要继续补 linkage/event/resource 和组件属性级 schema。 + +### P5:多 Agent 协作和 AI 员工 + +状态:第一版完成。 + +目标: + +- 在平台内提供面向业务用户的 AI 助手能力,而不只是在开发侧使用 Agent。 + +建议方向: + +- 数据分析 Agent +- 表单配置 Agent +- 服务流诊断 Agent +- 权限风险审查 Agent +- 发布审计 Agent + +验收标准: + +- 每个 Agent 有独立权限、审计、工具白名单 +- 业务侧操作和开发侧操作共用平台审计模型 + +第一版已落地: + +- `GET /api/ai/tools` 下发工具注册表和 scope 要求。 +- `GET /api/ai/employees` 下发 AI employee 定义。 +- `POST /api/ai/tools/access-check` 统一检查 employee/tool/scope/targetEnv/productionWrite。 +- 生产写默认阻断;当前只开放本地开发、校验、smoke、功能包和发布准备工具。 + +## 四、不照搬的部分 + +NocoBase 是 TypeScript/Yarn workspace/插件包体系。EIP4 是 Java/Spring/Maven,并且必须兼容 EIP3 的实体、服务流和 XML 模板迁移路径。直接照搬 NocoBase 插件运行时会引入过高迁移成本。 + +EIP4 应该借鉴的是边界和流程: + +1. 稳定核心能力。 +2. 业务功能包化。 +3. Agent 通过 CLI/API 操作。 +4. 人审控制生产变更。 +5. 每一步有 evidence、版本和回滚。 + +## 五、当前推进状态 + +| 阶段 | 状态 | 说明 | +|---|---|---| +| P0 | 完成 | `platform-ai` 主链路已提交 | +| P1 | 第一版完成 | 已新增 `platform-cli` 和 Skills 规范骨架 | +| P2 | 第一版完成 | 已新增功能包快照、里程碑 revision、CLI 命令和持久化表 | +| P3 | 进行中 | 已完成 env registry/current env/cross-env guard/release verify/export/import-preview/diff/rollback-plan 第一版 | +| P4 | 第一版完成 | 已新增组件 registry、typed schema validator、校验 API 和 overlay 保存前门禁 | +| P5 | 第一版完成 | 已新增 AI tool registry、AI employee registry 和 access-check 门禁 | diff --git a/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md b/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md new file mode 100644 index 0000000..c649b0a --- /dev/null +++ b/docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md @@ -0,0 +1,136 @@ +# NocoBase 源码级对照和 EIP4 修订 + +日期:2026-06-17 + +本文件补充 `docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md` 的源码级依据。结论:EIP4 不照搬 NocoBase 的 TypeScript 插件运行时,但 P3 之后必须参考它的 CLI/env/revision/skills/tool-registry 边界,否则容易只做出“HTTP wrapper”,做不到可持续的 Agent 开发体系。 + +## 一、已抽样源码 + +| 主题 | NocoBase 源码 | 对 EIP4 的影响 | +|---|---|---| +| CLI env status | `packages/core/cli/src/commands/env/status.ts` | CLI 要有 env registry/current env/status,不应只靠 `--base-url` | +| 跨 env 确认 | `packages/core/cli/src/lib/env-guard.ts` | 显式选择非当前 env 时需要确认边界 | +| API client | `packages/core/cli/src/lib/api-client.ts` | CLI 请求应带结构化 env/token/role/header,后续不能散落在命令里 | +| runtime command registry | `packages/core/cli/src/generated/command-registry.ts` | 可根据运行时 API 生成命令,EIP4 后续可用 OpenAPI 生成安全 CLI | +| generic resource command | `packages/core/cli/src/lib/resource-command.ts` | CRUD 类命令应统一处理 JSON body、分页、过滤、错误输出 | +| plugin import/enable | `packages/core/cli/src/commands/plugin/import.ts`, `packages/core/cli/src/commands/plugin/enable.ts` | EIP4 的 FeaturePackage 后续也要区分导入、启用、发布和重启/刷新 | +| revision create | `packages/core/cli/src/commands/revision/create.ts` | revision 不能只是保存 JSON,发布前要检查版本控制能力是否可用 | +| skills install | `packages/core/cli/src/commands/skills/install.ts` | Skills 应由 CLI 安装/检查/更新,而不是只放仓库文档 | +| AI plugin server | `packages/plugins/@nocobase/plugin-ai/src/server/plugin.ts` | AI 功能要注册 tools、skills、MCP、AI employees、ACL snippet | +| FlowEngine | `packages/core/flow-engine/src/flowEngine.ts`, `packages/core/flow-engine/src/models/flowModel.tsx` | 页面 schema 需要演进到 typed model/action/event/resource registry | + +## 二、对当前实现的校正 + +### P0-P2 是否做实 + +已做实: + +- `platform-ai` 主链路有 Java 实现、JDBC/内存 store、DDL、Web API 和测试。 +- `platform-cli` 是可运行 jar,不是伪命令。 +- `FeaturePackage` 和 `Revision` 已有最小持久化模型。 + +但它还不是 NocoBase 级完整度: + +- CLI 之前缺少 env registry/current env。 +- revision 只是功能包快照,不是完整版本控制。 +- Skills 只是仓库文档,没有 CLI 安装/检查/更新。 +- AI tools/permissions/MCP/AI employee 还没有平台级注册。 +- 页面配置还没有 typed FlowModel registry。 + +### 已按源码对照修订的 P3 第一批 + +- `platform-cli` 新增本地 env registry,默认保存到 `~/.eip4/eip4-cli.json`。 +- 新增 `eip4 env add/list/use/current/status`。 +- AI 命令支持 `--env`。 +- 显式选择非当前 env 时必须加 `--yes`,避免误操作共享环境。 +- 新增 `eip4 release verify --package-file FILE`,离线检查功能包是否具备本地门禁 evidence、人审标记、SQL/rollback,并阻断 `${...}` 占位符。 +- 新增 `eip4 release export --package-file FILE --output FILE`,将功能包封装为 `.eip4pkg.json`,包含格式版本和 SHA-256 checksum。 +- 新增 `eip4 release import-preview --package-file FILE`,离线验证 `.eip4pkg.json` checksum 和发布门禁,不写任何环境。 +- 新增 `eip4 release diff --left FILE --right FILE`,离线比较两个功能包或 `.eip4pkg.json` 的标识、SQL、rollback SQL 和 manifest 差异。 +- 新增 `eip4 release rollback-plan --package-file FILE --output FILE`,只生成结构化回滚计划,不执行生产写入。 + +## 三、后续实现顺序 + +### P3-1:CLI env 和发布前治理 + +状态:进行中。 + +目标: + +- env registry/current env +- `release verify` +- package/revision 差异检查 +- 生产环境默认只读 + +### P3-2:FeaturePackage 导出/导入 + +状态:第一版完成。 + +目标: + +- `.eip4pkg.json` 文件格式 +- checksum +- import preview +- import 后不自动启用 + +第一版已落地: + +- export: 普通 feature package JSON -> `.eip4pkg.json` 信封。 +- import-preview: 校验 format/version/checksum/payload 和 release gate。 +- import-preview 只读,不落库、不启用、不发布。 + +### P3-3:Revision diff/restore + +状态:第一版完成。 + +目标: + +- revision diff +- rollback plan +- rollback 只生成计划和 SQL,不默认执行生产写入 + +第一版已落地: + +- diff: 比较两个普通 feature package JSON 或 `.eip4pkg.json`,支持 checksum 校验和 JSON 输出。 +- rollback-plan: 生成 `EIP4_ROLLBACK_PLAN` JSON,包含 package/task/changeSet、rollback SQL、source evidence 和人审要求。 +- rollback-plan 会阻断 rollback SQL 中的 `${...}` 占位符;命令不连接环境、不落库、不执行 SQL。 + +### P4:Typed UI Registry + +状态:第一版完成。 + +目标: + +- typed page schema +- component/action/event registry +- AI 只能选择 registry 中允许的组件和动作 + +第一版已落地: + +- `PageComponentRegistry` 提供页面组件能力表,当前覆盖 page/crud/form/operation/button、常用 layout/display 和字段组件。 +- `TypedPageSchemaValidator` 校验根节点、已注册组件和 actionType 能力。 +- `GET /api/page/schema/components` 返回组件能力表。 +- `POST /api/page/schema/validate` 离线校验页面 schema,不写库。 +- `PUT /api/page/schema/{templateId}/overlay` 保存前会先跑 typed schema 校验,未注册组件或不支持 action 会被 400 阻断。 + +### P5:AI tools/skills/employee/ACL + +状态:第一版完成。 + +目标: + +- AI tool registry +- AI employee registry +- ACL/scope check +- 生产写默认阻断 + +第一版已落地: + +- `AiToolRegistry` 注册工具、操作入口、所需 scope、本地限定和生产写边界。 +- `GET /api/ai/tools` 返回 AI 工具注册表。 +- `GET /api/ai/employees` 返回 AI employee 定义。 +- `POST /api/ai/tools/access-check` 只做权限判定,不执行工具;`local.apply` 等本地工具在 prod target 会被阻断。 +- 当前所有工具都不允许生产写;线上部署仍由人工拿发布包执行。 +- Skills CLI check/update +- AI Agent 权限和审计 +- MCP 工具白名单 diff --git a/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md b/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md new file mode 100644 index 0000000..5d747b0 --- /dev/null +++ b/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md @@ -0,0 +1,127 @@ +# AI Agent Page Blueprint Contract + +日期:2026-06-17 + +## 目标 + +EIP4 的 AI Agent 不直接自由生成 amis JSON。Agent 应先生成 EIP4 PageBlueprint,再由平台编译器输出 amis schema,并继续通过 typed page schema、amis schema 和真实浏览器 E2E。 + +这条路径借鉴 NocoBase 的做法:AI 操作受控配置模型,平台负责规范化、校验、模板复用和版本证据。 + +## 当前已落地对象 + +代码位置: + +- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprint.java` +- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintField.java` +- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompiler.java` +- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.java` +- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeValidator.java` +- `platform-ai/src/main/resources/ai/page-recipes/maintenance-crud-v1.yaml` +- `platform-ai/src/main/resources/ai/page-recipes/tree-crud-v1.yaml` + +AI 可查询入口: + +- `GET /api/ai/page-recipes` +- `GET /api/ai/page-recipes/{recipe}` + +工具注册表中对应工具为 `page-recipe.read`,所需 scope 为 `ai:page-recipe:read`。Agent 生成 +PageBlueprint 前应先读取 recipe 定义,再生成草稿。 + +AI 辅助开发链路中的 `PAGE_SCHEMA` 草稿仍然保存编译后的 amis schema,保持现有落库和前端渲染契约不变;草稿 metadata 额外保存: + +- `pageRecipe` +- `pageBlueprintVersion` +- `pageBlueprint` + +声明了 `pageRecipe` 的草稿必须通过 `page-recipe` 门禁。该门禁会重新解析 metadata 中的 +`pageBlueprint`,用平台注册的 recipe/compiler 重新编译,并要求草稿 payload 与编译结果一致。 +因此 Agent 不能一边声明使用标准 recipe,一边绕过 compiler 私改 amis JSON。没有声明 recipe 的 +历史/手工 `PAGE_SCHEMA` 草稿暂按自由 schema 处理,只走 amis schema 和 typed page schema。 + +## Recipe: maintenance-crud-v1 + +适用范围: + +- 普通实体维护页 +- 单主表列表 +- 新增、编辑、删除 +- 本地 smoke 可覆盖列表、新增、服务流搜索 + +标准输出结构: + +- 顶层 `type=page` +- `body` 为 `crud` +- `crud.name` 固定为 `{lowerCamel(tableName)}Crud` +- `crud.syncLocation=false` +- 列表 API 固定为 `/api/entity/{table}/list?page=${page}&perPage=${perPage}` +- 新增按钮位于 `headerToolbar[0]` +- 新增按钮使用 `level=primary`、`icon=fa fa-plus`、`actionType=dialog` +- 新增和编辑表单提交到 `post:/api/entity/{table}/save` +- 编辑按钮位于操作列第一位 +- 删除按钮位于操作列第二位 +- 删除按钮使用 `className=text-danger`、`actionType=ajax`、`confirmText` +- 删除 API 固定为 `/api/entity/{table}/delete` +- 页大小默认 `20` +- `footerToolbar` 固定包含 `statistics` 和 `pagination` + +## Recipe: tree-crud-v1 + +适用范围: + +- 自引用层级实体维护页 +- 实体必须包含 `PARENTID` 字段 +- 覆盖树形列表、新增顶级节点、加子节点、编辑、删除 + +标准输出结构: + +- 顶层 `type=page` +- `body` 为 `crud` +- `crud.name` 固定为 `{lowerCamel(tableName)}TreeCrud` +- `crud.childrenColumnName=children` +- 列表 API 固定为 `/api/entity/{table}/tree?parentKey=PARENTID&idKey={primaryKey}&perPage=2000` +- 新增顶级按钮位于 `headerToolbar[0]` +- 新增顶级按钮使用 `level=primary`、`icon=fa fa-plus`、`actionType=dialog` +- 操作列按钮顺序固定为:加子项、编辑、删除 +- 加子项表单必须隐藏写入 `PARENTID=${primaryKey}` +- 编辑表单必须保留隐藏主键和 `PARENTID` +- 删除按钮使用 `className=text-danger`、`actionType=ajax`、`confirmText` +- 树数据端点返回 `data.items` 层级数组,每个节点的子节点字段为 `children` + +字段映射: + +- `string` -> `input-text` +- `integer` / `number` -> `input-number` +- `date` -> `input-date` +- `datetime` -> `input-datetime` +- `boolean` -> `switch` +- 主键不出现在新增表单,编辑表单最后追加 `hidden` + +## 当前边界 + +本阶段只解决“AI 生成维护类 CRUD 页时走受控 recipe”。还未覆盖: + +- 主子表页面 +- 审批办理页面 +- 看板、日历、图表、报表页 +- 复杂字段分组 +- 条件联动 +- 引用选择器策略 +- 权限按钮策略 + +这些类型必须作为新的 recipe 增量加入,不能让 Agent 直接绕过 blueprint 生成最终 amis JSON。 + +## 已落地门禁 + +- `page-recipe`:校验 recipe 已注册、metadata 证据完整、payload 等于 blueprint 编译结果。 +- `typed-page-schema`:校验组件和 actionType 来自 EIP4 注册表。 +- `amis-schema`:校验最终 schema 符合 amis schema。 +- `local-smoke`:本地发布后访问页面、实体、服务流和新增接口。 +- `render-plan`:`TEST` 草稿必须提供 Playwright 可消费的 `renderTests`,包含 recipe、schemaUrl、previewUrl、预期根组件、CRUD 名、数据 API、列表列、页面动作和关键文本。 + +## 后续演进 + +1. 增加 `master-detail-v1`、`approval-task-v1` recipe。 +2. 让设计器 overlay 保存也能记录对应 blueprint 或 template 来源。 +3. 在功能包中导出 blueprint,线上部署包继续导出编译后的 amis schema。 +4. Playwright E2E 消费 `renderTests`,执行真实浏览器渲染并回写运行证据。 diff --git a/docs/AI_AGENT_REPAIR_CONTRACT.md b/docs/AI_AGENT_REPAIR_CONTRACT.md new file mode 100644 index 0000000..34517d2 --- /dev/null +++ b/docs/AI_AGENT_REPAIR_CONTRACT.md @@ -0,0 +1,155 @@ +# AI Agent Repair LLM 接入契约 + +本文档定义 `platform-ai` 调用外部 LLM 修复服务的最小契约。该服务只负责根据失败证据生成安全草稿补丁,不直接写库、不发布线上、不访问生产环境。 + +## 启用配置 + +默认不启用外部 LLM 修复。需要显式配置: + +```properties +eip4.ai.llm.repair.enabled=true +eip4.ai.llm.repair.endpoint=http://127.0.0.1:18081/ai-agent/repair +eip4.ai.llm.repair.api-key=${AI_REPAIR_API_KEY} +eip4.ai.llm.repair.model=${AI_REPAIR_MODEL} +``` + +`api-key` 为空时不发送 `Authorization` 头;非空时使用 `Authorization: Bearer `。接口超时为 60 秒。服务返回非 2xx、响应格式非法或调用异常时,平台会忽略外部结果并回退到内置确定性修复规则。 + +## 请求格式 + +`HttpAiLlmRepairClient` 向配置的 endpoint 发送 `POST application/json`: + +```json +{ + "model": "repair-model-name", + "taskId": "ait-1", + "changeSetId": "aics-1", + "repairPlan": { + "taskId": "ait-1", + "changeSetId": "aics-1", + "sourceRunId": "run-1", + "status": "READY", + "generatedAt": 1710000000000, + "actions": [], + "messages": [] + }, + "drafts": [], + "contract": { + "responseField": "draftPatches", + "patchShape": "artifactType,targetId,payload,metadata", + "rule": "Return only safe draft patches; do not execute production changes" + } +} +``` + +字段说明: + +- `repairPlan`: 平台根据最近失败的 `AUTO_DEVELOP` / `LOCAL_APPLY` / `SMOKE` 证据生成的修复计划。 +- `drafts`: 当前任务的草稿快照,LLM 只能基于这些草稿生成替代草稿。 +- `contract`: 平台要求的响应约束,外部服务必须遵守。 + +## 响应格式 + +外部服务必须返回 JSON 对象,且补丁数组放在 `draftPatches` 字段: + +```json +{ + "draftPatches": [ + { + "artifactType": "ENTITY", + "targetId": "CUSTOMER", + "payload": { + "publishTarget": "/api/meta/entity", + "tableName": "SYS_CUSTOMER", + "entityName": "Customer", + "fields": [] + }, + "metadata": { + "source": "llm-repair", + "reason": "补齐实体发布目标" + } + } + ] +} +``` + +`artifactType` 只允许: + +- `ENTITY` +- `PAGE_SCHEMA` +- `SERVICEFLOW` +- `MENU` +- `TEST` +- `CODE` + +平台当前主要自动修复 `ENTITY`、`PAGE_SCHEMA`、`SERVICEFLOW`、`MENU`、`TEST`。`CODE` 补丁即使返回,也仍然必须经过后续门禁、人审和部署包流程。 + +## 安全边界 + +外部 LLM 服务不得执行以下操作: + +- 连接或修改线上数据库。 +- 触发线上发布、重启、脚本执行或远程 shell。 +- 绕过平台的草稿、变更包、本地 apply、smoke、部署包和人工审批流程。 +- 返回除 `draftPatches` 之外需要平台立即执行的命令。 + +平台接收补丁后的流程是: + +1. 将补丁写成新的 `AiDraft`,保留 `metadata.source` 和原因。 +2. 基于同一 `artifactType + targetId` 取最新草稿重新生成 change set。 +3. 执行本地 apply 和 smoke。 +4. 生成线上人工部署包。 +5. 线上部署仍由人工审批和发布系统执行。 + +## 示例:修复 TEST 契约 + +请求中的 `repairPlan.actions` 指出 smoke 期望状态码与实际接口不一致时,外部服务可以返回: + +```json +{ + "draftPatches": [ + { + "artifactType": "TEST", + "targetId": "customer-smoke", + "payload": { + "smokes": [ + { + "name": "打开客户列表", + "method": "GET", + "path": "/api/customer/list", + "expectedStatus": 200 + } + ] + }, + "metadata": { + "source": "llm-repair", + "reason": "同步 smoke 期望状态码" + } + } + ] +} +``` + +## 示例:修复 PAGE_SCHEMA + +页面 schema 缺少 `type`、`title` 或 `body` 时,外部服务可以返回: + +```json +{ + "draftPatches": [ + { + "artifactType": "PAGE_SCHEMA", + "targetId": "customer-page", + "payload": { + "type": "page", + "title": "客户管理", + "body": [] + }, + "metadata": { + "source": "llm-repair", + "reason": "补齐 amis 页面必填结构" + } + } + ] +} +``` diff --git a/docs/plans/2026-06-19-EIP4开发平台-架构方向-design.md b/docs/plans/2026-06-19-EIP4开发平台-架构方向-design.md new file mode 100644 index 0000000..851a629 --- /dev/null +++ b/docs/plans/2026-06-19-EIP4开发平台-架构方向-design.md @@ -0,0 +1,133 @@ +# EIP4 开发平台 · 架构方向(与最初设计对齐版) + +> 日期:2026-06-19 | 性质:方向级 design(brainstorm 收敛 + 最初设计考古 + 引擎代码核实 + 对抗审查产出) +> 配套权威:`项目进度与路线-总览-2026-06-17.md`(A 兼容 / B 新功能全景)、`架构设计.md`(双层制/选型/红线)、`决策与盘点/EIP4前端与收尾实施计划.md`(F4 低代码工具链原始定义) +> 方法:9-agent workflow(7 路考古/代码核实 → 综合 → 对抗审查),逐行核实引擎实况。 + +--- + +## 0. 一句话结论 + +**「153 收尾后做可视化开发平台」不是另起炉灶,是项目最初路线图里 F4「低代码工具链 L1→L3」的兑现。** 方向成立(对抗审查判决 `sound-with-fixes`),但最初设计逼出三根硬约束(一根是「触发重新决策」级),需带 6 条修正落地。 + +## 1. 背景与驱动(用户拍板) + +- **先 B 提效、再 A 卖点**:先用新能力填「建页/建模/交付太慢太贵」的钱坑,再讲 AI/现代化差异化。 +- **递进**:存量 153 定制视图用现有兼容方式(转换器 mutator)啃完(已完成几十个);真正重点是 153 后,面向「**未来功能维护 + 新功能开发**」要有一套现代可视化开发平台,覆盖【**元数据 → 表结构 → 设计 → 实现功能 → 发布**】五环。 +- **AI 独立轨**:已在另一分支做,定位=给 AI coding 工具(Claude Code/Cursor)供 **MCP + CLI**,不是应用内 AI 生成 schema。 +- **定位**:内部交付提效工具(**非**对客户售卖的低代码/自助配置平台——见 §5 红线)。 + +## 2. 与最初设计「一脉相承」的依据(5 处文档锚点) + +| 本方向 | 最初设计原文锚点 | +|---|---| +| 五环【元数据→表→设计→实现→发布】 | 《EIP4前端与收尾实施计划》F4 总览:**「低代码工具链 L1→L3,门控:无(架构已拍板)」**;§七:L1 页面设计器=amis-editor 二开 / L2 实体建模器=可视化维护 SYS_ENTITY / L3 流程设计器=bpmn.js + Flowable。末环=§6.3 在线导入发布 | +| 现代层 authoring 长在引擎上 | 架构设计 §一「**保真层供奉、现代层生长**」+ ArchUnit 单向纪律(`com.eip4.*` 可调 `com.dsasp.*`,反向禁止) | +| 一个 schema 世界 | §6.2「SYS_PAGE_SCHEMA 标准层 + overlay 层,升级时标准层整体替换、overlay 保留提示 diff」 | +| AI 独立轨给 MCP+CLI | 最初 **P5「MCP/AI 工具层」** 逐字吻合 | + +**引擎实况(已读码核实)**:四环里**三环引擎已在保真层活着**——`Entity.java`/`POInfo.java`/`POJOCRUDServiceImpl`(元数据 CRUD)、`Entity.createTableSql`→`DataDicServiceImpl`(动态建表)、`FlowExcuteServiceImpl`(534 行,含 `insertNodeAfter/removeNode` 图编辑原语 + `saveOrUpdate` 写回 `SYS_SERVICEFLOW`)、Groovy/JUEL 脚本引擎。 + +## 3. 最初设计强加的三根硬约束(对抗审查核实) + +### ① 最大矛盾 · 焊死退路(go/no-go 级)—— 决策:**签字下注 amis** +最初把 amis-editor/自研设计器钉为「amis fork 失败时的防御性 **Plan B**」(止损 S2,换渲染器损失仅 1–2 人月)。架构决策报告 §四「触发重新决策条件#1」:*若决策层不接受永久 fork + 终身自维护前端渲染器的预算 → 须重评其他 Apache 渲染层*。把 amis-editor 升为战略主线 = 主动焊死退路 = 踩中该触发条件。 +**已知天花板(写进立项)**:amis-fork 6.13.0 冻结于 2025-08、近 3 月零上游提交、bus factor≈1、需 **0.5–1 人/年自维护**。 +**用户拍板**:✅ 签字下注 amis。**但附带关键现实**:**DesignerPage 当前还无法真正使用**(见 §7)——下注成立的前提是先把它弄到能用。 + +### ② 「补 UI 非造引擎」被系统性低估 —— 真实=「一环就位 + 两环要补引擎」 +- **设计环**:✅ 就位,但**仅 edit-only on 存量页**(e2e 68/68 验的是 overlay 存取往返,**不等于设计器可用**)。 +- **建模环**:🔴 引擎层**不能 ALTER**(`executeCreateSql` 只接受 CREATE,`DataDicServiceImpl:193-200`);`MetaController` 是克隆 SYS_USERGROUP、限 `EIP4AI_` 前缀的 **AI 雏形**,非面向人。新建实体后改字段**零迁移路径**。 +- **编排环**:🔴 `FlowController` **只执行不编辑**,flow 仍是老 XML,EIP4 侧 **0 个 authoring REST**。 + +### ③ overlay 是 edit-only —— 「一个 schema 世界」附条件成立(一次性数据建模门) +`SYS_PAGE_SCHEMA_OVERLAY` 以 `template_id` 为主键、`base_etag` 挂靠**转换器产出的标准层**。「一个 schema 世界 + 可升级」的优雅**只在「先有标准底版、overlay 是其差量」时成立**。**从零新建的页没有标准底版**,其生命周期/升级/diff 在最初设计里是**空白**。「改存量页已上线」≠「新建页平台就绪」。 + +## 4. 逻辑编排器(唯一硬骨头)—— 决策:**b 主干 + 人工 20% + c 增量,否决 a** + +- **否决 a(节点图编辑器)**:最初零根基;`Flow.java:422/454` 对非线性流主动抛「请用高级配置进行编辑」——证明**连老 EIP3 自己的可视化也只覆盖线性流**。节点图是最重前端投资、对冻结栈纯新增,ROI 最差。 +- **b 主干**:80% 常规联动/线性服务流走声明式配置面(32 个 facade 动词 onEvent 面板,复用已有),不写代码即提效。 +- **诚实修正(对抗审查)**:b 只覆盖**老系统已能可视化的线性流**;那 20% 复杂逻辑(非线性流/有副作用 Groovy/跨流条件=最初 S3 留下的 **115 份人工作业单**)**b 接不住**。 +- **故**:那 20% **默认保留「人工作业单」兜底**(人写 Groovy/JUEL,复用 `field-editor`);**c(AI 生成)仅「加速人工 + 人工复核入库」增量**,platform-ai 空壳未落地前**不算进对外交付能力**。对外能力边界=「**b 声明式 80% + 人工 20%**」。 + +## 5. 落地形态(与最初设计对齐) + +不立「新平台」为独立大项目,而是把 F4 三件套 + §6.2 overlay + §6.3 发布 + P5 MCP 正式化为一套「**现代层 authoring 模块集合**」,落在 `platform-metadata` 等现有模块内(不新进程),守三红线: + +> **4 进程私有化单体 / 无新中间件 / 无多租户**;authoring 必须走既有引擎接口签名(POInfo/Entity/DataPrivilege/FlowExcuteService)**不旁路**。 + +- **存储层零新增**:authoring 全部读写 `SYS_ENTITY`/`SYS_ENTITYATTRIBUTE`(元数据真相)、`SYS_SERVICEFLOW.CONTENTXML`(服务流真相)、`SYS_PAGE_SCHEMA`+overlay(页面真相)。「元数据即白名单」运行期/开发期同源。 +- **定位红线**:架构决策报告 §2.1a 已把「交付带动态建表的低代码平台能力给客户继续配置」定性为合同敏感地带(曾用于否决路线 B)。新平台守在**内部提效工具**,不对外做 SaaS/多租户配置平台。 + +## 6. 分期路线(每期标复用什么 / 补什么引擎欠账) + +| 期 | 目标 | 关键交付 | 真实前置 / 复用 | +|---|---|---|---| +| **P0** | 立底座 + 门禁 | 组件设计体系 **L1 主题 token 做到生产级**(决策2「先 B 提效」的 UI 前提);为新 authoring 产物补**正确性门禁**(新建页无对拍基准!→ 元数据变更 CRUD 烟测 + 编排执行对拍 + overlay 版本可审计回滚 + schema 双闸复用);amis 战略取舍立项书签字 | **真实前置=组件 L1,非 153**;复用 overlay 双层、schema 双闸 | +| **P1** | 设计环正式化 + **先修 DesignerPage 可用性** | 诊断并修复 DesignerPage「无法使用」(见 §7);从「改存量」升级到能用;**补 net-new 页数据模型/生命周期**(闭合 §3③门);收敛独立设计中心(评估 `DesignCenterPage.tsx` 雏形);facade onEvent 声明式面板第一块 | 复用 DesignerPage/overlayApi、PageSchemaController、facade 动词表 | +| **P2** | 建模环 | **先补引擎安全 `alterTableSql`**(加法在线/改删走升级窗口,守 §6.3 红线)再做 L2 建模器 UI;MetaController 从 AI 雏形重写为面向人 | 复用 Entity.createTableSql + 缓存失效免重启 | +| **P3** | 编排环(硬骨头·打法 b) | 服务流 authoring REST 出口(暴露 `FlowServiceImpl.saveOrUpdate` + 图编辑原语)+ 声明式线性流配置面 + Groovy 代码编辑器兜底;BPMN 审批流走 L3 bpmn.js | 复用 FlowExcuteService + Flow 图编辑原语 + DefaultFlowHelper | +| **P4** | 发布环 + 链条贯通 | §6.3 元数据资产包另存/导入;「建实体→合成默认流→生成默认页→设计器微调→发布」串通 | 复用 §6.3 资产包 + 缓存失效 + DefaultFlowHelper | +| **P5** | AI 工具面(决策3 独立轨·c 兜底) | Meta/Flow 端点升级为正式 MCP,接通 platform-ai 空壳,消除两套 authoring 入口 | 复用已建端点 + schema 校验 | + +> 启动次序:**与 153 收尾并行**(用户拍板)。解除「153 收尾后才做」硬前置——153 进度由商务 S1 拍板、不由技术,挂其后会被无限期阻塞。**但据实承认**:新平台真实前置是组件 L1,不是把「等 153」换成「等组件 L1」的隐藏依赖游戏。 + +## 7. DesignerPage 现状(状态标记,非当前动手任务) + +> 定性:这是一个**已知状态**(用户实测不可用),作为 D1 amis 下注的前置验证项纳入 P1,**不在架构方向讨论里展开 debug**。诊断已查实环境层根因嫌疑(见下),最终复现/修复留到 P1 执行期。 + +**入口模型(D5 已定)**:单一「设计中心」菜单入口(运行态/设计态分离),废弃每页注入按钮。`DesignCenterPage.tsx`(fetchMenu→collectLeaves 列页 + 「设计」入口)是正确雏形方向,需补「新建页」与 net-new 生命周期(§3③)。 + +**「打开没有内容」环境层查实(curl/lsof 实测,2026-06-19)**: +- **8093 是纯 API 后端,完全不托管前端**(`/`、`/index.html`、`/assets/*`、`/editor.html` 全 404); +- 前端只活在 **4 个 stale 重复 vite dev server**(5174-5177);`.env` 有重复 `VITE_BACKEND_TARGET`(8084→8093)——**stale 实例代理到死端口 8084 → schema 拉不到 → 画布空** 是头号嫌疑; +- editor.html 入口页本身没坏(vite 上 200 + CSS 直链 200,dist 构建也正确); +- 这同时暴露 **A10:整个前端(设计器在内)没有被托管的家,只跑临时 dev 进程** —— 设计器「无法使用」一半是部署/托管缺失。 + +**旧线索(仍待 P1 复现确认)**: +- e2e 只验 overlay 存取往返,**未验设计器作为 authoring 工具可用**; +- 报告自承「**facade onEvent 可视化面板未做**」——能拖布局、配不了行为; +- `editor.html` CSS 走 `/node_modules/...` 直链(dev-only hack),**生产构建可能裂**; +- **edit-only on 存量页**,不能新建/绑新实体(§3③门); +- `DesignerPage.handleRestore` 注释自承:amis-editor 整体替换 value 会「白屏」,故还原后整页 reload(提示 amis-editor 二开的脆性)。 + +**下一步**:钉准「无法使用」的真实症状(开不了 / 白屏 / 只能改存量 / 能改但太糙/配不了逻辑 / 生产构建裂),再定 P1 第一锤。 + +## 8. 6 条必须吞下的修正(对抗审查 fixes) + +1. 「放弃渲染层可换退路」升为立项**硬 go/no-go**,立项书签字接受 amis-fork 冻结天花板。(✅ 用户已签) +2. 为 net-new 页补数据模型与生命周期,再谈「一个 schema 世界」;闭合前不把「设计中心」当「新平台就绪」对外宣称。 +3. 拆 b/c 真空:20% 复杂逻辑默认「人工作业单」兜底,c 仅「加速人工 + 人工复核」,platform-ai 落地前不算进交付。 +4. 引擎层**先补安全 `alterTableSql` 并冻结边界**再做 L2 UI;MetaController 重写为面向人,别在 AI 雏形上长 UI。 +5. 解除「153 后才做」硬前置,但 P0 据实命名「L1 底座 + authoring 门禁」,不用隐藏前置替换显式前置。 +6. 为新 authoring 产物新设正确性门禁(新建页无对拍基准)——提为 **P0 交付物**,是绕过最初数据事故控制机制的唯一补偿。 + +## 9. 顶层风险 + +- 逻辑编排环是最初真空地带、无对拍基准、最高不确定(S3 自动化率 <80% 即触发工期重估)。 +- amis-fork 冻结天花板被加码(押更多二开在 bus factor≈1 的栈上)。 +- 建表 ALTER 缺口 × §6.3「DDL 只允许加法在线」红线夹击——「改表」体验天然受限,不能做成自由在线 DDL。 +- 「元数据即白名单」在线 authoring 下可能反转为约束:白名单变活动目标,并发 authoring 的一致性/缓存时序是新攻击面。 +- 组件体系未达生产级即做设计中心=重蹈「功能对但观感差」覆辙。 + +## 10. 决策记录(本次锁定) + +| # | 决策 | 选择 | +|---|---|---| +| D1 | amis-editor 战略下注 | ✅ 签字下注(接受冻结天花板);前提=先修 DesignerPage 可用性 | +| D2 | 新平台启动次序 | ✅ 与 153 并行(真实前置=组件 L1) | +| D3 | 逻辑编排打法 | ✅ b 主干 + 人工 20% + c 增量,否决 a | +| D4 | 对外定位 | 内部提效工具(守 §5 合同红线)| +| D5 | **设计入口模型** | ✅ **单一「设计中心」菜单入口**(运行态/设计态分离);**废弃每页注入的设计按钮**(转换器 `EngineclassDelta:898` + PageRenderPage「设计」按钮,用户已移除)。开发/设计是独立工作区,不混进业务页工具栏 | +| D6 | **AI 轨形态** | ✅ AI = **独立 NocoBase 式 CLI 编程轨**(`feature-package` 为单元的 scaffold→dev→verify→release 生命周期,供 Claude Code/Cursor 等 AI coding 工具操作),**不并入设计中心**。EIP4 的「插件」等价物 = 元数据 feature-package(非代码插件) | +| D7 | **设计中心定位** | ✅ 设计中心 = **给实施人员的纯人工 no-code**(b 轨),不挂 AI 入口;AI 走 D6 独立 CLI 轨 | + +--- + +## 11. 落地状态(2026-06-19 续) + +- **AI agent 分支已合入 main(`9aea6c1`)**:交付了五环+横向的后端地基一大半(schema 门禁/三真相 authoring 端点/recipe-blueprint/元数据建实体/CLI 种子),并由 3 个收口提交保障合 main 安全(分流 `bac69d8` / admin 门 `c379f5b` / 对外口径 `9aea6c1`)。逐项对账 + 有序里程碑见 **`2026-06-19-EIP4开发平台-落地执行路线图.md`**(活计划)。 +- **仍为 P0 锁定前置且未起步**:组件设计体系 **L1 主题 token 生产级**(D2)——路线图 M0。 +- 本方向级 design 为权威决策记录;可执行里程碑/状态以路线图为准。 + +*本文为方向级 design;细化实施计划见配套《落地执行路线图》。* diff --git a/docs/plans/2026-06-19-EIP4开发平台-落地执行路线图.md b/docs/plans/2026-06-19-EIP4开发平台-落地执行路线图.md new file mode 100644 index 0000000..633e9cd --- /dev/null +++ b/docs/plans/2026-06-19-EIP4开发平台-落地执行路线图.md @@ -0,0 +1,76 @@ +# EIP4 开发平台 · 落地执行路线图 + +> 日期 2026-06-19 | 活计划,配套《2026-06-19-EIP4开发平台-架构方向-design.md》(方向+锁定决策 D1-D7)。本文是该 design doc 承诺的「另立 plan 文档」。每里程碑落地后回写状态。 +> **经对抗审查修订**:补回 D2 锁定的 P0 前置(组件 L1);把正确性门禁(渲染冒烟)置于真库 dogfood 之前;net-new 旁路先收口为单一写真相再立新端点;区分「build 完成 vs env 终验」。 + +## 0. 修订要点(为什么不照搬初稿) + +- design §6 的 P0 = **组件 L1 主题 token 生产级**,是 D2 锁定的「真实前置」;初稿漏了,本版补为 **M0**,且设计中心-facing 里程碑(M3b 新建入口 / M5 面板)必须 gated 在 M0 之后(否则重蹈 design §9「功能对观感差」覆辙)。 +- design fix#6:新 authoring 产物无对拍基准,**渲染冒烟闸是绕过原数据事故控制的唯一补偿**——必须先于任何真库 dogfood。 +- net-new 标准层现由 `AiLocalReleaseExecutor:158` 裸 JDBC 旁路直写;新端点必须**先把旁路收口为单一写函数**,否则两套写法并存(语义/审计/etag 漂移)。 + +## 1. AI 合并交付对账(设计五环+横向 → 已交付 → 状态 → 剩余) + +> 图例:🟢=主体已交付且无 P0 级剩余 | 🟡=部分交付/有 P0 级剩余(见右列)| 🔴=未起步。main 现位于 `9aea6c1`(fast-forward 纳入 AI 合并 `bd4c642` + 3 收口 `bac69d8`/`c379f5b`/`9aea6c1`,全 reactor 10 模块绿)。 + +| 环/横向 | 已交付 | 状态 | 剩余(含 P0 标注) | +|---|---|---|---| +| 横向·正确性门禁 | TypedPageSchemaValidator + recipe 逐字节对拍 + 官方 draft-07,已接 putOverlay(分流后只对 AI 草稿严格) | 🟡 | **[P0] 渲染冒烟闸未做**(`AiSmokeRunner` 仅 HTTP 探针,playwright-render 无执行代码)= design fix#6 唯一补偿控制 | +| ①元数据 | `MetaController.createEntity` + 动态 CREATE + 缓存失效 | 🟡 | 引擎不能 ALTER;L2 建模器 UI 无;仍克隆 `SYS_USERGROUP` 做载体 | +| ②表结构 | `createTableDdl`(控制器内联) | 🟡 | ALTER 缺口;DDL 类型映射双份真相(与引擎漂移险) | +| ③设计 | recipe/blueprint 编译器(2 recipe)生成 amis 页;DesignerPage 改存量(分流后存量页可存 overlay) | 🟡 | DesignerPage 打不开(serving/env);net-new 正规写端点缺(走 AI 旁路);onEvent 声明式面板未做;recipe 仅 2 | +| ④实现功能 | `AiFeatureDraftGenerator` 用保真层 `DefaultFlowHelper` 生成默认 5 服务流 | 🟡 | 无人工编排 UI;只默认流;无服务流语义级 gate | +| ⑤发布 | deployment-package + CLI release ops + feature-package/revision 快照 | 🟡 | online apply 断档(人工跑 SQL);菜单注册未串端到端;**净新标准行无删除/回滚路径** | +| 横向·CLI | `Eip4Cli`(env/ai/release ops) | 🟡 | feature-package 为单元的 scaffold→dev→verify→release 生命周期未成型 | +| 横向·安全 | admin 门 + localhost 门 | 🟡 | `check()` 身份/scope 未织入写路径(等 CLI 身份模型) | +| 横向·UI 底座(组件 L1) | — | 🔴 | **[P0] L1 主题 token 未起步**(design §6 P0 锁定前置,D2);repo 无 token 资产 | + +## 2. 有序里程碑 + +### 前置地基(design 锁定 P0,先于一切设计中心-facing 工作) +- **M0 组件设计体系 L1 主题 token 生产级**[自主 build / 需 env 终验观感]:落 `组件设计体系-design` L1 主题层。D2 锁定前置 + 设计中心/设计器观感底座。**M3b/M5 必须在 M0 后**。 +- **M-Gate 正确性门禁第二闸(渲染冒烟)**[harness 自主 / 需 headless 终验]:Playwright/headless 对 previewUrl 真渲染断言(可视 + 无控制台报错),替 `AiSmokeRunner` HTTP 探针。design fix#6 唯一补偿控制——**必须先于任何真库 dogfood(M2)**。 + +### 先宽度(让 2 recipe + 设计器对存量 真端到端可用) +- **M1 Serving 解锁(A10)**[配置部分自主 / 终验需 env]:(a) 修 stale vite 代理死端口 8084 + `safeLocalBase` 默认(可自主改配置);(b) 前端(含设计器)被真正托管 → DesignerPage 能打开(终验需 env)。先消 design §7 已定位的环境性根因。 +- **M3a net-new 写路径收口(单一写真相)**[自主 + TDD]:把 `AiLocalReleaseExecutor:158` 裸 `INSERT sys_page_schema` 改为调用**唯一共享写函数**(复用 typed 校验/审计/etag);`PageSchemaController` 加标准层写端点复用同一函数。**验收 = sys_page_schema 写入只剩一个函数,无旁路裸 INSERT**。**收口先于新建入口**。 +- **M2 真库 dogfood(沙箱 schema)**[需 env + admin creds]:AI 产 EIP4AI_净新 CRUD → 过三闸(**含 M-Gate 渲染冒烟**)→ **写一次性/沙箱 schema(非共享生产 PG)** → 浏览器打开可用;附净新行清理/回滚脚本。**前置 = M-Gate + M3a**。 +- **M3b 设计中心「新建功能」入口**[前端,gated by M0 + M3a]:`DesignCenterPage` 加新建入口,走 M3a 共享写函数;设计角色细分(复用 RBAC)。 +- → **宽度闭环**「建实体→生成默认页→设计器微调→发布」可演示(前置 M0/M-Gate/M1/M3a 全绿)。 + +### 再深度 +- **M4 引擎 ALTER 安全通道 + DDL 单源**[自主 build / 需 env 终验]:保真层白名单化 `alterTableSql`(只加列/扩长/改可空,改删走升级窗口)+ `MetaController` alter 端点 + 独立安全门;顺带把 `createTableDdl` 的第二份 DDL 类型映射收敛回引擎单源(消漂移)。 +- **M5 onEvent 声明式面板(逻辑 b 主干第一块·design P3 硬骨头)**[前端,gated by M0]:32 facade 动词配置面板。**风险储备**:design 标的最高不确定环(S3 自动化率 <80% 触发工期重估);**20% 复杂逻辑保留「人工作业单」兜底**(design fix#3),不进面板。 +- **M7 recipe 扩面**[自主 + TDD]:主子表/EditGrid/审批/组合 tabs recipe + 字段控件补 select/picker/input-tree/引用列(每种自带逐字节对拍基准)。 +- **M8 CLI NocoBase 化 + 安全 Part2**[design + code 自主]:feature-package 为单元 scaffold→dev→verify→release 生命周期(D6);「认证用户→AI employee→scope」映射 + `check()` 织入写路径。 + +## 3. 自主 vs 需环境(build 完成 ≠ 集成已证) + +| 里程碑 | 可自主 build + unit-test | 需 env/creds 终验 | +|---|---|---| +| M0 L1 token | 定义 token 层 | 生产级观感(浏览器) | +| M-Gate 渲染冒烟 | Playwright harness 代码 | 真渲染断言(headless) | +| M1 serving | 改 vite/8084 配置 | 托管 + 打开终验 | +| M3a 收口 | 共享写函数 + 端点 + TDD | —(纯写路径,集成在 M2 证) | +| M2 dogfood | — | 端到端(沙箱 PG + admin) | +| M3b 新建入口 | 端点接线 | 浏览器新建终验 | +| M4 ALTER | alterSql + 端点 + TDD | 真 PG 在线加列证 | +| M5 面板 | 面板代码 | 浏览器联动证 | +| M7 recipe | 编译器 + 对拍 TDD | 渲染证 | +| M8 CLI/Part2 | 命令 + 身份映射 + TDD | 端到端证 | + +> **纪律**:M3a/M4/M7 的「完成」= **code-complete, integration-pending**;集成声明等 env 终验,不在绿单测上宣称端到端 done。 + +## 4. 下一步(已定,honest) + +**M3a — net-new 写路径收口为单一写真相**(自主 + TDD,不依赖 env,不碰 L1-gated UI,收口 critic 点名的三真相旁路纪律)。其「完成」严格限 **code-complete**;端到端宽度价值待 M0/M-Gate/M1/M2 解锁后证。 +**M0(L1)与 M1(serving 配置)可并行起**(L1 是 D2 锁定前置);M2/M3b/M5 的浏览器/真库终验等用户给登录方式。 + +## 5. Housekeeping +- 本文 + design doc(补 D6/D7)commit 进 main。 +- main 现领先 origin/main 20 提交(AI 合并 + 3 收口),**push = 用户决策**(两仓需先 add remote / git.latent.chat,见 memory `eip3-git-remotes-latentchat`)。 +- worktree `eip4-platform-ai-agent` 已与 main 同 commit,可清理。 + +--- + +*本文为活的执行计划;状态随里程碑落地回写。方向/决策权威见配套 design doc。* diff --git a/docs/plans/2026-06-20-人走五环建新功能-NocoBase式-design.md b/docs/plans/2026-06-20-人走五环建新功能-NocoBase式-design.md new file mode 100644 index 0000000..4145a1e --- /dev/null +++ b/docs/plans/2026-06-20-人走五环建新功能-NocoBase式-design.md @@ -0,0 +1,99 @@ +# 人走五环建新功能 · NocoBase 式(建模器 + 实时设计器)· 设计 + +> 日期 2026-06-20 | brainstorm 产物 | 配套《2026-06-19-EIP4开发平台-架构方向-design.md》(方向 D1-D7)+《2026-06-19-EIP4开发平台-落地执行路线图.md》(里程碑 M0-M8)。 +> 决策来源:memory `eip4-human-five-ring-wizard`(宽度 vs 深度 → 选 B:人走五环建新功能,AI 退回加速器)。 +> 本文是该特性的设计定型,供新会话直接跑 `superpowers:writing-plans` 出实施计划。 + +## 0. 一句话 + +给老引擎本来就有的「元数据驱动低代码核」配一套 **NocoBase 式的现代 UI(建模器 + 实时设计器),不做线性问卷向导**;让人能走完整五环(元数据→设计→实现→发布)建新功能,AI 作为加速器、不是唯一通道。 + +## 1. 锁定的决策(带依据) + +- **D-A 形态 = 建模器 + 实时设计器,不做线性 wizard。** 依据:用户指定参考 NocoBase,NocoBase 用「实时所见即所得区块设计器 + 一键切使用/配置模式」,明确**不用向导**;且我们今天刚把 DesignerPage(amis-editor)修到全闭环,与之天然契合。 +- **D-B v1 只「建新功能」,不「改已有表」。** 依据:CREATE 建表后端已 live 验证(见 §3);唯一缺口是 ALTER(改已有表的列)= 路线图 M4,留给 v2。 +- **D-C 建完实体走「recipe 自动产默认页 → 进设计器微调」,不走「空白页现拖组件绑实体」。** 依据:`PageBlueprintCompiler.compile()` 吃 blueprint 直接产出**已接好 `/api/flow/{TABLE}_SEARCH` 的页**(`PageBlueprintCompiler.java:50`);DesignerPage 现为 **edit-only**(只改存量页),recipe 预接好页正好落在它能干的范围内,**设计器无需长「从零绑实体」的新能力**。 +- **D-D「AI 帮我」走 ①面(外部 agent + Skills + CLI 驱动确定性工具),不在平台内置生成 LLM。** 依据:见 §3——平台主路径零 LLM,NocoBase 的「建功能 AI」本身就是外部 coding-agent CLI + Skills;EIP4 已建好这套底座(`docs/skills/` + `platform-cli` + `AiToolRegistry` + `AiEmployee`)。②面(in-app AI employees,平台内置 LLM)= v1 之后单独立项。 +- **D-E 元数据单一真相 = `SYS_ENTITY` + `SYS_ENTITYATTRIBUTE`(老系统保真层),新旧共用。** 见 §3。 + +## 2. 整体形态 + 建功能流程 + +**两个界面(落在设计中心):** +1. **建模器**(新建的唯一无对应 UI 的环)— 建/浏览实体 + 字段,包 `POST /api/meta/entity`。 +2. **实时设计器**(DesignerPage / amis-editor,已有,edit-only)— 微调页面。 + +**建一个新功能的流:** + +``` +①建模器建实体+字段 + → POST /api/meta/entity(写 SYS_ENTITY/SYS_ENTITYATTRIBUTE + 真 CREATE 物理表) +②选 recipe(维护CRUD / 树CRUD) + → PageBlueprintCompiler 自动产出已接 /api/flow 的默认页 → 落 sys_page_schema(标准层) +③默认页进 DesignerPage 微调(拖列/调布局) +④选菜单位置 + 发布(PageSchemaWriter 单一写真相 + 菜单注册) + (五流 _ADD/_UPDATE/_SEARCH/_DELETE/_LOAD 由 DefaultFlowHelper 默认生成,可见可确认,多数不用人管) +``` + +**设计中心两入口(人/AI 共用同一套后端 + 同一份 schema):** +- **`[+ 新建功能]`**(人):自己在建模器 + 设计器里走五环。 +- **`[⚡ AI 建功能]`**(AI ①面):触发外部 agent + 现有 skills/CLI 链(`POST /api/ai/features/auto-develop`),产 `READY_FOR_HUMAN_REVIEW` 草稿,人回设计器审/改/发。 + +## 3. 关键架构事实(brainstorm 核实,几条反直觉的) + +1. **元数据单一真相、新旧共用。** `MetaController.createEntity` 把实体行写进 **`SYS_ENTITY`**(`:89`,克隆 SYS_USERGROUP 的实体描述行做模板载体)、字段行写进 **`SYS_ENTITYATTRIBUTE`**(`:246`)。这两张表 + 引擎在 `platform-legacy-core`,包名 `com.dsasp.server.common.dataDic.service`——**老系统保真层原物**。eip3 老系统本身就是元数据驱动低代码平台;「转换」只动页面层(XML/engineclass → amis `sys_page_schema`),元数据一行没转。 +2. **CREATE 建表后端已 live。** `createEntity` 走 `createTableDdl()` 拼真 DDL → `dataDicService.executeCreateSql(ddl)` 真执行(`MetaController.java:130-131`),补索引、失效缓存。AI agent 建新表就走这条。**唯一缺口是 ALTER**(改已有表)= M4。 +3. **平台主路径零 LLM。** `AiFeatureRequest` 完全结构化(`featureName/tableName/entityName/List fields/pageRecipe`),连 `auto-develop` 吃的都是它,不是自然语言。`AiFeatureDraftGenerator` 按规则确定性编译。**平台内唯一 LLM = `HttpAiLlmRepairClient`,`@ConditionalOnProperty(...repair.enabled,"true")` 默认关,且只做修复不做生成。** NL→结构化 spec 的魔法在平台外(外部 coding-agent 经 CLI)。 +4. **NocoBase 的「建功能 AI」= 外部 agent CLI + Skills。** NocoBase Skills 官方定义 =「给 AI Agent CLI(Claude Code、Codex、Cursor 等)用的可复用领域知识包」,外部加载、非服务端组件,agent 经 CLI/API 在权限+审计下驱动 no-code 操作。EIP4 已有对应底座。NocoBase 另有 in-platform「AI Employees」(业务用户在 App 内对话,内置 LLM)= 我们的 ②面,v1 不做。 +5. **recipe 编译器吃 blueprint 产已接 API 的页。** `PageBlueprintCompiler.compile()` 设 `crud.api=/api/flow/{TABLE}_SEARCH`、列、增删改按钮(`:45-72`);`AiFeatureDraftGenerator` 已串了这条(`:47-52`)。 + +## 4. 真正要新建 vs 复用(端点均已核实) + +**复用(端点/能力都已 live):** + +| 环 | 复用 | +|---|---| +| 建实体+建表 | `POST /api/meta/entity` | +| 标准层页写 | `PUT /api/page/schema/{templateId}/standard`(M3a 单一真相)| +| 设计器存改+门禁 | `/api/page/schema/{templateId}/overlay` + `/validate` + `/components` | +| recipe 列表 | `GET /api/ai/page-recipes` | +| 菜单注册 | `POST /api/admin/menus/create` | +| 微调页面 | DesignerPage(amis-editor) | +| AI 建功能链(①面) | `POST /api/ai/features/auto-develop`(基址 `/api/ai`)| +| CRUD/flow 自动伺服 | 保真层引擎 | + +**真正要新建(4 件):** +1. **建模器 UI(前端,最大块)**:列已有实体 / 建新实体(名/表)+ 字段表(列/类型/显示名/长度/必填/引用其它实体)。包 `POST /api/meta/entity`。最复杂控件 = **引用列(referenceid,外键选其它实体)**。 +2. **「recipe→默认页→落标准层」单步端点(后端,小)**:把 `PageBlueprintCompiler.compile` + `/standard` 写串成人可单步调的端点(现在只埋在 `auto-develop` 里)。属路线图「把 AI pipeline 拆成可单步调」收口的第一块。 +3. **「+ 新建功能」编排薄壳(前端)**:建模器→选 recipe→落页→跳设计器→发布(菜单注册)串起来。 +4. **「⚡ AI 建功能」入口接线(前端 + 少量后端)**:网页触发 `auto-develop`,把 `READY_FOR_HUMAN_REVIEW` 草稿回流到设计器供人审/改/发。 + +## 5. v1 边界(YAGNI) + +- 只建新,**不改已有表**(ALTER/M4 = v2)。 +- recipe 限现有 2 种(维护 CRUD / 树 CRUD)→ **v1 只覆盖简单 CRUD/树类功能**;主子表/审批/组合 = 路线图 M7 扩面后。 +- 设计器 **edit-only** 够用(recipe 预接好页)。 +- **②面 in-app AI employees 不做**(平台内置 LLM = 独立大特性 + 红线扩面,v1 之后立项)。 + +## 6. 守红线(与架构 D3 + memory `eip4-ai-agent-merge-mapping` 一致) + +- 发布**恒人审**。 +- AI 入口产物状态**恒 `READY_FOR_HUMAN_REVIEW`**。 +- 标准层写**恒走 `PageSchemaWriter` 单一真相**(M3a 已收口,不得旁路裸 INSERT)。 +- 平台进程内**不内置生成 LLM**(仅 repair 钩子,默认关)。 + +## 7. 要在 plan 里钉死的 3 个未知 + +1. **建模器引用列(外键)UI**:怎么选其它实体?下拉已有实体列表 + 选目标显示列?这是建模器最复杂的控件,需先定交互。 +2. **recipe 仅 2 种 = v1 能建的功能类型窄**:这是 v1 定位,需跟产品对齐——v1 明确只支持简单 CRUD/树类新功能,复杂功能引导走老路或等 M7。 +3. **发布 online apply 断档**(路线图:线上仍人工跑 SQL):v1「发布」到哪一步算完?**真上线** vs **出部署包人工执行**?决定 ④环的终点与是否需要 env/creds 终验。 + +## 8. 不做 / 推迟 + +- ALTER/改已有表(M4,v2) +- recipe 扩面:主子表/EditGrid/审批/组合 tabs(M7) +- ②面 in-app AI employees / 平台内置 LLM 生成端点 +- 纯 NocoBase「空白页拖组件现绑实体」(需给 amis-editor 造绑定能力,v1 用 recipe 预接好规避) + +--- + +*本文为 brainstorm 定型设计。下一步:新会话跑 `superpowers:writing-plans` 出带文件路径/代码示例/验证步骤的实施计划,§7 三未知在 plan 阶段钉死。* diff --git a/docs/plans/2026-06-20-人走五环建新功能-实施计划.md b/docs/plans/2026-06-20-人走五环建新功能-实施计划.md new file mode 100644 index 0000000..84bc623 --- /dev/null +++ b/docs/plans/2026-06-20-人走五环建新功能-实施计划.md @@ -0,0 +1,5650 @@ +# 人走五环建新功能 · 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/_*` 的 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/
_SEARCH|_ADD|_UPDATE|_DELETE`。⇒ 五流必须被**发布编排显式触发**(第 3 节 Task 11 调 `FlowServiceWithSynthesis.addDefaultFlowService`,幂等)。设计文档「五流由 DefaultFlowHelper 默认生成、多数不用人管」**只在被触发后成立**。 +2. **maintenance recipe 列表 API = `/api/flow/
_SEARCH`(设计文档对、旧 blueprint 契约文档已漂移)。** 当前编译器(`PageBlueprintCompiler.java:50`,commit `1ff0d33`/`5f32050`/`6c60383` house-style 对齐后)maintenance 读走 `/api/flow/
_SEARCH`、写走 `/api/flow/
_ADD|_UPDATE|_DELETE`;tree 读走 `/api/entity/
/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{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 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 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/
/list'` 是引擎遗留返回,**recipe 页不消费它**(recipe 列表走 `/api/flow/
_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 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 resp = newController(jdbc).entities(); + + assertEquals(0, resp.get("status")); + List> data = (List>) 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 entities() { + List> data = jdbcTemplate.query( + "SELECT SYS_ENTITY_ID, TABLENAME, NAME FROM SYS_ENTITY " + + "WHERE ISACTIVE=1 AND ISVIEW=0 ORDER BY TABLENAME", + (rs, i) -> { + Map 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 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) " +``` + +--- + +### 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 attrRow(String col, String display, String refId, + int isKey, int isEntityDisplay) { + Map 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 resp = newController(jdbc, dataDic).attributes("eip4_order"); + + assertEquals(0, resp.get("status")); + Map data = (Map) resp.get("data"); + assertEquals("EIP4_ORDER", data.get("tablename")); + // 无 ISENTITYDISPLAY → 首个非主键非审计的 string 列 = TITLE + assertEquals("TITLE", data.get("displayColumn")); + List> cols = (List>) data.get("columns"); + Map qty = cols.stream().filter(c -> "QTY".equals(c.get("column"))).findFirst().get(); + assertEquals("integer", qty.get("type")); + Map cust = cols.stream().filter(c -> "CUSTOMERID".equals(c.get("column"))).findFirst().get(); + assertEquals("reference", cust.get("type")); + assertEquals("EIP4_CUSTOMER", cust.get("referenceTable")); + Map 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 attributes(@PathVariable String table) { + String t = table.toUpperCase(); + List> 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 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> columns = new ArrayList<>(); + String displayByFlag = null; + String displayByString = null; + String keyColumn = null; + for (Map 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 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 data = new LinkedHashMap<>(); + data.put("tablename", t); + data.put("displayColumn", displayColumn); + data.put("columns", columns); + Map 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) " +``` + +--- + +### 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, , 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 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> attrs = (List>) req.get("attributes"); + if (attrs != null) { + for (Map 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`,在 Task 4 引入并传入 DDL。这里先声明它(在 `created` 列表声明附近,即第95行 `List created = new ArrayList<>();` 下面加一行 —— 实际加入放在 Task 4 实现,本 Task 的代码块假定它已存在;为让本 Task 单独编译,先在第95行下临时加:`Map 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) " +``` + +--- + +### Task 4 — 修 DDL 外键:把 `REFERENCES ` 改成 `REFERENCES ` + +**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 attrs, Map refTargets) { + if (attrs == null || attrs.isEmpty()) { + throw new IllegalStateException("实体属性为空,无法建表: " + table); + } + Map 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 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) " +``` + +--- + +### 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 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) " +``` + +--- + +> **本节产出供后续节使用的契约**(务必照搬名字/形状): +> - `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:'',display?,mandatory?}`;响应结构不变。 +> - Java:`MetaController.createTableDdl(String,List,Map)`、`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/
_SEARCH"`;对 `tree-crud-v1` 产出 `body.api.url == "/api/entity/
/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)`,为引用列注入 `_DISPLAY__` 显名(house-style,见 `PickerController` L234-268)。因此引用列只需把 amis 列 `name` 指向 `_DISPLAY__`,无需新组件类型,`TypedPageSchemaValidator` 平凡通过。 +> - `requireAdmin()` / `currentUserId()` 的实现见 `PageSchemaController` L515-540,本节控制器**逐字复制**该模式。 +> - 测试命令:`JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-metadata -am test -Dtest=`。 + +可参考技能:@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/
_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/
_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}。 + * + *

人工单步端点(DesignFeatureController)与未来 AI 路径共用同一装配口径(DRY),UI/UE 规则集中在 + * recipe/compiler 而非散落在调用方。本类不写库、不校验白名单(严格 typed 闸在端点层),只负责装配+编译。 + * + *

装配口径镜像 {@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 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 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 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) " +``` + +--- + +### 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> resp = controller(writer, reader).compile(body); + + assertEquals(200, resp.getStatusCode().value()); + @SuppressWarnings("unchecked") + Map data = (Map) 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 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> 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 部分。 + * + *

第 1 节若已提供属性服务 bean,可直接实现本接口或被本默认实现替换;契约不变。 + * 引用列 type=="reference" 且 referenceTable 非空,由第 1 节 createEntity 写入的 SYS_REFERENCE 行驱动。 + */ +public interface EntityAttributeReader { + + EntityAttributes read(String tableName); + + record EntityAttributes(String tablename, String displayColumn, List 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 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(用 `

_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)。 + * + *

{@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> 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 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 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 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 ok(String msg, Map data) { + Map r = new LinkedHashMap<>(); + r.put("status", 0); + r.put("msg", msg); + if (data != null) r.put("data", data); + return r; + } + + private static Map fail(String msg) { + return fail(msg, null); + } + + private static Map fail(String msg, Map data) { + Map 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) " +``` + +--- + +### Task 8 · 编译器引用列渲染:`reference` 字段渲染显名而非裸 id + +`PageBlueprintCompiler.applyColumnRender` 当前只认 `boolean/date/datetime`。扩展为:当字段 type 为 `reference` 时,列 `name` 指向 `

_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 — 写失败测试(引用列渲染显名列 `_DISPLAY__`)** + +在 `PageBlueprintCompilerTest.java` 末尾(最后一个 `}` 之前)追加: + +```java + @Test + @DisplayName("引用列渲染显名: list 列 name 指向 _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: but was: `(当前列 `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 改指 _DISPLAY__(运行时 _SEARCH 流 + // 经 UserColumnResolver.resolveRows 注入显名)。此处保持纯文本渲染即可, + // 不引入新 amis 组件类型 → TypedPageSchemaValidator 白名单平凡通过。 + } +``` + +在类内(紧邻 `applyColumnRender` 之后)新增私有方法 `listColumnName`: + +```java + /** + * 列表列 name 解析:引用列改指 {@code _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 指向 _DISPLAY__(运行时 _SEARCH 注入,白名单安全) + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +### 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 含引用列的页 → 列显名 `_DISPLAY__`)** + +在 `RecipePageComposerTest.java` 末尾(最后一个 `}` 之前)追加: + +```java + @Test + @DisplayName("4. 端到端: compose 含 reference 列的页 → list 列 name 显名 _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 " -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/` 返回该 amis 页,引用列 `name` 为 `_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 列→编译显名 _DISPLAY__ + +Co-Authored-By: Claude Opus 4.8 (1M context) " +``` + +--- + +> 本节产出供第 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 · 发布前人工确认)。 + * + *

flowName 与 {@link com.dsasp.server.core.service.flow.model.DefaultFlowHelper} + * 的 Flow id 完全一致({@code

_ADD} 等),在 SYS_SERVICEFLOW 中即主键 sys_serviceflow_id。 + * + * + * + *

不引入保真层重型 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 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 synthesizedFlows(String entityId, String tableName) { + List 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 persistedFlows(String entityId) { + List> rows = jdbcTemplate.queryForList( + "SELECT TRIM(sys_serviceflow_id) AS fid, displayname FROM SYS_SERVICEFLOW WHERE entityid=?" + + " ORDER BY sys_serviceflow_id", entityId); + List out = new ArrayList<>(); + for (Map 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 flows(@org.springframework.web.bind.annotation.RequestParam("entityId") String entityId) { + requireAdmin(); + DefaultFlowPreviewService.FlowsPreview p = flowPreviewService.preview(entityId); + java.util.List> flowList = new java.util.ArrayList<>(); + for (DefaultFlowPreviewService.FlowItem f : p.flows()) { + Map m = new java.util.LinkedHashMap<>(); + m.put("flowName", f.flowName()); + m.put("displayName", f.displayName()); + m.put("kind", f.kind()); + flowList.add(m); + } + Map 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 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) " +``` + +--- + +### 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 部署包。 + * + *

红线:本类只 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 publish(@org.springframework.web.bind.annotation.RequestBody Map 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 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 resp = new java.util.LinkedHashMap<>(); + resp.put("status", 0); + resp.put("data", data); + return resp; + } + + private String requireDesignString(Map 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 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 flowNames(String entityId) { +> java.util.List 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) " +``` + +--- + +### 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 · 发布编排)。 + * + *

镜像 {@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 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 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 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 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 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) " +``` + +--- + +### 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)。 + * + *

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

不依赖 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 flows) { + } + + public DeploymentPackage build(Input in) { + long now = System.currentTimeMillis(); + + Map 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 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 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 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 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 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 flowsForPkg = (java.util.List) data.get("flows"); + DeploymentPackage pkg = publishOrchestrator.buildDeploymentPackage( + entityId, tableName, templateId, menuName, menuId, flowsForPkg, generatePkg); + if (pkg != null) { + Map 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=' -H "Authorization: Bearer " +# 发布 +curl -s -X POST 'http://localhost:8093/api/design/publish' -H "Authorization: Bearer " \ + -H 'Content-Type: application/json' \ + -d '{"entityId":"","tableName":"

","templateId":"","menuName":"演示功能"}' +``` +预期:`flows` 含 `
_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) " +``` + +--- + +**本节交付物汇总**:`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 -- `(`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 { + status: number; + data: T; +} + +/** POST /api/meta/entity —— 建表(标准列由后端自动追加)。 */ +export async function createEntity(body: CreateEntityBody): Promise { + const resp = await http.post>('/api/meta/entity', body); + return resp.data.data; +} + +/** GET /api/meta/entities —— 实体目录(供引用列选择器)。 */ +export async function listEntities(): Promise { + const resp = await http.get>('/api/meta/entities'); + return resp.data.data; +} + +/** GET /api/meta/entity/{table}/attributes —— 某表的列定义(含 displayColumn)。 */ +export async function listEntityColumns(table: string): Promise { + const resp = await http.get>(`/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 { status: number; data: T; } + +/** POST /api/design/recipe/compile —— 服务端建蓝图→编译→校验→PageSchemaWriter.upsertStandard。 */ +export async function compileRecipe(body: CompileRecipeBody): Promise { + const resp = await http.post>('/api/design/recipe/compile', body); + return resp.data.data; +} + +/** GET /api/ai/page-recipes —— recipe 目录(下拉用)。 */ +export async function listRecipes(): Promise { + const resp = await http.get>('/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 { status: number; data: T; } + +/** POST /api/design/publish。 */ +export async function publishFeature(body: PublishFeatureBody): Promise { + const resp = await http.post>('/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) " +``` + +--- + +### 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 + ``,第 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(); + expect(screen.getByText(/仅管理员可用/)).toBeInTheDocument(); + }); + + it('管理员加载并展示已有实体', async () => { + render(); + await waitFor(() => expect(screen.getByText('OA_DEMO')).toBeInTheDocument()); + expect(mList).toHaveBeenCalled(); + }); + + it('点新建实体打开 Dialog,非法表名禁用提交', async () => { + render(); + 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([]); + 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([]); + 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
建模器仅管理员可用。
; + } + + 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 ( +
+
+
+

建模器

+
+ 新建实体(建表)。v1 只建新不改表 · 标准列由后端自动追加 +
+
+
+ +
+ + {loading ? ( +
加载中…
+ ) : error ? ( +
实体加载失败:{error}
+ ) : entities.length === 0 ? ( +
尚无实体,点「新建实体」开始
+ ) : ( +
+
+ + + + + + + + + {entities.map((e) => ( + + + + + + ))} + +
表名显示名实体ID
{e.tablename}{e.name}{e.entityId}
+ + )} + + {open ? ( + setOpen(false)} + foot={ + <> + + + + } + > +
+ + + + + + {submitErr ?
{submitErr}
: null} +
+
+ ) : null} + + ); +} +``` + +> 注:本文件 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> }) { + return null; +} +``` + +**Step 15.4 — 接路由** + +在 `src/App.tsx`: +- 第 10 行 `import { DesignCenterPage } from './pages/DesignCenterPage';` 之后加: + ```tsx + import { ModelerPage } from './pages/ModelerPage'; + ``` +- 第 42 行 `} />` 之后加: + ```tsx + {/* 建模器(五环第①环·元数据→表,仅管理员)*/} + } /> + ``` + +**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) " +``` + +--- + +### Task 16 — 字段表 + 加字段 Dialog + UI 类型→api 类型映射(buildAttribute) + +用纯 HTML `` 渲染字段行 `{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([]); + return ( +
+ +
{rows.length}
+
+ ); +} + +describe('FieldTable 交互', () => { + beforeEach(() => { /* no-op */ }); + + it('加字段:填列名/显示名/选类型→提交→出现在表里', () => { + render(); + 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(); + 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
(本仓无可复用表格组件)+ 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 = { + 文本: '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>; +} + +export function FieldTable({ rows, onChange }: FieldTableProps) { + const [adding, setAdding] = useState(false); + // 加字段草稿 + const [column, setColumn] = useState(''); + const [display, setDisplay] = useState(''); + const [type, setType] = useState('文本'); + 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 ( +
+
+ 字段(标准列由后端自动追加,无需在此添加 ID/创建人等) + +
+
+ + + + + + + + + + {rows.length === 0 ? ( + + ) : ( + rows.map((r, i) => ( + + + + + + + + )) + )} + +
列名显示名类型必填 +
尚无字段
{r.column}{r.display} + {r.type}{r.type === '引用' && r.referenceTable ? `→${r.referenceTable}` : ''} + {r.mandatory ? '是' : ''} + removeRow(i)}>删除 +
+ + {adding ? ( + setAdding(false)} + foot={ + <> + + + + } + > +
+ + + + {type === '文本' ? ( + + ) : null} + {type === '引用' ? ( + + ) : null} + +
+
+ ) : null} + + ); +} +``` + +同时创建最小 `src/pages/ReferencePicker.tsx`(占位;Task 17 用 TDD 替换): + +```tsx +// 占位(Task 17 实现引用列选择器)。 +export function ReferencePicker(props: { value: string; onChange: (t: string) => void }) { + return ( + 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) " +``` + +--- + +### Task 17 — 引用列选择器(目标实体 + 显示列) + +替换占位 `ReferencePicker`:type=引用时,目标实体 ``(选中目标后 `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( {}} />); + 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(); + 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([]); + const [cols, setCols] = useState([]); + 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 ( +
+ + {value ? ( + + ) : null} + {err ?
{err}
: null} +
+ ); +} +``` + +**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) " +``` + +--- + +**第 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/.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( + + + , + ); +} + +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 行的 `
` 替换为以下三段(弹簧 + 两按钮): + +```tsx +
+ + +``` + +> 非 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) " +``` + +--- + +### 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( + + + , + ); +} + +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('entity'); + const [entities, setEntities] = useState([]); + const [loadErr, setLoadErr] = useState(''); + const [selectedEntity, setSelectedEntity] = useState(null); + + const [recipe, setRecipe] = useState(RECIPES[0]?.id ?? 'maintenance-crud-v1'); + const [title, setTitle] = useState(''); + const [displayField, setDisplayField] = useState(''); + const [pageSize, setPageSize] = useState(''); + + 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
新建功能仅管理员可用。
; + } + + 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 ( +
+
+ +

新建功能 · 人走五环

+
+ + {/* 步骤指示 */} +
+ {step === 'entity' ? '步骤 1 / 2 :选择实体(元数据+表)' : '步骤 2 / 2 :选 recipe、生成页面、发布'} +
+ + {loadErr ?
实体加载失败:{loadErr}
: null} + + {step === 'entity' ? ( +
+
选择已有实体
+ + + + + + + + + {entities.map((en) => ( + + + + + + ))} + +
名称表名 +
{en.name}{en.tablename} + +
+
+ +
+
+ ) : ( +
+
+ 实体:{selectedEntity?.name}{' '} + ({selectedEntity?.tablename}){' '} + setStep('entity')}>更换 +
+ +
+
页面模板 recipe
+ {RECIPES.map((r) => ( + + ))} +
+ +
+ + + +
+ +
+ + +
+ + {templateId ? ( +
+
+ 已生成模板:{templateId} +
+
+ + +
+
+ 发布 = 写标准页 + 触发 5 条默认流 + 注册菜单(当前后端立即可用);并生成生产部署包供人审上线。 +
+
+ ) : null} +
+ )} +
+ ); +} +``` + +**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) " +``` + +--- + +### 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 { + // 透传 baseUrl=当前前端 origin,让后端回调经 vite 代理打到正在跑的 8093(而非死的 8084)。 + const payload: AiAutoDevelopBody = { + baseUrl: window.location.origin, + generateDeploymentPackage: true, + ...body, + }; + const { data } = await http.post('/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(); + return { ...actual, autoDevelop: (...a: unknown[]) => autoDevelop(...a) }; +}); + +function renderForm() { + return render( + + + , + ); +} + +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([{ column: '', label: '', type: 'string' }]); + + const [running, setRunning] = useState(false); + const [run, setRun] = useState(null); + + if (!isAdmin) { + return
AI 建功能仅管理员可用。
; + } + + const reviewTemplateId = run && run.status === READY_STATUS ? extractPageSchemaTemplateId(run) : undefined; + + function setField(i: number, patch: Partial) { + 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 ( +
+
+ +

⚡ AI 建功能

+
+
+ 外部 AI agent 起草,产物恒人审;点「审阅草稿」进设计器,平台不自动发布。 +
+ +
+
+