gdt-tool/QWEN.md

# Vutron - Vite + Vue 3 + Electron Template

## Project Overview

Vutron is a preconfigured template for developing cross-platform desktop applications using modern web technologies. The project combines:

- **Vite** as the build tool and development server
- **Vue 3** with TypeScript for the user interface
- **Electron** for creating desktop applications
- **Vuetify** as the UI component library
- **Pinia** for state management
- **vue-i18n** for internationalization
- **Playwright** for automated testing

The template provides a ready-to-use development environment with hot-reload, cross-platform build support, automated testing, and theme management (dark/light).

## Architecture

The project follows the typical Electron architecture with three main processes:

### Main Process (`src/main/`)

- Handles application lifecycle
- Manages windows and system integration
- Located in `src/main/index.ts`
- Also includes utilities, tray functionality, and IPC handlers

### Preload Process (`src/preload/`)

- Acts as an isolated bridge between main and renderer processes
- Uses `contextBridge` to securely expose APIs to the renderer
- Located in `src/preload/index.ts`

### Renderer Process (`src/renderer/`)

- Contains the Vue 3 application
- Uses Vuetify for UI components
- Located in `src/renderer/` with:
  - Components (`src/renderer/components/`)
  - Screens/views (`src/renderer/screens/`)
  - Router (`src/renderer/router/index.ts`)
  - State management with Pinia (`src/renderer/store/`)
  - Internationalization (`src/renderer/locales/`)
  - Utility functions (`src/renderer/utils/`)

## Building and Running

### Prerequisites

- Node.js >= 20.0.0
- pnpm package manager (recommended)

### Development

```bash
# Install dependencies
pnpm install

# Start development server with hot-reload
pnpm dev

# Development with debug info
pnpm dev:debug

# Force reinstall dependencies and start development
pnpm dev:debug:force

# run Typescript Type check
pnpm typecheck
```

### Building

```bash
# Build for all platforms
pnpm build:all

# Build for specific platforms
pnpm build:mac    # macOS
pnpm build:win    # Windows
pnpm build:linux  # Linux

# Build without packaging (useful for quick testing)
pnpm build:dir

# Run type checking, formatting, and build
pnpm build
```

### Testing

```bash
# Run Playwright tests
pnpm test

# Run tests on Linux with virtual display
pnpm test:linux
```

### Linting and Formatting

```bash
# Check for linting issues
pnpm lint

# Fix linting issues automatically
pnpm lint:fix

```

## Key Features

1. **Hot Module Replacement**: Develop with instant feedback via Vite's fast hot-reload
2. **Type Safety**: Full TypeScript support across the application
3. **Internationalization**: Built-in multi-language support (11 languages available)
4. **Theme Management**: Easy switching between dark and light themes
5. **State Management**: Pinia for reactive state management
6. **Cross-platform Builds**: Build for Windows, macOS, and Linux from a single codebase
7. **Testing**: Integrated Playwright testing setup
8. **Logging**: electron-log for both main and renderer processes
9. **Security**: Secure IPC communication between processes

## Project Structure

```
├── buildAssets/              # Build configurations and icons
├── dist/                     # Build output directory
├── docs/                     # Documentation
├── node_modules/             # Dependencies
├── src/                      # Source code
│   ├── main/                 # Electron main process code
│   ├── preload/              # Preload script for context isolation
│   └── renderer/             # Vue application code
│       ├── components/       # Vue components
│       ├── locales/          # Translation files
│       ├── plugins/          # Vue plugins (i18n, Pinia, Vuetify)
│       ├── router/           # Vue Router configuration
│       ├── screens/          # Application views/pages
│       ├── store/            # Pinia stores
│       ├── utils/            # Utility functions
│       ├── App.vue           # Root component
│       ├── index.html        # HTML entry point
│       └── main.ts           # Vue application entry point
├── tests/                    # Test files
├── .vscode/                  # VS Code settings
├── .editorconfig             # Editor configuration
├── .gitignore                # Git ignore rules
├── .prettierignore           # Prettier ignore rules
├── .prettierrc               # Prettier configuration
├── eslint.config.ts          # ESLint configuration
├── package.json              # Project dependencies and scripts
├── playwright.config.ts      # Playwright test configuration
├── pnpm-lock.yaml            # Dependency lock file
├── pnpm-workspace.yaml       # pnpm workspace configuration
├── README.md                 # Project documentation
├── tsconfig.json             # TypeScript configuration
├── tsconfig.node.json        # TypeScript configuration for Node.js files
└── vite.config.mts           # Vite configuration
```

## Development Conventions

1. **Code Style**:
   - Uses ESLint with TypeScript and Vue plugin
   - Formatted with Prettier
   - Follows Vue 3 Composition API with TypeScript

2. **Component Structure**:
   - Components use Vue 3's `<script setup>` syntax
   - Written in TypeScript with proper typing
   - Utilize Vuetify components for UI

3. **Internationalization**:
   - Uses vue-i18n for multi-language support
   - Translation files stored in `src/renderer/locales/`
   - Keys are organized in JSON format

4. **State Management**:
   - Uses Pinia for state management
   - Stores are defined in `src/renderer/store/`
   - Follow Pinia's composition store pattern

5. **Routing**:
   - Uses Vue Router with web hash history
   - Routes defined in `src/renderer/router/index.ts`

6. **IPC Communication**:
   - Secure communication between main and renderer processes
   - Uses whitelisted channels defined in preload script
   - Accessible via `window.mainApi` in renderer process

## Internationalization

The application supports multiple languages with the following locale files:

- English (`en`)
- Korean (`ko`)
- Simplified Chinese (`zh-hans`)
- Traditional Chinese (`zh-hant`)
- German (`de`)
- Spanish (`es`)
- Japanese (`ja`)
- French (`fr`)
- Russian (`ru`)
- Portuguese (`pt`)
- Dutch (`nl`)

## Electron Integration

The application integrates with Electron features through:

- IPC communication for sending messages between processes
- Native file dialog support
- External link opening
- Application version retrieval
- Error handling and logging

## Testing

The project includes Playwright for end-to-end testing, with configuration in `playwright.config.ts` and test files in the `tests/` directory.

## Build Outputs

Building creates different distribution formats based on the platform:

- **macOS**: DMG installer for x64, arm64, and universal architectures
- **Windows**: APPX, ZIP, Portable, and NSIS installers (x64)
- **Linux**: SNAP, DEB, and RPM packages (x64)

Artifacts are named with the format `${productName} ${version}_${arch}.${ext}` and stored in the `release/${version}` directory.

run `pnpm typecheck` before finish the task if need，don't run `pnpm dev` or `pnpm build`.

Always respond in 中文