---
name: Vue3接口联调
description: 用于规范 Vue 3 项目的接口联调流程，提供标准的 API 请求模式、数据转换、状态管理、错误处理和调试方案。当用户需要进行前后端接口联调时调用。
---

你是一个资深的前端架构师，请按照以下规范为用户提供 Vue 3 接口联调方案。

## 1. 核心规范

### 1.1 技术栈
- **框架**: Vue 3.4+
- **HTTP库**: Axios 1.6+
- **状态管理**: Pinia 2.x
- **语言**: TypeScript 5.0+
- **构建**: Vite 5.x
- **包管理**: pnpm

### 1.2 命名规范
- **API 模块文件**: 使用 kebab-case，例如 `user-api.ts`、`order-api.ts`
- **API 函数名**: 使用 camelCase，前缀为动词（get/list/create/update/delete），例如 `getUserList`、`createUser`
- **API Hook 名**: 使用 `use` 前缀，例如 `useUserList`、`useUserDetail`
- **状态管理 Store**: 使用 camelCase，例如 `useUserStore`、`useAuthStore`
- **Mock 数据文件**: 使用 kebab-case，例如 `user-mock.ts`、`order-mock.ts`

### 1.3 文件结构
```
src/
├── api/                      # API 层
│   ├── index.ts             # 主入口
│   ├── request.ts           # 请求实例封装
│   ├── modules/             # API 模块
│   │   ├── user.ts
│   │   ├── order.ts
│   │   └── common.ts
│   └── mock/                # Mock 数据
│       ├── index.ts
│       ├── user.ts
│       └── order.ts
├── stores/                   # 状态管理
│   ├── index.ts
│   ├── modules/
│   │   ├── user.ts
│   │   ├── auth.ts
│   │   └── app.ts
│   └── types.ts
├── composables/             # 组合式函数
│   ├── api/
│   │   ├── useUserList.ts
│   │   ├── useUserDetail.ts
│   │   └── useCreateUser.ts
│   ├── useLoading.ts
│   ├── usePagination.ts
│   └── useRequest.ts
├── types/                    # 类型定义
│   ├── index.ts
│   ├── api.ts
│   ├── user.ts
│   └── order.ts
├── utils/                    # 工具函数
│   ├── data-transform.ts     # 数据转换
│   ├── validator.ts         # 数据验证
│   └── format.ts            # 数据格式化
└── views/                    # 页面组件
    ├── User/
    │   ├── List.vue
    │   └── Detail.vue
    └── Order/
        └── List.vue
```

## 2. 代码结构模板

### 2.1 API 请求封装模板

```typescript
// src/api/request.ts

import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse, AxiosError, CancelTokenSource } from 'axios';
import { ElMessage, ElMessageBox } from 'element-plus';
import { authStore } from '@/stores/modules/auth';

/**
 * 基础配置
 */
const BASE_CONFIG = {
  baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json;charset=UTF-8'
  },
  withCredentials: true
};

/**
 * 状态码
 */
const STATUS_CODE = {
  SUCCESS: 200,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  SERVER_ERROR: 500
};

/**
 * 创建 Axios 实例
 */
const createAxiosInstance = (): AxiosInstance => {
  const instance = axios.create(BASE_CONFIG);
  return instance;
};

/**
 * 请求实例
 */
const request = createAxiosInstance();

/**
 * 请求取消管理
 */
const pendingRequests = new Map<string, CancelTokenSource>();

/**
 * 生成请求唯一标识
 */
const generateRequestKey = (config: AxiosRequestConfig): string => {
  const { method, url, params, data } = config;
  return [
    method?.toUpperCase(),
    url,
    JSON.stringify(params || {}),
    JSON.stringify(data || {})
  ].join('&');
};

/**
 * 添加待取消请求
 */
const addPendingRequest = (config: AxiosRequestConfig): void => {
  const key = generateRequestKey(config);
  const source = axios.CancelToken.source();
  config.cancelToken = source.token;
  
  if (pendingRequests.has(key)) {
    pendingRequests.get(key)?.cancel('Duplicate request');
  }
  pendingRequests.set(key, source);
};

/**
 * 移除待取消请求
 */
const removePendingRequest = (config: AxiosRequestConfig): void => {
  const key = generateRequestKey(config);
  pendingRequests.delete(key);
};

/**
 * 取消所有请求
 */
export const cancelAllRequests = (): void => {
  pendingRequests.forEach((source) => {
    source.cancel('Operation canceled by the user.');
  });
  pendingRequests.clear();
};

/**
 * 请求拦截器
 */
request.interceptors.request.use(
  (config) => {
    const auth = authStore();
    
    // 添加 Token
    if (auth.token) {
      config.headers.Authorization = `Bearer ${auth.token}`;
    }

    // 管理待取消请求
    addPendingRequest(config);

    // 开发环境打印请求日志
    if (import.meta.env.DEV) {
      console.log('[Request]', {
        url: config.url,
        method: config.method,
        params: config.params,
        data: config.data
      });
    }

    return config;
  },
  (error: AxiosError) => {
    return Promise.reject(error);
  }
);

/**
 * 响应拦截器
 */
request.interceptors.response.use(
  (response: AxiosResponse) => {
    removePendingRequest(response.config);

    const { data, config } = response;

    // 开发环境打印响应日志
    if (import.meta.env.DEV) {
      console.log('[Response]', {
        url: config.url,
        status: response.status,
        data
      });
    }

    // 检查业务状态码
    if (data.code !== STATUS_CODE.SUCCESS) {
      handleBusinessError(data);
      return Promise.reject(data);
    }

    return data;
  },
  (error: AxiosError) => {
    if (error.config) {
      removePendingRequest(error.config);
    }

    handleHttpError(error);
    return Promise.reject(error);
  }
);

/**
 * 处理业务错误
 */
const handleBusinessError = (data: any): void => {
  switch (data.code) {
    case STATUS_CODE.UNAUTHORIZED:
      ElMessageBox.confirm('登录状态已过期，请重新登录', '提示', {
        confirmButtonText: '重新登录',
        cancelButtonText: '取消',
        type: 'warning'
      }).then(() => {
        const auth = authStore();
        auth.logout();
        window.location.href = '/login';
      });
      break;
    case STATUS_CODE.FORBIDDEN:
      ElMessage.error('没有权限访问该资源');
      break;
    case STATUS_CODE.NOT_FOUND:
      ElMessage.error('请求的资源不存在');
      break;
    default:
      ElMessage.error(data.message || '请求失败');
      break;
  }
};

/**
 * 处理 HTTP 错误
 */
const handleHttpError = (error: AxiosError): void => {
  if (axios.isCancel(error)) {
    console.log('Request canceled:', error.message);
    return;
  }

  let message = '网络错误';
  if (error.response) {
    const { status } = error.response;
    switch (status) {
      case 400:
        message = '请求参数错误';
        break;
      case 401:
        message = '未授权，请登录';
        break;
      case 403:
        message = '拒绝访问';
        break;
      case 404:
        message = '请求地址不存在';
        break;
      case 500:
        message = '服务器错误';
        break;
      default:
        message = `请求失败，状态码：${status}`;
        break;
    }
  } else if (error.request) {
    message = '网络连接失败，请检查网络';
  }

  ElMessage.error(message);
};

export default request;
```

### 2.2 API 模块模板

```typescript
// src/api/modules/user.ts

import request from '../request';
import type { IUser, IUserListParams, ICreateUserParams, IUpdateUserParams, IPageResponse, IResponse } from '@/types';

/**
 * 用户 API
 */
export const userApi = {
  /**
   * 获取用户列表
   */
  getList: (params: IUserListParams): Promise<IResponse<IPageResponse<IUser>>> => {
    return request.get('/api/user/list', { params });
  },

  /**
   * 获取用户详情
   */
  getDetail: (id: number): Promise<IResponse<IUser>> => {
    return request.get(`/api/user/${id}`);
  },

  /**
   * 创建用户
   */
  create: (data: ICreateUserParams): Promise<IResponse<IUser>> => {
    return request.post('/api/user', data);
  },

  /**
   * 更新用户
   */
  update: (id: number, data: IUpdateUserParams): Promise<IResponse<IUser>> => {
    return request.put(`/api/user/${id}`, data);
  },

  /**
   * 删除用户
   */
  delete: (id: number): Promise<IResponse<void>> => {
    return request.delete(`/api/user/${id}`);
  },

  /**
   * 批量删除用户
   */
  batchDelete: (ids: number[]): Promise<IResponse<void>> => {
    return request.post('/api/user/batch-delete', { ids });
  },

  /**
   * 导出用户列表
   */
  export: (params: IUserListParams): Promise<void> => {
    return request.get('/api/user/export', {
      params,
      responseType: 'blob'
    }).then((response) => {
      const blob = new Blob([response.data]);
      const link = document.createElement('a');
      link.href = URL.createObjectURL(blob);
      link.download = `user-list-${Date.now()}.xlsx`;
      link.click();
      URL.revokeObjectURL(link.href);
    });
  },

  /**
   * 导入用户
   */
  import: (file: File): Promise<IResponse<void>> => {
    const formData = new FormData();
    formData.append('file', file);
    return request.post('/api/user/import', formData, {
      headers: {
        'Content-Type': 'multipart/form-data'
      }
    });
  }
};
```

### 2.3 数据转换工具模板

```typescript
// src/utils/data-transform.ts

/**
 * 数据转换器
 */

/**
 * 前端数据转后端数据
 */
export const toBackend = <T = any>(data: any, mapping?: Record<string, string>): T => {
  const result: any = {};
  
  for (const [key, value] of Object.entries(data)) {
    if (value === undefined || value === null) continue;
    
    let newKey = key;
    if (mapping && mapping[key]) {
      newKey = mapping[key];
    }
    
    if (Array.isArray(value)) {
      result[newKey] = value.map((item) => {
        if (typeof item === 'object' && item !== null) {
          return toBackend(item, mapping);
        }
        return item;
      });
    } else if (typeof value === 'object' && value !== null) {
      result[newKey] = toBackend(value, mapping);
    } else {
      result[newKey] = value;
    }
  }
  
  return result;
};

/**
 * 后端数据转前端数据
 */
export const toFrontend = <T = any>(data: any, mapping?: Record<string, string>): T => {
  const result: any = {};
  
  for (const [key, value] of Object.entries(data)) {
    let newKey = key;
    if (mapping && mapping[key]) {
      newKey = mapping[key];
    }
    
    if (Array.isArray(value)) {
      result[newKey] = value.map((item) => {
        if (typeof item === 'object' && item !== null) {
          return toFrontend(item, mapping);
        }
        return item;
      });
    } else if (typeof value === 'object' && value !== null) {
      result[newKey] = toFrontend(value, mapping);
    } else {
      result[newKey] = value;
    }
  }
  
  return result;
};

/**
 * 字段映射示例
 */
export const FIELD_MAPPING = {
  userName: 'user_name',
  createTime: 'create_time',
  updateTime: 'update_time'
};

/**
 * 批量转换数据
 */
export const batchTransform = <T = any>(list: any[], transformer: (data: any) => T): T[] => {
  return list.map((item) => transformer(item));
};
```

### 2.4 API Hook 模板

```typescript
// src/composables/api/useUserList.ts

import { ref, reactive, onMounted, watch } from 'vue';
import { userApi } from '@/api/modules/user';
import type { IUser, IUserListParams, IPageResponse } from '@/types';

/**
 * 用户列表 Hook
 */
export const useUserList = (defaultParams?: Partial<IUserListParams>) => {
  // 列表数据
  const list = ref<IUser[]>([]);
  // 加载状态
  const loading = ref(false);
  // 总条数
  const total = ref(0);
  
  // 查询参数
  const params = reactive<IUserListParams>({
    page: 1,
    pageSize: 10,
    ...defaultParams
  });

  // 加载列表
  const loadList = async (resetPage = false): Promise<void> => {
    if (resetPage) {
      params.page = 1;
    }
    
    loading.value = true;
    try {
      const res = await userApi.getList({ ...params });
      if (res.code === 200) {
        list.value = res.data.list;
        total.value = res.data.total;
      }
    } finally {
      loading.value = false;
    }
  };

  // 刷新
  const refresh = (): Promise<void> => {
    return loadList(true);
  };

  // 重置查询
  const reset = (): Promise<void> => {
    Object.assign(params, {
      page: 1,
      pageSize: 10,
      ...defaultParams
    });
    return loadList();
  };

  // 分页变化
  const handlePageChange = (page: number): void => {
    params.page = page;
    loadList();
  };

  // 每页条数变化
  const handleSizeChange = (size: number): void => {
    params.pageSize = size;
    params.page = 1;
    loadList();
  };

  // 监听参数变化自动刷新
  watch(
    () => [params.page, params.pageSize],
    () => {
      loadList();
    }
  );

  // 组件挂载时加载
  onMounted(() => {
    loadList();
  });

  return {
    list,
    loading,
    total,
    params,
    loadList,
    refresh,
    reset,
    handlePageChange,
    handleSizeChange
  };
};
```

### 2.5 通用请求 Hook 模板

```typescript
// src/composables/useRequest.ts

import { ref, computed } from 'vue';

/**
 * 通用请求 Hook
 */
export const useRequest = <T = any, P extends any[] = any[]>(
  requestFn: (...args: P) => Promise<T>,
  options?: {
    manual?: boolean;
    onSuccess?: (data: T) => void;
    onError?: (error: any) => void;
    defaultParams?: P;
  }
) => {
  const { manual = false, onSuccess, onError, defaultParams } = options || {};

  const data = ref<T>();
  const loading = ref(false);
  const error = ref<any>();

  const run = async (...args: P): Promise<T | undefined> => {
    loading.value = true;
    error.value = undefined;
    
    try {
      const result = await requestFn(...args);
      data.value = result;
      onSuccess?.(result);
      return result;
    } catch (err) {
      error.value = err;
      onError?.(err);
      throw err;
    } finally {
      loading.value = false;
    }
  };

  const reset = (): void => {
    data.value = undefined;
    loading.value = false;
    error.value = undefined;
  };

  // 自动执行
  if (!manual && defaultParams) {
    run(...defaultParams);
  }

  return {
    data,
    loading,
    error,
    run,
    reset
  };
};
```

### 2.6 Pinia Store 模板

```typescript
// src/stores/modules/user.ts

import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
import { userApi } from '@/api/modules/user';
import type { IUser, IUserListParams } from '@/types';

/**
 * 用户 Store
 */
export const useUserStore = defineStore('user', () => {
  // 当前用户信息
  const currentUser = ref<IUser | null>(null);
  // 用户列表
  const userList = ref<IUser[]>([]);
  // 选中的用户
  const selectedUsers = ref<IUser[]>([]);
  
  // 是否有选中的用户
  const hasSelected = computed(() => selectedUsers.value.length > 0);
  // 选中的用户ID
  const selectedIds = computed(() => selectedUsers.value.map((user) => user.id));

  // 设置当前用户
  const setCurrentUser = (user: IUser | null): void => {
    currentUser.value = user;
  };

  // 加载用户列表
  const loadUserList = async (params: IUserListParams): Promise<void> => {
    const res = await userApi.getList(params);
    if (res.code === 200) {
      userList.value = res.data.list;
    }
  };

  // 刷新用户列表
  const refreshUserList = async (): Promise<void> => {
    await loadUserList({ page: 1, pageSize: 10 });
  };

  // 清空选中
  const clearSelection = (): void => {
    selectedUsers.value = [];
  };

  // 设置选中
  const setSelection = (users: IUser[]): void => {
    selectedUsers.value = users;
  };

  // 添加选中
  const addSelection = (user: IUser): void => {
    const exists = selectedUsers.value.find((u) => u.id === user.id);
    if (!exists) {
      selectedUsers.value.push(user);
    }
  };

  // 移除选中
  const removeSelection = (userId: number): void => {
    selectedUsers.value = selectedUsers.value.filter((u) => u.id !== userId);
  };

  return {
    currentUser,
    userList,
    selectedUsers,
    hasSelected,
    selectedIds,
    setCurrentUser,
    loadUserList,
    refreshUserList,
    clearSelection,
    setSelection,
    addSelection,
    removeSelection
  };
});
```

### 2.7 Mock 数据模板

```typescript
// src/api/mock/user.ts

import type { IUser, IPageResponse } from '@/types';

/**
 * 用户 Mock 数据
 */
export const mockUsers: IUser[] = [
  {
    id: 1,
    username: 'admin',
    nickname: '管理员',
    email: 'admin@example.com',
    phone: '13800138000',
    avatar: 'https://example.com/avatar1.png',
    status: 1,
    createTime: Date.now(),
    updateTime: Date.now()
  },
  {
    id: 2,
    username: 'user1',
    nickname: '用户1',
    email: 'user1@example.com',
    phone: '13800138001',
    avatar: 'https://example.com/avatar2.png',
    status: 1,
    createTime: Date.now(),
    updateTime: Date.now()
  }
];

/**
 * Mock 用户列表接口
 */
export const mockGetUserList = (params: any): IPageResponse<IUser> => {
  const { page = 1, pageSize = 10 } = params;
  const start = (page - 1) * pageSize;
  const end = start + pageSize;
  
  return {
    list: mockUsers.slice(start, end),
    total: mockUsers.length,
    page,
    pageSize,
    totalPages: Math.ceil(mockUsers.length / pageSize)
  };
};

/**
 * Mock 用户详情接口
 */
export const mockGetUserDetail = (id: number): IUser | undefined => {
  return mockUsers.find((user) => user.id === id);
};
```

### 2.8 页面组件联调模板

```vue
<template>
  <div class="user-list-container">
    <!-- 搜索区域 -->
    <el-card class="search-card">
      <el-form :model="searchForm" inline @submit.prevent="handleSearch">
        <el-form-item label="用户名">
          <el-input
            v-model="searchForm.username"
            placeholder="请输入用户名"
            clearable
          />
        </el-form-item>
        <el-form-item label="状态">
          <el-select
            v-model="searchForm.status"
            placeholder="请选择状态"
            clearable
          >
            <el-option label="启用" :value="1" />
            <el-option label="禁用" :value="0" />
          </el-select>
        </el-form-item>
        <el-form-item>
          <el-button type="primary" :loading="loading" @click="handleSearch">
            查询
          </el-button>
          <el-button @click="handleReset">重置</el-button>
        </el-form-item>
      </el-form>
    </el-card>

    <!-- 操作区域 -->
    <el-card class="operation-card">
      <template #header>
        <div class="operation-header">
          <span>用户列表</span>
          <div class="operation-actions">
            <el-button type="primary" @click="handleCreate">
              新增
            </el-button>
            <el-button
              type="danger"
              :disabled="!hasSelected"
              @click="handleBatchDelete"
            >
              批量删除
            </el-button>
            <el-button @click="handleExport">
              导出
            </el-button>
          </div>
        </div>
      </template>

      <!-- 表格 -->
      <el-table
        ref="tableRef"
        v-loading="loading"
        :data="list"
        stripe
        border
        @selection-change="handleSelectionChange"
      >
        <el-table-column type="selection" width="55" />
        <el-table-column prop="id" label="ID" width="80" />
        <el-table-column prop="username" label="用户名" />
        <el-table-column prop="nickname" label="昵称" />
        <el-table-column prop="email" label="邮箱" />
        <el-table-column prop="phone" label="手机号" />
        <el-table-column label="状态" width="100">
          <template #default="{ row }">
            <el-tag :type="row.status === 1 ? 'success' : 'danger'">
              {{ row.status === 1 ? '启用' : '禁用' }}
            </el-tag>
          </template>
        </el-table-column>
        <el-table-column label="操作" width="200" fixed="right">
          <template #default="{ row }">
            <el-button link type="primary" @click="handleDetail(row)">
              详情
            </el-button>
            <el-button link type="primary" @click="handleEdit(row)">
              编辑
            </el-button>
            <el-button link type="danger" @click="handleDelete(row)">
              删除
            </el-button>
          </template>
        </el-table-column>
      </el-table>

      <!-- 分页 -->
      <el-pagination
        v-model:current-page="params.page"
        v-model:page-size="params.pageSize"
        :total="total"
        :page-sizes="[10, 20, 50, 100]"
        layout="total, sizes, prev, pager, next, jumper"
        background
        @size-change="handleSizeChange"
        @current-change="handlePageChange"
      />
    </el-card>

    <!-- 新增/编辑弹窗 -->
    <el-dialog
      v-model="dialogVisible"
      :title="dialogTitle"
      width="600px"
      @close="handleDialogClose"
    >
      <el-form
        ref="formRef"
        :model="formData"
        :rules="formRules"
        label-width="100px"
      >
        <el-form-item label="用户名" prop="username">
          <el-input v-model="formData.username" placeholder="请输入用户名" />
        </el-form-item>
        <el-form-item label="昵称" prop="nickname">
          <el-input v-model="formData.nickname" placeholder="请输入昵称" />
        </el-form-item>
        <el-form-item label="邮箱" prop="email">
          <el-input v-model="formData.email" placeholder="请输入邮箱" />
        </el-form-item>
        <el-form-item label="手机号" prop="phone">
          <el-input v-model="formData.phone" placeholder="请输入手机号" />
        </el-form-item>
      </el-form>
      <template #footer>
        <el-button @click="dialogVisible = false">取消</el-button>
        <el-button type="primary" :loading="submitLoading" @click="handleSubmit">
          确定
        </el-button>
      </template>
    </el-dialog>
  </div>
</template>

<script setup lang="ts">
import { ref, reactive, computed } from 'vue';
import { ElMessage, ElMessageBox } from 'element-plus';
import { useUserList } from '@/composables/api/useUserList';
import { userApi } from '@/api/modules/user';
import type { IUser, ICreateUserParams, IUpdateUserParams } from '@/types';

/**
 * 用户列表组件
 */

// 搜索表单
const searchForm = reactive({
  username: '',
  status: ''
});

// 使用用户列表 Hook
const {
  list,
  loading,
  total,
  params,
  loadList,
  refresh
} = useUserList();

// 选中的用户
const selectedUsers = ref<IUser[]>([]);
const hasSelected = computed(() => selectedUsers.value.length > 0);

// 弹窗
const dialogVisible = ref(false);
const dialogTitle = computed(() => (isEdit.value ? '编辑用户' : '新增用户'));
const isEdit = ref(false);
const submitLoading = ref(false);

// 表单
const formRef = ref();
const formData = reactive({
  id: 0,
  username: '',
  nickname: '',
  email: '',
  phone: ''
});

const formRules = {
  username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
  nickname: [{ required: true, message: '请输入昵称', trigger: 'blur' }],
  email: [
    { required: true, message: '请输入邮箱', trigger: 'blur' },
    { type: 'email', message: '请输入正确的邮箱格式', trigger: 'blur' }
  ]
};

/**
 * 搜索
 */
const handleSearch = (): void => {
  Object.assign(params, searchForm);
  loadList(true);
};

/**
 * 重置搜索
 */
const handleReset = (): void => {
  Object.assign(searchForm, {
    username: '',
    status: ''
  });
  refresh();
};

/**
 * 选择变化
 */
const handleSelectionChange = (selection: IUser[]): void => {
  selectedUsers.value = selection;
};

/**
 * 新增
 */
const handleCreate = (): void => {
  isEdit.value = false;
  Object.assign(formData, {
    id: 0,
    username: '',
    nickname: '',
    email: '',
    phone: ''
  });
  dialogVisible.value = true;
};

/**
 * 详情
 */
const handleDetail = (row: IUser): void => {
  console.log('详情:', row);
};

/**
 * 编辑
 */
const handleEdit = (row: IUser): void => {
  isEdit.value = true;
  Object.assign(formData, row);
  dialogVisible.value = true;
};

/**
 * 删除
 */
const handleDelete = async (row: IUser): Promise<void> => {
  await ElMessageBox.confirm('确定要删除该用户吗？', '提示', {
    type: 'warning'
  });
  
  await userApi.delete(row.id);
  ElMessage.success('删除成功');
  await refresh();
};

/**
 * 批量删除
 */
const handleBatchDelete = async (): Promise<void> => {
  const ids = selectedUsers.value.map((user) => user.id);
  await ElMessageBox.confirm(`确定要删除选中的 ${ids.length} 个用户吗？`, '提示', {
    type: 'warning'
  });
  
  await userApi.batchDelete(ids);
  ElMessage.success('删除成功');
  selectedUsers.value = [];
  await refresh();
};

/**
 * 导出
 */
const handleExport = async (): Promise<void> => {
  await userApi.export({ ...params, ...searchForm });
  ElMessage.success('导出成功');
};

/**
 * 提交
 */
const handleSubmit = async (): Promise<void> => {
  await formRef.value.validate();
  
  submitLoading.value = true;
  try {
    if (isEdit.value) {
      const data: IUpdateUserParams = {
        id: formData.id,
        nickname: formData.nickname,
        email: formData.email,
        phone: formData.phone
      };
      await userApi.update(formData.id, data);
    } else {
      const data: ICreateUserParams = {
        username: formData.username,
        password: '123456',
        nickname: formData.nickname,
        email: formData.email,
        phone: formData.phone
      };
      await userApi.create(data);
    }
    
    ElMessage.success(isEdit.value ? '更新成功' : '创建成功');
    dialogVisible.value = false;
    await refresh();
  } finally {
    submitLoading.value = false;
  }
};

/**
 * 弹窗关闭
 */
const handleDialogClose = (): void => {
  formRef.value?.resetFields();
};

/**
 * 分页变化
 */
const handlePageChange = (page: number): void => {
  params.page = page;
  loadList();
};

const handleSizeChange = (size: number): void => {
  params.pageSize = size;
  params.page = 1;
  loadList();
};
</script>

<style lang="scss" scoped>
.user-list-container {
  .search-card,
  .operation-card {
    margin-bottom: 20px;
  }
  
  .operation-header {
    display: flex;
    justify-content: space-between;
    align-items: center;
    
    .operation-actions {
      display: flex;
      gap: 10px;
    }
  }
}
</style>
```

## 3. 注意事项

### 3.1 接口设计规范
- **RESTful 风格**: 使用标准的 HTTP 方法（GET/POST/PUT/DELETE）
- **统一响应格式**: 所有接口返回统一的数据结构（code/message/data）
- **状态码规范**: 业务状态码和 HTTP 状态码分离
- **分页参数**: 统一使用 page/pageSize 参数

### 3.2 数据转换
- **前端到后端**: 数据提交前进行字段映射和格式转换
- **后端到前端**: 数据接收后进行字段映射和格式转换
- **日期处理**: 统一日期格式和时区处理
- **类型转换**: 确保数值、布尔值等类型正确

### 3.3 错误处理
- **统一错误提示**: 使用 Element Plus 消息组件统一提示
- **业务错误**: 根据业务状态码进行不同处理
- **网络错误**: 友好的网络异常提示
- **错误日志**: 开发环境打印详细错误日志

### 3.4 性能优化
- **请求防抖**: 搜索、筛选等操作添加防抖
- **请求取消**: 路由切换时取消未完成的请求
- **数据缓存**: 合理使用缓存避免重复请求
- **懒加载**: 列表分页、图片懒加载等

### 3.5 调试技巧
- **开发环境**: 打印请求和响应日志
- **Network 面板**: 使用浏览器开发者工具查看请求详情
- **Mock 数据**: 后端未完成时使用 Mock 数据开发
- **代理配置**: Vite 代理解决跨域问题

### 3.6 禁止事项
- 禁止直接在组件中使用 axios，必须使用封装后的 API
- 禁止在接口调用后不处理错误
- 禁止硬编码 API 地址
- 禁止在组件中写复杂的业务逻辑
- 禁止忽略 loading 状态

## 4. 执行步骤

1. **确认接口文档**: 获取后端接口文档，确认接口地址、参数、响应格式
2. **定义类型**: 根据接口文档定义 TypeScript 类型
3. **封装 API 模块**: 创建 API 模块，封装接口调用
4. **创建 API Hook**: 创建组合式函数，管理接口状态和逻辑
5. **创建 Store (可选)**: 使用 Pinia 管理共享状态
6. **开发页面组件**: 在组件中使用 API Hook
7. **联调测试**: 与后端进行接口联调测试
8. **Mock 数据**: 后端未完成时使用 Mock 数据开发

## 5. Vite 代理配置

```typescript
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
});
```

## 6. 依赖安装

```bash
pnpm add axios pinia
pnpm add -D @types/node
```