create-yss-spec 2.2.0 → 2.2.1

package/template/.cursor/skills/page-skeleton/examples/AdvancedFormPage/hooks/useRuleConfig.ts

@@ -0,0 +1,75 @@
+import { reactive, ref } from 'vue';
+import { message } from 'ant-design-vue';
+import type { ConditionGroup, OptionItem } from '@yss-ui/components';
+import { FIELD_OPTIONS, RULE_OPERATOR_OPTIONS } from '../constant';
+
+/** 创建空条件组。 */
+const createEmptyGroup = (id: string): ConditionGroup => ({
+  id,
+  type: 'GROUP',
+  logicalOp: 'AND',
+  children: [],
+});
+
+/** 按关键词筛选条件字段。 */
+const filterFields = (keyword: string): OptionItem[] => {
+  const normalizedKeyword = keyword.trim().toLowerCase();
+  if (!normalizedKeyword) return FIELD_OPTIONS;
+  return FIELD_OPTIONS.filter(item =>
+    [item.label, item.value].some(value =>
+      String(value ?? '')
+        .toLowerCase()
+        .includes(normalizedKeyword)
+    )
+  );
+};
+
+/** 管理条件构建器与预览状态。 */
+export const useRuleConfig = () => {
+  const filterCondition = ref<ConditionGroup>(createEmptyGroup('filter-root'));
+  const checkCondition = ref<ConditionGroup>(createEmptyGroup('check-root'));
+  const filterPreview = ref('');
+  const checkPreview = ref('');
+  const loading = reactive({ filterPreview: false, checkPreview: false });
+
+  /** 为 YConditionBuilder 加载可搜索字段。 */
+  const loadFields = async (keyword: string): Promise<OptionItem[]> => filterFields(keyword);
+
+  /** 生成条件 JSON 预览。 */
+  const generatePreview = async (
+    condition: ConditionGroup,
+    target: 'filterPreview' | 'checkPreview'
+  ): Promise<void> => {
+    if (!condition.children.length) {
+      message.warning('请先配置完整条件');
+      return;
+    }
+
+    loading[target] = true;
+    try {
+      const preview = JSON.stringify(condition, null, 2);
+      if (target === 'filterPreview') filterPreview.value = preview;
+      else checkPreview.value = preview;
+    } finally {
+      loading[target] = false;
+    }
+  };
+
+  /** 生成校验范围预览。 */
+  const generateFilterPreview = (): Promise<void> => generatePreview(filterCondition.value, 'filterPreview');
+
+  /** 生成校验表达式预览。 */
+  const generateCheckPreview = (): Promise<void> => generatePreview(checkCondition.value, 'checkPreview');
+
+  return {
+    filterCondition,
+    checkCondition,
+    filterPreview,
+    checkPreview,
+    loading,
+    operatorOptions: RULE_OPERATOR_OPTIONS,
+    loadFields,
+    generateFilterPreview,
+    generateCheckPreview,
+  };
+};

package/template/.cursor/skills/page-skeleton/examples/AdvancedFormPage/index.vue

@@ -0,0 +1,107 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { YButton, YCard, YConditionBuilder, YFormily } from '@yss-ui/components';
+import { FORM_OPTIONS } from './constant';
+import { useRuleConfig } from './hooks/useRuleConfig';
+import { ruleConfigSchema } from './schemas/ruleConfigSchema';
+
+defineOptions({ name: 'AdvancedFormPage' });
+
+/** YFormily 校验实例。 */
+interface FormilyRef {
+  submit: () => Promise<Record<string, unknown>>;
+}
+
+/** YConditionBuilder 校验实例。 */
+interface ConditionBuilderRef {
+  validate: () => boolean;
+}
+
+const formData = ref<Record<string, unknown>>({
+  intensity: 'WEAK',
+  errorStorage: true,
+  errorStorageLimit: 1000,
+  errorStorageType: 'FILE_SYSTEM',
+});
+const schema = computed(() => ruleConfigSchema(FORM_OPTIONS));
+const formRef = ref<FormilyRef>();
+const filterBuilderRef = ref<ConditionBuilderRef>();
+const checkBuilderRef = ref<ConditionBuilderRef>();
+const {
+  filterCondition,
+  checkCondition,
+  filterPreview,
+  checkPreview,
+  loading,
+  operatorOptions,
+  loadFields,
+  generateFilterPreview,
+  generateCheckPreview,
+} = useRuleConfig();
+
+/** 校验表单与指定条件构建器。 */
+const validateBeforeGenerate = async (builder?: ConditionBuilderRef): Promise<boolean> => {
+  if (!formRef.value || !builder) return false;
+  try {
+    await formRef.value.submit();
+  } catch {
+    return false;
+  }
+  return builder.validate();
+};
+
+/** 校验后生成校验范围预览。 */
+const handleGenerateFilterPreview = async (): Promise<void> => {
+  if (await validateBeforeGenerate(filterBuilderRef.value)) await generateFilterPreview();
+};
+
+/** 校验后生成校验表达式预览。 */
+const handleGenerateCheckPreview = async (): Promise<void> => {
+  if (await validateBeforeGenerate(checkBuilderRef.value)) await generateCheckPreview();
+};
+</script>
+
+<template>
+  <div class="rule-config-page">
+    <YCard class="rule-config-page__content">
+      <YFormily ref="formRef" v-model="formData" :schema="schema">
+        <template #conditionFilter>
+          <YConditionBuilder
+            ref="filterBuilderRef"
+            v-model="filterCondition"
+            :load-fields="loadFields"
+            :operator-options="operatorOptions"
+          />
+        </template>
+        <template #filterPreview>
+          <div class="rule-config-page__preview">
+            <pre>{{ filterPreview || '配置校验范围后生成预览' }}</pre>
+            <YButton type="primary" :loading="loading.filterPreview" @click="handleGenerateFilterPreview">
+              生成校验范围
+            </YButton>
+          </div>
+        </template>
+        <template #checkCondition>
+          <YConditionBuilder
+            ref="checkBuilderRef"
+            v-model="checkCondition"
+            :load-fields="loadFields"
+            :operator-options="operatorOptions"
+          />
+        </template>
+        <template #checkPreview>
+          <div class="rule-config-page__preview">
+            <pre>{{ checkPreview || '配置校验表达式后生成预览' }}</pre>
+            <YButton type="primary" :loading="loading.checkPreview" @click="handleGenerateCheckPreview">
+              生成校验表达式
+            </YButton>
+          </div>
+        </template>
+      </YFormily>
+    </YCard>
+  </div>
+</template>
+
+<style scoped lang="less">
+@import url('./style.less');
+</style>

package/template/.cursor/skills/page-skeleton/examples/AdvancedFormPage/schemas/ruleConfigSchema.ts

@@ -0,0 +1,256 @@
+/**
+ * 规则配置表单Schema
+ * 包含：Grid布局、表单分组、字段联动 (Reactions)、Slot插槽
+ */
+import type { FormOptions } from '../constant';
+
+/**
+ * 规则配置Schema
+ * @param formOptions 表单选项数据
+ */
+export const ruleConfigSchema = (formOptions: FormOptions): Record<string, any> => ({
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': {
+        layout: 'horizontal',
+        labelWidth: 110, // ← 根据最长 label 确定（一般 5 个字约 100px，这里稍大）
+        labelAlign: 'right', // ← 必须右对齐
+      },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': {
+            maxColumns: 3,
+            minColumns: 1,
+            columnGap: 16,
+            rowGap: 0,
+          },
+          properties: {
+            // -------------------------------------------------------------
+            // 分组1：规则配置
+            // -------------------------------------------------------------
+            ruleConfigHeader: {
+              type: 'void',
+              title: '规则配置',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                feedbackLayout: 'none',
+                colon: false,
+                gridSpan: 3,
+                labelWidth: 0,
+                wrapperCol: { span: 24 },
+              },
+              'x-component': 'GroupHeader', // 自定义组件 or 标题组件
+            },
+            intensity: {
+              type: 'string',
+              title: '规则强度',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-component': 'Radio.Group',
+              enum: formOptions.intensity,
+            },
+            // 开关字段，控制其他字段显示
+            errorStorage: {
+              type: 'boolean',
+              title: '异常存储',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-component': 'Switch',
+              'x-component-props': {
+                checkedChildren: '开',
+                unCheckedChildren: '关',
+              },
+            },
+            // 受控字段：异常限制 (当 errorStorage=true 时显示)
+            errorStorageLimit: {
+              type: 'number',
+              title: '异常限制',
+              'x-decorator': 'FormItem',
+              'x-component': 'NumberPicker',
+              'x-component-props': {
+                placeholder: '请输入异常限制',
+                style: { width: '100%' },
+              },
+              'x-reactions': {
+                dependencies: ['errorStorage'],
+                fulfill: {
+                  state: {
+                    visible: '{{$deps[0]}}',
+                  },
+                },
+              },
+            },
+
+            // -------------------------------------------------------------
+            // 分组2：异常数据存储
+            // 这里的 GroupHeader 本身也受 errorStorage 控制显示
+            // -------------------------------------------------------------
+            exceptionDataHeader: {
+              type: 'void',
+              title: '异常数据存储',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                feedbackLayout: 'none',
+                colon: false,
+                gridSpan: 3,
+                labelWidth: 0,
+                wrapperCol: { span: 24 },
+              },
+              'x-component': 'GroupHeader',
+              'x-reactions': {
+                dependencies: ['errorStorage'],
+                fulfill: {
+                  state: {
+                    visible: '{{$deps[0]}}',
+                  },
+                },
+              },
+            },
+            errorStorageType: {
+              type: 'string',
+              title: '存储方式',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-component': 'Select',
+              'x-component-props': {
+                placeholder: '请选择存储方式',
+              },
+              enum: formOptions.errorStorageType,
+              'x-reactions': {
+                dependencies: ['errorStorage'],
+                fulfill: {
+                  state: {
+                    visible: '{{$deps[0]}}',
+                  },
+                },
+              },
+            },
+            errorStorageName: {
+              type: 'string',
+              title: '存储名称',
+              required: true,
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                gridSpan: 1,
+              },
+              'x-component': 'Input',
+              'x-component-props': {
+                placeholder: '请选择异常数据存储名称',
+              },
+              'x-reactions': {
+                dependencies: ['errorStorage'],
+                fulfill: {
+                  state: {
+                    visible: '{{$deps[0]}}',
+                  },
+                },
+              },
+            },
+            errorStoragePath: {
+              type: 'string',
+              title: '存储地址',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                gridSpan: 1,
+              },
+              'x-component': 'Input',
+              'x-component-props': {
+                placeholder: '请输入异常数据存储地址',
+              },
+              // 也可以配置 reactions
+            },
+
+            // -------------------------------------------------------------
+            // 分组3：校验规则 (使用 Slot 自定义渲染)
+            // -------------------------------------------------------------
+            filterHeader: {
+              type: 'void',
+              title: '校验规则',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                feedbackLayout: 'none',
+                colon: false,
+                gridSpan: 3,
+                labelWidth: 0,
+                wrapperCol: { span: 24 },
+              },
+              'x-component': 'GroupHeader',
+            },
+            // Slot：校验范围构建器
+            conditionFilter: {
+              type: 'object',
+              title: '校验范围',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                gridSpan: 3, // 占满一行
+              },
+              'x-component': 'Slot', // 关键：使用 Slot 组件
+              'x-component-props': {
+                name: 'conditionFilter', // 对应 <template #conditionFilter>
+              },
+            },
+            // Slot：条件结构预览
+            filterPreview: {
+              type: 'string',
+              title: '预览',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                gridSpan: 3,
+              },
+              'x-component': 'Slot',
+              'x-component-props': {
+                name: 'filterPreview',
+              },
+            },
+
+            // -------------------------------------------------------------
+            // 分组4：校验设置
+            // -------------------------------------------------------------
+            checkHeader: {
+              type: 'void',
+              title: '校验设置',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                feedbackLayout: 'none',
+                colon: false,
+                gridSpan: 3,
+                labelWidth: 0,
+                wrapperCol: { span: 24 },
+              },
+              'x-component': 'GroupHeader',
+            },
+            checkCondition: {
+              type: 'object',
+              title: '校验配置',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                gridSpan: 3,
+              },
+              'x-component': 'Slot',
+              'x-component-props': {
+                name: 'checkCondition',
+              },
+            },
+            checkPreview: {
+              type: 'string',
+              title: '预览',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': {
+                gridSpan: 3,
+              },
+              'x-component': 'Slot',
+              'x-component-props': {
+                name: 'checkPreview',
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});

package/template/.cursor/skills/page-skeleton/examples/AdvancedFormPage/style.less

@@ -0,0 +1,30 @@
+.rule-config-page {
+  width: 100%;
+  height: 100%;
+
+  &__content {
+    height: 100%;
+    overflow: auto;
+  }
+
+  &__preview {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+
+    pre {
+      flex: 1;
+      min-height: 72px;
+      max-height: 220px;
+      margin: 0;
+      padding: 12px;
+      overflow: auto;
+      color: var(--text-color, rgb(0 0 0 / 88%));
+      background: var(--bg-color, #f0f2f5);
+      border: 1px solid var(--border-color-split, #f0f0f0);
+      border-radius: 6px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+  }
+}

package/template/.cursor/skills/page-skeleton/examples/StandardListPage/constant.ts

@@ -0,0 +1,28 @@
+import type { YTableColumn } from '@yss-ui/components';
+import type { QualityBusinessRuleVO } from '@/api/generated/quality/schemas';
+
+/** 质量规则列表行数据。 */
+export type QualityRuleItem = QualityBusinessRuleVO;
+
+/** 质量规则查询表单。 */
+export interface SearchFormData {
+  ruleName: string;
+}
+
+/** 状态文案映射。 */
+export const STATUS_LABELS: Record<number, string> = {
+  0: '禁用',
+  1: '启用',
+};
+
+/** 质量规则表格列。 */
+export const TABLE_COLUMNS: YTableColumn[] = [
+  { field: 'ruleName', title: '质量规则名称', minWidth: 180, slots: { default: 'ruleName' } },
+  { field: 'ruleCode', title: '规则编码', minWidth: 160 },
+  {
+    field: 'status',
+    title: '状态',
+    width: 100,
+    formatter: ({ cellValue }: { cellValue?: number }) => STATUS_LABELS[cellValue ?? -1] ?? '-',
+  },
+];

package/template/.cursor/skills/page-skeleton/examples/StandardListPage/hooks/useQualityRuleList.ts

@@ -0,0 +1,58 @@
+import { reactive, ref } from 'vue';
+import { getApiApi } from '@/api/generated/quality';
+import type { QualityRulePage } from '@/api/generated/quality/schemas';
+import type { QualityRuleItem, SearchFormData } from '../constant';
+
+const { pageQualityRule } = getApiApi();
+
+/** 管理质量规则列表、查询和远程分页。 */
+export const useQualityRuleList = () => {
+  const tableData = ref<QualityRuleItem[]>([]);
+  const loading = ref(false);
+  const pagination = reactive({ current: 1, pageSize: 20, total: 0, remote: true });
+  const searchForm = reactive<SearchFormData>({ ruleName: '' });
+
+  /** 组装 Orval 查询 DTO。 */
+  const getQueryParams = (): QualityRulePage => ({
+    pageIndex: pagination.current,
+    pageSize: pagination.pageSize,
+    ruleName: searchForm.ruleName || undefined,
+  });
+
+  /** 加载列表；错误提示由 mutator 统一处理。 */
+  const fetchList = async (): Promise<void> => {
+    loading.value = true;
+    try {
+      const res = await pageQualityRule(getQueryParams());
+      tableData.value = res.data ?? [];
+      pagination.total = res.totalCount ?? 0;
+    } catch {
+      tableData.value = [];
+      pagination.total = 0;
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  /** 处理分页变化。 */
+  const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }): void => {
+    pagination.current = current;
+    pagination.pageSize = pageSize;
+    void fetchList();
+  };
+
+  /** 从第一页执行查询。 */
+  const handleSearch = (): void => {
+    pagination.current = 1;
+    void fetchList();
+  };
+
+  /** 重置查询条件并刷新。 */
+  const handleReset = (): void => {
+    searchForm.ruleName = '';
+    pagination.current = 1;
+    void fetchList();
+  };
+
+  return { tableData, loading, pagination, searchForm, fetchList, handlePageChange, handleSearch, handleReset };
+};

package/template/.cursor/skills/page-skeleton/examples/StandardListPage/hooks/useRuleActions.ts

@@ -0,0 +1,65 @@
+import { computed } from 'vue';
+import { message } from 'ant-design-vue';
+import type { YTableActionConfig } from '@yss-ui/components';
+import { getApiApi } from '@/api/generated/quality';
+import type { QualityRuleItem } from '../constant';
+
+const { deleteQualityRule } = getApiApi();
+
+/** 行操作与页面容器的通信回调。 */
+export interface RuleActionCallbacks {
+  refreshList: () => Promise<void>;
+  onCreate: () => void;
+  onEdit: (row: QualityRuleItem) => void;
+  onView: (row: QualityRuleItem) => void;
+}
+
+/** YTable 气泡确认助手。 */
+interface ActionHelpers {
+  close: () => void;
+  hideLoading: () => void;
+}
+
+/** 管理质量规则行操作和 YTable 操作列配置。 */
+export const useRuleActions = (callbacks: RuleActionCallbacks) => {
+  /** 删除规则并刷新列表。 */
+  const handleDelete = async (row: QualityRuleItem): Promise<void> => {
+    if (!row.id) return;
+
+    try {
+      await deleteQualityRule(row.id);
+      message.success('删除成功');
+      await callbacks.refreshList();
+    } catch {
+      // mutator 已展示错误，此处不重复 message.error。
+    }
+  };
+
+  /** 标准操作列：查看/编辑立即执行，删除使用气泡确认。 */
+  const actionConfig = computed<YTableActionConfig>(() => ({
+    title: '操作',
+    width: 180,
+    fixed: 'right',
+    buttons: [
+      { label: '查看', value: 'view', click: ({ row }) => callbacks.onView(row) },
+      { label: '编辑', value: 'edit', click: ({ row }) => callbacks.onEdit(row) },
+      {
+        label: '删除',
+        value: 'delete',
+        type: 'link',
+        isConfirm: true,
+        confirmProps: { title: '确认删除此规则吗？删除后无法恢复', needLoading: true },
+        click: async ({ row }, _button, helpers: ActionHelpers) => {
+          try {
+            await handleDelete(row);
+          } finally {
+            helpers.hideLoading();
+            helpers.close();
+          }
+        },
+      },
+    ],
+  }));
+
+  return { actionConfig, handleCreate: callbacks.onCreate };
+};