# Project Conventions and Technical Guidelines

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>`.