create-yss-spec 3.0.0 → 3.1.0

package/template/.hermes/skills/formily-foundation/SKILL.md

@@ -1,176 +0,0 @@
----
-name: formily-foundation
-description: 指导 YFormily 基础表单开发；当创建或修复普通单页表单、字段校验、提交链路、查询表单布局、scope 表达式或导入边界时使用。
----
-
-# Formily Foundation Skill
-
-## 触发条件
-
-- 创建或改造 `YFormily` 基础表单（字段、校验、提交）。
-- 修复表单导入路径、schema 层级、提交不触发等问题。
-- 实现普通单页表单，不含复杂联动或详情插槽。
-
-## 不适用场景
-
-- 复杂联动、副作用、跨字段逻辑：使用 `../formily-linkage-effects/SKILL.md`。
-- 查看态 detail 插槽和 mode 切换：使用 `../formily-mode-slot-detail/SKILL.md`。
-- 分步表单：使用 `../formily-step-flow/SKILL.md`。
-
-## 文档检索
-
-1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的基础 Props、Methods 与 Schema 边界；实现字段布局、提交或校验失败时，再用 `get_demo` 获取 `formily/basic`、`formily/grid`、`formily/submit-failed` 等官方 Demo。
-2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
-
-## 硬约束（禁止/必须）
-
-- 业务生成代码统一从 `@yss-ui/components` 导入 `YFormily` 与 `ISchema`；`YssFormily` 仅作为历史兼容别名说明。
-- 禁止业务层导入 `@formily/antdv`、`@formily/antd*` UI 组件。
-- 必须使用三层结构：`FormLayout -> FormGrid -> 字段`，禁止字段直接挂在根节点或单独以 `FormGrid` 作为顶层布局。
-- `Submit` 必须传 `onSubmit`，否则不触发表单提交。
-- 标准业务列表/CRUD 查询区默认让 `YFormily` 只渲染字段；查询/重置按钮用外部 `YButton` 放在 `.xxx__search-actions`，由 hook 的 `handleSearch/handleReset` 控制分页重置和请求。
-- `AutoButtonGroup -> Submit/Reset` 仅用于纯 Formily 表单提交，不作为业务列表查询区默认方案。
-- 查询区禁止横向放“表单 + 按钮”后用大 `gap`、`align-items: flex-start` 或 `padding-top` 硬调位置；字段换行时按钮必须在搜索卡片右下角。
-- 横向表单必须显式设置 `FormLayout` 的 `labelWidth` 和 `labelAlign: 'right'`，抽屉/弹窗场景尤其不能让 label 宽度自适应。
-- `FormGrid` 默认保持响应式：`minColumns: 1`，通过 `maxColumns` 和 `minWidth` 控制宽屏列数；不要写 `minColumns: maxColumns` 固定列数，除非用户明确要求不响应式。
-- 查询表单常用 `labelWidth: 100~120`、`FormGrid { maxColumns: 3 或 4, minColumns: 1, minWidth: 260~360 }`，按钮行在表单外部右下角；抽屉/弹窗编辑表单常用 `labelWidth: 140`、`FormGrid { maxColumns: 2, minColumns: 1, minWidth: 320~360 }`。
-- 备注、说明等长字段必须用 `x-decorator-props.gridSpan` 占满整行，例如两列布局用 `gridSpan: 2`。
-- 下拉选择器（`Select`, `TreeSelect`, `Radio.Group` 等）异步数据源必须通过 `enum` 或 `x-reactions` / `field.dataSource` 注入，严禁写入 `x-component-props.options`（会导致 Formily 首次挂载空数组且后续不更新，产生首次打开弹窗显示“暂无数据”的 Bug）。
-- 事件表达式必须字符串化（`'{{ ... }}'`），并按组件语义使用事件名。
-- 只使用源码已公开的 Props 和实例方法；当前没有 `show-button-group`、`detail-as`、`validate`、`reset`、`clearValidate` 等 YFormily API。
-- Orval API 的网络错误及 `success === false` 业务错误已由 `mutator.ts` 统一 `message.error` 并 reject；提交 hook 禁止在 `else` 或 `catch` 中重复提示。
-- 客户端校验提示使用 `onFormSubmitValidateFailed`；禁止在 `onFormSubmitFailed` 或 `Submit.onSubmitFailed` 中调用 `message.error`，它们也会捕获 `onSubmit` 内的 API reject。
-- **Formily 表单校验规则（x-validator）防坑规范**：
-  - 必填文本字段必须声明 `whitespace: true`，即 `{ required: true, whitespace: true, message: '请输入xxx' }`，防止输入纯空格绕过前端校验。
-  - 自定义长度、格式和跨字段校验不得重复承担必填职责；函数式校验必须在空值时返回通过（如 `validator: (val) => { const str = (val || '').trim(); if (!str) return true; return validateContentLength(val) || true; }`），空值统一交由 `required` 报错，非空时才校验具体规则。
-  - 当前 YFormily 的 FormItem 适配层会在运行时归一化反馈：空值优先显示必填提示，非空值移除残留必填提示，多条相关消息只拼接一次。该兜底不替代正确的 Schema 校验职责拆分。
-- 分步需求默认走 `formily-step-flow`，不在本 skill 内给 `FormStep` 方案。
-
-## 标准代码骨架
-
-```vue
-<script setup lang="ts">
-import { YFormily, type ISchema } from '@yss-ui/components';
-
-/** 表单保存回调 Props。 */
-interface SaveFormProps {
-  onSave: (values: Record<string, any>) => Promise<void>;
-}
-
-/** 表单保存回调。 */
-const props = defineProps<SaveFormProps>();
-
-/** 校验通过后提交表单数据。 */
-const onSubmit = (values: Record<string, any>) => {
-  return props.onSave(values);
-};
-
-/** 基础表单 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
-          properties: {
-            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true },
-            submit: {
-              type: 'void',
-              'x-component': 'Submit',
-              'x-content': '提交',
-              'x-component-props': { onSubmit: '{{ onSubmit }}' },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :scope="{ onSubmit }" />
-</template>
-```
-
-## 业务查询区布局
-
-```vue
-<template>
-  <YCard class="demo-page__search-card" :padding="16">
-    <div class="demo-page__search-content">
-      <div class="demo-page__search-form">
-        <YFormily v-model="queryModel" :schema="searchSchema" />
-      </div>
-      <div class="demo-page__search-actions">
-        <YButton type="primary" @click="handleSearch">查询</YButton>
-        <YButton @click="handleReset">重置</YButton>
-      </div>
-    </div>
-  </YCard>
-</template>
-```
-
-```less
-.demo-page {
-  &__search-content {
-    display: flex;
-    flex-direction: column;
-    align-items: stretch;
-    gap: 16px;
-  }
-
-  &__search-form {
-    width: 100%;
-    min-width: 0;
-
-    :deep(.ant-formily-form-item) {
-      margin-bottom: 0;
-    }
-
-    :deep(.ant-formily-form-grid) {
-      width: 100%;
-    }
-  }
-
-  &__search-actions {
-    display: flex;
-    width: 100%;
-    flex: 0 0 auto;
-    align-items: center;
-    justify-content: flex-end;
-    gap: 12px;
-  }
-}
-```
-
-## 交付检查清单
-
-- [ ] 导入来源和组件边界正确。
-- [ ] schema 三层结构完整。
-- [ ] 横向表单有固定 `labelWidth` 且 label 右对齐。
-- [ ] `FormGrid` 使用响应式列配置，未把 `minColumns` 固定成宽屏列数。
-- [ ] `Submit` 提交链路可用，校验可触发。
-- [ ] 只使用公开 Props/实例方法，未出现 `show-button-group`、`detail-as` 等旧式或虚构 API。
-- [ ] 业务列表查询/重置按钮在外部 `.xxx__search-actions`，按钮行独占下一行并右对齐；缩窄后不会贴在第一行字段旁。
-- [ ] label 宽度和右对齐已显式配置。
-- [ ] 包含可运行 `initial-values` 或 `v-model` 示例。
-- [ ] 未出现 `@formily/antdv` 业务层导入。
-- [ ] API 失败仅由 `mutator.ts` 统一提示，业务 `else`/`catch` 未重复 `message.error`。
-
-## 失败兜底策略
-
-- 若提交不触发：先检查 `Submit.x-component-props.onSubmit`。
-- 若字段不显示：先核对 `FormLayout/FormGrid/properties` 层级。
-- 若 API 调用 reject：只恢复 loading 或回滚局部状态，不重复弹出错误提示。
-- 若需求升级为联动/模式/分步：立即切换对应 skill，不在本 skill 内硬扩展。
-
-## 参考
-
-- 完整示例：`./references/examples.md`

package/template/.hermes/skills/formily-foundation/references/examples.md

@@ -1,486 +0,0 @@
-# YFormily 代码示例库
-
-本参考只保留可直接复用且已与当前源码核对的模式。基础 Props、实例方法与详情配置以最新 `llms-full.txt` 和 `packages/components/src/formily` 为准；不要从旧 demo 推断未公开 API。
-
-## 目录
-
-1. [基础表单与提交](#1-基础表单与提交)
-2. [表达式显隐与禁用](#2-表达式显隐与禁用)
-3. [x-reactions 级联选项](#3-x-reactions-级联选项)
-4. [新增编辑查看与双通道插槽](#4-新增编辑查看与双通道插槽)
-5. [Schema Slot 自定义字段](#5-schema-slot-自定义字段)
-6. [分步表单路由](#6-分步表单路由)
-7. [动态 Schema 与动态插槽](#7-动态-schema-与动态插槽)
-8. [Orval 提交与错误处理](#8-orval-提交与错误处理)
-
-## 1. 基础表单与提交
-
-`Submit` 必须通过表达式拿到 `onSubmit`。业务列表查询区不使用 schema 内按钮组，查询/重置按钮应放到外部操作区。
-
-```vue
-<script setup lang="ts">
-import { YFormily, type ISchema } from '@yss-ui/components';
-
-/** 表单提交事件。 */
-const emit = defineEmits<{ submit: [values: Record<string, any>] }>();
-
-/** 校验通过后向上层提交。 */
-const onSubmit = (values: Record<string, any>) => {
-  emit('submit', values);
-};
-
-/** 纯 Formily 表单 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
-          properties: {
-            name: {
-              type: 'string',
-              title: '姓名',
-              required: true,
-              'x-decorator': 'FormItem',
-              'x-component': 'Input',
-              'x-component-props': { placeholder: '请输入姓名', allowClear: true },
-              'x-validator': [
-                { required: true, whitespace: true, message: '请输入姓名' },
-                {
-                  validator: (value: string) => {
-                    const str = (value || '').trim();
-                    if (!str) return true;
-                    if (str.length < 2 || str.length > 50) return '姓名长度需在2到50之间';
-                    return true;
-                  },
-                },
-              ],
-            },
-            gender: {
-              type: 'string',
-              title: '性别',
-              enum: [
-                { label: '男', value: 'male' },
-                { label: '女', value: 'female' },
-              ],
-              'x-decorator': 'FormItem',
-              'x-component': 'Select',
-            },
-            actions: {
-              type: 'void',
-              'x-decorator': 'FormItem',
-              'x-decorator-props': { gridSpan: 2, colon: false },
-              'x-component': 'AutoButtonGroup',
-              properties: {
-                reset: { type: 'void', 'x-component': 'Reset', 'x-content': '重置' },
-                submit: {
-                  type: 'void',
-                  'x-component': 'Submit',
-                  'x-content': '提交',
-                  'x-component-props': { onSubmit: '{{ onSubmit }}' },
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :scope="{ onSubmit }" :initial-values="{ gender: 'male' }" />
-</template>
-```
-
-## 2. 表达式显隐与禁用
-
-只依赖 `$values` 的显隐和禁用直接写表达式，初始化和后续变更都会生效，不要为此创建 `effects`。
-
-```vue
-<script setup lang="ts">
-import { YFormily, type ISchema } from '@yss-ui/components';
-
-/** 简单表达式联动 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
-          properties: {
-            needCompany: {
-              type: 'boolean',
-              title: '是否任职',
-              'x-decorator': 'FormItem',
-              'x-component': 'Switch',
-            },
-            companyName: {
-              type: 'string',
-              title: '公司名称',
-              required: true,
-              'x-decorator': 'FormItem',
-              'x-component': 'Input',
-              'x-visible': '{{ $values.needCompany === true }}',
-            },
-            systemCode: {
-              type: 'string',
-              title: '系统编码',
-              'x-decorator': 'FormItem',
-              'x-component': 'Input',
-              'x-disabled': '{{ $values.needCompany === false }}',
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :initial-values="{ needCompany: false }" />
-</template>
-```
-
-## 3. x-reactions 级联选项
-
-级联项更新时，仅当旧值不在新选项中才清空。无条件 `field.value = undefined` 会破坏合法回填值。
-
-```vue
-<script setup lang="ts">
-import { YFormily, type Field, type ISchema } from '@yss-ui/components';
-
-/** 城市选项。 */
-interface CityOption {
-  label: string;
-  value: string;
-}
-
-/** 省份到城市的静态映射。 */
-const cityMap: Record<string, CityOption[]> = {
-  zhejiang: [{ label: '杭州', value: 'hangzhou' }],
-  jiangsu: [{ label: '南京', value: 'nanjing' }],
-};
-
-/** 基于省份同步当前城市字段。 */
-const syncCityReaction = (field: Field) => {
-  const province = field.query('province').get('value') as string | undefined;
-  const options = province ? cityMap[province] ?? [] : [];
-  field.dataSource = options;
-  if (!options.some(item => item.value === field.value)) field.value = undefined;
-};
-
-/** 级联选择 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
-          properties: {
-            province: {
-              type: 'string',
-              title: '省份',
-              enum: [
-                { label: '浙江', value: 'zhejiang' },
-                { label: '江苏', value: 'jiangsu' },
-              ],
-              'x-decorator': 'FormItem',
-              'x-component': 'Select',
-            },
-            city: {
-              type: 'string',
-              title: '城市',
-              'x-decorator': 'FormItem',
-              'x-component': 'Select',
-              'x-reactions': syncCityReaction,
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :initial-values="{ province: 'zhejiang', city: 'hangzhou' }" />
-</template>
-```
-
-需要首屏与变更都执行的表单级副作用时，读取 `../../formily-linkage-effects/SKILL.md`，成对使用 `onFieldInit` 与 `onFieldValueChange`。
-
-## 4. 新增编辑查看与双通道插槽
-
-`mode=2` 直接进入 Descriptions；不存在 `detail-as` 开关。默认响应式详情用 `maxColumns/minColumns/minWidth`，`columns` 只在 `responsive: false` 时生效。
-
-```vue
-<script setup lang="ts">
-import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
-import { ref } from 'vue';
-
-/** 表单模式。 */
-type FormMode = 0 | 1 | 2;
-
-/** 当前模式。 */
-const mode = ref<FormMode>(1);
-/** 编辑与查看回填值。 */
-const initialValues = { user: { email: 'user@example.com' }, sql: 'select 1' };
-/** 三态共用 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
-          properties: {
-            user: {
-              type: 'object',
-              properties: {
-                email: {
-                  type: 'string',
-                  title: '邮箱',
-                  'x-decorator': 'FormItem',
-                  'x-component': 'Input',
-                },
-              },
-            },
-            sql: {
-              type: 'string',
-              title: 'SQL',
-              'x-decorator': 'FormItem',
-              'x-decorator-props': { gridSpan: 2 },
-              'x-component': 'Slot',
-              'x-component-props': { name: 'sql' },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily
-    :key="mode"
-    :schema="schema"
-    :initial-values="initialValues"
-    :mode="mode"
-    :detail-options="{ bordered: true, maxColumns: 2, minColumns: 1, minWidth: 320 }"
-  >
-    <template #sql="{ value, onChange }">
-      <YMonaco :model-value="value" language="sql" @change="onChange" />
-    </template>
-    <template #detail-user-email="{ value }">
-      <a :href="`mailto:${value}`">{{ value }}</a>
-    </template>
-    <template #detail-sql="{ value }">
-      <YMonaco :model-value="value" language="sql" readonly />
-    </template>
-  </YFormily>
-</template>
-```
-
-## 5. Schema Slot 自定义字段
-
-`value/onChange` 默认注入；只有确实需要 `field` 或全表值时才配置 `params: ['field', '$values']`。
-
-```vue
-<script setup lang="ts">
-import { YButton, YFormily, type ISchema } from '@yss-ui/components';
-import { Input as AInput } from 'ant-design-vue';
-
-/** 模拟选人并把主键写回字段。 */
-const selectUser = (onChange: (value?: string) => void) => {
-  onChange('user-001');
-};
-
-/** 自定义选人字段 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
-          properties: {
-            category: {
-              type: 'string',
-              title: '分类',
-              'x-decorator': 'FormItem',
-              'x-component': 'Input',
-            },
-            userId: {
-              type: 'string',
-              title: '关联用户',
-              'x-decorator': 'FormItem',
-              'x-component': 'Slot',
-              'x-component-props': { name: 'userSelector', params: ['$values'] },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema">
-    <template #userSelector="{ value, onChange, values }">
-      <AInput :value="value" readonly />
-      <YButton @click="selectUser(onChange)">选择用户</YButton>
-      <YButton v-if="value" @click="onChange(undefined)">清除</YButton>
-      <span>当前分类：{{ values.category ?? '无' }}</span>
-    </template>
-  </YFormily>
-</template>
-```
-
-## 6. 分步表单路由
-
-完整实现读取 `../../formily-step-flow/SKILL.md`，必须遵循以下边界：
-
-- 从 `ant-design-vue` 导入 `Steps as ASteps`；组件库没有 `YSteps`。
-- 每步使用独立 YFormily ref 与 `v-model`，统一收敛到一个 `reactive` 数据源。
-- `await formRef.submit()` 成功后前进，校验失败会 reject；不要写 `ok !== false`。
-- 确认步骤读取前序数据的 `computed` 聚合，不要绑定空的 `step3`。
-- 最终提交只聚合真实业务步骤；API 错误交给 `mutator.ts` 提示。
-
-## 7. 动态 Schema 与动态插槽
-
-动态 schema 优先由 `computed` 派生，避免在 `onMounted` 中清空后原地修改深层 `properties`。
-
-```vue
-<script setup lang="ts">
-import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
-import { computed, ref } from 'vue';
-
-/** 后端动态字段描述。 */
-interface PluginParam {
-  field: string;
-  name: string;
-  type: 'string' | 'boolean' | 'input-code';
-  required?: boolean;
-}
-
-/** 动态字段配置。 */
-const pluginParams = ref<PluginParam[]>([
-  { field: 'tableName', name: '表名', type: 'string', required: true },
-  { field: 'enabled', name: '是否启用', type: 'boolean' },
-  { field: 'customSql', name: '自定义 SQL', type: 'input-code', required: true },
-]);
-/** 动态表单值。 */
-const formValues = ref<Record<string, any>>({});
-
-/** 将动态字段描述转换为 Formily 字段节点。 */
-const createFieldSchema = (param: PluginParam): ISchema => ({
-  type: param.type === 'boolean' ? 'boolean' : 'string',
-  title: param.name,
-  required: param.required ?? false,
-  'x-decorator': 'FormItem',
-  'x-component': param.type === 'boolean' ? 'Switch' : param.type === 'input-code' ? 'Slot' : 'Input',
-  'x-component-props': param.type === 'input-code' ? { name: `${param.field}Slot` } : { placeholder: `请输入${param.name}` },
-});
-
-/** 动态字段名到 Schema 的映射。 */
-const dynamicProperties = computed<Record<string, ISchema>>(() =>
-  Object.fromEntries(pluginParams.value.map(param => [param.field, createFieldSchema(param)]))
-);
-/** 完整动态表单 Schema。 */
-const schema = computed<ISchema>(() => ({
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'vertical' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 1, minColumns: 1, minWidth: 260 },
-          properties: dynamicProperties.value,
-        },
-      },
-    },
-  },
-}));
-/** 需要代码编辑器插槽的字段名。 */
-const codeEditorFields = computed(() =>
-  pluginParams.value.filter(param => param.type === 'input-code').map(param => param.field)
-);
-</script>
-
-<template>
-  <YFormily v-model="formValues" :schema="schema">
-    <template v-for="fieldKey in codeEditorFields" :key="fieldKey" #[`${fieldKey}Slot`]="{ value, onChange }">
-      <YMonaco :model-value="value" language="sql" :height="160" @change="onChange" />
-    </template>
-  </YFormily>
-</template>
-```
-
-## 8. Orval 提交与错误处理
-
-底层 `mutator.ts` 已对网络错误和 `success === false` 统一执行 `message.error` 并 reject。业务提交只处理成功动作与 loading，不写重复失败提示。若需要统一提示 Formily 客户端校验失败，使用 `onFormSubmitValidateFailed`；不要在会同时接收 API reject 的 `onFormSubmitFailed` 或 `Submit.onSubmitFailed` 中调用 `message.error`。
-
-```typescript
-import { message } from 'ant-design-vue';
-import { ref } from 'vue';
-
-/** 保存状态。 */
-const saving = ref(false);
-
-/** 提交表单；saveRecord 代表项目中实际生成的 Orval 方法。 */
-const handleSubmit = async (values: Record<string, any>) => {
-  saving.value = true;
-  try {
-    await saveRecord(values);
-    message.success('保存成功');
-    emit('success');
-  } finally {
-    saving.value = false;
-  }
-};
-```
-
-禁止以下模式：
-
-- `if (res.success) { ... } else { message.error(...) }`
-- `catch (error) { message.error(...) }`
-- API reject 后仍继续关闭弹窗、切换步骤或刷新成功态
-
-如果必须做回滚，可以在 `catch` 中回滚后继续 `throw error`，但仍不重复提示。