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

// 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

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

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

API Choice

// 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)

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

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

API Choice

// 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

// 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

// 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