Development Guide

Basic Response Format

The default response format is as follows. To modify it, please edit the src/types/common/response.ts file:

/** Base Response */
interface BaseResponse<T = unknown> {
  code: number; // Status code
  msg: string; // Message
  data: T; // Data
}

Network requests return the data in data by default, not the entire response body:

try {
  const { token, refreshToken } = await fetchLogin({
    userName: username,
    password,
  });
} catch (error) {
  if (error instanceof HttpError) {
    // Handle different status codes
    // console.log(error.code)
  }
}

Menu API Integration

Switch permission mode in the .env file:

# Permission mode [frontend / backend]
VITE_ACCESS_MODE = backend

After switching to backend mode, open the browser console's Network panel to see the menu API response format.

Backend menu API response format:

{
  code: 200,
  msg: "success",
  data: [
    {
      name: 'Dashboard',
      path: '/dashboard',
      component: "/index/index",
      meta: {
        title: 'menus.dashboard.title',
        icon: 'ri:pie-chart-line'
      },
      children: [...]
    }
  ]
}

View data format in console:

Frontend mode (asyncRoutes.ts):

In frontend mode, the roles field is used for permission filtering. The menu is filtered by comparing the roles returned from the user info API with the roles configured in the menu:

{
  name: 'Dashboard',
  path: '/dashboard',
  component: "/index/index",
  meta: {
    title: 'menus.dashboard.title',
    icon: 'ri:pie-chart-line',
    roles: ['R_SUPER', 'R_ADMIN'] // Only these roles can access
  }
}

Note: In backend mode, the menu is returned by the backend based on user roles, so the roles field is not needed.

Table Pagination API Integration

Configuration file: src/utils/table/tableConfig.ts

The system automatically searches for backend response fields in priority order, supporting multiple common field names. If the backend uses field names not in the configuration list, you can add custom field names to the configuration.

export const tableConfig = {
  // Response data field mapping configuration, the system searches for these fields in order
  // List data
  recordFields: ["list", "data", "records", "items", "result", "rows"],
  // Total count
  totalFields: ["total", "count"],
  // Current page number
  currentFields: ["current", "page", "pageNum"],
  // Page size
  sizeFields: ["size", "pageSize", "limit"],

  // Request parameter mapping configuration, pagination parameter names used when sending requests
  // useTable composable passes pagination parameters using current and size
  paginationKey: {
    current: "current", // Current page number
    size: "size", // Page size
  },
};

Extension example: If the backend uses other field names, add them to the corresponding array:

recordFields: ["list", "data", "records", "items", "yourCustomField"];

Blank Page on Route Switching

Cause: Route transition animations are enabled, and Vue's <Transition> component requires page components to have a single root element. If a component has multiple root elements (including comment nodes), the animation will fail and result in a blank page.

Solution: Wrap all content in a single container element.

❌ Incorrect examples

<template>
  <!-- Multiple root elements -->
  <div>Content 1</div>
  <span>Content 2</span>
</template>

<template>
  <!-- Comments are also treated as root nodes -->
  <div>
    <div>Content 1</div>
    <span>Content 2</span>
  </div>
</template>

✅ Correct example

<template>
  <div>
    <!-- Comments inside the root element -->
    <div>Content 1</div>
    <span>Content 2</span>
  </div>
</template>

Page Auto-Refresh on Menu Click

Cause: Vite automatically performs dependency pre-bundling optimization in development mode. When using certain component library sub-modules for the first time (such as Element Plus style files), Vite detects new dependencies and re-optimizes, causing the page to refresh.

Identification: Open the browser console. If you see a message like this, you've encountered this issue:

[vite] new dependencies optimized: element-plus/es/components/tooltip/style/index

Solution: Add the dependencies shown in the console to the optimizeDeps.include configuration in vite.config.ts:

export default defineConfig({
  optimizeDeps: {
    include: [
      "element-plus/es/components/tooltip/style/index",
      "element-plus/es/components/message/style/index",
      // Add other dependencies based on console messages
    ],
  },
});

Restart the development server after adding the configuration. This issue only occurs in development environment and does not affect production.

Route Configuration Errors

If there are issues with route configuration (such as missing fields, format errors, non-existent component paths, etc.), the system will provide detailed error messages in the browser console.

Debugging tip: Open the browser console (F12) to view error messages and check the route configuration based on the prompts.

Build Information

• Full version project: approximately 8.4MB
• Lite version project: approximately 4.7MB

The project enables gzip compression by default. When gzip is disabled, the actual build size is approximately 3.7MB. When enabled, the output size is smaller (browsers will prioritize loading .gz files).

To modify compression settings, adjust the viteCompression plugin parameters in vite.config.ts.