First commit
This commit is contained in:
shaw
338
frontend/src/views/auth/README.md
Normal file
338
frontend/src/views/auth/README.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# Authentication Views
|
||||
|
||||
This directory contains Vue 3 authentication views for the Sub2API frontend application.
|
||||
|
||||
## Components
|
||||
|
||||
### LoginView.vue
|
||||
|
||||
Login page for existing users to authenticate.
|
||||
|
||||
**Features:**
|
||||
- Username and password inputs with validation
|
||||
- Remember me checkbox for persistent sessions
|
||||
- Form validation with real-time error display
|
||||
- Loading state during authentication
|
||||
- Error message display for failed login attempts
|
||||
- Redirect to dashboard on successful login
|
||||
- Link to registration page for new users
|
||||
|
||||
**Usage:**
|
||||
```vue
|
||||
<template>
|
||||
<LoginView />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { LoginView } from '@/views/auth';
|
||||
</script>
|
||||
```
|
||||
|
||||
**Route:**
|
||||
- Path: `/login`
|
||||
- Name: `Login`
|
||||
- Meta: `{ requiresAuth: false }`
|
||||
|
||||
**Validation Rules:**
|
||||
- Username: Required, minimum 3 characters
|
||||
- Password: Required, minimum 6 characters
|
||||
|
||||
**Behavior:**
|
||||
- Calls `authStore.login()` with credentials
|
||||
- Shows success toast on successful login
|
||||
- Shows error toast and inline error message on failure
|
||||
- Redirects to `/dashboard` or intended route from query parameter
|
||||
- Redirects authenticated users away from login page
|
||||
|
||||
### RegisterView.vue
|
||||
|
||||
Registration page for new users to create accounts.
|
||||
|
||||
**Features:**
|
||||
- Username, email, password, and confirm password inputs
|
||||
- Comprehensive form validation
|
||||
- Password strength requirements (8+ characters, letters + numbers)
|
||||
- Email format validation with regex
|
||||
- Password match validation
|
||||
- Loading state during registration
|
||||
- Error message display for failed registration
|
||||
- Redirect to dashboard on success
|
||||
- Link to login page for existing users
|
||||
|
||||
**Usage:**
|
||||
```vue
|
||||
<template>
|
||||
<RegisterView />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { RegisterView } from '@/views/auth';
|
||||
</script>
|
||||
```
|
||||
|
||||
**Route:**
|
||||
- Path: `/register`
|
||||
- Name: `Register`
|
||||
- Meta: `{ requiresAuth: false }`
|
||||
|
||||
**Validation Rules:**
|
||||
- Username:
|
||||
- Required
|
||||
- 3-50 characters
|
||||
- Only letters, numbers, underscores, and hyphens
|
||||
- Email:
|
||||
- Required
|
||||
- Valid email format (RFC 5322 regex)
|
||||
- Password:
|
||||
- Required
|
||||
- Minimum 8 characters
|
||||
- Must contain at least one letter and one number
|
||||
- Confirm Password:
|
||||
- Required
|
||||
- Must match password
|
||||
|
||||
**Behavior:**
|
||||
- Calls `authStore.register()` with user data
|
||||
- Shows success toast on successful registration
|
||||
- Shows error toast and inline error message on failure
|
||||
- Redirects to `/dashboard` after successful registration
|
||||
- Redirects authenticated users away from register page
|
||||
|
||||
## Architecture
|
||||
|
||||
### Component Structure
|
||||
|
||||
Both views follow a consistent structure:
|
||||
|
||||
```
|
||||
<template>
|
||||
<AuthLayout>
|
||||
<div class="space-y-6">
|
||||
<!-- Title -->
|
||||
<!-- Form -->
|
||||
<!-- Error Message -->
|
||||
<!-- Submit Button -->
|
||||
</div>
|
||||
|
||||
<template #footer>
|
||||
<!-- Footer Links -->
|
||||
</template>
|
||||
</AuthLayout>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
// Imports
|
||||
// State
|
||||
// Validation
|
||||
// Form Handlers
|
||||
</script>
|
||||
```
|
||||
|
||||
### State Management
|
||||
|
||||
Both views use:
|
||||
- `useAuthStore()` - For authentication actions (login, register)
|
||||
- `useAppStore()` - For toast notifications and UI feedback
|
||||
- `useRouter()` - For navigation and redirects
|
||||
|
||||
### Validation Strategy
|
||||
|
||||
**Client-side Validation:**
|
||||
- Real-time validation on form submission
|
||||
- Field-level error messages
|
||||
- Comprehensive validation rules
|
||||
- TypeScript type safety
|
||||
|
||||
**Server-side Validation:**
|
||||
- Backend API validates all inputs
|
||||
- Error responses handled gracefully
|
||||
- User-friendly error messages displayed
|
||||
|
||||
### Styling
|
||||
|
||||
**Design System:**
|
||||
- TailwindCSS utility classes
|
||||
- Consistent color scheme (indigo primary)
|
||||
- Responsive design
|
||||
- Accessible form controls
|
||||
- Loading states with spinner animations
|
||||
|
||||
**Visual Feedback:**
|
||||
- Red border on invalid fields
|
||||
- Error messages below inputs
|
||||
- Global error banner for API errors
|
||||
- Success toasts on completion
|
||||
- Loading spinner on submit button
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Components
|
||||
- `AuthLayout` - Layout wrapper for auth pages from `@/components/layout`
|
||||
|
||||
### Stores
|
||||
- `authStore` - Authentication state management from `@/stores/auth`
|
||||
- `appStore` - Application state and toasts from `@/stores/app`
|
||||
|
||||
### Libraries
|
||||
- Vue 3 Composition API
|
||||
- Vue Router for navigation
|
||||
- Pinia for state management
|
||||
- TypeScript for type safety
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Login Flow
|
||||
|
||||
```typescript
|
||||
// User enters credentials
|
||||
formData.username = 'john_doe';
|
||||
formData.password = 'SecurePass123';
|
||||
|
||||
// Submit form
|
||||
await handleLogin();
|
||||
|
||||
// On success:
|
||||
// - authStore.login() called
|
||||
// - Token and user stored
|
||||
// - Success toast shown
|
||||
// - Redirected to /dashboard
|
||||
|
||||
// On error:
|
||||
// - Error message displayed
|
||||
// - Error toast shown
|
||||
// - Form remains editable
|
||||
```
|
||||
|
||||
### Basic Registration Flow
|
||||
|
||||
```typescript
|
||||
// User enters registration data
|
||||
formData.username = 'jane_smith';
|
||||
formData.email = 'jane@example.com';
|
||||
formData.password = 'SecurePass123';
|
||||
formData.confirmPassword = 'SecurePass123';
|
||||
|
||||
// Submit form
|
||||
await handleRegister();
|
||||
|
||||
// On success:
|
||||
// - authStore.register() called
|
||||
// - Token and user stored
|
||||
// - Success toast shown
|
||||
// - Redirected to /dashboard
|
||||
|
||||
// On error:
|
||||
// - Error message displayed
|
||||
// - Error toast shown
|
||||
// - Form remains editable
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Client-side Errors
|
||||
|
||||
```typescript
|
||||
// Validation errors
|
||||
errors.username = 'Username must be at least 3 characters';
|
||||
errors.email = 'Please enter a valid email address';
|
||||
errors.password = 'Password must be at least 8 characters with letters and numbers';
|
||||
errors.confirmPassword = 'Passwords do not match';
|
||||
```
|
||||
|
||||
### Server-side Errors
|
||||
|
||||
```typescript
|
||||
// API error responses
|
||||
{
|
||||
response: {
|
||||
data: {
|
||||
detail: 'Username already exists'
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Displayed as:
|
||||
errorMessage.value = 'Username already exists';
|
||||
appStore.showError('Username already exists');
|
||||
```
|
||||
|
||||
## Accessibility
|
||||
|
||||
- Semantic HTML elements (`<label>`, `<input>`, `<button>`)
|
||||
- Proper `for` attributes on labels
|
||||
- ARIA attributes for loading states
|
||||
- Keyboard navigation support
|
||||
- Focus management
|
||||
- Error announcements
|
||||
- Sufficient color contrast
|
||||
|
||||
## Testing Considerations
|
||||
|
||||
### Unit Tests
|
||||
- Form validation logic
|
||||
- Error handling
|
||||
- State management
|
||||
- Router navigation
|
||||
|
||||
### Integration Tests
|
||||
- Full login flow
|
||||
- Full registration flow
|
||||
- Error scenarios
|
||||
- Redirect behavior
|
||||
|
||||
### E2E Tests
|
||||
- Complete user journeys
|
||||
- Form interactions
|
||||
- API integration
|
||||
- Success/error states
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements:
|
||||
- OAuth/SSO integration (Google, GitHub)
|
||||
- Two-factor authentication (2FA)
|
||||
- Password strength meter
|
||||
- Email verification flow
|
||||
- Forgot password functionality
|
||||
- Social login buttons
|
||||
- CAPTCHA integration
|
||||
- Session timeout warnings
|
||||
- Password visibility toggle
|
||||
- Autofill support enhancement
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Passwords are never logged or displayed
|
||||
- HTTPS required in production
|
||||
- JWT tokens stored securely in localStorage
|
||||
- CORS protection on API
|
||||
- XSS protection with Vue's automatic escaping
|
||||
- CSRF protection with token-based auth
|
||||
- Rate limiting on backend API
|
||||
- Input sanitization
|
||||
- Secure password requirements
|
||||
|
||||
## Performance
|
||||
|
||||
- Lazy-loaded routes
|
||||
- Minimal bundle size
|
||||
- Fast initial render
|
||||
- Optimized re-renders with reactive refs
|
||||
- No unnecessary watchers
|
||||
- Efficient form validation
|
||||
|
||||
## Browser Support
|
||||
|
||||
- Modern browsers (Chrome, Firefox, Safari, Edge)
|
||||
- ES2015+ required
|
||||
- Flexbox and CSS Grid
|
||||
- Tailwind CSS utilities
|
||||
- Vue 3 runtime
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Auth Store Documentation](/src/stores/README.md#auth-store)
|
||||
- [AuthLayout Component](/src/components/layout/README.md#authlayout)
|
||||
- [Router Configuration](/src/router/index.ts)
|
||||
- [API Documentation](/src/api/README.md#authentication)
|
||||
- [Type Definitions](/src/types/index.ts)
|
||||
Reference in New Issue
Block a user