From 05f36509a018d59cac0651f28e12e144299f25d3 Mon Sep 17 00:00:00 2001
From: chansee97 <chen.dev@foxmail.com>
Date: Thu, 15 Jan 2026 23:07:02 +0800
Subject: [PATCH] docs: add nova-admin AGENT.md

---
 AGENTS.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f0af1a6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,158 @@
+# Nova Admin - Agent Coding Guidelines
+
+This document provides guidelines for agentic coding agents working on this codebase.
+
+## Build, Lint & Test Commands
+
+```bash
+# Development
+pnpm dev              # Start dev server (uses vite --mode dev)
+pnpm dev:prod         # Start with production config
+
+# Build
+pnpm build            # Production build
+pnpm preview          # Preview production build
+
+# Linting
+pnpm lint             # Run eslint + vue-tsc type check
+pnpm lint:fix         # Auto-fix eslint issues
+pnpm lint:check       # Inspect eslint configuration
+pnpm sizecheck        # Visualize bundle size
+
+# Pre-commit hook
+# Automatically runs pnpm lint-staged (eslint --fix) on commit
+```
+
+## Code Style Guidelines
+
+### Imports
+- No strict import sorting enforced (eslint `perfectionist/sort-imports` is OFF)
+- Imports use `@/` alias for `src/` directory (e.g., `@/api`, `@/store`, `@/hooks`)
+- Third-party and local imports are mixed; follow the pattern in existing files
+- Auto-imports are enabled via `unplugin-auto-import` for Vue APIs
+
+### Formatting & Structure
+- **Vue components**: Use `<script setup lang="ts">` or `<script setup lang="tsx">`
+- **File naming**: PascalCase for components (e.g., `UserModal.vue`), camelCase for utilities (e.g., `useBoolean.ts`)
+- **Template**: Use UnoCSS utility classes (e.g., `class="w-70"`, `class="flex-1"`)
+- **Comments**: Use Chinese comments for user-facing text; JSDoc for functions
+
+### TypeScript
+- **Strict mode enabled** (`strict: true`, `strictNullChecks: true`)
+- **No `I` prefix** for interfaces/types (use `UserQueryParams`, not `IUserQueryParams`)
+- **Naming**: PascalCase for types/interfaces, camelCase for variables
+- **Global namespaces**:
+  - `Entity` for database entities (e.g., `Entity.User`, `Entity.Role`)
+  - `Api` for response types (e.g., `Api.Response<T>`, `Api.ListResponse<T>`)
+- **Props typing**: Use `defineProps<Props>()` with interface
+
+```typescript
+// Example: Props typing
+interface Props {
+  modalName?: string
+}
+const { modalName = '' } = defineProps<Props>()
+```
+
+### Naming Conventions
+- **Variables/Functions**: `camelCase` (e.g., `selectedDeptId`, `loadDeptTree`)
+- **Async functions**: Start with action verbs (e.g., `fetchLogin`, `getUserList`)
+- **Components**: `PascalCase` (e.g., `UserModal`, `DarkModeSwitch`)
+- **Constants/Enums**: `PascalCase` (e.g., `Regex.Phone`, `ThemeColor`)
+- **Files**: `PascalCase` for components, `camelCase` for hooks/utils
+
+### Error Handling
+- **Try-catch**: Wrap async operations that may fail
+- **User feedback**: Use `window.$message.success/error` for UI feedback
+- **Logging**: Use `console.error()` for error details
+- **Silent catch**: Acceptable for non-critical errors (e.g., in search handlers)
+- **Empty catch blocks**: Sometimes used; avoid in critical operations
+
+```typescript
+// Example: Standard error handling
+try {
+  await deleteUser(id)
+  window.$message.success('用户删除成功')
+  refresh()
+}
+catch (error) {
+  console.error('删除用户失败:', error)
+}
+
+// Example: Non-critical error with fallback
+try {
+  const { data } = await getUserList()
+  return data
+}
+catch {
+  return { list: [], total: 0 }
+}
+```
+
+### API Patterns
+- **Alova wrapper**: Use `request.Get/Post/Patch/Delete` from `@/utils/alova`
+- **Response types**: Wrap with `Api.Response<T>` or `Api.ListResponse<T>`
+- **Entity updates**: Use `Partial<Entity.Type>` for update payloads
+
+```typescript
+// Example: API function
+export function getUserList(params?: UserQueryParams) {
+  return request.Get<Api.ListResponse<Entity.User>>('/user', { params })
+}
+```
+
+### State Management (Pinia)
+- **Store naming**: `PascalCase` with `Store` suffix (e.g., `useAuthStore`)
+- **State**: Return object with explicit types
+- **Getters**: Computed properties with JSDoc
+- **Actions**: Async functions for mutations
+
+```typescript
+export const useAuthStore = defineStore('auth-store', {
+  state: (): AuthStatus => {
+    return { userInfo: {}, roles: [], permissions: [] }
+  },
+  getters: {
+    isLogin(state) { return Boolean(state.userInfo) },
+  },
+  actions: {
+    async login() {
+      // ...
+    },
+  },
+})
+```
+
+### CSS & Styling
+- **UnoCSS**: Use utility classes (e.g., `grid grid-cols-2`, `col-span-2`)
+- **Scoped styles**: `<style scoped>` for component-specific CSS
+- **Tailwind-like syntax**: `w-70`, `flex-1`, `text-2xl`, etc.
+
+### Vue Component Best Practices
+- **Composition API**: Use `<script setup>` exclusively
+- **Expose methods**: Use `defineExpose({ openModal })` for modal/ref methods
+- **Event emission**: Use `defineEmits<{ success: [] }>()`
+- **Reactive refs**: Use `shallowRef` for non-reactive objects (e.g., `modalType`)
+
+## Key File Locations
+
+| Purpose | Path |
+|---------|------|
+| API definitions | `src/api/` |
+| Types/Entities | `src/typings/` |
+| State stores | `src/store/` |
+| Hooks | `src/hooks/` |
+| Constants | `src/constants/` |
+| Utils | `src/utils/` |
+| Views | `src/views/` |
+| Components | `src/components/` |
+| Configs | `src/modules/` |
+
+## Important Dependencies
+
+- **Vue 3** with Composition API
+- **Naive UI** for components (auto-imported)
+- **Alova** for API requests
+- **Pinia** for state management
+- **UnoCSS** for styling
+- **TypeScript** with strict mode