create-yss-spec 3.5.5 → 3.5.8

package/template/.codex/skills/formily-foundation/references/async-save-example.md

@@ -0,0 +1,57 @@
+# 异步保存回调
+
+等待父回调完成的保存场景读取本例。`onSubmit` 必须返回实际保存 Promise；发送 `emit` 事件只返回 void，不能等待父组件的异步请求。
+
+Orval 请求失败沿用 [错误处理](examples.md#8-orval-提交与错误处理)，由 mutator 统一提示，调用方恢复 loading 并传播 reject。
+
+```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, 'x-validator': [{ required: true, whitespace: true, message: '请输入名称' }] },
+            submit: {
+              type: 'void',
+              'x-component': 'Submit',
+              'x-content': '提交',
+              'x-component-props': { onSubmit: '{{ onSubmit }}' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily :schema="schema" :scope="{ onSubmit }" />
+</template>
+```
+

package/template/.codex/skills/formily-foundation/references/query-layout.md

@@ -0,0 +1,50 @@
+## 业务查询区布局
+
+```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;
+  }
+}
+```

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

@@ -3,7 +3,7 @@ name: formily-linkage-effects
 description: 指导 YFormily 字段联动与表单级副作用；当实现动态显隐、禁用、级联选项、scope 事件、x-reactions、effects、异步联动或客户端校验失败兜底时使用。
 ---
 
-# Formily Linkage Effects Skill
+# YFormily 联动与副作用
 
 ## 触发条件
 
@@ -33,122 +33,9 @@ description: 指导 YFormily 字段联动与表单级副作用；当实现动态
 - 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>
-```
+首次组织 `createForm + effects`、排查初始化联动或校验反馈时，读取 [联动与 effects 示例](references/linkage-example.md)。基础布局和提交仍按 `formily-foundation`。
 
 ## 交付检查清单
 

package/template/.codex/skills/formily-linkage-effects/references/linkage-example.md

@@ -0,0 +1,116 @@
+## 标准代码骨架
+
+```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>
+```

package/template/.codex/skills/formily-mode-slot-detail/SKILL.md

@@ -3,7 +3,7 @@ name: formily-mode-slot-detail
 description: 指导 YFormily 新增、编辑、查看三态与插槽渲染；当配置 mode 0/1/2、查看态只读、详情页 Descriptions 展示、detail-options、Schema Slot 或详情字段插槽时使用。
 ---
 
-# Formily Mode Slot Detail Skill
+# YFormily 三态与插槽
 
 ## 触发条件
 
@@ -35,87 +35,9 @@ description: 指导 YFormily 新增、编辑、查看三态与插槽渲染；当
 - 加载详情的 Orval API 错误已由 `mutator.ts` 统一 `message.error` 并 reject，业务 `else`/`catch` 禁止重复提示。
 - 分步需求默认走 `formily-step-flow`，不在本 skill 中给 `FormStep` 默认方案。
 
-## 标准代码骨架
+## 按需示例
 
-```vue
-<script setup lang="ts">
-import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
-import { ref } from 'vue';
-
-/** YFormily 业务模式。 */
-type FormMode = 0 | 1 | 2;
-
-/** 当前表单模式。 */
-const mode = ref<FormMode>(0);
-
-/** 编辑和查看回填值。 */
-const initialValues = {
-  user: { email: 'user@example.com' },
-  sql: 'select * from users',
-};
-
-/** 编辑与详情共用的 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
-    :schema="schema"
-    :initial-values="initialValues"
-    :mode="mode"
-    :detail-options="{ bordered: true, maxColumns: 3, minColumns: 1, minWidth: 260 }"
-  >
-    <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>
-```
+首次组合三态、编辑 Slot 与详情插槽，或排查字段路径时，读取 [三态与双通道插槽示例](references/mode-slot-example.md)。示例不替代目标工程的导出与版本核验。
 
 ## 交付检查清单
 

package/template/.codex/skills/formily-mode-slot-detail/references/mode-slot-example.md

@@ -0,0 +1,81 @@
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
+import { ref } from 'vue';
+
+/** YFormily 业务模式。 */
+type FormMode = 0 | 1 | 2;
+
+/** 当前表单模式。 */
+const mode = ref<FormMode>(0);
+
+/** 编辑和查看回填值。 */
+const initialValues = {
+  user: { email: 'user@example.com' },
+  sql: 'select * from users',
+};
+
+/** 编辑与详情共用的 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
+    :schema="schema"
+    :initial-values="initialValues"
+    :mode="mode"
+    :detail-options="{ bordered: true, maxColumns: 3, minColumns: 1, minWidth: 260 }"
+  >
+    <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>
+```

package/template/.codex/skills/formily-step-flow/SKILL.md

@@ -3,7 +3,7 @@ name: formily-step-flow
 description: 指导 YSS UI 分步表单与流程录入；当需要 Ant Design Vue Steps、多 YFormily 独立校验、跨步数据保留、确认预览或最终聚合提交时使用。
 ---
 
-# Formily Step Flow Skill
+# YFormily 分步流程
 
 ## 触发条件
 
@@ -32,149 +32,9 @@ description: 指导 YSS UI 分步表单与流程录入；当需要 Ant Design Vu
 - 最终 API 提交只聚合业务步骤，禁止把纯确认步骤当作新数据源。
 - Orval API 的网络错误及 `success === false` 业务错误已由 `mutator.ts` 统一 `message.error` 并 reject；最终提交的 `else`/`catch` 禁止重复提示，loading 放在 `finally` 恢复。
 
-## 标准代码骨架
+## 按需示例
 
-```vue
-<script setup lang="ts">
-import { YButton, YFormily, type ISchema } from '@yss-ui/components';
-import { Steps as ASteps } from 'ant-design-vue';
-import { computed, reactive, ref } from 'vue';
-
-/** YFormily 对外提交能力。 */
-interface YssFormilyExpose {
-  submit: () => Promise<Record<string, any>>;
-}
-
-/** 分步表单数据。 */
-interface StepFormData {
-  step1: { name: string };
-  step2: { level: string };
-}
-
-/** 分步表单提交回调 Props。 */
-interface StepFlowProps {
-  onSubmit: (values: StepFormData) => Promise<void>;
-}
-
-/** 分步表单提交回调。 */
-const props = defineProps<StepFlowProps>();
-/** 当前步骤，从 0 开始。 */
-const currentStep = ref(0);
-/** 最终提交状态。 */
-const submitting = ref(false);
-/** 第一步表单实例。 */
-const step1Ref = ref<YssFormilyExpose>();
-/** 第二步表单实例。 */
-const step2Ref = ref<YssFormilyExpose>();
-/** 步骤导航配置。 */
-const stepItems = [{ title: '基础信息' }, { title: '策略配置' }, { title: '确认提交' }];
-/** 跨步唯一数据源。 */
-const formData = reactive<StepFormData>({
-  step1: { name: '' },
-  step2: { level: 'normal' },
-});
-
-/** 创建符合业务三层布局约定的步骤 Schema。 */
-const createStepSchema = (properties: Record<string, ISchema>): 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,
-        },
-      },
-    },
-  },
-});
-
-/** 第一步 Schema。 */
-const step1Schema = createStepSchema({
-  name: {
-    type: 'string',
-    title: '任务名称',
-    required: true,
-    'x-validator': [{ required: true, whitespace: true, message: '请输入任务名称' }],
-    'x-decorator': 'FormItem',
-    'x-component': 'Input',
-  },
-});
-/** 第二步 Schema。 */
-const step2Schema = createStepSchema({
-  level: {
-    type: 'string',
-    title: '策略等级',
-    required: true,
-    enum: [
-      { label: '普通', value: 'normal' },
-      { label: '严格', value: 'strict' },
-    ],
-    'x-decorator': 'FormItem',
-    'x-component': 'Select',
-  },
-});
-/** 确认步骤 Schema。 */
-const confirmSchema = createStepSchema({
-  name: { type: 'string', title: '任务名称', 'x-decorator': 'FormItem', 'x-component': 'Input' },
-  level: { type: 'string', title: '策略等级', 'x-decorator': 'FormItem', 'x-component': 'Input' },
-});
-/** 确认步骤展示数据。 */
-const confirmValues = computed(() => ({ name: formData.step1.name, level: formData.step2.level }));
-
-/** 校验当前步骤，成功后前进。 */
-const next = async () => {
-  const currentRef = currentStep.value === 0 ? step1Ref.value : step2Ref.value;
-  if (!currentRef) return;
-  try {
-    await currentRef.submit();
-    currentStep.value += 1;
-  } catch {
-    return;
-  }
-};
-
-/** 返回上一步。 */
-const back = () => {
-  currentStep.value = Math.max(0, currentStep.value - 1);
-};
-
-/** 提交全部步骤数据。 */
-const submitAll = async () => {
-  submitting.value = true;
-  try {
-    await props.onSubmit({ step1: { ...formData.step1 }, step2: { ...formData.step2 } });
-  } finally {
-    submitting.value = false;
-  }
-};
-</script>
-
-<template>
-  <ASteps :current="currentStep" :items="stepItems" />
-
-  <YFormily v-if="currentStep === 0" ref="step1Ref" v-model="formData.step1" :schema="step1Schema" />
-  <YFormily v-else-if="currentStep === 1" ref="step2Ref" v-model="formData.step2" :schema="step2Schema" />
-  <YFormily
-    v-else
-    :schema="confirmSchema"
-    :initial-values="confirmValues"
-    :mode="2"
-    :detail-options="{ bordered: true, maxColumns: 2, minColumns: 1, minWidth: 320 }"
-  />
-
-  <YButton :disabled="currentStep === 0" @click="back">上一步</YButton>
-  <YButton v-if="currentStep < 2" type="primary" @click="next">下一步</YButton>
-  <YButton v-else type="primary" :loading="submitting" @click="submitAll">提交</YButton>
-</template>
-```
-
-当 schema、步骤状态和页面编排难以独立理解或验证时，分别拆到 `constant.ts`、`hooks/useStepFlow.ts`；以职责清晰和状态可测试为准，不按固定行数拆分。
+首次组织分步实例、聚合数据和确认页，或排查步骤回填时，读取 [分步表单组合示例](references/step-flow-example.md)。按业务阶段拆 schema、Hook 与私有视图，不按固定行数拆分。
 
 ## 交付检查清单