9 changed files with 2399 additions and 3214 deletions
@ -0,0 +1,222 @@ |
|||
--- |
|||
description: |
|||
globs: |
|||
alwaysApply: true |
|||
--- |
|||
# Camera Implementation Documentation |
|||
|
|||
## Overview |
|||
|
|||
This document describes how camera functionality is implemented across the TimeSafari application. The application uses cameras for two main purposes: |
|||
|
|||
1. QR Code scanning |
|||
2. Photo capture |
|||
|
|||
## Components |
|||
|
|||
### QRScannerDialog.vue |
|||
|
|||
Primary component for QR code scanning in web browsers. |
|||
|
|||
**Key Features:** |
|||
|
|||
- Uses `qrcode-stream` for web-based QR scanning |
|||
- Supports both front and back cameras |
|||
- Provides real-time camera status feedback |
|||
- Implements error handling with user-friendly messages |
|||
- Includes camera switching functionality |
|||
|
|||
**Camera Access Flow:** |
|||
|
|||
1. Checks for camera API availability |
|||
2. Enumerates available video devices |
|||
3. Requests camera permissions |
|||
4. Initializes camera stream with preferred settings |
|||
5. Handles various error conditions with specific messages |
|||
|
|||
### PhotoDialog.vue |
|||
|
|||
Component for photo capture and selection. |
|||
|
|||
**Key Features:** |
|||
|
|||
- Cross-platform photo capture interface |
|||
- Image cropping capabilities |
|||
- File selection fallback |
|||
- Unified interface for different platforms |
|||
|
|||
## Services |
|||
|
|||
### QRScanner Services |
|||
|
|||
#### WebDialogQRScanner |
|||
|
|||
Web-based implementation of QR scanning. |
|||
|
|||
**Key Methods:** |
|||
|
|||
- `checkPermissions()`: Verifies camera permission status |
|||
- `requestPermissions()`: Requests camera access |
|||
- `isSupported()`: Checks for camera API support |
|||
- Handles various error conditions with specific messages |
|||
|
|||
#### CapacitorQRScanner |
|||
|
|||
Native implementation using Capacitor's MLKit. |
|||
|
|||
**Key Features:** |
|||
|
|||
- Uses `@capacitor-mlkit/barcode-scanning` |
|||
- Supports both front and back cameras |
|||
- Implements permission management |
|||
- Provides continuous scanning capability |
|||
|
|||
### Platform Services |
|||
|
|||
#### WebPlatformService |
|||
|
|||
Web-specific implementation of platform features. |
|||
|
|||
**Camera Capabilities:** |
|||
|
|||
- Uses HTML5 file input with capture attribute |
|||
- Falls back to file selection if camera unavailable |
|||
- Processes captured images for consistent format |
|||
|
|||
#### CapacitorPlatformService |
|||
|
|||
Native implementation using Capacitor. |
|||
|
|||
**Camera Features:** |
|||
|
|||
- Uses `Camera.getPhoto()` for native camera access |
|||
- Supports image editing |
|||
- Configures high-quality image capture |
|||
- Handles base64 image processing |
|||
|
|||
#### ElectronPlatformService |
|||
|
|||
Desktop implementation (currently unimplemented). |
|||
|
|||
**Status:** |
|||
|
|||
- Camera functionality not yet implemented |
|||
- Planned to use Electron's media APIs |
|||
|
|||
## Platform-Specific Considerations |
|||
|
|||
### iOS |
|||
|
|||
- Requires `NSCameraUsageDescription` in Info.plist |
|||
- Supports both front and back cameras |
|||
- Implements proper permission handling |
|||
|
|||
### Android |
|||
|
|||
- Requires camera permissions in manifest |
|||
- Supports both front and back cameras |
|||
- Handles permission requests through Capacitor |
|||
|
|||
### Web |
|||
|
|||
- Requires HTTPS for camera access |
|||
- Implements fallback mechanisms |
|||
- Handles browser compatibility issues |
|||
|
|||
## Error Handling |
|||
|
|||
### Common Error Scenarios |
|||
|
|||
1. No camera found |
|||
2. Permission denied |
|||
3. Camera in use by another application |
|||
4. HTTPS required |
|||
5. Browser compatibility issues |
|||
|
|||
### Error Response |
|||
|
|||
- User-friendly error messages |
|||
- Troubleshooting tips |
|||
- Clear instructions for resolution |
|||
- Platform-specific guidance |
|||
|
|||
## Security Considerations |
|||
|
|||
### Permission Management |
|||
|
|||
- Explicit permission requests |
|||
- Permission state tracking |
|||
- Graceful handling of denied permissions |
|||
|
|||
### Data Handling |
|||
|
|||
- Secure image processing |
|||
- Proper cleanup of camera resources |
|||
- No persistent storage of camera data |
|||
|
|||
## Best Practices |
|||
|
|||
### Camera Access |
|||
|
|||
1. Always check for camera availability |
|||
2. Request permissions explicitly |
|||
3. Handle all error conditions |
|||
4. Provide clear user feedback |
|||
5. Implement proper cleanup |
|||
|
|||
### Performance |
|||
|
|||
1. Optimize camera resolution |
|||
2. Implement proper resource cleanup |
|||
3. Handle camera switching efficiently |
|||
4. Manage memory usage |
|||
|
|||
### User Experience |
|||
|
|||
1. Clear status indicators |
|||
2. Intuitive camera controls |
|||
3. Helpful error messages |
|||
4. Smooth camera switching |
|||
5. Responsive UI feedback |
|||
|
|||
## Future Improvements |
|||
|
|||
### Planned Enhancements |
|||
|
|||
1. Implement Electron camera support |
|||
2. Add advanced camera features |
|||
3. Improve error handling |
|||
4. Enhance user feedback |
|||
5. Optimize performance |
|||
|
|||
### Known Issues |
|||
|
|||
1. Electron camera implementation pending |
|||
2. Some browser compatibility limitations |
|||
3. Platform-specific quirks to address |
|||
|
|||
## Dependencies |
|||
|
|||
### Key Packages |
|||
|
|||
- `@capacitor-mlkit/barcode-scanning` |
|||
- `qrcode-stream` |
|||
- `vue-picture-cropper` |
|||
- Platform-specific camera APIs |
|||
|
|||
## Testing |
|||
|
|||
### Test Scenarios |
|||
|
|||
1. Permission handling |
|||
2. Camera switching |
|||
3. Error conditions |
|||
4. Platform compatibility |
|||
5. Performance metrics |
|||
|
|||
### Test Environment |
|||
|
|||
- Multiple browsers |
|||
- iOS and Android devices |
|||
- Desktop platforms |
|||
- Various network conditions |
@ -0,0 +1,20 @@ |
|||
<?xml version="1.0" encoding="UTF-8"?> |
|||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> |
|||
<plist version="1.0"> |
|||
<dict> |
|||
<key>com.apple.security.cs.allow-jit</key> |
|||
<true/> |
|||
<key>com.apple.security.cs.allow-unsigned-executable-memory</key> |
|||
<true/> |
|||
<key>com.apple.security.cs.debugger</key> |
|||
<true/> |
|||
<key>com.apple.security.device.audio-input</key> |
|||
<true/> |
|||
<key>com.apple.security.device.camera</key> |
|||
<true/> |
|||
<key>com.apple.security.personal-information.addressbook</key> |
|||
<true/> |
|||
<key>com.apple.security.personal-information.calendars</key> |
|||
<true/> |
|||
</dict> |
|||
</plist> |
@ -0,0 +1,308 @@ |
|||
# Camera Implementation Documentation |
|||
|
|||
## Overview |
|||
|
|||
This document describes how camera functionality is implemented across the TimeSafari application. The application uses cameras for several purposes: |
|||
|
|||
1. QR Code scanning for contact sharing and verification |
|||
2. Photo capture for gift records |
|||
3. Profile photo management |
|||
4. Shared photo handling |
|||
5. Image upload and processing |
|||
|
|||
## Components |
|||
|
|||
### QRScannerDialog.vue |
|||
|
|||
Primary component for QR code scanning in web browsers. |
|||
|
|||
**Key Features:** |
|||
|
|||
- Uses `qrcode-stream` for web-based QR scanning |
|||
- Supports both front and back cameras |
|||
- Provides real-time camera status feedback |
|||
- Implements error handling with user-friendly messages |
|||
- Includes camera switching functionality |
|||
|
|||
**Camera Access Flow:** |
|||
|
|||
1. Checks for camera API availability |
|||
2. Enumerates available video devices |
|||
3. Requests camera permissions |
|||
4. Initializes camera stream with preferred settings |
|||
5. Handles various error conditions with specific messages |
|||
|
|||
### PhotoDialog.vue |
|||
|
|||
Component for photo capture and selection. |
|||
|
|||
**Key Features:** |
|||
|
|||
- Cross-platform photo capture interface |
|||
- Image cropping capabilities |
|||
- File selection fallback |
|||
- Unified interface for different platforms |
|||
|
|||
### ImageMethodDialog.vue |
|||
|
|||
Component for selecting image input method. |
|||
|
|||
**Key Features:** |
|||
- Multiple input methods (camera, file upload, URL) |
|||
- Unified interface for image selection |
|||
- Integration with PhotoDialog for processing |
|||
- Support for image cropping |
|||
- URL-based image handling |
|||
|
|||
### SharedPhotoView.vue |
|||
|
|||
Component for handling shared photos. |
|||
|
|||
**Key Features:** |
|||
- Processes incoming shared photos |
|||
- Options to use photo for gifts or profile |
|||
- Image preview and confirmation |
|||
- Server upload integration |
|||
- Temporary storage management |
|||
|
|||
## Services |
|||
|
|||
### QRScanner Services |
|||
|
|||
#### WebDialogQRScanner |
|||
|
|||
Web-based implementation of QR scanning. |
|||
|
|||
**Key Methods:** |
|||
|
|||
- `checkPermissions()`: Verifies camera permission status |
|||
- `requestPermissions()`: Requests camera access |
|||
- `isSupported()`: Checks for camera API support |
|||
- Handles various error conditions with specific messages |
|||
|
|||
#### CapacitorQRScanner |
|||
|
|||
Native implementation using Capacitor's MLKit. |
|||
|
|||
**Key Features:** |
|||
|
|||
- Uses `@capacitor-mlkit/barcode-scanning` |
|||
- Supports both front and back cameras |
|||
- Implements permission management |
|||
- Provides continuous scanning capability |
|||
|
|||
### Platform Services |
|||
|
|||
#### WebPlatformService |
|||
|
|||
Web-specific implementation of platform features. |
|||
|
|||
**Camera Capabilities:** |
|||
|
|||
- Uses HTML5 file input with capture attribute |
|||
- Falls back to file selection if camera unavailable |
|||
- Processes captured images for consistent format |
|||
|
|||
#### CapacitorPlatformService |
|||
|
|||
Native implementation using Capacitor. |
|||
|
|||
**Camera Features:** |
|||
|
|||
- Uses `Camera.getPhoto()` for native camera access |
|||
- Supports image editing |
|||
- Configures high-quality image capture |
|||
- Handles base64 image processing |
|||
|
|||
#### ElectronPlatformService |
|||
|
|||
Desktop implementation (currently unimplemented). |
|||
|
|||
**Status:** |
|||
|
|||
- Camera functionality not yet implemented |
|||
- Planned to use Electron's media APIs |
|||
|
|||
## Camera Usage Scenarios |
|||
|
|||
### Gift Photo Capture |
|||
|
|||
**Implementation:** |
|||
- Uses PhotoDialog for capture/selection |
|||
- Supports multiple input methods |
|||
- Optional image cropping |
|||
- Server upload with authentication |
|||
- Integration with gift records |
|||
|
|||
**Flow:** |
|||
1. User initiates photo capture from gift details |
|||
2. ImageMethodDialog presents input options |
|||
3. PhotoDialog handles capture/selection |
|||
4. Image is processed and uploaded |
|||
5. URL is attached to gift record |
|||
|
|||
### Profile Photo Management |
|||
|
|||
**Implementation:** |
|||
- Uses same PhotoDialog component |
|||
- Enforces square aspect ratio |
|||
- Requires image cropping |
|||
- Updates user profile settings |
|||
- Handles profile image updates |
|||
|
|||
**Flow:** |
|||
1. User initiates profile photo update |
|||
2. PhotoDialog opens with cropping enabled |
|||
3. Image is captured/selected |
|||
4. User crops to square aspect ratio |
|||
5. Image is uploaded and profile updated |
|||
|
|||
### Shared Photo Processing |
|||
|
|||
**Implementation:** |
|||
- Handles incoming shared photos |
|||
- Temporary storage in IndexedDB |
|||
- Options for photo usage |
|||
- Server upload integration |
|||
- Cleanup after processing |
|||
|
|||
**Flow:** |
|||
1. Photo is shared to application |
|||
2. Stored temporarily in IndexedDB |
|||
3. SharedPhotoView presents options |
|||
4. User chooses usage (gift/profile) |
|||
5. Image is processed accordingly |
|||
|
|||
### Image Upload and Processing |
|||
|
|||
**Implementation:** |
|||
- Secure server upload |
|||
- Authentication handling |
|||
- Image format standardization |
|||
- Error handling and retry |
|||
- Progress feedback |
|||
|
|||
**Flow:** |
|||
1. Image is prepared for upload |
|||
2. Authentication token is obtained |
|||
3. Multipart form data is created |
|||
4. Upload progress is monitored |
|||
5. Server URL is returned |
|||
|
|||
## Platform-Specific Considerations |
|||
|
|||
### iOS |
|||
|
|||
- Requires `NSCameraUsageDescription` in Info.plist |
|||
- Supports both front and back cameras |
|||
- Implements proper permission handling |
|||
|
|||
### Android |
|||
|
|||
- Requires camera permissions in manifest |
|||
- Supports both front and back cameras |
|||
- Handles permission requests through Capacitor |
|||
|
|||
### Web |
|||
|
|||
- Requires HTTPS for camera access |
|||
- Implements fallback mechanisms |
|||
- Handles browser compatibility issues |
|||
|
|||
## Error Handling |
|||
|
|||
### Common Error Scenarios |
|||
|
|||
1. No camera found |
|||
2. Permission denied |
|||
3. Camera in use by another application |
|||
4. HTTPS required |
|||
5. Browser compatibility issues |
|||
|
|||
### Error Response |
|||
|
|||
- User-friendly error messages |
|||
- Troubleshooting tips |
|||
- Clear instructions for resolution |
|||
- Platform-specific guidance |
|||
|
|||
## Security Considerations |
|||
|
|||
### Permission Management |
|||
|
|||
- Explicit permission requests |
|||
- Permission state tracking |
|||
- Graceful handling of denied permissions |
|||
|
|||
### Data Handling |
|||
|
|||
- Secure image processing |
|||
- Proper cleanup of camera resources |
|||
- No persistent storage of camera data |
|||
|
|||
## Best Practices |
|||
|
|||
### Camera Access |
|||
|
|||
1. Always check for camera availability |
|||
2. Request permissions explicitly |
|||
3. Handle all error conditions |
|||
4. Provide clear user feedback |
|||
5. Implement proper cleanup |
|||
|
|||
### Performance |
|||
|
|||
1. Optimize camera resolution |
|||
2. Implement proper resource cleanup |
|||
3. Handle camera switching efficiently |
|||
4. Manage memory usage |
|||
|
|||
### User Experience |
|||
|
|||
1. Clear status indicators |
|||
2. Intuitive camera controls |
|||
3. Helpful error messages |
|||
4. Smooth camera switching |
|||
5. Responsive UI feedback |
|||
|
|||
## Future Improvements |
|||
|
|||
### Planned Enhancements |
|||
|
|||
1. Implement Electron camera support |
|||
2. Add advanced camera features |
|||
3. Improve error handling |
|||
4. Enhance user feedback |
|||
5. Optimize performance |
|||
|
|||
### Known Issues |
|||
|
|||
1. Electron camera implementation pending |
|||
2. Some browser compatibility limitations |
|||
3. Platform-specific quirks to address |
|||
|
|||
## Dependencies |
|||
|
|||
### Key Packages |
|||
|
|||
- `@capacitor-mlkit/barcode-scanning` |
|||
- `qrcode-stream` |
|||
- `vue-picture-cropper` |
|||
- Platform-specific camera APIs |
|||
|
|||
## Testing |
|||
|
|||
### Test Scenarios |
|||
|
|||
1. Permission handling |
|||
2. Camera switching |
|||
3. Error conditions |
|||
4. Platform compatibility |
|||
5. Performance metrics |
|||
|
|||
### Test Environment |
|||
|
|||
- Multiple browsers |
|||
- iOS and Android devices |
|||
- Desktop platforms |
|||
- Various network conditions |
File diff suppressed because it is too large
Loading…
Reference in new issue