add docs part 2
This commit is contained in:
@@ -0,0 +1,344 @@
|
||||
# Error Handling
|
||||
|
||||
The app implements comprehensive error handling to provide a robust user experience.
|
||||
|
||||
## Error Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ UI Layer │
|
||||
│ (Shows error messages to user) │
|
||||
└─────────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────────────▼───────────────────────┐
|
||||
│ State Management │
|
||||
│ (Catches errors, updates state) │
|
||||
└─────────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────────────▼───────────────────────┐
|
||||
│ Service Layer │
|
||||
│ (Logs errors, returns defaults) │
|
||||
└─────────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────────────▼───────────────────────┐
|
||||
│ Repository Layer │
|
||||
│ (Handles API/DB errors) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Logger Mixin
|
||||
|
||||
Services use a standardized error handling pattern:
|
||||
|
||||
### Guard Error
|
||||
|
||||
Wraps async operations and returns result or error:
|
||||
|
||||
```
|
||||
Input: Async function
|
||||
Output: AsyncValue<T>
|
||||
- AsyncData(result) on success
|
||||
- AsyncError(error, stackTrace) on failure
|
||||
|
||||
Behavior:
|
||||
1. Execute async function
|
||||
2. If success → return AsyncData with result
|
||||
3. If exception → log error, return AsyncError
|
||||
```
|
||||
|
||||
### Log Error
|
||||
|
||||
Executes operation and returns default on failure:
|
||||
|
||||
```
|
||||
Input:
|
||||
- Async function
|
||||
- Default value
|
||||
- Error message
|
||||
|
||||
Output: T (result or default)
|
||||
|
||||
Behavior:
|
||||
1. Execute async function
|
||||
2. If success → return result
|
||||
3. If exception → log error, return default value
|
||||
```
|
||||
|
||||
## Log Levels
|
||||
|
||||
| Level | Value | Usage |
|
||||
|-------|-------|-------|
|
||||
| ALL | 0 | All messages |
|
||||
| FINEST | 300 | Extremely detailed |
|
||||
| FINER | 400 | Very detailed |
|
||||
| FINE | 500 | Detailed tracing |
|
||||
| CONFIG | 700 | Configuration info |
|
||||
| INFO | 800 | General information |
|
||||
| WARNING | 900 | Potential problems |
|
||||
| SEVERE | 1000 | Serious failures |
|
||||
| SHOUT | 1200 | Critical errors |
|
||||
| OFF | 2000 | No logging |
|
||||
|
||||
Default level: INFO (800)
|
||||
|
||||
## API Error Handling
|
||||
|
||||
### HTTP Error Responses
|
||||
|
||||
| Status Code | Meaning | Handling |
|
||||
|-------------|---------|----------|
|
||||
| 400 | Bad Request | Show validation error |
|
||||
| 401 | Unauthorized | Redirect to login |
|
||||
| 403 | Forbidden | Show access denied |
|
||||
| 404 | Not Found | Show not found message |
|
||||
| 409 | Conflict | Handle duplicate |
|
||||
| 500 | Server Error | Show generic error |
|
||||
|
||||
### Network Errors
|
||||
|
||||
| Error Type | Handling |
|
||||
|------------|----------|
|
||||
| No Connection | Show offline message |
|
||||
| Timeout | Retry with backoff |
|
||||
| SSL Error | Check certificate settings |
|
||||
| DNS Failure | Check server URL |
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "ErrorType",
|
||||
"statusCode": 400,
|
||||
"message": "Human-readable error message"
|
||||
}
|
||||
```
|
||||
|
||||
## Authentication Errors
|
||||
|
||||
### Login Failures
|
||||
|
||||
| Error | Message | Action |
|
||||
|-------|---------|--------|
|
||||
| Wrong credentials | "Incorrect email or password" | Show error, stay on login |
|
||||
| Account locked | "Account temporarily locked" | Show lockout message |
|
||||
| Server unavailable | "Cannot connect to server" | Check server URL |
|
||||
|
||||
### Session Expiration
|
||||
|
||||
1. API returns 401
|
||||
2. Clear local token
|
||||
3. Navigate to login
|
||||
4. Show "Session expired" message
|
||||
|
||||
### OAuth Errors
|
||||
|
||||
| Error | Handling |
|
||||
|-------|----------|
|
||||
| User cancelled | Return to login silently |
|
||||
| Invalid state | Show security error |
|
||||
| Token exchange failed | Show error, retry option |
|
||||
|
||||
## Upload Errors
|
||||
|
||||
### Upload Failure Handling
|
||||
|
||||
```
|
||||
Upload Attempt
|
||||
│
|
||||
▼
|
||||
Success?
|
||||
│ │
|
||||
Yes No
|
||||
│ │
|
||||
▼ ▼
|
||||
Done Retry?
|
||||
│ │
|
||||
Yes No (max retries)
|
||||
│ │
|
||||
▼ ▼
|
||||
Retry Mark Failed
|
||||
│
|
||||
▼
|
||||
Add to Error Queue
|
||||
│
|
||||
▼
|
||||
Grace Period Check
|
||||
│
|
||||
┌────┴────┐
|
||||
│ │
|
||||
Within Exceeded
|
||||
│ │
|
||||
▼ ▼
|
||||
Silent Show Notification
|
||||
```
|
||||
|
||||
### Error Grace Period
|
||||
|
||||
- Don't immediately notify on upload failures
|
||||
- Wait for `uploadErrorNotificationGracePeriod` failures
|
||||
- Then show notification
|
||||
- Prevents spam for transient errors
|
||||
|
||||
### Duplicate Detection
|
||||
|
||||
When server returns duplicate error:
|
||||
1. Mark local asset as backed up
|
||||
2. Don't show error to user
|
||||
3. Continue with next asset
|
||||
|
||||
## Download Errors
|
||||
|
||||
| Error | Handling |
|
||||
|-------|----------|
|
||||
| Asset not found | Show "Photo not available" |
|
||||
| Permission denied | Show access error |
|
||||
| Storage full | Show storage warning |
|
||||
| Network error | Offer retry |
|
||||
|
||||
## Sync Errors
|
||||
|
||||
### Sync Failure Recovery
|
||||
|
||||
1. Log sync error
|
||||
2. Keep existing local data
|
||||
3. Schedule retry
|
||||
4. Show sync indicator if prolonged
|
||||
|
||||
### Conflict Resolution
|
||||
|
||||
When local and remote conflict:
|
||||
1. Remote data takes precedence
|
||||
2. Merge where possible
|
||||
3. Log conflict details
|
||||
|
||||
## UI Error Display
|
||||
|
||||
### Snackbar Messages
|
||||
|
||||
For transient errors:
|
||||
```
|
||||
┌────────────────────────────────────┐
|
||||
│ Error message here [RETRY]│
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- Auto-dismiss after 3-5 seconds
|
||||
- Optional action button
|
||||
- Non-blocking
|
||||
|
||||
### Dialog Messages
|
||||
|
||||
For critical errors requiring action:
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Error Title │
|
||||
├─────────────────────────────────┤
|
||||
│ │
|
||||
│ Detailed error description │
|
||||
│ with helpful guidance. │
|
||||
│ │
|
||||
├─────────────────────────────────┤
|
||||
│ [OK] [RETRY] │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Inline Errors
|
||||
|
||||
For form validation:
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Email │
|
||||
│ ┌───────────────────────────┐ │
|
||||
│ │ invalid-email │ │
|
||||
│ └───────────────────────────┘ │
|
||||
│ ⚠ Please enter a valid email │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Empty States
|
||||
|
||||
When no data due to error:
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ │
|
||||
│ [Error Icon] │
|
||||
│ │
|
||||
│ Something went wrong │
|
||||
│ │
|
||||
│ [Try Again] │
|
||||
│ │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Localization Keys
|
||||
|
||||
Common error message keys:
|
||||
|
||||
| Key | Usage |
|
||||
|-----|-------|
|
||||
| `error_generic` | Unknown error occurred |
|
||||
| `error_network` | Network connection error |
|
||||
| `error_server` | Server error |
|
||||
| `error_unauthorized` | Not authorized |
|
||||
| `error_not_found` | Resource not found |
|
||||
| `error_upload_failed` | Upload failed |
|
||||
| `error_download_failed` | Download failed |
|
||||
|
||||
## Debug Logging
|
||||
|
||||
### Enable Advanced Troubleshooting
|
||||
|
||||
When enabled in settings:
|
||||
- Log all API requests/responses
|
||||
- Log state changes
|
||||
- Log error stack traces
|
||||
- Log sync operations
|
||||
|
||||
### Log Output
|
||||
|
||||
Logs include:
|
||||
- Timestamp
|
||||
- Logger name (component)
|
||||
- Log level
|
||||
- Message
|
||||
- Error object (if applicable)
|
||||
- Stack trace (if applicable)
|
||||
|
||||
### Viewing Logs
|
||||
|
||||
- Settings → Advanced → Export Logs
|
||||
- Share log file for support
|
||||
|
||||
## Error Recovery Patterns
|
||||
|
||||
### Automatic Retry
|
||||
|
||||
For transient failures:
|
||||
```
|
||||
Attempt 1
|
||||
↓
|
||||
Fail → Wait 1s → Attempt 2
|
||||
↓
|
||||
Fail → Wait 2s → Attempt 3
|
||||
↓
|
||||
Fail → Give Up
|
||||
```
|
||||
|
||||
### Manual Retry
|
||||
|
||||
User-triggered retry:
|
||||
1. Show error with retry button
|
||||
2. User taps retry
|
||||
3. Clear error state
|
||||
4. Repeat operation
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
When feature unavailable:
|
||||
1. Disable affected UI elements
|
||||
2. Show explanation
|
||||
3. Continue with available features
|
||||
|
||||
---
|
||||
|
||||
[Previous: Settings](settings.md) | [Next: UI Components](ui-components.md)
|
||||
Reference in New Issue
Block a user