front/.kilo/skill/vue-admin-dev.md

# Vue Admin Development Skill

## Overview

This skill provides comprehensive guidance for developing features in this Vue 3 + Arco Design admin project.

## Core Patterns

### 1. Page Module Structure

Every page module follows this pattern:

```
src/views/ops/pages/{category}/{module}/
├── index.vue           # Main page (SearchTable + CRUD)
├── components/
│   ├── FormDialog.vue  # Create/Edit dialog
│   ├── Detail.vue      # Detail view
│   └── QuickConfigDialog.vue # Optional quick config
└── config/
    ├── columns.ts      # Table columns config
    └── search-form.ts  # Search form config
```

### 2. API Module Structure

```
src/api/ops/{module}.ts
├── /** {{Module}}类型 */
├── Interfaces (Item, ListResponse, ListParams, CreateData, UpdateData)
├── /** 获取{{Module}}列表（分页） */
├── fetch{Module}List(params)
├── /** 获取{{Module}}详情 */
├── fetch{Module}Detail(id)
├── /** 创建{{Module}} */
├── create{Module}(data)
├── /** 更新{{Module}} */
├── update{Module}(id, data)
└── /** 删除{{Module}} */
└── delete{Module}(id)
```

### 3. API Response Handling

```ts
// Standard response: {code: 0, details: {...}}
const response = await fetchList(params)
if (response && response.code === 0 && response.details) {
  tableData.value = response.details.data || []
  pagination.total = response.details.total || 0
}
```

src/api/ops/{module}.ts
├── Interfaces (Item, ListResponse, ListParams, CreateData, UpdateData)
├── fetch{Module}List(params)
├── fetch{Module}Detail(id)
├── create{Module}(data)
├── update{Module}(id, data)
└── delete{Module}(id)

````

### 3. Component Template

```vue
<template>
  <div class="container">
    <search-table ...>
      <template #toolbar-left>
        <!-- Action buttons -->
      </template>
      <template #column-slot="{ record }">
        <!-- Custom column rendering -->
      </template>
    </search-table>
    <FormDialog v-model:visible="..." />
    <a-drawer v-model:visible="...">
      <Detail :record="..." />
    </a-drawer>
  </div>
</template>

<script lang="ts" setup>
// Imports in order: Vue → Third-party → Components → Configs → APIs → Types
</script>

<script lang="ts">
export default { name: 'ModuleName' }
</script>

<style scoped lang="less"></style>
````

## Critical Rules

### Storage

```ts
// CORRECT
SafeStorage.set(AppStorageKey.TOKEN, token, 3600000)
SafeStorage.get(AppStorageKey.USER_INFO)

// WRONG
localStorage.setItem('token', token)
```

### API Choice

```ts
// Workspace-aware APIs (most ops APIs)
import { request } from '@/api/request'
request.post('/DC-Control/v1/servers', data)
// Response: {code: 0, details: {data: [...], total: number}}

// Standard Bearer token APIs
import axios from 'axios' // Uses interceptor.ts defaults
// Response: {code: 20000, data: {...}}
```

### Comments (JSDoc Style)

```ts
/** 服务器类型 */
export interface ServerItem {
  id: number
  name: string
}

/** 获取服务器列表（分页） */
export const fetchServerList = (params?: ServerListParams) => {
  return request.get<ServerListResponse>('/DC-Control/v1/servers', { params })
}
```

### API Choice

```ts
// Workspace-aware APIs (most ops APIs)
import { request } from '@/api/request'
request.post('/DC-Control/v1/servers', data)

// Standard Bearer token APIs
import axios from 'axios' // Uses interceptor.ts defaults
```

### useRequest Hook

```ts
// CORRECT - Use in setup scope
const { loading, response } = useRequest(fetchList.bind(null, params))

// WRONG - Use in async function
async function loadData() {
  const { loading, response } = useRequest(fetchList()) // Doesn't work!
}
```

### Dynamic Routes

```ts
// Routes auto-loaded by permission guard
// Don't manually add routes except in menu config
// Don't modify isMenuLoading/isMenuLoaded flags
```

## Quick Reference

### Arco Design Components

- Table: `<a-table>` with columns, pagination, slots
- Form: `<a-form>` with `<a-form-item>` and validation
- Dialog: `<a-modal>` with v-model:visible
- Drawer: `<a-drawer>` for side panels
- Message: `Message.success/error/info/warning()`
- Modal: `Modal.confirm/info/error()`

### Common Slots

- `#toolbar-left` - Left toolbar buttons
- `#toolbar-right` - Right toolbar buttons
- `#actions` - Row actions column
- `#enabled` - Status toggle column
- `#{fieldName}` - Custom field rendering

### Import Order

1. Vue: `ref, reactive, computed, watch, onMounted`
2. Arco: `Message, Modal` + Icons
3. Components: `SearchTable, FormDialog`
4. Configs: `searchFormConfig, columns`
5. APIs: `fetchList, createItem, updateItem`
6. Types: `Item, ListParams, CreateData`

## Workflow

### Creating New Module

1. Run `/new-api {module}` to create API
2. Run `/new-page {module} {category}` to create page
3. Adjust columns and search-form configs
4. Customize FormDialog fields
5. Add Detail view content
6. Test with `pnpm dev`

### Adding Feature to Existing Module

1. Check existing patterns in similar modules
2. Add API function if needed
3. Update columns/search-form config
4. Add component or slot if needed
5. Run `pnpm lint` after changes

## Debugging

- Console logs prefixed with `[Permission Guard]` for route issues
- Network tab for API debugging
- Vue DevTools for state inspection
- `pnpm lint` for code issues