create-yss-spec 2.2.0 → 2.2.2

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

@@ -0,0 +1,486 @@
+# 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`，但仍不重复提示。

package/template/.hermes/skills/formily-linkage-effects/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: formily-linkage-effects
+description: 指导 YFormily 字段联动与表单级副作用；当实现动态显隐、禁用、级联选项、scope 事件、x-reactions、effects、异步联动或客户端校验失败兜底时使用。
+---
+
+# Formily Linkage Effects Skill
+
+## 触发条件
+
+- 需要字段联动（A 影响 B）、动态显隐/禁用、级联下拉。
+- 需要 `scope`、`x-reactions` 或 `createForm + effects`。
+- 需要处理异步选项竞态、旧值清理或 Formily 校验失败反馈。
+
+## 不适用场景
+
+- 纯基础字段与提交：使用 `../formily-foundation/SKILL.md`。
+- 详情态渲染和 mode 切换：使用 `../formily-mode-slot-detail/SKILL.md`。
+- 分步流程：使用 `../formily-step-flow/SKILL.md`。
+
+## 文档检索
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的 `scope`/Schema/表单实例边界；实现字段联动、多字段反应或 effects 时，再用 `get_demo` 获取 `formily/linkage`、`formily/linkage-multi`、`formily/effects` 等官方 Demo。
+2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+
+## 硬约束（禁止/必须）
+
+- 按复杂度选择机制：表达式 < `x-reactions` < `scope` < `effects`，避免同一联动在多处重复实现。
+- 仅显隐/禁用优先使用 `$values` 表达式；当前字段依赖其他字段时优先 `x-reactions`；跨字段事件用 `scope`；表单级监听才用 `effects`。
+- `effects` 需要首屏即生效时，同时注册 `onFieldInit` 和 `onFieldValueChange`，禁止只监听变化导致初始状态错误。
+- 修改其他字段状态时使用 `form.setFieldState`；级联选项变化后，只有旧值不在新选项中时才清空，避免初始化误删合法回填值。
+- 异步联动必须处理空依赖、loading、请求竞态与卸载；旧请求不得覆盖新选择。
+- 客户端校验提示使用 `onFormSubmitValidateFailed`。禁止在 `onFormSubmitFailed` 或 `Submit.onSubmitFailed` 中调用 `message.error`：Formily 会把 `onSubmit` 中的 API reject 也交给这些通用失败回调，导致与 `mutator.ts` 重复提示。
+- Orval API 的网络/业务错误已由 `mutator.ts` 提示并 reject，业务 `else`/`catch` 禁止重复 `message.error`。
+- 分步需求默认走 `formily-step-flow`，不在此 skill 中给 `FormStep` 默认方案。
+
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import type { DataField, Form, IFieldState } from '@formily/core';
+import { createForm, onFieldInit, onFieldValueChange, onFormSubmitValidateFailed } from '@formily/core';
+import { YFormily, type ISchema } from '@yss-ui/components';
+import { message } from 'ant-design-vue';
+
+/** 下拉选项。 */
+interface OptionItem {
+  label: string;
+  value: string;
+}
+
+/** 根据省份返回城市选项。 */
+const getCityOptions = (province?: string): OptionItem[] =>
+  province === 'zhejiang'
+    ? [{ label: '杭州', value: 'hangzhou' }]
+    : province === 'jiangsu'
+      ? [{ label: '南京', value: 'nanjing' }]
+      : [];
+
+/** 同步城市选项并清理已经失效的旧值。 */
+const syncCity = (field: DataField) => {
+  const options = getCityOptions(field.value as string | undefined);
+  field.form.setFieldState('city', (state: IFieldState) => {
+    state.dataSource = options;
+    if (!options.some(item => item.value === state.value)) state.value = undefined;
+  });
+};
+
+/** 外部 Form 实例，用于承载表单级 effects。 */
+const form: Form = createForm({
+  values: { province: 'zhejiang', city: 'hangzhou' },
+  effects() {
+    onFieldInit('province', field => syncCity(field as DataField));
+    onFieldValueChange('province', field => syncCity(field as DataField));
+    onFormSubmitValidateFailed(() => {
+      const feedbacks = form.queryFeedbacks({ type: 'error' });
+      message.error(feedbacks[0]?.messages?.[0] ?? '请检查表单');
+    });
+  },
+});
+
+/** 表单保存回调 Props。 */
+interface SaveFormProps {
+  onSave: (values: Record<string, any>) => Promise<void>;
+}
+
+/** 表单保存回调。 */
+const props = defineProps<SaveFormProps>();
+
+/** 校验通过后提交；API 错误由 mutator 统一提示。 */
+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: 2, minColumns: 1, minWidth: 320 },
+          properties: {
+            province: {
+              type: 'string',
+              title: '省份',
+              required: true,
+              enum: [
+                { label: '浙江', value: 'zhejiang' },
+                { label: '江苏', value: 'jiangsu' },
+              ],
+              'x-decorator': 'FormItem',
+              'x-component': 'Select',
+            },
+            city: {
+              type: 'string',
+              title: '城市',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-component': 'Select',
+            },
+            actions: {
+              type: 'void',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': { gridSpan: 2, colon: false },
+              'x-component': 'AutoButtonGroup',
+              properties: {
+                submit: {
+                  type: 'void',
+                  'x-component': 'Submit',
+                  'x-content': '提交',
+                  'x-component-props': { onSubmit: '{{ onSubmit }}' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily :schema="schema" :form="form" :scope="{ onSubmit }" />
+</template>
+```
+
+## 交付检查清单
+
+- [ ] 已说明为何选择表达式、`x-reactions`、`scope` 或 `effects`。
+- [ ] 首屏需要联动时同时覆盖初始化与变更事件。
+- [ ] 字段切换后旧值、选项和 loading 状态正确，异步请求有竞态保护。
+- [ ] Formily 客户端校验提示集中在 `onFormSubmitValidateFailed`，未用通用 `onFormSubmitFailed`/`Submit.onSubmitFailed` 处理 API reject。
+- [ ] API 错误只由 `mutator.ts` 提示，业务 `else`/`catch` 未重复 `message.error`。
+- [ ] 无 DOM hack、无无意义 `setTimeout`，未把分步逻辑塞入本 skill。
+
+## 失败兜底策略
+
+- `x-reactions` 失效时先校验字段路径和实际 schema 层级，再决定是否升级为 `setFieldState`。
+- 首屏状态错误时检查是否遗漏 `onFieldInit`；回填值丢失时检查是否无条件清空了级联字段。
+- 异步结果乱序时使用请求序号或 `AbortController`，只接受最后一次请求结果。
+- API 调用 reject 时只恢复 loading 或回滚局部状态，不重复弹出错误提示。