forge_admin/code-copilot/changes/archive/2026-06-27-app-entry-page-form-unification/spec.md

变更规格：app-entry-page-form-unification

status: done

背景

应用中心当前同时存在访问入口、业务对象、表单设计、列表设计和运行态发布能力。近期列表设计器已经支持多页面画布，表单设计器前端也支持多个表单资产，但整体协议仍以单表单 formDesignerSchema 为主，访问入口也没有显式绑定 pageKey/formKey，导致用户无法清晰理解“入口、对象、页面、表单”的边界。

目标

建立统一主链路：

访问入口 AppEntry
  -> 业务对象 BusinessObject
  -> 页面 pageKey
  -> 表单 formKey

本变更覆盖：

• 多表单协议标准化：formDesignerSchema.forms[] + defaultFormKey，兼容旧单表单结构。
• 表单设计器语义统一：区分“当前对象主表单”和“关联对象表单”，避免和业务对象设计混淆。
• 访问入口配置增强：入口可选择业务对象、目标页面、目标表单和默认参数。
• 列表页面动作增强：按钮、行操作、页面跳转支持 targetFormKey。
• 发布检查增强：检查入口/按钮引用的目标页面、目标表单是否存在。
• 运行态承接：入口和页面动作能把 pageKey/formKey 传递到运行页。

非目标

• 不新增独立业务对象类型来代表表单。
• 不把每个表单强制发布为单独入口。
• 不重写整个运行页，只补齐现有运行态对 pageKey/formKey 的识别和透传。
• 不在本轮改动资金、状态机或真实权限策略。

设计原则

• 访问入口解决“从哪里进来”。
• 业务对象解决“操作哪类数据”。
• 页面解决“展示哪个页面布局”。
• 表单解决“使用哪套填写/展示结构”。
• 旧数据必须兼容：没有 forms[] 的旧 formDesignerSchema 自动视为默认表单。

阶段划分

1. 协议层：前后端 DTO 和前端 schema 工具统一多表单结构。
2. 设计器层：表单设计 UI 和列表动作配置补齐 formKey。
3. 入口层：访问入口配置选择对象、页面、表单。
4. 运行层：打开入口、页面跳转、按钮动作透传 pageKey/formKey。
5. 发布检查：阻断失效页面、失效表单、无动作按钮等问题。

本轮已覆盖

• formDesignerSchema 升级为兼容多表单结构，新增 forms[] 和 defaultFormKey，旧单表单结构会自动包装为默认表单。
• 后端 FormDesignerSchemaDTO 增加 defaultFormKey/forms，运行态配置会携带完整表单 schema。
• 访问入口配置支持选择目标页面、目标表单和默认参数，并在打开运行态时转为 pageKey/formKey/defaultParams 查询参数。
• 访问入口配置补齐入口类型、入口权限码和结构化默认参数，运行态会把 URL 公共参数带入列表查询，把表单默认值带入新增/编辑表单。
• 表单设计器文案避免继续使用“设计对象”，改为主表单/关联表单语义。
• 表单设计器支持多表单资产的新增、复制、删除、重命名、用途维护和默认表单设置。
• 表单设计器补齐表单治理配置：表单权限、字段覆盖规则、表单事件。运行态已应用字段隐藏、必填、只读、默认值；请求型表单事件已接入打开表单前、提交前、提交成功后。
• 列表设计器的按钮、行操作、页面跳转配置支持目标表单，发布和运行态会透传 targetFormKey。
• 按钮组件补齐主点击动作、权限码、二次确认和成功后行为，写入统一事件协议；普通画布按钮运行态已支持跳转、请求、确认提示和成功后行为。
• 按钮和行操作的参数映射支持固定值、当前行字段、路由参数、系统变量，运行态和后端构建器保留并解析 sourceType/sourceField。
• 列表设计器补齐桌面、窄屏、弹窗、抽屉、移动预览预设，复用现有画布宽度和缩放能力。
• 发布检查补齐入口、按钮、布局跳转中的页面和表单引用校验，并检查入口类型/权限、无动作按钮、动作目标、请求地址、敏感参数、表单治理配置和动作参数映射。
• 草稿/发布版本隔离已收口：设计保存仍更新草稿模型和页面，运行态 /ai/crud-config/render/{configKey} 对低代码已发布配置会读取 publishedVersion 对应的 ai_crud_config_version 快照字段，避免未发布表单或列表设计影响线上入口。
• 真实预览从单开关升级为模式化预览：模拟数据、真实列表、新增表单、编辑表单、详情状态，支持预览记录 ID、请求状态、成功/失败信息和最后错误；发布检查会阻断最后一次真实接口预览失败的页面。
• 按钮配置继续产品化：自定义按钮和普通画布按钮支持显示条件，运行态按当前用户权限集合过滤 permissionCode，条件表达式采用安全的 field=value / field!=value / field in A,B 子集，不执行任意脚本。
• 表单事件补齐安全执行边界：请求型事件支持结果回填；自定义脚本只允许白名单函数 noop、fillCurrentDate、fillCurrentTime，发布检查会阻断未登记脚本。

后续待办

• 参数映射继续产品化：入口参数和表单事件结果回填后续可抽成同一套映射编辑器；本轮已打通运行协议，暂未做 UI 组件级复用。
• 浏览器实机验证：本轮完成构建/编译/静态检查，未启动本地后端和浏览器做真实点击链路验证。

归档记录（HARD-GATE）

• 状态：done
• 归档时间：2026-06-27
• 归档人：yaomd（批量归档）
• 归档路径：code-copilot/changes/archive/2026-06-27-app-entry-page-form-unification/
• 判定依据：任务清单全部完成，execution-log 验证通过（编译/构建/lint 闭环）。