vue-ts-example/.github/copilot-instructions.md

description, globs, alwaysApply

description	globs	alwaysApply
		true

GitHub Copilot Instructions

本文件定义了项目的代码生成规范，GitHub Copilot 和其他 AI 助手应遵循这些指令。

This document outlines the core technical choices, coding conventions, and configuration details for this project. Adhering to these guidelines ensures consistency and leverages the project's setup effectively.

🚀 Core Technologies & Conventions

• Framework: Vue 3
• Language: TypeScript
• API Style: Strictly use the Composition API with <script setup> syntax. The Options API and the standard <script> block with the setup() function are not used in this project.
• Single File Component (SFC) Structure: Follow this order within .vue files:
  1. <script setup lang="ts"> (Imports, logic, composables, etc.)
  2. <template> (HTML structure)
  3. <style> (Preferably <style scoped>)
• Code Comments:
  • All comments within the codebase must be written in Chinese. (代码中的所有注释必须使用中文。)
  • 注释应解释代码的“为什么”（设计意图、选择某方案的原因）或复杂逻辑/算法的“如何”，而不是解释“是什么”（重复代码功能）或“在哪里”（描述定义位置）。
  • 严禁添加仅说明代码被移动、重构或提取到其他文件的注释。 例如，避免 // XxxState 接口已移至 types.ts 或 // 提取为 useXYZ composable 这样的注释。依赖代码结构、类型系统和 IDE 功能（如 Go To Definition）来理解这些信息，而不是通过注释。Focus comments on the logic itself, not its location or history.
  • 同样地，严禁添加描述代码是“新增”、“修改”、“临时”或标记其开发状态的注释。 例如，避免 // 新增功能、// (新增)、// 临时修复、// TODO: 优化（除非 TODO 指向具体的技术债务或未完成的逻辑，而不仅仅是标记状态）等注释。注释的目标是解释代码的内在逻辑或设计决策，而不是其变更历史或当前状态。

📦 UI Libraries & Components

• UI Libraries: This project utilizes both Ant Design Vue and PrimeVue.
• Component Auto-Import: Components from Ant Design Vue, PrimeVue, and those defined in src/components/**/*.vue (excluding filenames starting with __) are automatically imported via unplugin-vue-components.
  • Ant Design Vue: Use components directly (e.g., <a-button>, <a-table>). Icons are also resolved (e.g., <UserOutlined />). CSS-in-JS is used; no manual style import is needed.
  • PrimeVue: Use components directly with their standard names (e.g., <Button>, <InputText>, <DataTable>).
  • Custom Components: Local components (e.g., <MyCustomComponent /> defined in src/components/MyCustomComponent.vue) should be used directly in templates without explicit imports in <script setup>.
• Custom Icons: Custom SVG icons are available via unplugin-icons with the prefix icon-. Usage: <icon-your-svg-file-name />.
• No Auto-Import Comments for Components: When using auto-imported components (UI libraries, local components), do not add comments indicating they are auto-imported. Assume this behavior is known. Trust the tooling.

✨ API Auto-Import (unplugin-auto-import)

• Automatic API Availability: This project leverages unplugin-auto-import extensively. APIs from the following libraries/modules are globally available and SHOULD NOT be explicitly imported in <script setup> blocks unless necessary for specific type augmentation or rare cases:
  • vue (e.g., ref, computed, watch, onMounted, defineProps, defineEmits, etc.)
  • pinia (e.g., defineStore, storeToRefs)
  • vue-router/auto (e.g., useRouter, useRoute, useLink) - Provided by unplugin-vue-router integration.
  • @vueuse/core (Common utility functions)
  • vue-i18n (e.g., useI18n)
  • consola/browser (Available as the consola global for logging)
• Auto-Imported Directories: All exports from files within src/stores/** and src/utils/** are also auto-imported globally. Functions, variables, or stores defined and exported in these directories can be used directly without explicit import statements.
• Template Usage: Auto-import functionality also applies within the <template> block where appropriate (e.g., accessing store state or using certain utility functions directly).
• Important: Rely on the auto-import mechanism for the specified libraries and directories. Explicitly importing these APIs clutters the code unnecessarily.
• No Auto-Import Explanation Comments: When using auto-imported APIs (from libraries like Vue, Pinia, VueUse, or custom directories like src/utils, src/stores), simply use them directly. Absolutely avoid adding comments that merely state an item is auto-imported (e.g., DO NOT add comments like "// xxx is auto-imported from src/utils"). Focus comments on explaining complex logic or intent.

✅ Summary of Key Rules & Conventions

• Always use <script setup lang="ts">.
• Composition API is the only accepted style.
• Code comments must be in Chinese and explain why/how (logic, intent), strictly avoiding comments that explain what (code repetition), where (definition location), refactoring history, code status (e.g., 'new', 'modified'), or auto-import mechanisms.
• Vue 3 Composition API, Pinia, Vue Router (auto), VueUse functions, consola, and exports from src/stores & src/utils are globally available via auto-import; do not import them explicitly.
• Ant Design Vue, PrimeVue, and local src/components components are auto-imported; use them directly in templates without explicit imports.
• Crucially: Do not add comments solely to explain that an API or component is auto-imported OR where code has been moved/refactored OR the status of the code (e.g., 'new'). Trust the auto-import setup and IDE navigation. Focus on logic.
• Use custom SVG icons via the <icon-name /> syntax.
• Maintain the specified SFC structure: <script setup>, <template>, <style>.