sub2api/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