create-yss-spec 3.3.1 → 3.3.4

package/template/.trae/skills/page-skeleton/SKILL.md

@@ -1,76 +0,0 @@
----
-name: page-skeleton
-description: 指导搭建 Vue3 YSS UI 列表、表单、详情和弹窗页面模块骨架，统一 index.vue、constant.ts、style.less、hooks 与私有组件职责；当新建页面或需要拆分超过 150 行的业务组件时使用。
----
-
-# Page Skeleton Skill
-
-## 触发条件
-
-- 新建业务页面模块（列表、表单、详情、弹窗任意组合）。
-- 需要快速搭建目录结构、类型文件、hooks、组件分层。
-- 需要把页面代码控制在可维护结构，而不是单文件堆叠。
-
-## 不适用场景
-
-- 仅补一个局部交互逻辑，不涉及页面骨架重建。
-- 仅改 API 请求细节：使用 `../yss-api-integration/SKILL.md`。
-- 仅做 Formily 细节：使用 `../formily-*` 系列 skill。
-
-## 硬约束（禁止/必须）
-
-- 开发前必须先执行组件选型：`../component-selection-imports/SKILL.md`。
-- 页面目录默认拆分：`index.vue + constant.ts + style.less + hooks/`；存在多个私有视图或大量独立类型时再增加 `components/` 和 `type.ts`。
-- `index.vue` 只做 hooks 组合和视图编排，原则上控制在 150 行以内；超过 150 行或包含多个独立职责时必须拆分。
-- 表格列超过 10 行时放入 `constant.ts`；状态、API 调用、副作用和事件处理放入 `hooks/useXxx.ts`。
-- 所有样式放入 `style.less`，SFC 只保留 `<style scoped lang="less">@import './style.less';</style>`。
-- 所有导出函数、hooks、类型和静态配置必须有中文 JSDoc。
-- 表单方案默认用 `YFormily`；分步场景默认用 `formily-step-flow`。
-- 不得导入 `@formily/antdv` 作为业务 UI 方案。
-
-## 标准代码骨架
-
-```text
-packages/src/views/{ModuleName}/
-├── index.vue
-├── constant.ts
-├── style.less
-├── hooks/
-│   ├── use{Module}List.ts
-│   └── use{Module}Form.ts
-├── type.ts              # 独立类型较多时增加
-└── components/          # 存在多个私有视图时增加
-    ├── {Module}Table.vue
-    └── {Module}Modal.vue
-```
-
-```vue
-<script setup lang="ts">
-import { useModuleList } from './hooks/useModuleList';
-import { useModuleForm } from './hooks/useModuleForm';
-
-const list = useModuleList();
-const form = useModuleForm({ onSuccess: list.fetchData });
-</script>
-```
-
-## 交付检查清单
-
-- [ ] 目录拆分完整，职责清晰。
-- [ ] `index.vue` 不超过 150 行，且仅负责组合和渲染。
-- [ ] 类型定义与常量已抽离，不在页面内硬编码。
-- [ ] hooks 可复用且命名清晰（`useXxx`）。
-- [ ] 样式已抽离到 `style.less`，SFC 样式块已 scoped。
-- [ ] 页面导入组件来源符合组件选型规则。
-- [ ] 若包含表单，已选择对应 Formily skill。
-
-## 失败兜底策略
-
-- 当需求不清晰时，先落地最小骨架（列表区 + 操作区 + 弹窗占位），再增量填充。
-- 当页面复杂度超预期时，优先继续拆 hooks 和私有组件，而不是在 `index.vue` 堆逻辑。
-- 若组件是否封装存在歧义，回退到 `component-selection-imports` 先判定导入来源。
-
-## 示例
-
-- `./examples/StandardListPage/`
-- `./examples/AdvancedFormPage/`

package/template/.trae/skills/page-skeleton/examples/AdvancedFormPage/constant.ts

@@ -1,34 +0,0 @@
-import type { OperatorOption, OptionItem } from '@yss-ui/components';
-
-/** 表单字典选项。 */
-export interface FormOptions {
-  intensity: Array<{ label: string; value: string }>;
-  errorStorageType: Array<{ label: string; value: string }>;
-}
-
-/** 规则配置表单字典。 */
-export const FORM_OPTIONS: FormOptions = {
-  intensity: [
-    { label: '弱规则', value: 'WEAK' },
-    { label: '强规则', value: 'STRONG' },
-  ],
-  errorStorageType: [
-    { label: '文件服务', value: 'FILE_SYSTEM' },
-    { label: '数据落地表', value: 'DATATABLE_SYSTEM' },
-  ],
-};
-
-/** 条件构建器可选字段。 */
-export const FIELD_OPTIONS: OptionItem[] = [
-  { label: '用户编号', value: 'userId' },
-  { label: '金额', value: 'amount' },
-  { label: '状态', value: 'status' },
-];
-
-/** 条件构建器操作符。 */
-export const RULE_OPERATOR_OPTIONS: OperatorOption[] = [
-  { label: '等于', value: '=', kind: 'single' },
-  { label: '大于', value: '>', kind: 'single' },
-  { label: '介于', value: 'between', kind: 'between' },
-  { label: '包含于', value: 'in', kind: 'multiple' },
-];

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

@@ -1,75 +0,0 @@
-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/.trae/skills/page-skeleton/examples/AdvancedFormPage/index.vue

@@ -1,107 +0,0 @@
-<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/.trae/skills/page-skeleton/examples/AdvancedFormPage/schemas/ruleConfigSchema.ts

@@ -1,256 +0,0 @@
-/**
- * 规则配置表单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/.trae/skills/page-skeleton/examples/AdvancedFormPage/style.less

@@ -1,30 +0,0 @@
-.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/.trae/skills/page-skeleton/examples/StandardListPage/constant.ts

@@ -1,28 +0,0 @@
-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/.trae/skills/page-skeleton/examples/StandardListPage/hooks/useQualityRuleList.ts

@@ -1,58 +0,0 @@
-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 };
-};