skytek_xinliang
ea1aec67dc
Add guidance for choosing SectionFormPage and SectionQueryPage based on visible UI patterns in prototypes or screenshots. Document required visual feature descriptions for new page/section components and expand section component usage notes with query page guidance.docs: document visual cues for section page selection Add guidance for choosing SectionFormPage and SectionQueryPage based on visible UI patterns in prototypes or screenshots. Document required visual feature descriptions for new page/section components and expand section component usage notes with query page guidance.
67 lines
4.7 KiB
Markdown
67 lines
4.7 KiB
Markdown
# Project Rules
|
|
|
|
## General
|
|
- Follow the existing code style and patterns.
|
|
- Use pnpm for running project commands.
|
|
- Keep code in TypeScript unless migration is required.
|
|
- Before modifying or adding files in a `src/` subdirectory, read the corresponding `src/**/GUIDE.md` to understand the layer's constraints and conventions. Use `docs/llm-development-guide.md` as the index to find which GUIDE applies.
|
|
- When the change introduces a new pattern, directory, or convention that affects layer boundaries, create or update the relevant `src/**/GUIDE.md` and ensure `docs/llm-development-guide.md` indexes it.
|
|
- When refactoring or creating new components, review `docs/architecture-strategy.md` first and follow its layering and responsibility guidelines.
|
|
- For UI debugging that spans implementation, state flow, and live browser behavior, use subagents deliberately: one for component contracts and event flow, one for data sources / routing / integration, and one for live browser verification. Do not edit files until the evidence from those threads converges on a root cause.
|
|
- Treat subagent output as scoped evidence, not as a final answer. Use subagents to narrow the search space, confirm or eliminate hypotheses, and reduce local context load before making edits.
|
|
- When a problem is directly tied to Vuetify component behavior, props, slots, accessibility output, or generated DOM, consult Vuetify MCP and official Vuetify API documentation before changing the implementation. Prefer supported Vuetify props, slots, and documented extension points over custom replacements unless the documented API is insufficient.
|
|
|
|
## Naming Generalization Rule
|
|
- This project is a **template** intended to be reused across different data domains (student, course, teacher, etc.).
|
|
- **Reusable abstractions** (Page Components, Sections, Items, generic composables, base components) **must not contain domain-specific names** (e.g., `Student`, `Course`) in their file names, type names, or export names.
|
|
- Domain-specific names are **only allowed** in:
|
|
- `src/models/<domain>.ts` — domain models
|
|
- `src/stores/<domain>.ts` — domain stores
|
|
- `src/services/modules/<domain>.ts` — service modules
|
|
- Examples of correct vs. incorrect naming:
|
|
- ❌ `PageStudentMaintenance.vue` → ✅ `PageMaintenance.vue`
|
|
- ❌ `useStudentMaintenancePage.ts` → ✅ `useMaintenancePage.ts`
|
|
- ❌ `ItemStudentRow.vue` → ✅ `ItemDataRow.vue`
|
|
- ❌ `useStudentCrudCommands.ts` → ✅ `useCrudCommands.ts`
|
|
- ✅ `models/student.ts`, `stores/students.ts` — domain layer, specific names are correct
|
|
|
|
## GUIDE.md 寫作規則
|
|
|
|
- `src/**/GUIDE.md` 只保留該層/目錄的**約束、慣例與索引**，不要塞入詳細 API 文件。
|
|
- 當新增 pattern、目錄或慣例影響層邊界時，建立或更新對應的 `src/**/GUIDE.md`，並確保 `docs/llm-development-guide.md` 將其列入索引。
|
|
- 元件的 Props/Slots/Emits 詳細說明放在各子目錄的 `GUIDE.md`（如 `src/components/base/GUIDE.md`、`src/components/sections/GUIDE.md`），不要放在上層 `src/components/GUIDE.md`。
|
|
- **新增 page/section 元件時，必須一併描述「視覺特徵」**：說明畫面上出現哪些元素（如標題卡片、按鈕類型、表格位置），讓 LLM 能從截圖或設計稿判斷該用哪個元件。視覺特徵寫在對應子目錄 `GUIDE.md` 的「視覺特徵」小節。
|
|
|
|
## Stack
|
|
- Framework: Vue 3 + Vite
|
|
- UI Library: Vuetify
|
|
- Enabled Features: Vuetify MCP, Pinia, Vue I18n, Vue Router
|
|
|
|
## Icon Usage
|
|
```js
|
|
<script setup>
|
|
import { mdiAccount } from '@mdi/js'
|
|
</script>
|
|
|
|
<template>
|
|
<v-icon :icon="mdiAccount" />
|
|
</template>
|
|
```
|
|
|
|
## Vuetify MCP
|
|
|
|
- When looking up Vuetify versions, release notes, component APIs, directive APIs, installation guides, FAQs, feature guides, or package exports, use Vuetify MCP first.
|
|
- When a question involves Vuetify component props, events, slots, exposed methods, generated DOM, accessibility output, or officially supported extension points, verify with Vuetify MCP before changing the implementation.
|
|
- Prefer the official API and documentation information returned by MCP. Do not infer Vuetify behavior.
|
|
|
|
### 常用工具
|
|
|
|
- `get_release_notes_by_version`: 查詢指定版本或 latest 的 release notes。
|
|
- `get_component_api_by_version`: 查詢指定 Vuetify 元件的 props、events、slots、exposed methods。
|
|
- `get_directive_api_by_version`: 查詢指定 Vuetify directive 的 API。
|
|
- `get_vuetify_api_by_version`: 下載並快取指定版本的 Vuetify API types。
|
|
- `get_installation_guide`: 查詢 Vite、Nuxt、Laravel、CDN 等安裝方式。
|
|
- `get_feature_guide`: 查詢 theme、icons、i18n、display、layout 等功能指南。
|
|
- `get_exposed_exports`: 查詢 Vuetify npm package 可匯出的項目。
|
|
- `get_frequently_asked_questions`: 查詢 Vuetify FAQ。
|