fec-vue3-project-standard · diff
git:20260609.e2e224a to git:20260611.9d7f5e4
38 added, 38 removed. Audit B to B.
---
name: fec-vue3-project-standard
- description: Use when designing or reviewing Vue 3 + TypeScript project structure, SFC/component boundaries, composables organization, route composition, Pinia ownership, API/error/styling defaults, directives, or repository-wide Vue conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include Vue 3 项目规范, Vue 组件架构.
+ description: Use when designing or reviewing Vue 3 + TypeScript project structure, SFC/component boundaries, composables organization, route composition, Pinia ownership, API/error/styling defaults, directives, or repository-wide Vue conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include Vue 3 project specification, Vue component architecture.
---
- # Vue 3 项目规范
+ # Vue 3 project specifications
- 适用于使用 Vue 3 + TypeScript 的仓库。
+ For repositories using Vue 3 + TypeScript.
## Purpose
- 为 Vue 3 + TypeScript 项目提供工程结构、组件边界、Composables 和默认实现约定，确保约定式开发和类型安全。
+ Provides project structure, component boundaries, Composables, and default implementation conventions for Vue 3 + TypeScript projects to ensure conventional development and type safety.
## Procedure
- 1. 识别仓库已有 Vue 约定：目录、路由、Pinia、请求层、样式体系、组件库和测试框架。
- 2. 划分页面、业务组件、通用组件、composables、stores、services 和 utils 的边界。
- 3. 优先沿用 `<script setup lang="ts">`、组合式 API 和仓库现有自动导入/模块出口约定。
- 4. 输出时补齐状态归属、API 层、错误处理、样式隔离和专项 skill 分流。
- 5. 页面和模块要有可恢复错误 UI；全局 `errorHandler`、`onErrorCaptured`、请求错误映射和路由错误页分工明确。
- 6. Tailwind token/variant 或响应式布局需求应分流到对应专项 skill，避免把样式系统规则塞进 Vue 组件规范。
- 7. 状态归属复杂时先做状态清单；DTO、公共 props、泛型 composable 或 `tsconfig` 边界复杂时，先使用 TypeScript 项目规范流程收敛跨框架类型契约。
- 8. 设计可复用 composable 时明确输入是否支持 plain value、ref、computed 或 getter；测试 Vue 组件时覆盖 Pinia、Router、Teleport、Suspense 和 async setup 的常见边界。
+ 1. Identify the existing Vue conventions in the warehouse: directory, routing, Pinia, request layer, style system, component library and test framework.
+ 2. Demarcate the boundaries between pages, business components, common components, composables, stores, services and utils.
+ 3. Prioritize the existing automatic import/module export conventions of `<script setup lang="ts">`, composite API and warehouse.
+ 4. Complete state ownership, API layer, error handling, style isolation and special skill offloading when outputting.
+ 5. Pages and modules must have recoverable error UI; global `errorHandler`, `onErrorCaptured`, request error mapping and routing error page have clear division of labor.
+ 6. Tailwind token/variant or responsive layout requirements should be diverted to corresponding special skills to avoid stuffing style system rules into Vue component specifications.
+ 7. When the state ownership is complex, first make a state list; when the boundaries of DTO, public props, generic composable or `tsconfig` are complex, first use the TypeScript project specification process to converge cross-framework type contracts.
+ 8. When designing reusable composables, clarify whether the input supports plain value, ref, computed or getter; when testing Vue components, cover the common boundaries of Pinia, Router, Teleport, Suspense and async setup.
- ## 详细参考
+ ## Detailed reference
- 按需要加载更细的参考文件：
+ Load more detailed reference files as needed:
- - 项目目录、组件分层、组件规范、注释和 TypeScript：加载 [references/vue3-project-structure.md](references/vue3-project-structure.md)。
- - Composables、slots、Provide/Inject 和路由组织：加载 [references/vue3-composables-routing.md](references/vue3-composables-routing.md)。
- - Pinia、API 层、错误处理、指令、样式、测试、反模式和输出检查清单：加载 [references/vue3-state-api-quality.md](references/vue3-state-api-quality.md)。
- - Vue 项目规范层面的轻量性能约定：加载 [references/vue3-performance-patterns.md](references/vue3-performance-patterns.md)。
+ - Project directory, component layering, component specifications, annotations, and TypeScript: Load [references/vue3-project-structure.md](references/vue3-project-structure.md).
+ - Composables, slots, Provide/Inject and routing organizations: Load [references/vue3-composables-routing.md](references/vue3-composables-routing.md).
+ - Pinia, API layer, error handling, directives, styles, tests, anti-patterns and output checklist: Loading [references/vue3-state-api-quality.md](references/vue3-state-api-quality.md).
+ - Lightweight performance conventions at the Vue project specification level: Load [references/vue3-performance-patterns.md](references/vue3-performance-patterns.md).
## Constraints
- - 使用 `<script setup lang="ts">`，禁止使用 Options API 新增组件
- - 组件文件规模宜约 **300 行**内；逾 **500 行**或复杂度过高须拆子组件与 Composables
- - Props / Emits 必须使用 TypeScript interface 定义，禁止使用 `any`
- - Composable 返回 `readonly` 引用，防止外部意外修改
- - 不要在 store 中存放 UI 临时状态（modal 开关、表单输入等）
- - 服务端数据优先用请求库管理，而非手动存入 Pinia
- - 避免在 `v-for` 中使用 `v-if`（提取为 computed 过滤）
- - 禁止直接从 feature 内部深层路径导入，绕过 `index.ts`
- - 不用全局错误处理吞掉组件内可恢复的 API、表单或权限错误。
- - 不把函数型参数误当 getter 自动调用；composable 参数若可能是回调，应避免使用 getter 型输入约定。
- - 不依赖快照作为 Vue 组件唯一断言；异步组件、Teleport 和 Pinia 场景要有用户可见行为断言。
+ - Use `<script setup lang="ts">` to disable using Options API to add new components
+ - The size of the component file should be approximately **300 lines**; if it exceeds **500 lines** or is too complex, sub-components and Composables must be separated
+ - Props / Emits must be defined using the TypeScript interface, and `any` is prohibited
+ - Composable returns a `readonly` reference to prevent accidental external modifications
+ - Do not store UI temporary states (modal switches, form inputs, etc.) in the store
+ - Server-side data is first managed by the request library rather than manually stored in Pinia
+ - Avoid using `v-if` in `v-for` (extract to computed filtering)
+ - It is forbidden to import directly from the deep path inside the feature, bypassing `index.ts`
+ - No need for global error handling to swallow recoverable API, form or permission errors within components.
+ - Do not mistake function parameters for getter automatic calls; if composable parameters may be callbacks, avoid using getter input conventions.
+ - Do not rely on snapshots as the only assertions for Vue components; asynchronous components, Teleport and Pinia scenes must have user-visible behavior assertions.
## Expected Output
- - 组件使用 `<script setup lang="ts">`，Props / Emits 类型完整
- - 可复用逻辑已提取到 composable，返回 `readonly` 引用
- - Loading / Error / Empty / Data 状态均已处理
- - 路由组件使用动态 import 加载，状态管理符合就近原则
- - URL 状态、服务端状态、表单状态和 Pinia 全局状态边界明确
- - API 调用有类型约束和统一错误处理
- - 样式使用 scoped 隔离，关键行为有测试覆盖
- - 文件结构与项目约定一致（pages / features / components 分离）
- - 可复用 composable 的输入响应性、Pinia/Router 边界和异步组件测试策略已说明
+ - The component uses `<script setup lang="ts">`, and the Props/Emits type is complete
+ - Reusable logic has been extracted to composable, returning `readonly` reference
+ - Loading / Error / Empty / Data status have been processed
+ - Routing components are loaded using dynamic import, and state management conforms to the proximity principle
+ - URL status, server status, form status and Pinia global status have clear boundaries
+ - API calls have type constraints and unified error handling
+ - Styles are isolated using scoped, and key behaviors are covered by tests
+ - The file structure is consistent with the project convention (pages/features/components are separated)
+ - Input responsiveness, Pinia/Router boundaries and asynchronous component testing strategies for reusable composables explained