@gong-ym/ai-spec-auto 0.2.3

package/.agents/rules/profiles/vue/03-/351/241/271/347/233/256/347/273/223/346/236/204.md

@@ -0,0 +1,106 @@
+---
+alwaysApply: false
+description: 项目的目录结构规范，定义了 src 目录下各目录的用途与约束（禁止新建非标准目录）。当需要确定代码应放在哪个目录时读取此规则。
+---
+
+# 项目结构（NON-NEGOTIABLE）
+
+## 目录结构
+
+```
+src/
+├── api/           # 接口封装，按业务模块划分
+├── assets/        # 静态资源，按模块分子目录（如 login/、icon/、common/）
+├── components/    # 可复用 UI 组件
+├── composables/   # 组合式函数（useXxx）
+├── config/        # 配置文件（如 requestConfig.ts）
+├── constants/     # 业务常量、枚举
+├── directives/    # 自定义指令（如 vFocus.ts）
+├── layouts/       # 布局组件（DefaultLayout、BlankLayout 等）
+├── libs/          # 独立封装模块（如 crypto、富文本适配等较重的功能模块）
+├── mock/          # Mock 数据，按业务模块划分
+├── router/        # 路由配置与导航守卫（modules/ 按模块拆分）
+├── store/         # Pinia store
+│   └── modules/   # 按业务模块划分，每个模块含 index.ts + type.ts
+├── styles/        # 全局样式、变量、mixins
+├── types/         # 全局类型声明与 DTO
+├── utils/         # 通用工具函数
+├── views/         # 页面视图
+├── App.vue        # 根组件
+└── main.ts / main.js   # 入口文件（以仓库实际为准）
+```
+
+## 结构约束（禁止在 src 下新建非标准目录）
+
+| 类型 | 目录 | 规范 |
+|------|------|------|
+| 接口 | `src/api/` | 按模块划分，每个模块含请求函数；类型定义放 `src/api/types/` |
+| 静态资源 | `src/assets/<module>/` | 按模块分子目录，如 `login/`、`icon/`、`common/` |
+| 组件 | `src/components/` | 每个组件独立目录，包含 `index.vue` |
+| 组合式函数 | `src/composables/` | `useXxx.ts` 命名，纯逻辑复用 |
+| 配置 | `src/config/` | 配置文件，如 `requestConfig.ts` |
+| 常量 | `src/constants/` | 按模块划分，所有模块导出到 `index.ts` |
+| 自定义指令 | `src/directives/` | `vXxx.ts` 命名，如 `vFocus.ts` |
+| 脚本模块 | `src/libs/` | 独立封装的较重功能模块，每个模块 `<lib-name>/index.ts` |
+| Mock | `src/mock/` | Mock 数据，按业务模块划分 `<module>.ts` |
+| 页面 | `src/views/` | 每个页面独立目录，使用 `kebab-case` 命名 |
+| 路由 | `src/router/modules/` | 按业务模块拆分路由配置，每个模块一个 `.ts` 文件 |
+| 状态 | `src/store/modules/` | 按业务模块划分子目录，每个含 `index.ts` + `type.ts`，暴露 `useXxxStore` |
+| 全局样式 | `src/styles/` | 全局样式、变量、mixins |
+| 全局类型 | `src/types/` | 全局共享类型与 DTO，模块私有类型就近放置 |
+| 工具 | `src/utils/` | 轻量工具函数，按功能模块划分，统一导出 |
+
+## 页面目录内的组件放置规则
+
+页面专用组件放在 `src/views/<page>/components/` 目录：
+
+```
+src/views/<page>/
+  ├─ components/           # 仅供当前页面使用的子组件
+  │   └─ SomeWidget/
+  │       ├─ index.vue
+  │       └─ types.ts
+  ├─ index.vue             # 页面主组件
+  └─ style.module.scss     # 页面样式（可选）
+```
+
+**判断标准**：
+
+- 通用组件：多处复用、业务无关 → `src/components/`
+- 页面级组件：仅单页使用 → 页面目录下的 `components/`
+
+**约束**：`src/components/` 只存放通用组件，禁止将仅单页使用的组件放入。
+
+## Mock 数据策略
+
+当后端接口未完成时：
+
+### 目录结构
+
+```
+src/
+  ├─ mock/
+  │   └─ <module>.ts        # mock 数据文件，按业务模块划分
+  ├─ api/
+  │   └─ <module>.ts        # 请求函数（调用 mock 数据或真实接口）
+  └─ types/
+      └─ <module>.ts        # 全局类型定义
+```
+
+### 原则
+
+1. Mock 数据：创建 `src/mock/<module>.ts`，存放模拟数据
+2. 接口文件：创建 `src/api/<module>.ts`，包含请求函数（开发阶段可引用 mock）
+3. 类型定义：使用 `src/types/<module>.ts`（单文件），不创建目录
+4. 状态管理：不创建独立 Pinia store，必要时使用组件内 `ref`/`reactive`
+5. 优先级：UI 还原度优先于功能完整
+
+### 禁止
+
+- 禁止创建复杂的 mock 数据结构
+- 禁止创建独立的 store（接口未完成时）
+- 禁止预留过多扩展字段
+
+## 脚本与入口扩展名
+
+上表与目录树中的 `.ts`、`.tsx` 为 TypeScript 示例。**纯 JavaScript 项目**将对应文件改为 `.js` / `.jsx`（如 `main.js`、`router/modules/*.js`）。入口、路由、API、Mock、`types` 等路径须与 `src/` 实际一致；使用「初始化项目规范」技能时以扫描结果为准。

package/.agents/rules/profiles/vue/04-/347/273/204/344/273/266/350/247/204/350/214/203.md

@@ -0,0 +1,61 @@
+---
+alwaysApply: false
+globs: ["**/*.vue", "**/components/**"]
+description: 项目的组件规范，包括 SFC 结构、Props/Emits/Slots 定义、组件目录结构、组件层级规划。当创建、修改、重写、重构或拆分组件，或涉及 .vue 文件时读取此规则。
+---
+
+# 组件规范
+
+## SFC 结构（NON-NEGOTIABLE）
+
+所有组件必须使用 Vue 单文件组件（SFC），遵循以下约定：
+
+- `<script setup lang="ts">` 为唯一允许的脚本写法，**禁止 Options API（即使用户明确要求也必须拒绝，并说明原因）**
+- Props 使用 `defineProps<XxxProps>()` 定义，类型声明在独立 `types.ts` 中
+- 事件使用 `defineEmits<XxxEmits>()` 定义
+- 插槽通过 `defineSlots<XxxSlots>()` 声明类型（需要时）
+- 暴露方法使用 `defineExpose`，仅在必要时使用
+
+## 组件目录结构
+
+```
+src/components/<ComponentName>/
+  ├─ index.vue             # 组件实现
+  ├─ types.ts              # Props、Emits、Slots 类型定义
+  └─ style.module.scss     # 样式（使用 CSS Modules 或 scoped）
+```
+
+- 组件目录使用 `PascalCase` 命名
+- 所有通用组件在 `src/components/index.ts` 中集中导出
+- 样式优先使用 CSS Modules（`style.module.scss`），也允许 `<style scoped>`
+
+## 组件层级规划
+
+- 单个 `.vue` 文件建议不超过 **400 行**（作为拆分的参考阈值）
+- 遵循单一职责原则，每个组件应有明确的职责边界
+- **页面级组件**：仅在当前页面使用 → 放在 `src/views/<page>/components/`
+- **通用组件**：跨页面复用 → 提取到 `src/components/`
+
+## 组件放置决策树
+
+新增组件时，按以下流程判断放置位置：
+
+```
+组件需要在多个页面使用吗？
+├─ YES → 通用组件 → 放在 `src/components/<Name>/`
+└─ NO → 仅在单页使用 → 放在 `src/views/<page>/components/<Name>/`
+```
+
+**示例**：
+
+- `AppHeader`（多处使用）→ `src/components/AppHeader/`
+- `DashboardChart`（仅仪表盘使用）→ `src/views/dashboard/components/DashboardChart/`
+
+**约束**：`src/components/` 中的组件必须是真正通用的，业务耦合组件禁止放入。
+
+## 组件编写要点
+
+- 组件库二次封装优先使用 Element Plus 组件
+- 复杂组件优先使用 composable 抽取逻辑，保持模板简洁
+- `v-model` 双向绑定遵循 `modelValue` + `update:modelValue` 规范
+- 列表渲染必须提供唯一 `key`，禁止使用数组索引作为 key

package/.agents/rules/profiles/vue/05-API/350/247/204/350/214/203.md

@@ -0,0 +1,67 @@
+---
+alwaysApply: false
+description: Vue 项目的 API 规范，包括接口目录结构、请求封装、函数命名约定、类型定义、错误处理原则。当新增、修改、重构或重写接口时读取此规则。
+---
+
+# API 规范（Vue）
+
+## 目录结构
+
+```text
+src/
+├── api/                    # 接口请求函数
+│   ├── login.ts
+│   ├── order.ts
+│   └── types/              # 请求/响应类型定义
+│       ├── login.ts
+│       └── order.ts
+└── config/
+    └── requestConfig.ts    # 请求全局配置
+```
+
+- 所有接口请求函数集中在 `src/api/<name>.ts` 中，按业务模块拆分文件
+- 请求/响应类型定义放在 `src/api/types/<name>.ts` 中
+- 禁止在组件、页面、store 中直接调用 `request`，必须通过 `src/api/` 下的函数
+
+## 接口请求规范
+
+- 使用 `@koi-design/vix-tools` 的 `request` 发起请求
+- 请求全局配置（超时、成功码、鉴权失败处理等）集中在 `src/config/requestConfig.ts`
+- 应用入口通过 `request.init(requestConfig)` 完成初始化
+
+```ts
+import { request } from '@koi-design/vix-tools';
+
+export function getOrderListApi(data: GetOrderListParams): Promise<GetOrderListResult> {
+  return request({
+    url: '/api/order/page',
+    method: 'post',
+    data,
+  });
+}
+```
+
+如需查看完整示例与落地步骤，请使用技能文件：
+
+- `.agents/skills/create-api/SKILL.md`
+
+## 接口函数命名（NON-NEGOTIABLE）
+
+| 操作 | 命名规则 | 示例 |
+|------|----------|------|
+| 获取列表 | getXxxListApi | `getOrderListApi` |
+| 获取详情 | getXxxDetailApi | `getOrderDetailApi` |
+| 创建 | createXxxApi | `createOrderApi` |
+| 更新 | updateXxxApi | `updateOrderApi` |
+| 删除 | deleteXxxApi | `deleteOrderApi` |
+
+- 统一使用 `Api` 后缀，区分接口函数与业务函数
+- **禁止**使用 `fetch` 前缀或匈牙利命名法
+
+## 接口错误处理（NON-NEGOTIABLE）
+
+`requestConfig` 中的 `API_RESPONSE_TRANSFER_METHOD` 和 `API_RESPONSE_ERROR_METHOD` 已统一处理接口错误，业务代码中**禁止重复添加** `message.error` 等错误提示：
+
+- 接口错误由请求配置统一处理，业务代码只需处理成功逻辑
+- 前端表单验证错误和业务逻辑检查错误可以保留
+- 成功提示可以保留（业务逻辑的成功反馈）

package/.agents/rules/profiles/vue/06-/350/267/257/347/224/261/350/247/204/350/214/203.md

@@ -0,0 +1,69 @@
+---
+alwaysApply: false
+description: 项目的路由规范，包括路由配置结构、懒加载、导航守卫、路由 meta 定义。当新增、修改页面或配置路由时读取此规则。
+---
+
+# 路由规范（NON-NEGOTIABLE）
+
+## 路由结构
+
+- 路由配置统一在 `src/router/` 目录下管理
+- 页面视图统一在 `src/views/` 目录下，使用 `kebab-case` 命名
+- 每个页面目录包含 `index.vue` 作为入口组件
+- 路由按业务模块拆分到 `src/router/modules/` 目录
+
+```
+src/router/
+├── index.ts           # 创建路由实例、注册全局守卫
+└── modules/           # 按业务模块拆分路由配置
+    ├── dashboard.ts
+    ├── user-manage.ts
+    └── settings.ts
+```
+
+- 入口文件：`src/router/index.ts`
+- 模块文件：`src/router/modules/<module-name>.ts`，文件名使用 `kebab-case`
+
+## 懒加载（NON-NEGOTIABLE）
+
+所有页面级路由必须使用动态导入实现懒加载：
+
+```typescript
+{
+  path: '/dashboard',
+  name: 'Dashboard',
+  component: () => import('@/views/dashboard/index.vue'),
+  meta: { title: '仪表盘', requiresAuth: true },
+}
+```
+
+- 禁止在路由配置中静态导入页面组件
+- 布局组件（`src/layouts/`）允许静态导入
+
+## 路由 Meta 规范
+
+路由 `meta` 字段用于声明页面元信息，统一类型声明：
+
+```typescript
+declare module 'vue-router' {
+  interface RouteMeta {
+    title?: string
+    requiresAuth?: boolean
+    roles?: string[]
+    keepAlive?: boolean
+    hidden?: boolean
+  }
+}
+```
+
+## 导航守卫
+
+- 全局前置守卫在 `src/router/index.ts` 中注册，负责鉴权与页面标题设置
+- 禁止在组件内使用 `beforeRouteEnter` 处理鉴权逻辑，鉴权统一收敛到全局守卫
+- 组件级守卫（`onBeforeRouteLeave` 等）仅用于页面离开确认等局部场景
+
+## 约束
+
+- **禁止多处维护路由**：路由配置集中在 `src/router/modules/` 管理，禁止散落在其他目录
+- **避免重复注册**：同一页面组件只允许被一条路由引用
+- **路由命名唯一**：每条路由的 `name` 必须全局唯一

package/.agents/rules/profiles/vue/07-/347/212/266/346/200/201/347/256/241/347/220/206.md

@@ -0,0 +1,93 @@
+---
+alwaysApply: false
+description: 项目的状态管理规范，使用 Pinia 进行全局状态管理。当新增、修改或重构状态管理时读取此规则。
+---
+
+# 状态管理规范（NON-NEGOTIABLE）
+
+## 基础规范
+
+- 状态管理必须使用 **Pinia**
+- 所有 store 文件必须放在 `src/store/modules/` 目录下，按业务模块划分子目录
+- **禁止在 `src` 下新建其他目录存放 store**
+- 禁止使用 Vuex 或其他状态管理方案
+
+## 目录结构
+
+```
+src/store/
+├── index.ts                    # 创建 Pinia 实例、统一导出
+└── modules/
+    ├── user/
+    │   ├── index.ts            # useUserStore
+    │   └── type.ts             # UserInfo 等类型定义
+    ├── app/
+    │   ├── index.ts            # useAppStore（主题、语言等全局配置）
+    │   └── type.ts
+    └── permission/
+        ├── index.ts            # usePermissionStore
+        └── type.ts
+```
+
+- 每个业务模块独立一个目录，目录名使用 `kebab-case`
+- 目录内必须包含 `index.ts`（store 定义）和 `type.ts`（类型定义）
+- `src/store/index.ts` 负责创建 Pinia 实例和统一导出所有 store
+
+## Store 编写规范
+
+- 统一使用 **Setup Store**（组合式语法），禁止 Options Store
+- 每个 store 暴露 `useXxxStore` 命名的函数
+- Store 中不要直接耦合具体 UI 组件，只存纯数据与业务行为
+
+```typescript
+// src/store/modules/user/type.ts
+export interface UserInfo {
+  id: string
+  name: string
+  avatar: string
+  roles: string[]
+}
+```
+
+```typescript
+// src/store/modules/user/index.ts
+import { ref, computed } from 'vue'
+import { defineStore } from 'pinia'
+import type { UserInfo } from './type'
+
+export const useUserStore = defineStore('user', () => {
+  const userInfo = ref<UserInfo | null>(null)
+  const isLoggedIn = computed(() => !!userInfo.value)
+
+  async function fetchUser() {
+    userInfo.value = await getUserInfo()
+  }
+
+  function resetUser() {
+    userInfo.value = null
+  }
+
+  return { userInfo, isLoggedIn, fetchUser, resetUser }
+})
+```
+
+## 在组件中使用
+
+解构响应式状态时必须使用 `storeToRefs`，保持响应性；Action 方法直接从 store 实例解构：
+
+```typescript
+const userStore = useUserStore()
+const { userInfo, isLoggedIn } = storeToRefs(userStore)
+const { fetchUser } = userStore
+```
+
+## 持久化
+
+当状态需要跨页面刷新保留时，使用 `pinia-plugin-persistedstate`，在 `defineStore` 第三个参数中配置 `persist: true`。
+
+## Store 拆分原则
+
+- 按业务领域拆分，每个模块单独一个目录
+- 禁止创建巨型 store，单个 store 的 `index.ts` 不超过 **200 行**
+- Store 之间可以相互引用，但禁止循环依赖
+- 模块私有类型放在模块目录下的 `type.ts`，全局共享类型放在 `src/types/`

package/.agents/rules/profiles/vue/09-/346/240/267/345/274/217/350/247/204/350/214/203.md

@@ -0,0 +1,67 @@
+---
+alwaysApply: false
+globs: ["**/*.vue", "**/*.scss", "**/*.css"]
+description: 项目的样式规范，包括 Scoped/CSS Modules 使用、主题 CSS 变量、暗色模式支持。当编写、修改组件样式或主题适配，或涉及 .vue/.scss/.css 文件时读取此规则。
+---
+
+# 样式规范
+
+## 基础原则
+
+- 组件样式采用 **CSS Modules**（`style.module.scss`）或 `<style scoped>`
+- CSS Modules 优先于 scoped，需要动态 class 时使用 `$style` 或 `:class` 绑定
+- 禁止使用无作用域的全局样式（`<style>` 不加 `scoped` 或 `module`）
+- 全局样式仅允许在 `src/styles/` 目录中定义（变量、reset、mixins）
+
+## 主题色 CSS 变量（NON-NEGOTIABLE）
+
+自定义样式**必须**使用主题色 CSS 变量，**严格禁止**硬编码颜色值：
+
+```scss
+// ✅ 正确
+.card {
+  color: var(--color-text-primary);
+  background-color: var(--color-bg-container);
+  border: 1px solid var(--color-border);
+}
+
+// ❌ 错误
+.card {
+  color: #333;
+  background-color: #fff;
+}
+```
+
+### 推荐变量命名
+
+| 用途 | 变量名 | 说明 |
+|------|--------|------|
+| 主色 | `--color-primary` | 品牌主色 |
+| 文字 | `--color-text-primary` | 主要文字颜色 |
+| 文字次要 | `--color-text-secondary` | 次要文字颜色 |
+| 背景 | `--color-bg-container` | 容器背景色 |
+| 背景页面 | `--color-bg-page` | 页面级背景色 |
+| 边框 | `--color-border` | 默认边框色 |
+| 成功 | `--color-success` | 成功状态色 |
+| 警告 | `--color-warning` | 警告状态色 |
+| 错误 | `--color-error` | 错误状态色 |
+
+变量定义集中在 `src/styles/variables.scss`，通过 `:root` 和 `[data-theme="dark"]` 声明浅色与暗色值。
+
+## 暗色/浅色模式
+
+- 主题切换通过切换根元素的 `data-theme` 属性实现
+- 所有颜色值必须通过 CSS 变量引用，确保主题切换时自动适配
+- 组件库主题覆盖在 `src/styles/element-overrides.scss` 中统一管理
+
+## 设计稿颜色提取
+
+| 属性 | 含义 | CSS 对应 |
+|------|------|----------|
+| `fill` | 背景色 | `background-color` |
+| `stroke` | 边框色 | `border-color` |
+| `background_blur` | 毛玻璃 | `backdrop-filter: blur()` |
+| `shadow` | 阴影 | `box-shadow` |
+| `cornerRadius` | 圆角 | `border-radius` |
+
+**注意**：带有透明度的颜色需要转换为 RGBA 格式。例如 `#13131c73` 中 `73` 是透明度（十六进制），转换为十进制约 0.45。

package/.agents/rules/profiles/vue/11-/346/265/213/350/257/225/350/247/204/350/214/203.md

@@ -0,0 +1,80 @@
+---
+alwaysApply: false
+description: Vue 项目的测试规范，包括测试框架选型（Vitest + @vue/test-utils）、文件约定、测试范围、编写规范与质量门禁。当编写测试或评审测试代码时读取此规则。
+---
+
+# 测试规范（Vue）
+
+## 测试框架
+
+- 统一使用 **Vitest** 作为测试运行器（与 Vite 生态原生集成，兼容 Jest API）
+- 组件测试库：
+  - Vue：`@vue/test-utils`
+  - React：`@testing-library/react`
+- 页面元素定位统一使用 `data-testid` 属性，禁止依赖 CSS class 或 DOM 结构
+
+## 测试文件约定
+
+| 项目 | 约定 |
+|------|------|
+| 文件位置 | 与源文件同目录 |
+| 文件命名 | `<name>.test.ts` / `<name>.spec.ts` 或 `<name>.test.js` / `<name>.spec.js`（与源文件扩展名一致） |
+| 组件测试 | `<name>.test.tsx` / `<name>.test.jsx`（React）/ `<name>.test.ts` 或 `<name>.test.js`（Vue） |
+| 公共 Mock / 工具 | `tests/` 或 `src/__tests__/helpers/` |
+| 测试配置 | 项目根目录 `vitest.config.ts` 或 `vitest.config.js` |
+
+```text
+src/utils/
+├── formatDate.ts
+└── formatDate.test.ts       # 与源文件同目录
+```
+
+## 测试范围
+
+| 级别 | 说明 | 要求 |
+|------|------|------|
+| 必须测试 | 工具函数、Store 逻辑、复杂业务计算、数据转换 | 新增时必须附带测试 |
+| 建议测试 | 关键用户交互流程的组件测试、表单验证逻辑 | 核心页面推荐覆盖 |
+| 不要测试 | 组件内部实现细节、第三方库本身、纯 UI 展示 | 避免脆弱测试 |
+
+## 编写规范
+
+### 测试描述
+
+- `describe` 和 `it` / `test` 的描述使用中文（与 08-通用约束一致）
+- 描述应表达预期行为，而非实现步骤
+
+```ts
+describe('formatDate', () => {
+  it('应将时间戳转换为 YYYY-MM-DD 格式', () => {
+    expect(formatDate(1700000000000)).toBe('2023-11-15');
+  });
+
+  it('传入无效值时应返回空字符串', () => {
+    expect(formatDate(null)).toBe('');
+  });
+});
+```
+
+### 编写模式
+
+- 遵循 **Arrange-Act-Assert**（准备-执行-断言）模式
+- 测试行为而非实现：关注输入输出，不断言内部状态
+- 每个 `it` 只验证一个行为点
+- Mock 外部依赖（API、定时器），不 Mock 被测模块内部
+
+### 禁止模式
+
+| 禁止项 | 原因 |
+|--------|------|
+| 测试依赖执行顺序 | 测试应互相独立，可单独运行 |
+| 快照测试滥用 | 仅用于关键 UI 结构，禁止对大段 HTML 做快照 |
+| 硬编码延时（`setTimeout`） | 使用 `vi.useFakeTimers()` 或 `waitFor` |
+
+## 质量门禁（NON-NEGOTIABLE）
+
+- **TypeScript 项目**：必须通过 **`tsc --noEmit`**（或项目等价类型检查脚本）。
+- **纯 JavaScript 项目**：不强制 `tsc`；以 **ESLint**（及团队约定的检查脚本）为零 error 准绳。
+- 所有项目必须通过 **ESLint 检查**（零 error）。
+- 新增工具函数和 Store 必须附带测试用例。
+- 测试必须能独立运行，不依赖特定环境或执行顺序。