create-yss-spec 3.0.1 → 3.1.3

package/template/.trae/skills/yss-page-module-development/SKILL.md

@@ -1,165 +0,0 @@
----
-name: yss-page-module-development
-description: 指导创建标准 Vue 3 YSS 业务页面模块，覆盖 CRUD、列表、表单、详情、左树右表、组件选型、Orval 接口、主题 Token、原型还原和交付验证。
----
-
-# YSS Page Module Development
-
-> **核心路由说明**：新页面生成开发请优先以 `../yss-ui-business-page-generation/SKILL.md` 为统一主规则与硬约束。当前会话可用 yss-ui MCP 时，生成业务代码前必须先调用 `get_codegen_rules`。本技能作为兼容旧触发名与流程编排入口保留。
-
-Use this skill when the user asks for a business page, CRUD module, tree-table page, detail page, or any standard YSS Vue 3 page module.
-
-## Authoritative Docs And Skill Boundaries
-
-- YSS UI components: `http://192.168.164.27:3200/components`
-- YSS UI hooks: `http://192.168.164.27:3200/hooks`
-- YSS UI skills: `http://192.168.164.27:3200/skills`
-- Local reference index: `references/frontend-docs.md`
-
-This skill orchestrates page/module creation. Load narrower skills only when their details are needed:
-
-中文说明：这个技能负责“建页面模块的流程编排”。遇到具体组件、接口、Hook、高度、Formily 细节时，再补充加载更窄的专项技能。
-
-- `yss-components` for layout, YTable/YTree/YssFormily/YSplitPane component specifics.
-- `yss-hook` for request, pagination, parameter, and mapping logic.
-- `yss-api-integration` for Orval-generated APIs and submit/list/detail flows.
-- `yss-use-table-height` and `yss-use-tree-height` for height calculation.
-- `yss-formily` for detailed schema behavior.
-
-## What this skill produces
-
-- a page folder with predictable structure
-- a clear split between page composition and hook logic
-- YSS-aligned query, table, tree, and layout wiring
-- code that follows the existing app conventions instead of ad hoc UI assembly
-
-## Recommended workflow
-
-1. Identify the page type: list, tree-table, detail, or mixed.
-2. Decide whether the page needs `YssFormily`, `YTable`, `YTree`, `YSplitPane`, or custom blocks.
-3. Create the page folder structure.
-4. Move request and parameter logic into hooks.
-5. Assemble the page with minimal logic in `index.vue`.
-6. Verify loading, empty, and error states.
-
-## Standard structure
-
-```text
-views/PageName/
-  components/
-    XxxBlock/
-      index.vue
-      style.less
-      type.ts
-  hooks/
-    usePageTable.ts
-    usePageTree.ts
-  schemas/
-    searchSchema.ts
-  index.vue
-  style.less
-```
-
-Rules:
-
-- `index.vue` is for composition only.
-- `hooks/` holds request, parameter, selection, and mapping logic.
-- `components/` holds reusable blocks and view fragments.
-- `schemas/` holds YssFormily schema definitions.
-
-## Component priority
-
-1. Prefer `@yss-ui/components`.
-2. Use `ant-design-vue` only when YSS does not provide the needed control.
-3. Reuse existing page patterns before inventing a new layout.
-
-## Layout rules
-
-For left-tree-right-content pages:
-
-- use `YSplitPane` or an equivalent flexible split layout
-- keep the right side ordered as Header -> Query -> Data
-- make the content area flexible, not fixed height
-- provide a clear empty state when nothing is selected
-
-For non-split pages:
-
-- keep the main region responsive
-- avoid nested fixed-height containers that fight scrolling
-
-## Height hooks
-
-Use `useTableHeight` and `useTreeHeight` when the page needs available-height calculation.
-
-- bind the ref to the container, not to the table/tree itself
-- include pagination or toolbar offsets when they exist
-- keep the container `flex: 1; overflow: hidden`
-
-## Query and data regions
-
-### YssFormily
-
-- use schema-driven queries
-- keep action buttons in the schema
-- keep local helper logic in `scope`
-
-### YTable
-
-- use `field/type` column definitions
-- prefer named slots for custom cells
-- keep pagination and loading state driven by hook state
-
-### YTree
-
-- keep tree data and selection logic in hooks
-- use search offsets and height helpers when search is present
-
-## Page coding rules
-
-- use `<script setup lang="ts">`
-- keep `index.vue` thin
-- move data transformation out of templates
-- keep action handlers small and explicit
-- preserve existing route, menu, and permission conventions in the repo
-
-## YSS business page contract
-
-- 页面实现前先按 `component-selection-imports` 判定真实导出；已封装能力优先从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入。
-- 标准列表使用 `YTable` 的真实 `data`、`columns`、`loading`、`pageable`、`v-model:pagination` 和 `@page-change`；主操作放在 `#toolbar-right`，只有确实需要列设置时才启用 `toolbar-config.custom`。
-- 查询区使用 `YFormily` 渲染字段，查询/重置按钮位于表单外部并在窄屏下保持右下对齐；表单、表格、树和导出细节分别加载 `yss-formily`、`ytable-usage`、`ytree-usage` 和 `file-export-download`。
-- 页面有原型或旧页面参考时先读取 `prototype-page-acceptance`，建立视觉、状态、交互和响应式验收清单；交付时必须逐项对照。
-- 页面和组件的颜色、状态色及暗色模式遵循 `theme-token-usage`，不得硬编码品牌色。
-- Orval API 必须使用当前生成导出和 DTO；错误由 mutator 统一处理，业务 Hook 不重复判断 `success` 或重复提示错误。
-- 列表/树高度按实际分页、工具栏和搜索状态选择 `yss-use-table-height` / `yss-use-tree-height`，不得用固定魔法高度替代。
-
-## Deliverables
-
-When implementing a page module, the result should usually include:
-
-- page shell
-- hook file(s)
-- schema file(s)
-- block components if needed
-- styles
-
-## Checklist
-
-- the page structure matches the chosen pattern
-- request logic is isolated in hooks
-- query, pagination, and selection state have one source of truth
-- empty, loading, and error states are covered
-- custom blocks are extracted only when they improve clarity or reuse
-
-## Do not
-
-- do not put large request flows in `index.vue`
-- do not duplicate parameter handling across page and hook
-- do not bypass YSS components when a project-standard control exists
-- do not over-split a simple page into unnecessary files
-
-## Stage 7 Contract
-
-- Require an approved `Slice Implementation Contract`, requirement freeze, low-fidelity review, state matrix, the selected H1/H2 prototype deliverable, schema v3 browser/Design-QA/profile evidence, user confirmation, and a current frontend implementation plan; production APIs come from YSS UI + the actual implementation lockfile only after entering implementation.
-- Bind page, hooks, schema, blocks, generated API client, component tests, and E2E paths to contract fields and `allowed_write_paths`.
-- User-visible loading, empty, error, permission, selection, pagination, and action behavior use `behavior-tdd`; purely mechanical page scaffolding may use documented `controlled-generation`.
-- Return the shared `YSS Skill Execution Result`. A prototype mismatch, new API, new permission state, path overrun, or missing evidence must produce `drift`, `violation`, or `new_impacts`, not `implemented`.

package/template/.trae/skills/yss-page-module-development/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Page Module"
-  short_description: "标准业务页面模块、分区布局与 Hook 开发实践规范"
-  default_prompt: "Use $yss-page-module-development to scaffold a YSS Vue 3 page module with hooks, schemas, and split layout."

package/template/.trae/skills/yss-page-module-development/examples/AdvancedFormPage/constant.ts

@@ -1,32 +0,0 @@
-/**
- * 复杂表单页面 - 常量配置
- */
-
-/** 步骤枚举 */
-export enum RULE_STEPS {
-  BASE_INFO = 1,
-  RULE_CONFIG = 2,
-  RULE_RESULT = 3,
-}
-
-/** 步骤配置 */
-export const QUALITY_RULE_STEPS = [
-  { value: RULE_STEPS.BASE_INFO, title: '基本信息' },
-  { value: RULE_STEPS.RULE_CONFIG, title: '规则配置' },
-  { value: RULE_STEPS.RULE_RESULT, title: '规则结果' },
-];
-
-/** 条件组节点接口 */
-export interface ConditionGroup {
-  id: string;
-  type: 'GROUP' | 'LEAF';
-  logicalOp: 'AND' | 'OR';
-  children: any[];
-}
-
-/** 表单选项接口 */
-export interface FormOptions {
-  intensity: Array<{ label: string; value: any }>;
-  errorStorageType: Array<{ label: string; value: string }>;
-  [key: string]: any;
-}

package/template/.trae/skills/yss-page-module-development/examples/AdvancedFormPage/hooks/useRuleConfig.ts

@@ -1,158 +0,0 @@
-/**
- * 规则配置Hook
- * 处理表单逻辑、SQL解析、条件初始化等
- */
-import { reactive, ref, watch } from 'vue';
-import { message } from 'ant-design-vue';
-// 假设有 API 客户端
-import { getPomApi } from '@/api/generated/quality';
-import type { ConditionGroup } from '../constant';
-
-export function useRuleConfig() {
-  const api = getPomApi();
-
-  /** 校验范围条件数据 (树形结构) */
-  const conditionData = ref<ConditionGroup>({
-    id: 'root',
-    type: 'GROUP',
-    logicalOp: 'AND',
-    children: [],
-  });
-
-  /** 校验范围SQL预览值 */
-  const sqlFieldValue = ref('');
-
-  /** 校验配置条件数据 */
-  const checkConditionData = ref<ConditionGroup>({
-    id: 'root2',
-    type: 'GROUP',
-    logicalOp: 'AND',
-    children: [],
-  });
-
-  /** 校验配置SQL预览值 */
-  const checkSqlFieldValue = ref('');
-
-  /** 字段选项（给 YConditionBuilder 使用） */
-  const filterFieldsOptions = ref<Array<{ label: string; value: string; type?: string }>>([]);
-  const checkFieldsOptions = ref<Array<{ label: string; value: string }>>([]);
-
-  /** 规则操作符选项 */
-  const ruleOperatorOptions = ref<any[]>([]);
-
-  /** 加载状态 */
-  const loading = reactive({
-    generateSqlCondition: false,
-    generateCheckSqlCondition: false,
-    loadFields: false,
-  });
-
-  /**
-   * 加载字段选项
-   */
-  const loadFieldOptions = async (exceptionCountSql: string) => {
-    // 模拟 API 调用逻辑
-    if (!exceptionCountSql) {
-      message.warning('请先填写异常行数SQL');
-      return;
-    }
-    // ... API调用逻辑
-  };
-
-  /**
-   * 初始化条件构建器数据
-   */
-  const initConditionData = (conditionJson?: string, checkJson?: string) => {
-    if (conditionJson) {
-      try {
-        const parsed = JSON.parse(conditionJson);
-        conditionData.value = parsed;
-      } catch (e) {
-        console.error('解析失败', e);
-      }
-    }
-    if (checkJson) {
-      try {
-        const parsed = JSON.parse(checkJson);
-        checkConditionData.value = parsed;
-      } catch (e) {
-        console.error('解析失败', e);
-      }
-    }
-  };
-
-  /**
-   * 生成校验范围SQL
-   * (由前端 JSON 结构 -> 调用后端 -> 返回 SQL)
-   */
-  const handleGenerateSqlCondition = async (silent = false) => {
-    if (!conditionData.value?.children?.length) {
-      if (!silent) message.warning('请先配置校验范围');
-      return null;
-    }
-
-    try {
-      loading.generateSqlCondition = true;
-      const res = await api.parserSql(JSON.stringify(conditionData.value));
-      if (res?.data) {
-        sqlFieldValue.value = res.data;
-        if (!silent) message.success('生成成功');
-        return res.data;
-      }
-      return null;
-    } catch (e) {
-      console.error(e);
-      return null;
-    } finally {
-      loading.generateSqlCondition = false;
-    }
-  };
-
-  /**
-   * 生成校验表达式SQL
-   */
-  const handleGenerateCheckSqlCondition = async (silent = false) => {
-    if (!checkConditionData.value?.children?.length) {
-      if (!silent) message.warning('请先配置校验表达式');
-      return null;
-    }
-    // API logic...
-    return null; // Mock
-  };
-
-  /**
-   * 模拟加载操作符
-   */
-  const loadRuleOperatorOptions = async () => {
-    // Mock data
-    ruleOperatorOptions.value = [
-      { label: '等于', value: '=', kind: 'single' },
-      { label: '大于', value: '>', kind: 'single' },
-      { label: '包含', value: 'in', kind: 'multi' },
-    ];
-  };
-
-  // 辅助函数：根据输入筛选选项
-  const filterOptions = (options: any[], q: string) => {
-    if (!q) return options;
-    return options.filter(i => i.label?.includes(q) || i.value?.includes(q));
-  };
-
-  return {
-    conditionData,
-    sqlFieldValue,
-    checkConditionData,
-    checkSqlFieldValue,
-    filterFieldsOptions,
-    checkFieldsOptions,
-    ruleOperatorOptions,
-    loading,
-    getFilterFields: async (q: string) => filterOptions(filterFieldsOptions.value, q),
-    getCheckFields: async (q: string) => filterOptions(checkFieldsOptions.value, q),
-    loadFieldOptions,
-    loadRuleOperatorOptions,
-    initConditionData,
-    handleGenerateSqlCondition,
-    handleGenerateCheckSqlCondition,
-  };
-}

package/template/.trae/skills/yss-page-module-development/examples/AdvancedFormPage/index.vue

@@ -1,188 +0,0 @@
-<script setup lang="ts">
-import { onMounted, computed, ref, reactive } from 'vue';
-import { Steps, Spin } from 'ant-design-vue';
-import { YCard, YButton, YConditionBuilder, YFormily } from '@yss-ui/components';
-import { QUALITY_RULE_STEPS, RULE_STEPS } from './constant';
-import { ruleConfigSchema } from './schemas/ruleConfigSchema';
-import { useRuleConfig } from './hooks/useRuleConfig';
-
-defineOptions({ name: 'AdvancedFormPage' });
-
-// 状态管理
-const currentStep = ref(RULE_STEPS.RULE_CONFIG);
-const formData = ref<any>({
-  intensity: 'WEAK',
-  errorStorage: true,
-  errorStorageLimit: 1000,
-  errorStorageType: 'FILE_SYSTEM',
-});
-
-// 表单选项
-const formOptions = reactive({
-  intensity: [
-    { label: '弱规则', value: 'WEAK' },
-    { label: '强规则', value: 'STRONG' },
-  ],
-  errorStorageType: [
-    { label: '文件服务', value: 'FILE_SYSTEM' },
-    { label: '数据落地表', value: 'DATATABLE_SYSTEM' },
-  ],
-});
-
-// 引入业务 Hook
-const {
-  conditionData,
-  sqlFieldValue,
-  checkConditionData,
-  checkSqlFieldValue,
-  ruleOperatorOptions,
-  getFilterFields,
-  getCheckFields,
-  handleGenerateSqlCondition,
-  handleGenerateCheckSqlCondition,
-  loading: ruleConfigLoading,
-  loadRuleOperatorOptions,
-} = useRuleConfig();
-
-// Refs
-const ruleConfigFormRef = ref();
-const conditionFilterRef = ref();
-const checkConditionRef = ref();
-
-// 初始化
-onMounted(() => {
-  loadRuleOperatorOptions();
-});
-
-// 计算属性：Schema
-const ruleConfigSchemaComputed = computed(() => ruleConfigSchema(formOptions));
-
-// 按钮事件处理
-/**
- * 生成校验范围SQL（带前置表单校验）
- * CRITICAL: 必须先触发表单校验，通过后再执行业务逻辑
- */
-const handleGenerateSqlConditionWithValidate = async () => {
-  // 1. 先触发 YFormily 表单校验
-  const formValid = await ruleConfigFormRef.value?.submit();
-  if (!formValid) {
-    // 表单校验失败，YFormily 会自动显示错误信息
-    return;
-  }
-
-  // 2. 再校验条件构建器本身（如果有）
-  const isValid = conditionFilterRef.value?.validate?.() ?? true;
-  if (!isValid) {
-    return;
-  }
-
-  // 3. 调用生成逻辑
-  await handleGenerateSqlCondition();
-};
-
-/**
- * 生成校验表达式SQL（带前置表单校验）
- */
-const handleGenerateCheckSqlConditionWithValidate = async () => {
-  // 同样的逻辑
-  const formValid = await ruleConfigFormRef.value?.submit();
-  if (!formValid) return;
-
-  const isValid = checkConditionRef.value?.validate?.() ?? true;
-  if (!isValid) return;
-
-  await handleGenerateCheckSqlCondition();
-};
-</script>
-
-<template>
-  <div class="complex-form-create">
-    <!-- 1. 步骤条 -->
-    <YCard class="steps-card">
-      <Steps :current="currentStep - 1">
-        <Steps.Step v-for="item in QUALITY_RULE_STEPS" :key="item.value" :title="item.title" />
-      </Steps>
-    </YCard>
-
-    <!-- 2. 表单内容区 -->
-    <YCard class="content-card">
-      <!-- 这里只展示第二步：规则配置 -->
-      <div v-show="currentStep === RULE_STEPS.RULE_CONFIG">
-        <YFormily ref="ruleConfigFormRef" v-model="formData" :schema="ruleConfigSchemaComputed">
-          <!-- 插槽1：校验范围构建器 -->
-          <template #conditionFilter>
-            <YConditionBuilder
-              ref="conditionFilterRef"
-              v-model="conditionData"
-              :load-fields="getFilterFields"
-              :operator-options="ruleOperatorOptions"
-            />
-          </template>
-
-          <!-- 插槽2：SQL 预览区 -->
-          <template #sqlField>
-            <div class="sql-preview-section">
-              <div class="sql-preview-content">
-                <pre v-if="sqlFieldValue" class="sql-code">{{ sqlFieldValue }}</pre>
-                <div v-else class="sql-placeholder">
-                  <span>SQL预览（配置校验范围后自动生成）</span>
-                </div>
-              </div>
-              <div class="sql-preview-actions">
-                <YButton
-                  type="primary"
-                  :loading="ruleConfigLoading.generateSqlCondition"
-                  @click="handleGenerateSqlConditionWithValidate"
-                >
-                  生成校验范围
-                </YButton>
-              </div>
-            </div>
-          </template>
-
-          <!-- 插槽3：校验配置构建器 -->
-          <template #checkCondition>
-            <YConditionBuilder
-              ref="checkConditionRef"
-              v-model="checkConditionData"
-              :load-fields="getCheckFields"
-              :operator-options="ruleOperatorOptions"
-            />
-          </template>
-
-          <!-- 插槽4：校验SQL 预览区 -->
-          <template #checkSqlField>
-            <div class="sql-preview-section">
-              <!-- 复用样式结构，实际项目中可封装为组件 -->
-              <div class="sql-preview-content">
-                <pre v-if="checkSqlFieldValue" class="sql-code">{{ checkSqlFieldValue }}</pre>
-                <div v-else class="sql-placeholder">
-                  <span>SQL预览（配置校验表达式后自动生成）</span>
-                </div>
-              </div>
-              <div class="sql-preview-actions">
-                <YButton
-                  type="primary"
-                  :loading="ruleConfigLoading.generateCheckSqlCondition"
-                  @click="handleGenerateCheckSqlConditionWithValidate"
-                >
-                  生成校验表达式
-                </YButton>
-              </div>
-            </div>
-          </template>
-        </YFormily>
-      </div>
-    </YCard>
-
-    <!-- 3. 底部按钮 -->
-    <div class="footer-actions">
-      <YButton>上一步</YButton>
-      <YButton type="primary">完成</YButton>
-    </div>
-  </div>
-</template>
-
-<style lang="less" scoped>
-@import './style.less';
-</style>