Page Schema Authoring

适用范围：Legacy Admin Kit / Schema 与旧 admin-vue。新 admin-nuxtui 的开发入口见管理端 Nuxt UI 指南。

Yoyo Page Schema 是管理页面意图的唯一人工 authoring source。使用 defineYoyoQueryPage 编写短、类型化的 schema.ts，再由 compileYoyoPageSchema 产生 normalized YoyoPageIR；IR、fixture、manifest、文档和 runtime snapshot 都不能反向成为第二份可编辑 Schema。

三种 page kind

• query：只读查询工作台。
• crud：标准 CRUD，不允许 extension，使用 runtime 默认 Editor Task。
• crud-ex：至少一个已登记 typed extension，适合明确的复杂编辑或 row overlay。

作者语义

query

声明 datasource reference、查询字段、pageSize、allowed URL params 与可选 default sort。URL、query key、请求 DTO 与 transport adapter 不进入 Schema。

table

声明 rowKey、column title、renderer key、sortable、role、priority 与 mobile placement。Renderer 必须存在于 registry；不要写任意 component path。

form

声明字段 kind、label、help、required 与 lifecycle。editableOn、create/edit default 表达 UI 生命周期，不复制后端 validation。字段缺失的 create/update mode 应修 generated validation owner。

只用于页面核对的字段仍放在同一个表单中。例如确认密码声明 lifecycle: { editableOn: 'create', submitOnCreate: false }，创建时可输入并参与 dirty/关闭保护，但不发送到后端。独立应用的角色选择可以声明 submitOnEdit: false，避免普通资料保存夹带角色变更。未声明开关时保持原有行为；只读字段的 submitOnEdit: true 仍用于回传服务端基线。提交字段仍须完整、精确对应生成合同，不能用这些开关绕开必填 API 字段。

扩展编辑器通过已有 commands.setValues / setFieldError 更新同一表单。独立关联保存后可以调用 reloadEditor({ preserveValues })，回读最新版本，只恢复显式指定且可编辑的未提交字段；不要把已提交关联、未编辑的旧资料、Id 或并发版本放进保留值。实际接入见用户模块 DataRoleEditor.vue。

actions 与 confirmation

声明稳定 action kind、placement、contract key 或 row overlay reference。Confirmation 只表达 intent 与 subject fields，不在 Schema 中嵌入 mutation 实现或权限结果。

presentation

页面标题、信息层级、mobile projection 与业务文案是作者选择。CLI 只能生成中性 skeleton，不能从字段名猜这些决定。

Fail-closed 边界

Compiler 必须拒绝未知 field/renderer/action/extension/datasource、slot 不匹配、非法 crud-ex、缺失 ActionContract/validation linkage。阻断诊断不能被局部 fallback 或隐式升级绕过。

Schema 不得包含：

• 裸 URL、DTO copy、generated hook 或 query key；
• grant boolean、Feature/Setting/session 当前值；
• 任意函数脚本、eval、组件文件路径；
• feature-local 新 keyword 或 legacy DynamicView JSON。

Public contract 位于 packages/yoyo-admin/admin-schema/src/index.ts，详细语义由该包和 canonical admin-schema-boundaries spec 拥有。