frontend/README.md

# Super-frpc Frontend

Frontend application for Super-frpc - a frpc instance integrated management system. This project provides a user-friendly web interface for managing frpc instances, users, sessions, and monitoring system resources.

## Features

- User authentication with token-based login and registration
- Instance management (create, delete, modify, start, stop, restart)
- User management (create, edit, delete users)
- Session management (view and delete active sessions)
- System logs viewing with filtering capabilities
- Real-time system monitoring (CPU, memory, disk, network)
- System information display
- Role-based access control (superuser, admin, visitor)
- Responsive design with modern UI

## Technology Stack

- **Vue.js 3** - Progressive JavaScript framework
- **Vue Router 4** - Official router for Vue.js
- **Axios** - HTTP client for API requests
- **Chart.js** - Charting library for data visualization
- **Vite** - Build tool and dev server

## Project Structure

```
frontend/
├── index.html              # Entry HTML file
├── package.json            # Project dependencies and scripts
├── vite.config.js          # Vite configuration
├── src/
│   ├── main.js            # Application entry point
│   ├── App.vue            # Root component
│   ├── router/
│   │   └── index.js      # Vue Router configuration
│   ├── api/
│   │   └── index.js      # API service layer
│   ├── utils/
│   │   └── functions.js   # Utility functions
│   ├── components/
│   │   ├── TopBar.vue     # Top navigation bar
│   │   └── SideBar.vue   # Side navigation menu
│   └── views/
│       ├── Login.vue      # Login/Register page
│       ├── Home.vue       # Main layout
│       ├── Instances.vue  # Instance management
│       ├── InstanceDetail.vue  # Instance details
│       ├── Users.vue      # User management
│       ├── Sessions.vue   # Session management
│       ├── Logs.vue       # System logs
│       ├── Monitor.vue    # System monitoring
│       └── SystemInfo.vue # System information
├── logger.js              # Logging utility
├── api-backend.md        # Backend API documentation
└── README.md             # This file
```

## Installation

### Prerequisites

- Node.js (v16 or higher)
- npm or yarn
- Backend server running (see backend README)

### Steps

1. Clone the repository:
```bash
git clone <repository-url>
cd Super-frpc/frontend
```

2. Install dependencies:
```bash
npm install
```

3. Configure backend API endpoint in `vite.config.js`:
```javascript
server: {
    proxy: {
        '/api': {
            target: 'http://localhost:8080',  // Change to your backend address
            changeOrigin: true,
            rewrite: (path) => path.replace(/^\/api/, '')
        }
    }
}
```

## Usage

### Development Mode

Start the development server:
```bash
npm run dev
```

The application will be available at `http://localhost:3000`

### Production Build

Build for production:
```bash
npm run build
```

The built files will be in the `dist/` directory.

### Preview Production Build

Preview the production build:
```bash
npm run preview
```

## User Roles and Permissions

| Feature | superuser | admin | visitor |
|---------|-----------|-------|---------|
| Login/Register | ✓ | ✓ | ✓ |
| Instance Management | ✓ | ✓ | ✓ (view only) |
| User Management | ✓ | ✗ | ✗ |
| Session Management | ✓ | ✓ | ✗ |
| System Logs | ✓ | ✓ | ✗ |
| System Monitoring | ✓ | ✓ | ✓ |
| System Information | ✓ | ✓ | ✓ |

## API Integration

The frontend communicates with the backend through RESTful APIs. All API calls are centralized in `src/api/index.js`.

### Authentication

All requests (except `/register`, `/login`, `/system/getStatus`, `/system/getSoftwareInfo`) require authentication via the `X-Token` header.

### Response Format

All API responses follow this format:

**Success:**
```json
{
  "success": true,
  "message": "success message",
  "data": { ... }
}
```

**Error:**
```json
{
  "success": false,
  "message": "error message"
}
```

For detailed API documentation, see [api-backend.md](api-backend.md).

## Development Guidelines

### Code Style

- Follow Vue.js official style guide
- Use component-based architecture
- Keep components small and focused
- Use composition API for new components
- Add comments for complex logic

### File Naming

- Components: PascalCase (e.g., `TopBar.vue`)
- Views: PascalCase (e.g., `Instances.vue`)
- Utilities: camelCase (e.g., `functions.js`)

### State Management

- Use Vue 3 Composition API for local state
- Use cookies for authentication state
- Use reactive refs for component data

### API Calls

- All API calls should go through `src/api/index.js`
- Handle errors appropriately
- Show user-friendly notifications
- Log errors using the `postLog` function

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Troubleshooting

### Common Issues

1. **API connection failed**
   - Check if backend server is running
   - Verify proxy configuration in `vite.config.js`
   - Check browser console for CORS errors

2. **Login not working**
   - Verify backend API is accessible
   - Check browser console for error messages
   - Ensure cookies are enabled in browser

3. **Build errors**
   - Clear `node_modules` and reinstall: `rm -rf node_modules && npm install`
   - Check Node.js version compatibility

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Workflow

1. Ensure all tests pass
2. Follow the code style guidelines
3. Add comments for complex logic
4. Update documentation as needed
5. Test thoroughly before submitting

## License

GPL-3.0

## Contact

For issues and questions, please open an issue on the repository.

## Acknowledgments

- Vue.js team for the amazing framework
- Chart.js for the visualization library
- All contributors who helped make this project better