First commit

2025-12-18 13:50:39 +08:00
parent 569f4882e5
commit 642842c29e
218 changed files with 86902 additions and 0 deletions
--- a/frontend/src/views/auth/USAGE_EXAMPLES.md
+++ b/frontend/src/views/auth/USAGE_EXAMPLES.md
@@ -0,0 +1,609 @@
+# Authentication Views Usage Examples
+
+This document provides practical examples of how to use the authentication views in the Sub2API frontend.
+
+## Quick Start
+
+### 1. Login Flow
+
+**Scenario:** User wants to log into their existing account
+
+```typescript
+// Route: /login
+// Component: LoginView.vue
+
+// User interactions:
+// 1. Navigate to /login
+// 2. Enter username: "john_doe"
+// 3. Enter password: "MySecurePass123"
+// 4. Optionally check "Remember me"
+// 5. Click "Sign In"
+
+// What happens:
+// - Form validation runs (client-side)
+// - If valid, authStore.login() is called
+// - API request to POST /api/auth/login
+// - On success:
+//   - Token stored in localStorage
+//   - User data stored in state
+//   - Success toast: "Login successful! Welcome back."
+//   - Redirect to /dashboard (or intended route)
+// - On error:
+//   - Error message displayed inline
+//   - Error toast shown
+//   - User can retry
+```
+
+### 2. Registration Flow
+
+**Scenario:** New user wants to create an account
+
+```typescript
+// Route: /register
+// Component: RegisterView.vue
+
+// User interactions:
+// 1. Navigate to /register
+// 2. Enter username: "jane_smith"
+// 3. Enter email: "jane@example.com"
+// 4. Enter password: "SecurePass123"
+// 5. Enter confirm password: "SecurePass123"
+// 6. Click "Create Account"
+
+// What happens:
+// - Form validation runs (client-side)
+//   - Username: 3-50 chars, alphanumeric + _ -
+//   - Email: Valid format
+//   - Password: 8+ chars, letters + numbers
+//   - Passwords match
+// - If valid, authStore.register() is called
+// - API request to POST /api/auth/register
+// - On success:
+//   - Token stored in localStorage
+//   - User data stored in state
+//   - Success toast: "Account created successfully! Welcome to Sub2API."
+//   - Redirect to /dashboard
+// - On error:
+//   - Error message displayed inline
+//   - Error toast shown
+//   - User can retry
+```
+
+## Code Examples
+
+### Importing the Views
+
+```typescript
+// Method 1: Direct import
+import LoginView from '@/views/auth/LoginView.vue';
+import RegisterView from '@/views/auth/RegisterView.vue';
+
+// Method 2: Named exports from index
+import { LoginView, RegisterView } from '@/views/auth';
+
+// Method 3: Lazy loading (recommended for routes)
+const LoginView = () => import('@/views/auth/LoginView.vue');
+const RegisterView = () => import('@/views/auth/RegisterView.vue');
+```
+
+### Using in Router
+
+```typescript
+import { createRouter, createWebHistory } from 'vue-router';
+
+const routes = [
+  {
+    path: '/login',
+    name: 'Login',
+    component: () => import('@/views/auth/LoginView.vue'),
+    meta: { requiresAuth: false },
+  },
+  {
+    path: '/register',
+    name: 'Register',
+    component: () => import('@/views/auth/RegisterView.vue'),
+    meta: { requiresAuth: false },
+  },
+];
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes,
+});
+
+export default router;
+```
+
+### Navigation to Auth Views
+
+```typescript
+// From template
+<router-link to="/login">Login</router-link>
+<router-link to="/register">Sign Up</router-link>
+
+// From script
+import { useRouter } from 'vue-router';
+
+const router = useRouter();
+
+// Navigate to login
+router.push('/login');
+
+// Navigate to register
+router.push('/register');
+
+// Navigate with redirect query
+router.push({
+  path: '/login',
+  query: { redirect: '/dashboard' }
+});
+```
+
+### Programmatic Auth Flow
+
+```typescript
+import { useAuthStore } from '@/stores';
+import { useAppStore } from '@/stores';
+import { useRouter } from 'vue-router';
+
+const authStore = useAuthStore();
+const appStore = useAppStore();
+const router = useRouter();
+
+// Login
+async function login() {
+  try {
+    await authStore.login({
+      username: 'john_doe',
+      password: 'MySecurePass123'
+    });
+
+    appStore.showSuccess('Login successful!');
+    router.push('/dashboard');
+  } catch (error) {
+    appStore.showError('Login failed. Please check your credentials.');
+  }
+}
+
+// Register
+async function register() {
+  try {
+    await authStore.register({
+      username: 'jane_smith',
+      email: 'jane@example.com',
+      password: 'SecurePass123'
+    });
+
+    appStore.showSuccess('Account created successfully!');
+    router.push('/dashboard');
+  } catch (error) {
+    appStore.showError('Registration failed. Please try again.');
+  }
+}
+```
+
+## Validation Examples
+
+### Login Validation
+
+```typescript
+// Valid inputs
+✅ Username: "john_doe" (3+ chars)
+✅ Password: "SecurePass123" (6+ chars)
+
+// Invalid inputs
+❌ Username: "jo" → Error: "Username must be at least 3 characters"
+❌ Password: "12345" → Error: "Password must be at least 6 characters"
+❌ Username: "" → Error: "Username is required"
+❌ Password: "" → Error: "Password is required"
+```
+
+### Registration Validation
+
+```typescript
+// Valid inputs
+✅ Username: "jane_smith" (3-50 chars, alphanumeric + _ -)
+✅ Email: "jane@example.com" (valid format)
+✅ Password: "SecurePass123" (8+ chars, letters + numbers)
+✅ Confirm: "SecurePass123" (matches password)
+
+// Invalid inputs
+❌ Username: "ja" → Error: "Username must be at least 3 characters"
+❌ Username: "jane@smith" → Error: "Username can only contain letters, numbers, underscores, and hyphens"
+❌ Email: "invalid-email" → Error: "Please enter a valid email address"
+❌ Password: "short" → Error: "Password must be at least 8 characters with letters and numbers"
+❌ Password: "12345678" → Error: "Password must be at least 8 characters with letters and numbers" (no letters)
+❌ Password: "password" → Error: "Password must be at least 8 characters with letters and numbers" (no numbers)
+❌ Confirm: "DifferentPass" → Error: "Passwords do not match"
+```
+
+## Error Handling Examples
+
+### Backend Errors
+
+```typescript
+// Example 1: Username already exists
+{
+  response: {
+    data: {
+      detail: "Username 'john_doe' is already taken"
+    }
+  }
+}
+// Displayed: "Username 'john_doe' is already taken"
+
+// Example 2: Invalid credentials
+{
+  response: {
+    data: {
+      detail: "Invalid username or password"
+    }
+  }
+}
+// Displayed: "Invalid username or password"
+
+// Example 3: Network error
+{
+  message: "Network Error"
+}
+// Displayed: "Network Error" + Error toast
+
+// Example 4: Unknown error
+{}
+// Displayed: "Login failed. Please check your credentials and try again." (default)
+```
+
+### Client-side Validation Errors
+
+```typescript
+// Multiple validation errors displayed simultaneously
+errors = {
+  username: "Username must be at least 3 characters",
+  email: "Please enter a valid email address",
+  password: "Password must be at least 8 characters with letters and numbers",
+  confirmPassword: "Passwords do not match"
+}
+
+// Each error appears below its respective input field with red styling
+```
+
+## Testing Examples
+
+### Unit Test: Login View
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { createPinia } from 'pinia';
+import LoginView from '@/views/auth/LoginView.vue';
+
+describe('LoginView', () => {
+  it('validates required fields', async () => {
+    const wrapper = mount(LoginView, {
+      global: {
+        plugins: [createPinia()],
+      },
+    });
+
+    // Submit empty form
+    await wrapper.find('form').trigger('submit');
+
+    // Check for validation errors
+    expect(wrapper.text()).toContain('Username is required');
+    expect(wrapper.text()).toContain('Password is required');
+  });
+
+  it('calls authStore.login on valid submission', async () => {
+    const wrapper = mount(LoginView, {
+      global: {
+        plugins: [createPinia()],
+      },
+    });
+
+    // Fill in form
+    await wrapper.find('#username').setValue('john_doe');
+    await wrapper.find('#password').setValue('SecurePass123');
+
+    // Submit form
+    await wrapper.find('form').trigger('submit');
+
+    // Verify authStore.login was called
+    // (mock implementation needed)
+  });
+});
+```
+
+### E2E Test: Registration Flow
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('user can register successfully', async ({ page }) => {
+  // Navigate to register page
+  await page.goto('/register');
+
+  // Fill in registration form
+  await page.fill('#username', 'new_user');
+  await page.fill('#email', 'new_user@example.com');
+  await page.fill('#password', 'SecurePass123');
+  await page.fill('#confirmPassword', 'SecurePass123');
+
+  // Submit form
+  await page.click('button[type="submit"]');
+
+  // Wait for redirect to dashboard
+  await page.waitForURL('/dashboard');
+
+  // Verify success toast appears
+  await expect(page.locator('.toast-success')).toBeVisible();
+  await expect(page.locator('.toast-success')).toContainText('Account created successfully');
+});
+
+test('shows validation errors for invalid inputs', async ({ page }) => {
+  await page.goto('/register');
+
+  // Enter mismatched passwords
+  await page.fill('#password', 'SecurePass123');
+  await page.fill('#confirmPassword', 'DifferentPass');
+
+  // Submit form
+  await page.click('button[type="submit"]');
+
+  // Verify error message
+  await expect(page.locator('text=Passwords do not match')).toBeVisible();
+});
+```
+
+## Integration with Navigation Guards
+
+### Router Guard Example
+
+```typescript
+import { useAuthStore } from '@/stores';
+
+router.beforeEach((to, from, next) => {
+  const authStore = useAuthStore();
+
+  // Redirect authenticated users away from auth pages
+  if (authStore.isAuthenticated && (to.path === '/login' || to.path === '/register')) {
+    next('/dashboard');
+    return;
+  }
+
+  // Redirect unauthenticated users to login
+  if (to.meta.requiresAuth && !authStore.isAuthenticated) {
+    next({
+      path: '/login',
+      query: { redirect: to.fullPath }
+    });
+    return;
+  }
+
+  next();
+});
+```
+
+## Customization Examples
+
+### Custom Success Redirect
+
+```typescript
+// In LoginView.vue
+async function handleLogin(): Promise<void> {
+  try {
+    await authStore.login({
+      username: formData.username,
+      password: formData.password,
+    });
+
+    appStore.showSuccess('Login successful!');
+
+    // Custom redirect logic
+    const isAdmin = authStore.isAdmin;
+    const redirectTo = isAdmin ? '/admin/dashboard' : '/dashboard';
+
+    await router.push(redirectTo);
+  } catch (error) {
+    // Error handling...
+  }
+}
+```
+
+### Custom Validation Rules
+
+```typescript
+// Custom password strength validation
+function validatePasswordStrength(password: string): boolean {
+  const hasMinLength = password.length >= 12;
+  const hasUpperCase = /[A-Z]/.test(password);
+  const hasLowerCase = /[a-z]/.test(password);
+  const hasNumber = /[0-9]/.test(password);
+  const hasSpecialChar = /[!@#$%^&*(),.?":{}|<>]/.test(password);
+
+  return hasMinLength && hasUpperCase && hasLowerCase && hasNumber && hasSpecialChar;
+}
+
+// Use in validation
+if (!validatePasswordStrength(formData.password)) {
+  errors.password = 'Password must be at least 12 characters with uppercase, lowercase, numbers, and special characters';
+  isValid = false;
+}
+```
+
+### Custom Error Handling
+
+```typescript
+// In RegisterView.vue
+async function handleRegister(): Promise<void> {
+  try {
+    await authStore.register({
+      username: formData.username,
+      email: formData.email,
+      password: formData.password,
+    });
+
+    appStore.showSuccess('Account created successfully!');
+    await router.push('/dashboard');
+  } catch (error: unknown) {
+    const err = error as { response?: { status?: number; data?: { detail?: string } } };
+
+    // Custom error handling based on status code
+    if (err.response?.status === 409) {
+      errorMessage.value = 'This username or email is already registered. Please use a different one.';
+    } else if (err.response?.status === 422) {
+      errorMessage.value = 'Invalid input. Please check your information and try again.';
+    } else if (err.response?.status === 500) {
+      errorMessage.value = 'Server error. Please try again later.';
+    } else {
+      errorMessage.value = err.response?.data?.detail || 'Registration failed. Please try again.';
+    }
+
+    appStore.showError(errorMessage.value);
+  }
+}
+```
+
+## Accessibility Examples
+
+### Keyboard Navigation
+
+```typescript
+// Tab order:
+// 1. Username input
+// 2. Password input
+// 3. Remember me checkbox (login) / Confirm password (register)
+// 4. Submit button
+// 5. Footer link (register/login)
+
+// Enter key submits form
+// Escape key can be used to clear focus
+```
+
+### Screen Reader Support
+
+```html
+<!-- Proper labels for screen readers -->
+<label for="username" class="block text-sm font-medium text-gray-700 mb-1">
+  Username
+</label>
+<input
+  id="username"
+  type="text"
+  aria-label="Username"
+  aria-required="true"
+  aria-invalid="false"
+  aria-describedby="username-error"
+/>
+<p id="username-error" role="alert" class="text-sm text-red-600">
+  <!-- Error message here -->
+</p>
+
+<!-- Loading state announced -->
+<button type="submit" aria-busy="true" aria-label="Signing in...">
+  <span class="sr-only">Signing in...</span>
+  <!-- Visual content -->
+</button>
+```
+
+## Performance Considerations
+
+### Lazy Loading
+
+```typescript
+// Router configuration with lazy loading
+{
+  path: '/login',
+  component: () => import('@/views/auth/LoginView.vue'), // ✅ Lazy loaded
+}
+
+// Direct import (not recommended for routes)
+import LoginView from '@/views/auth/LoginView.vue'; // ❌ Eager loaded
+```
+
+### Optimization Tips
+
+1. Use `v-once` for static content
+2. Debounce expensive validation operations
+3. Minimize reactive dependencies
+4. Use `shallowRef` for complex objects when possible
+5. Avoid unnecessary watchers
+
+## Security Best Practices
+
+1. Never log passwords or tokens
+2. Use HTTPS in production
+3. Implement rate limiting on backend
+4. Validate all inputs server-side
+5. Use secure password hashing (bcrypt, argon2)
+6. Implement CSRF protection
+7. Set secure cookie flags
+8. Use Content Security Policy headers
+9. Sanitize all user inputs
+10. Implement account lockout after failed attempts
+
+## Common Issues and Solutions
+
+### Issue: Token not persisting after refresh
+
+```typescript
+// Solution: Initialize auth state on app mount
+// In main.ts or App.vue
+import { useAuthStore } from '@/stores';
+
+const authStore = useAuthStore();
+authStore.checkAuth(); // Restore auth from localStorage
+```
+
+### Issue: Redirect loop after login
+
+```typescript
+// Solution: Check router guard logic
+router.beforeEach((to, from, next) => {
+  const authStore = useAuthStore();
+
+  // ✅ Correct: Check specific routes
+  if (authStore.isAuthenticated && (to.path === '/login' || to.path === '/register')) {
+    next('/dashboard');
+    return;
+  }
+
+  // ❌ Wrong: Blanket redirect
+  // if (authStore.isAuthenticated) {
+  //   next('/dashboard'); // This causes loops!
+  // }
+
+  next();
+});
+```
+
+### Issue: Form not clearing after successful submission
+
+```typescript
+// Solution: Reset form data
+async function handleLogin(): Promise<void> {
+  try {
+    await authStore.login({...});
+
+    // Reset form
+    formData.username = '';
+    formData.password = '';
+    formData.remember = false;
+
+    // Clear errors
+    errors.username = '';
+    errors.password = '';
+
+    await router.push('/dashboard');
+  } catch (error) {
+    // Error handling...
+  }
+}
+```
+
+## Additional Resources
+
+- [Vue 3 Documentation](https://vuejs.org/)
+- [Vue Router Documentation](https://router.vuejs.org/)
+- [Pinia Documentation](https://pinia.vuejs.org/)
+- [TailwindCSS Documentation](https://tailwindcss.com/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)