create-yss-spec 2.2.0 → 2.2.2

package/template/.agents/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 };
+};

package/template/.agents/skills/page-skeleton/examples/StandardListPage/index.vue

@@ -0,0 +1,91 @@
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { Input as AInput } from 'ant-design-vue';
+import { YButton, YCard, YTable } from '@yss-ui/components';
+import { useTableHeight } from '@yss-ui/hooks';
+import { TABLE_COLUMNS, type QualityRuleItem } from './constant';
+import { useQualityRuleList } from './hooks/useQualityRuleList';
+import { useRuleActions } from './hooks/useRuleActions';
+
+defineOptions({ name: 'StandardListPage' });
+
+const emit = defineEmits<{
+  create: [];
+  edit: [row: QualityRuleItem];
+  view: [row: QualityRuleItem];
+}>();
+
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight, isReady } = useTableHeight(tableAreaRef, {
+  withPagination: true,
+  withToolbar: true,
+});
+const { tableData, loading, pagination, searchForm, fetchList, handlePageChange, handleSearch, handleReset } =
+  useQualityRuleList();
+const { actionConfig, handleCreate } = useRuleActions({
+  refreshList: fetchList,
+  onCreate: () => emit('create'),
+  onEdit: row => emit('edit', row),
+  onView: row => emit('view', row),
+});
+
+/** 查看规则详情。 */
+const handleRuleNameClick = (row: QualityRuleItem): void => {
+  emit('view', row);
+};
+
+onMounted(() => {
+  void fetchList();
+});
+</script>
+
+<template>
+  <div class="quality-rule-page">
+    <YCard class="quality-rule-page__search-card">
+      <div class="quality-rule-page__search-content">
+        <AInput
+          v-model:value="searchForm.ruleName"
+          class="quality-rule-page__keyword"
+          placeholder="请输入规则名称"
+          allow-clear
+          @press-enter="handleSearch"
+        />
+        <div class="quality-rule-page__search-actions">
+          <YButton @click="handleReset">重置</YButton>
+          <YButton type="primary" :loading="loading" @click="handleSearch">查询</YButton>
+        </div>
+      </div>
+    </YCard>
+
+    <YCard class="quality-rule-page__table-card">
+      <div ref="tableAreaRef" class="quality-rule-page__table-area">
+        <YTable
+          v-if="isReady"
+          :data="tableData"
+          :columns="TABLE_COLUMNS"
+          :loading="loading"
+          :height="tableHeight"
+          :action-config="actionConfig"
+          :toolbar-config="{ custom: true }"
+          pageable
+          v-model:pagination="pagination"
+          @page-change="handlePageChange"
+        >
+          <template #toolbar-right>
+            <YButton @click="fetchList">刷新</YButton>
+            <YButton type="primary" @click="handleCreate">新增质量规则</YButton>
+          </template>
+          <template #ruleName="{ row }">
+            <button class="quality-rule-page__rule-link" type="button" @click="handleRuleNameClick(row)">
+              {{ row.ruleName ?? '-' }}
+            </button>
+          </template>
+        </YTable>
+      </div>
+    </YCard>
+  </div>
+</template>
+
+<style scoped lang="less">
+@import url('./style.less');
+</style>

package/template/.agents/skills/page-skeleton/examples/StandardListPage/style.less

@@ -0,0 +1,49 @@
+.quality-rule-page {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  gap: 12px;
+
+  &__search-content {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+
+  &__keyword {
+    width: min(100%, 360px);
+  }
+
+  &__search-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 8px;
+  }
+
+  &__table-card,
+  &__table-area {
+    flex: 1;
+    min-height: 0;
+  }
+
+  &__rule-link {
+    padding: 0;
+    color: var(--primary-color, #3371ff);
+    background: transparent;
+    border: 0;
+    cursor: pointer;
+
+    &:hover,
+    &:focus-visible {
+      color: var(--primary-color-hover, #4096ff);
+      text-decoration: underline;
+    }
+
+    &:focus-visible {
+      outline: 2px solid color-mix(in srgb, var(--primary-color, #3371ff) 35%, transparent);
+      outline-offset: 2px;
+    }
+  }
+}

package/template/.agents/skills/prototype-page-acceptance/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: prototype-page-acceptance
+description: 当用户提供原型截图、老项目路径、旧页面截图或要求按既有页面复刻业务页面时，指导先提取视觉和交互验收清单，开发后用截图/运行结果逐项对照，避免只实现字段而忽略布局、按钮、表格高度和控件类型。
+---
+
+# 原型页面还原验收 Skill
+
+## 触发条件
+
+- 用户提供原型图、截图、设计稿、旧项目 view/logic/service 路径。
+- 用户要求“参考老项目、照原型、复刻页面、保持和旧系统一致”。
+- 开发结果需要人工视觉对照，而不只是接口和类型正确。
+
+## 不适用场景
+
+- 纯逻辑修复、纯 API 对接、无 UI 改动。
+- 用户明确要求自由设计，不需要贴近旧页面。
+- 组件库内部能力开发，不涉及业务页面还原。
+
+## 硬约束（禁止/必须）
+
+- 开发前必须打开用户给出的旧项目 view 文件、相关 logic/service 文件和当前项目相近页面，不得只看接口。
+- 必须把截图/旧页面拆成验收清单：查询区布局、按钮位置、表格工具栏、表格高度/分页、操作列、弹窗/抽屉尺寸、表单 label 宽度和对齐、FormGrid 响应式、字段控件类型。
+- Vue3 + YSS UI 列表查询区默认验收“字段在上、查询/重置按钮独占下一行并右对齐”；缩放或窄屏导致字段换行时，按钮必须仍在搜索卡片右下角，不得贴在第一行字段旁。
+- 若截图里出现但需求文字没写的通用交互（查询/重置、表格列设置、新增按钮位置、分页器、抽屉底部按钮），默认按截图实现。
+- 不允许用“用户没说”跳过截图里明显存在的 UI；只有业务含义不明时才询问。
+- 开发后必须运行页面或至少完成类型/构建检查；可运行时必须截图对照首屏和关键弹窗/抽屉。
+- 交付说明必须列出“已对照原型的验收项”和“未能验证的项”。
+
+## 标准代码骨架
+
+```text
+原型验收清单：
+- 查询区：字段数量、FormGrid 响应式列数、label 固定宽度和右对齐、查询/重置按钮右下角位置，缩窄后按钮不贴第一行字段。
+- 表格区：YTable、toolbar-config.custom、#toolbar-right 新增按钮、分页、无底部大空白。
+- 操作列：按钮可见条件、更多菜单、删除气泡确认文案。
+- 抽屉/弹窗：响应式宽度、底部按钮、查看态只读、label 右对齐且宽度统一、缩窄时 2 列变 1 列、备注/长文本占满行。
+- 编辑表格：使用 YEditTable，列控件类型、可输入/多选、添加行/删除行、校验。
+```
+
+```text
+验收输出：
+- 通过：查询区三列栅格，查询/重置按钮独占下一行并右对齐；缩窄到字段两行或三行时按钮仍在搜索卡片右下角。
+- 通过：表格工具栏右侧为新增和列设置按钮，分页贴底显示，无大空白。
+- 通过：抽屉宽度使用 min(90vw, 1200px)，labelWidth 固定且右对齐，FormGrid 从 2 列响应式收缩为 1 列，查看态不显示保存。
+- 未验证：后端真实数据返回为空，仅用 mock/空态验证布局。
+```
+
+## 交付检查清单
+
+- [ ] 已读取旧项目 view/logic/service 或当前相近页面。
+- [ ] 已把截图中可见 UI 转成验收清单。
+- [ ] 查询/重置按钮右下角布局、表格工具栏、新增按钮、分页和空白高度已对照。
+- [ ] 抽屉/弹窗响应式、label 宽度和右对齐、FormGrid 换列、底部按钮已对照。
+- [ ] 编辑表格控件类型、可输入/多选、添加/删除已对照。
+- [ ] 已运行类型检查、构建或浏览器截图验证，并说明未验证项。
+
+## 失败兜底策略
+
+- 旧项目代码太复杂时，先提取最终 UI 结构和字段映射，再复用当前项目组件实现。
+- 截图与文字需求冲突时，优先按文字业务规则，UI 布局仍尽量按截图；冲突点写入交付说明。
+- 无法运行项目时，至少执行静态类型检查并逐项说明哪些视觉项未验证。

package/template/.agents/skills/theme-token-usage/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: theme-token-usage
+description: 指导 Vue3 YSS UI 微应用业务页面、公共组件、原型还原和主题修复使用可动态换肤的 CSS/Ant Design Token，覆盖主色、hover/active/selected/focus、状态色、中性色、透明色派生和暗色模式；当新增或修改 .vue、style.less、内联样式、TS 渲染配置、SVG 色值，或审查硬编码 #hex/rgb/渐变时使用。
+---
+
+# YSS UI 主题 Token 使用 Skill
+
+## 触发条件
+
+- 新增、重构或按原型实现 Vue3 业务页面、公共组件、布局、卡片、树、表格、表单、抽屉和详情页。
+- 修改 `.vue`、`.less`、`.css`、`.scss`、TS/TSX 渲染配置或 SVG 中的颜色、背景、边框、阴影、渐变。
+- 页面需要跟随主应用主题、JSP 预设主题、暗色模式或运行时主色切换。
+- 评审或修复 `#1677ff`、`#3371ff`、`rgb/rgba/hsl` 等硬编码色值。
+
+## 不适用场景
+
+- 只维护主题源文件中的默认值或主题预设，例如 `variables.less`、`store/theme.ts`、`config/themes.ts`。
+- 用户明确要求不可换肤的品牌插画、数据可视化固定色板或第三方资产原色；仍需在代码中注明固定色语义。
+- 只修改与视觉无关的类型、接口或纯业务逻辑。
+
+## 开发前检查
+
+1. 读取当前微应用的 `packages/src/styles/variables.less`、主题 store/config 和相近页面，确认真实 Token 名称与运行时同步逻辑。
+2. 确认主应用传入的 `colorPrimary` 最终是否同步到 Ant Design ConfigProvider、YSS CSS 变量和 VXE 变量。
+3. 搜索本次改动涉及的硬编码色值，覆盖 SFC style、`style.less`、内联 `style`、`:style`、TS 配置、SVG `fill/stroke`。
+4. 区分“主题消费代码”和“主题定义代码”；禁止机械替换主题源文件中的合法默认色板。
+
+> 变量在 `:root` 中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量。
+
+## Token 选择
+
+按以下优先级选值：
+
+| 语义 | 优先使用 | 兼容选择 |
+| --- | --- | --- |
+| 主色 | `var(--primary-color, #3371ff)` | `var(--yss-color-primary-6, #3371ff)` |
+| hover | `var(--primary-color-hover, #4096ff)` | `var(--yss-color-primary-5, #4096ff)` |
+| active | `var(--primary-color-active, #0958d9)` | `var(--yss-color-primary-7, #0958d9)` |
+| 成功/警告/错误/信息 | `--success-color` / `--warning-color` / `--error-color` / `--info-color` | 对应 `--yss-color-*-6` |
+| 正文/次要文字 | `--text-color` / `--text-color-secondary` | 使用项目已有语义 Token |
+| 容器/页面背景 | `--bg-color-container` / `--bg-color` | 使用项目已有语义 Token |
+| 边框/分割线 | `--border-color` / `--border-color-split` | 使用项目已有语义 Token |
+| 反色文字 | `--text-color-inverse` | 不直接写 `#fff` |
+
+需要主色透明背景、focus ring 或阴影时，从真实主色动态派生：
+
+```less
+background: color-mix(in srgb, var(--primary-color, #3371ff) 10%, transparent);
+box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, transparent);
+```
+
+仅当主题同步逻辑明确维护 `--primary-1` 时才可使用 `var(--primary-1)`。禁止用带蓝色 fallback 的 `var(--primary-1, rgba(...))` 冒充动态主题；变量未同步时，红色等主题仍会回落为蓝色。
+
+## 硬约束（禁止/必须）
+
+- 必须优先让 `YButton`、`YTable`、`YTree`、`YFormily` 和 Ant Design Vue 组件消费 ConfigProvider 主题；非必要不覆盖其主色样式。
+- 业务消费代码禁止直接写品牌蓝、主题红及其 hover/active/selected/focus 色阶，包括十六进制、`rgb/rgba/hsl`、渐变和阴影。
+- 必须使用语义 Token；禁止仅按“颜色长得接近”替换，例如把错误态改成主色。
+- `var()` fallback 必须与项目默认 Token 一致；fallback 只负责兼容，不得成为实际换肤来源。
+- 禁止在页面局部随意发明 `--primary-light` 等新变量。确需新增时，必须在统一主题源声明，并在运行时主题同步链路中更新。
+- 禁止对 CSS 变量使用 Less 编译期颜色函数，例如 `fade(@primary-color, 10%)`；`@primary-color` 指向 `var()` 时无法可靠计算。
+- 禁止写 `rgba(var(--primary-color), 0.1)`；十六进制 CSS 变量不能直接作为 `rgba()` 通道参数。
+- 固定数据可视化色板、品牌资产原色或遮罩色允许保留，但必须与换肤语义无关，并添加中文说明。
+- 新增交互样式时必须覆盖 default、hover、active、selected、focus、disabled 中实际存在的状态。
+
+## 标准代码骨架
+
+```less
+@import url('@/styles/variables.less');
+
+.module-card {
+  color: var(--text-color, rgba(0, 0, 0, 0.88));
+  background: var(--bg-color-container, #fff);
+  border: 1px solid var(--border-color-split, #f0f0f0);
+
+  &__link {
+    color: var(--primary-color, #3371ff);
+
+    &:hover {
+      color: var(--primary-color-hover, #4096ff);
+    }
+  }
+
+  &.is-selected {
+    color: var(--primary-color, #3371ff);
+    background: color-mix(in srgb, var(--primary-color, #3371ff) 10%, transparent);
+    border-color: var(--primary-color, #3371ff);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, transparent);
+  }
+}
+```
+
+仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用 Ant Design Vue `theme.useToken()`；若消费微应用 CSS 变量，则通过 `getComputedStyle(document.documentElement)` 读取，不复制默认色板到业务常量。
+
+## 验证流程
+
+1. 扫描本次变更中的 `#hex`、`rgb/rgba`、`hsl/hsla`、渐变和 SVG 色值，逐项说明保留理由或替换为 Token。
+2. 至少使用默认主色和一个明显不同的主色（例如红色）验证页面。
+3. 检查文字、链接、图标、边框、背景、阴影以及 hover/active/selected/focus 状态是否同步变化。
+4. 项目支持暗色模式时，再验证正文、次要文字、容器背景和边框；不得只验证主色。
+5. 有原型截图时，主题适配与视觉还原必须同时通过，不能为像素接近而写死色值。
+
+## 交付检查清单
+
+- [ ] 已检查项目真实主题入口、Token 声明与运行时同步链路。
+- [ ] 业务页面未硬编码品牌色及其交互态色阶。
+- [ ] 主色透明态来自可动态更新的 Token，不依赖未同步的 `--primary-1` fallback。
+- [ ] 状态色、中性色、容器背景和边框使用正确语义 Token。
+- [ ] 已检查 SFC、Less、内联样式、TS 配置和 SVG，不只检查 `style.less`。
+- [ ] 已用至少两种差异明显的主题色验证实际效果。
+- [ ] 项目支持暗色模式时已完成暗色验收。
+- [ ] 保留的固定色值均有明确、合理的非换肤语义。
+
+## 失败兜底策略
+
+- 找不到 Token 时，先查项目 `variables.less`、主题 store/config 和 `llms-full.txt`；禁止猜测变量名。
+- 只有颜色值但没有语义 Token 时，先在统一主题源补充语义变量和运行时同步，再在页面消费。
+- 第三方组件不跟随主题时，优先通过 ConfigProvider/component token 或其官方 CSS 变量桥接；最后才使用受控的深度样式覆盖。
+- 浏览器目标不支持 `color-mix()` 时，在主题层生成并同步明确的透明态变量；不要在各页面散落固定透明色。

package/template/.agents/skills/theme-token-usage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "YSS UI 主题 Token 使用"
+  short_description: "约束业务页面使用可动态换肤的主题 Token，禁止硬编码品牌色"
+  default_prompt: "使用 $theme-token-usage 检查并实现页面样式，确保主题色、状态色和明暗模式可动态切换。"

package/template/.agents/skills/vue3-best-practices/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: vue3-best-practices
+description: 在 Vue3 业务页面、组件和 composable 中规范响应式状态、组件通信、异步竞态与大数精度；实现或重构 Vue3 逻辑时使用。
+---
+
+# Vue3 Best Practices Skill
+
+## 触发条件
+
+- 业务页面出现响应式、组件通信、状态管理相关问题。
+- 需要重构复杂组件逻辑到更稳的 Composition API 模式。
+- 需要防止 `v-model`、`watch`、`reactive/ref` 常见误用。
+
+## 不适用场景
+
+- 纯样式调整，无状态逻辑修改。
+- 仅写提交信息，不涉及代码实现。
+- 仅做接口层封装，不涉及 Vue 组件行为。
+
+## 硬约束（禁止/必须）
+
+- 禁止直接修改 `props`，必须使用 `emit('update:xxx')`。
+- 禁止在模板层写复杂业务逻辑，必须下沉到 `computed` 或 hook。
+- 必须避免深层 watch 滥用，优先明确依赖源。
+- 必须对异步请求做取消或竞态保护，避免旧请求覆盖新状态。
+- 必须在复杂页面中拆 composable，禁止单文件耦合所有逻辑。
+- 导出函数、composable、接口、类型与常量必须使用中文 JSDoc。
+- 接口默认错误由 mutator 统一提示并 reject；业务逻辑只做状态恢复或错误转换，禁止在 `catch` 重复 `message.error`，除非请求显式设置了 `skipErrorHandler`。
+- 在 hook/computed/watch 等业务逻辑里使用接口返回的 number 字段（id、主键、金额、数量等）时，禁止用 `Number()`/`parseInt`/`parseFloat`/`+x`/`*1`/`~~` 做任何数字转换，一律按字符串透传与比较；确需高精度数值计算时用 `decimal.js`/`big.js` 以字符串入参。底层 json-bigint 已存为字符串保精度，详见 `../yss-api-integration/SKILL.md`「大数字与精度」。
+
+## 标准代码骨架
+
+```typescript
+const props = defineProps<{ modelValue: string }>();
+const emit = defineEmits<{ 'update:modelValue': [value: string] }>();
+
+const localValue = computed({
+  get: () => props.modelValue,
+  set: value => emit('update:modelValue', value),
+});
+
+const loading = ref(false);
+
+/** 请求数据并维护加载状态。 */
+const fetchData = async () => {
+  loading.value = true;
+  try {
+    await api();
+  } finally {
+    loading.value = false;
+  }
+};
+```
+
+## 交付检查清单
+
+- [ ] `props` 单向数据流未被破坏。
+- [ ] `v-model` 实现使用标准 `update:*` 事件。
+- [ ] 异步逻辑具备 loading 与异常处理。
+- [ ] 复杂逻辑已拆分到 composable。
+- [ ] 接口返回的 number 字段在逻辑中保持字符串透传，未被 `Number()`/`parseInt`/`+x` 等转换。
+- [ ] 模板表达式简洁，便于维护和测试。
+
+## 失败兜底策略
+
+- 响应式异常时，先定位是 `ref`/`reactive` 选型问题还是解构丢响应。
+- 双向绑定异常时，先检查 `emit` 事件名和参数签名。
+- 组件过重时，先抽离状态 hook，再处理视觉拆分。