# 变更规格：app-entry-page-form-unification
> status: done

## 背景

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

## 目标

建立统一主链路：

```text
访问入口 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 闭环）。