frontend/src/router/README.md

# Vue Router Configuration

## Overview

This directory contains the Vue Router configuration for the Sub2API frontend application. The router implements a comprehensive navigation system with authentication guards, role-based access control, and lazy loading.

## Files

- **index.ts**: Main router configuration with route definitions and navigation guards
- **meta.d.ts**: TypeScript type definitions for route meta fields

## Route Structure

### Public Routes (No Authentication Required)

| Path        | Component    | Description            |
| ----------- | ------------ | ---------------------- |
| `/login`    | LoginView    | User login page        |
| `/register` | RegisterView | User registration page |

### User Routes (Authentication Required)

| Path         | Component     | Description                  |
| ------------ | ------------- | ---------------------------- |
| `/`          | -             | Redirects to `/dashboard`    |
| `/dashboard` | DashboardView | User dashboard with stats    |
| `/keys`      | KeysView      | API key management           |
| `/usage`     | UsageView     | Usage records and statistics |
| `/redeem`    | RedeemView    | Redeem code interface        |
| `/profile`   | ProfileView   | User profile settings        |

### Admin Routes (Admin Role Required)

| Path               | Component          | Description                     |
| ------------------ | ------------------ | ------------------------------- |
| `/admin`           | -                  | Redirects to `/admin/dashboard` |
| `/admin/dashboard` | AdminDashboardView | Admin dashboard                 |
| `/admin/users`     | AdminUsersView     | User management                 |
| `/admin/groups`    | AdminGroupsView    | Group management                |
| `/admin/accounts`  | AdminAccountsView  | Account management              |
| `/admin/proxies`   | AdminProxiesView   | Proxy management                |
| `/admin/redeem`    | AdminRedeemView    | Redeem code management          |

### Special Routes

| Path              | Component    | Description    |
| ----------------- | ------------ | -------------- |
| `/:pathMatch(.*)` | NotFoundView | 404 error page |

## Navigation Guards

### Authentication Guard (beforeEach)

The router implements a comprehensive navigation guard that:

1. **Sets Page Title**: Updates document title based on route meta
2. **Checks Authentication**:
   - Public routes (`requiresAuth: false`) are accessible without login
   - Protected routes require authentication
   - Redirects to `/login` if not authenticated
3. **Prevents Double Login**:
   - Redirects authenticated users away from login/register pages
4. **Role-Based Access Control**:
   - Admin routes (`requiresAdmin: true`) require admin role
   - Non-admin users are redirected to `/dashboard`
5. **Preserves Intended Destination**:
   - Saves original URL in query parameter for post-login redirect

### Flow Diagram

```
User navigates to route
        ↓
Set page title from meta
        ↓
Is route public? ──Yes──→ Already authenticated? ──Yes──→ Redirect to /dashboard
        ↓ No                                        ↓ No
        ↓                                      Allow access
        ↓
Is user authenticated? ──No──→ Redirect to /login with redirect query
        ↓ Yes
        ↓
Requires admin role? ──Yes──→ Is user admin? ──No──→ Redirect to /dashboard
        ↓ No                                  ↓ Yes
        ↓                                     ↓
Allow access ←────────────────────────────────┘
```

## Route Meta Fields

Each route can define the following meta fields:

```typescript
interface RouteMeta {
  requiresAuth?: boolean // Default: true (requires authentication)
  requiresAdmin?: boolean // Default: false (admin access only)
  title?: string // Page title
  breadcrumbs?: Array<{
    // Breadcrumb navigation
    label: string
    to?: string
  }>
  icon?: string // Icon for navigation menu
  hideInMenu?: boolean // Hide from navigation menu
}
```

## Lazy Loading

All route components use dynamic imports for code splitting:

```typescript
component: () => import('@/views/user/DashboardView.vue')
```

Benefits:

- Reduced initial bundle size
- Faster initial page load
- Components loaded on-demand
- Automatic code splitting by Vite

## Authentication Store Integration

The router integrates with the Pinia auth store (`@/stores/auth`):

```typescript
const authStore = useAuthStore()

// Check authentication status
authStore.isAuthenticated

// Check admin role
authStore.isAdmin
```

## Usage Examples

### Programmatic Navigation

```typescript
import { useRouter } from 'vue-router'

const router = useRouter()

// Navigate to a route
router.push('/dashboard')

// Navigate with query parameters
router.push({
  path: '/usage',
  query: { filter: 'today' }
})

// Navigate to admin route (will be blocked if not admin)
router.push('/admin/users')
```

### Route Links

```vue
<template>
  <!-- Simple link -->
  <router-link to="/dashboard">Dashboard</router-link>

  <!-- Named route -->
  <router-link :to="{ name: 'Keys' }">API Keys</router-link>

  <!-- With query parameters -->
  <router-link :to="{ path: '/usage', query: { page: 1 } }"> Usage </router-link>
</template>
```

### Checking Current Route

```typescript
import { useRoute } from 'vue-router'

const route = useRoute()

// Check if on admin page
const isAdminPage = route.path.startsWith('/admin')

// Get route meta
const requiresAdmin = route.meta.requiresAdmin
```

## Scroll Behavior

The router implements automatic scroll management:

- **Browser Navigation**: Restores saved scroll position
- **New Routes**: Scrolls to top of page
- **Hash Links**: Scrolls to anchor (when implemented)

## Error Handling

The router includes error handling for navigation failures:

```typescript
router.onError((error) => {
  console.error('Router error:', error)
})
```

## Testing Routes

To test navigation guards and route access:

1. **Public Route Access**: Visit `/login` without authentication
2. **Protected Route**: Try accessing `/dashboard` without login (should redirect)
3. **Admin Access**: Login as regular user, try `/admin/users` (should redirect to dashboard)
4. **Admin Success**: Login as admin, access `/admin/users` (should succeed)
5. **404 Handling**: Visit non-existent route (should show 404 page)

## Development Tips

### Adding New Routes

1. Add route definition in `routes` array
2. Create corresponding view component
3. Set appropriate meta fields (`requiresAuth`, `requiresAdmin`)
4. Use lazy loading with `() => import()`
5. Update this README with route documentation

### Debugging Navigation

Enable Vue Router debug mode:

```typescript
// In browser console
window.__VUE_ROUTER__ = router

// Check current route
router.currentRoute.value
```

### Common Issues

**Issue**: 404 on page refresh

- **Cause**: Server not configured for SPA
- **Solution**: Configure server to serve `index.html` for all routes

**Issue**: Navigation guard runs twice

- **Cause**: Multiple `next()` calls
- **Solution**: Ensure only one `next()` call per code path

**Issue**: User data not loaded

- **Cause**: Auth store not initialized
- **Solution**: Call `authStore.checkAuth()` in App.vue or main.ts

## Security Considerations

1. **Client-Side Only**: Navigation guards are client-side; server must also validate
2. **Token Validation**: API should verify JWT token on every request
3. **Role Checking**: Backend must verify admin role, not just frontend
4. **XSS Protection**: Vue automatically escapes template content
5. **CSRF Protection**: Use CSRF tokens for state-changing operations

## Performance Optimization

1. **Lazy Loading**: All routes use dynamic imports
2. **Code Splitting**: Vite automatically splits route chunks
3. **Prefetching**: Consider adding route prefetch for common paths
4. **Route Caching**: Vue Router caches component instances

## Future Enhancements

- [ ] Add breadcrumb navigation system
- [ ] Implement route-based permissions beyond admin/user
- [ ] Add route transition animations
- [ ] Implement route prefetching for anticipated navigation
- [ ] Add navigation analytics tracking