appiq-solution 1.4.8 → 1.5.0

package/flutter/punkt.claude/punkt.claude/commands/feature-data-layer.md

@@ -1,572 +0,0 @@
-# Data Layer Development Command
-
-Develops the data layer (Freezed DTOs, Mappers, Repository Implementations) for a feature following AiGo architectural patterns with JSON annotations.
-
-**Usage:** `feature-data-layer [FEATURE_NAME] [FEATURE_DESCRIPTION]`
-
-**Example:** `feature-data-layer user-favorites "Allow users to mark places as favorites and view them in a separate list"`
-
-## Pre-Execution Checklist
-
-1. **Check Channel Status**: Read `/Users/vapps-it/Projects/AiGo/sourceCode/mobile_app/.claude/channel.md`
-2. **Verify Dependencies**: Ensure domain layer is completed
-3. **Update Channel**: Mark Data Layer status as "IN_PROGRESS" and assign agent
-4. **Check Blockers**: Verify domain layer provides all necessary interfaces
-
-## Implementation Process
-
-### Phase 1: Analysis & Planning
-
-1. **Study Existing Data Patterns**:
-   - Analyze `lib/data/dtos/` Freezed implementation patterns
-   - Study existing mappers in `lib/data/mappers/` for DTO <-> Domain conversion
-   - Review repository implementations in `lib/data/repositories/`
-   - Check JSON annotation patterns and custom converters
-   - Understand service locator registration patterns
-
-2. **Define Data Requirements**:
-   - Plan API endpoints and data structures
-   - Design DTO structure with Freezed and JSON annotations
-   - Plan mapper implementations for bidirectional conversion
-   - Define repository implementation with error handling
-   - Plan service locator integration
-
-3. **Update Channel**: Add data layer requirements to channel.md
-
-### Phase 2: Freezed DTO Implementation
-
-1. **Create DTO File** (`lib/data/dtos/[feature]_dto.dart`):
-   ```dart
-   import 'package:freezed_annotation/freezed_annotation.dart';
-   import '../../domain/models/[feature].dart';
-   
-   part '[feature]_dto.freezed.dart';
-   part '[feature]_dto.g.dart';
-   
-   @freezed
-   abstract class [FeatureName]DTO with _$[FeatureName]DTO {
-     factory [FeatureName]DTO({
-       required String id,
-       required String title,
-       String? description,
-       @JsonKey(name: 'created_at') DateTime? createdAt,
-       @JsonKey(name: 'updated_at') DateTime? updatedAt,
-       @Default(true) bool isActive,
-       Map<String, dynamic>? metadata,
-       @JsonKey(name: 'user_id') String? userId,
-       List<String>? tags,
-       @JsonKey(name: 'sort_order') int? sortOrder,
-     }) = _[FeatureName]DTO;
-   
-     factory [FeatureName]DTO.fromJson(Map<String, dynamic> json) =>
-         _$[FeatureName]DTOFromJson(json);
-   }
-   ```
-
-2. **Add Custom Converters** (if needed):
-   ```dart
-   // For complex data types like Position, DateTime with specific formats, etc.
-   @JsonKey(name: 'location', fromJson: _positionFromJson, toJson: _positionToJson)
-   Position? location,
-   
-   static Position? _positionFromJson(Map<String, dynamic>? json) {
-     if (json == null) return null;
-     return Position(
-       latitude: json['latitude']?.toDouble() ?? 0.0,
-       longitude: json['longitude']?.toDouble() ?? 0.0,
-       timestamp: DateTime.now(),
-       accuracy: json['accuracy']?.toDouble() ?? 0.0,
-       altitude: json['altitude']?.toDouble() ?? 0.0,
-       altitudeAccuracy: json['altitudeAccuracy']?.toDouble() ?? 0.0,
-       heading: json['heading']?.toDouble() ?? 0.0,
-       headingAccuracy: json['headingAccuracy']?.toDouble() ?? 0.0,
-       speed: json['speed']?.toDouble() ?? 0.0,
-       speedAccuracy: json['speedAccuracy']?.toDouble() ?? 0.0,
-     );
-   }
-   
-   static Map<String, dynamic>? _positionToJson(Position? position) {
-     if (position == null) return null;
-     return {
-       'latitude': position.latitude,
-       'longitude': position.longitude,
-       'accuracy': position.accuracy,
-       'altitude': position.altitude,
-       'altitudeAccuracy': position.altitudeAccuracy,
-       'heading': position.heading,
-       'headingAccuracy': position.headingAccuracy,
-       'speed': position.speed,
-       'speedAccuracy': position.speedAccuracy,
-     };
-   }
-   ```
-
-### Phase 3: Mapper Implementation
-
-1. **Create Mapper File** (`lib/data/mappers/[feature]_mapper.dart`):
-   ```dart
-   import '../dtos/[feature]_dto.dart';
-   import '../../domain/models/[feature].dart';
-   
-   class [FeatureName]Mapper {
-     /// Convert DTO to Domain Model
-     static [FeatureName] toDomain([FeatureName]DTO dto) {
-       return [FeatureName](
-         id: dto.id,
-         title: dto.title,
-         description: dto.description,
-         createdAt: dto.createdAt ?? DateTime.now(),
-         updatedAt: dto.updatedAt ?? DateTime.now(),
-         isActive: dto.isActive,
-         metadata: dto.metadata,
-         userId: dto.userId,
-         tags: dto.tags ?? [],
-         sortOrder: dto.sortOrder ?? 0,
-       );
-     }
-   
-     /// Convert Domain Model to DTO
-     static [FeatureName]DTO fromDomain([FeatureName] domain) {
-       return [FeatureName]DTO(
-         id: domain.id,
-         title: domain.title,
-         description: domain.description,
-         createdAt: domain.createdAt,
-         updatedAt: domain.updatedAt,
-         isActive: domain.isActive,
-         metadata: domain.metadata,
-         userId: domain.userId,
-         tags: domain.tags,
-         sortOrder: domain.sortOrder,
-       );
-     }
-   
-     /// Convert list of DTOs to Domain Models
-     static List<[FeatureName]> toDomainList(List<[FeatureName]DTO> dtos) {
-       return dtos.map((dto) => toDomain(dto)).toList();
-     }
-   
-     /// Convert list of Domain Models to DTOs
-     static List<[FeatureName]DTO> fromDomainList(List<[FeatureName]> domains) {
-       return domains.map((domain) => fromDomain(domain)).toList();
-     }
-   
-     /// Convert JSON Map to Domain Model (direct conversion)
-     static [FeatureName] fromJson(Map<String, dynamic> json) {
-       return toDomain([FeatureName]DTO.fromJson(json));
-     }
-   
-     /// Convert Domain Model to JSON Map (direct conversion)
-     static Map<String, dynamic> toJson([FeatureName] domain) {
-       return fromDomain(domain).toJson();
-     }
-   }
-   ```
-
-### Phase 4: Repository Implementation
-
-1. **Create Repository Implementation** (`lib/data/repositories/[feature]_repository_impl.dart`):
-   ```dart
-   import 'package:cloud_firestore/cloud_firestore.dart';
-   import 'package:firebase_auth/firebase_auth.dart';
-   import 'package:logger/logger.dart';
-   
-   import '../../domain/models/[feature].dart';
-   import '../../domain/repositories/[feature]_repository.dart';
-   import '../dtos/[feature]_dto.dart';
-   import '../mappers/[feature]_mapper.dart';
-   import '../../core/network/app_exception.dart';
-   import '../../service_locator.dart';
-   
-   class [FeatureName]RepositoryImpl implements [FeatureName]Repository {
-     final FirebaseFirestore _firestore;
-     final FirebaseAuth _auth;
-     final Logger _logger;
-   
-     [FeatureName]RepositoryImpl({
-       FirebaseFirestore? firestore,
-       FirebaseAuth? auth,
-       Logger? logger,
-     })  : _firestore = firestore ?? getIt<FirebaseFirestore>(),
-           _auth = auth ?? getIt<FirebaseAuth>(),
-           _logger = logger ?? getIt<Logger>();
-   
-     String get _collectionPath => '[feature]s';
-     
-     CollectionReference get _collection => _firestore.collection(_collectionPath);
-     
-     String? get _currentUserId => _auth.currentUser?.uid;
-   
-     @override
-     Future<List<[FeatureName]>> getItems({
-       int page = 1,
-       int limit = 20,
-       bool forceRefresh = false,
-     }) async {
-       try {
-         if (_currentUserId == null) {
-           throw const AuthException('User not authenticated');
-         }
-   
-         Query query = _collection
-             .where('userId', isEqualTo: _currentUserId)
-             .where('isActive', isEqualTo: true)
-             .orderBy('createdAt', descending: true)
-             .limit(limit);
-   
-         if (page > 1) {
-           // For pagination, you'd need to implement cursor-based pagination
-           // This is a simplified version
-           query = query.startAfter([(page - 1) * limit]);
-         }
-   
-         final querySnapshot = await query.get();
-         
-         final dtos = querySnapshot.docs
-             .map((doc) => [FeatureName]DTO.fromJson({
-                   'id': doc.id,
-                   ...doc.data() as Map<String, dynamic>,
-                 }))
-             .toList();
-   
-         return [FeatureName]Mapper.toDomainList(dtos);
-       } catch (error, stackTrace) {
-         _logger.e('Error fetching [feature] items', error, stackTrace);
-         if (error is FirebaseException) {
-           throw ServerException(error.message ?? 'Failed to fetch items');
-         }
-         rethrow;
-       }
-     }
-   
-     @override
-     Future<[FeatureName]?> getItemById(String itemId) async {
-       try {
-         if (_currentUserId == null) {
-           throw const AuthException('User not authenticated');
-         }
-   
-         final doc = await _collection.doc(itemId).get();
-         
-         if (!doc.exists) {
-           return null;
-         }
-   
-         final data = doc.data() as Map<String, dynamic>;
-         
-         // Check if user owns this item
-         if (data['userId'] != _currentUserId) {
-           throw const PermissionException('Access denied');
-         }
-   
-         final dto = [FeatureName]DTO.fromJson({
-           'id': doc.id,
-           ...data,
-         });
-   
-         return [FeatureName]Mapper.toDomain(dto);
-       } catch (error, stackTrace) {
-         _logger.e('Error fetching [feature] item by ID: $itemId', error, stackTrace);
-         if (error is FirebaseException) {
-           throw ServerException(error.message ?? 'Failed to fetch item');
-         }
-         rethrow;
-       }
-     }
-   
-     @override
-     Future<[FeatureName]> createItem({
-       required String title,
-       String? description,
-       Map<String, dynamic>? metadata,
-       Map<String, dynamic>? additionalData,
-     }) async {
-       try {
-         if (_currentUserId == null) {
-           throw const AuthException('User not authenticated');
-         }
-   
-         final now = DateTime.now();
-         final dto = [FeatureName]DTO(
-           id: '', // Will be set by Firestore
-           title: title,
-           description: description,
-           createdAt: now,
-           updatedAt: now,
-           isActive: true,
-           metadata: metadata,
-           userId: _currentUserId!,
-           tags: additionalData?['tags']?.cast<String>() ?? [],
-           sortOrder: additionalData?['sortOrder'] ?? 0,
-         );
-   
-         final docRef = await _collection.add(dto.toJson()..remove('id'));
-         
-         final createdDto = dto.copyWith(id: docRef.id);
-         return [FeatureName]Mapper.toDomain(createdDto);
-       } catch (error, stackTrace) {
-         _logger.e('Error creating [feature] item', error, stackTrace);
-         if (error is FirebaseException) {
-           throw ServerException(error.message ?? 'Failed to create item');
-         }
-         rethrow;
-       }
-     }
-   
-     @override
-     Future<[FeatureName]> updateItem([FeatureName] item) async {
-       try {
-         if (_currentUserId == null) {
-           throw const AuthException('User not authenticated');
-         }
-   
-         // Ensure user owns this item
-         if (item.userId != _currentUserId) {
-           throw const PermissionException('Access denied');
-         }
-   
-         final dto = [FeatureName]Mapper.fromDomain(item).copyWith(
-           updatedAt: DateTime.now(),
-         );
-   
-         await _collection.doc(item.id).update(dto.toJson()..remove('id'));
-         
-         return [FeatureName]Mapper.toDomain(dto);
-       } catch (error, stackTrace) {
-         _logger.e('Error updating [feature] item: ${item.id}', error, stackTrace);
-         if (error is FirebaseException) {
-           throw ServerException(error.message ?? 'Failed to update item');
-         }
-         rethrow;
-       }
-     }
-   
-     @override
-     Future<void> deleteItem(String itemId) async {
-       try {
-         if (_currentUserId == null) {
-           throw const AuthException('User not authenticated');
-         }
-   
-         // Soft delete - mark as inactive
-         await _collection.doc(itemId).update({
-           'isActive': false,
-           'updatedAt': DateTime.now().toIso8601String(),
-         });
-       } catch (error, stackTrace) {
-         _logger.e('Error deleting [feature] item: $itemId', error, stackTrace);
-         if (error is FirebaseException) {
-           throw ServerException(error.message ?? 'Failed to delete item');
-         }
-         rethrow;
-       }
-     }
-   
-     @override
-     Future<List<[FeatureName]>> searchItems(String query, {int limit = 20}) async {
-       try {
-         if (_currentUserId == null) {
-           throw const AuthException('User not authenticated');
-         }
-   
-         if (query.isEmpty) {
-           return await getItems(limit: limit);
-         }
-   
-         // Firestore text search is limited, so we'll do client-side filtering
-         // For production, consider using Algolia or similar service
-         final allItems = await getItems(limit: 100); // Get more items for search
-         
-         final searchResults = allItems.where((item) {
-           final titleMatch = item.title.toLowerCase().contains(query.toLowerCase());
-           final descriptionMatch = item.description?.toLowerCase().contains(query.toLowerCase()) ?? false;
-           return titleMatch || descriptionMatch;
-         }).take(limit).toList();
-   
-         return searchResults;
-       } catch (error, stackTrace) {
-         _logger.e('Error searching [feature] items with query: $query', error, stackTrace);
-         rethrow;
-       }
-     }
-   
-     @override
-     Future<List<[FeatureName]>> filterItems({
-       bool? isActive,
-       DateTime? createdAfter,
-       DateTime? createdBefore,
-       List<String>? tags,
-       Map<String, dynamic>? customFilters,
-     }) async {
-       try {
-         if (_currentUserId == null) {
-           throw const AuthException('User not authenticated');
-         }
-   
-         Query query = _collection.where('userId', isEqualTo: _currentUserId);
-   
-         if (isActive != null) {
-           query = query.where('isActive', isEqualTo: isActive);
-         }
-   
-         if (createdAfter != null) {
-           query = query.where('createdAt', isGreaterThanOrEqualTo: createdAfter);
-         }
-   
-         if (createdBefore != null) {
-           query = query.where('createdAt', isLessThanOrEqualTo: createdBefore);
-         }
-   
-         if (tags != null && tags.isNotEmpty) {
-           query = query.where('tags', arrayContainsAny: tags);
-         }
-   
-         // Add custom filters
-         if (customFilters != null) {
-           for (final filter in customFilters.entries) {
-             query = query.where(filter.key, isEqualTo: filter.value);
-           }
-         }
-   
-         final querySnapshot = await query.get();
-         
-         final dtos = querySnapshot.docs
-             .map((doc) => [FeatureName]DTO.fromJson({
-                   'id': doc.id,
-                   ...doc.data() as Map<String, dynamic>,
-                 }))
-             .toList();
-   
-         return [FeatureName]Mapper.toDomainList(dtos);
-       } catch (error, stackTrace) {
-         _logger.e('Error filtering [feature] items', error, stackTrace);
-         if (error is FirebaseException) {
-           throw ServerException(error.message ?? 'Failed to filter items');
-         }
-         rethrow;
-       }
-     }
-   }
-   ```
-
-### Phase 5: Service Locator Registration
-
-1. **Update Service Locator** (`lib/service_locator.dart`):
-   ```dart
-   // Add to setupServiceLocator() function
-   
-   // Register [FeatureName] Repository
-   ..registerLazySingleton<[FeatureName]Repository>(
-     () => [FeatureName]RepositoryImpl(
-       firestore: getIt<FirebaseFirestore>(),
-       auth: getIt<FirebaseAuth>(),
-       logger: getIt<Logger>(),
-     ),
-   )
-   ```
-
-### Phase 6: Error Handling Enhancement
-
-1. **Add comprehensive error handling patterns**:
-   ```dart
-   // Add to repository implementation
-   
-   Future<T> _handleFirebaseOperation<T>(
-     Future<T> Function() operation,
-     String operationName,
-   ) async {
-     try {
-       return await operation();
-     } on FirebaseAuthException catch (error) {
-       _logger.e('Auth error in $operationName', error);
-       throw AuthException(error.message ?? 'Authentication failed');
-     } on FirebaseException catch (error) {
-       _logger.e('Firebase error in $operationName', error);
-       throw ServerException(error.message ?? 'Server error occurred');
-     } catch (error, stackTrace) {
-       _logger.e('Unexpected error in $operationName', error, stackTrace);
-       rethrow;
-     }
-   }
-   ```
-
-## Quality Checklist
-
-### DTO Implementation
-- [ ] Uses Freezed for immutability and code generation
-- [ ] Proper JSON annotations for API mapping
-- [ ] Custom converters for complex types
-- [ ] Proper null safety implementation
-- [ ] Factory constructors for JSON conversion
-
-### Mapper Implementation
-- [ ] Bidirectional conversion (DTO ↔ Domain)
-- [ ] List conversion methods
-- [ ] Direct JSON conversion helpers
-- [ ] Null safety handling
-- [ ] Performance optimization
-
-### Repository Implementation
-- [ ] Implements all domain repository interface methods
-- [ ] Proper error handling with custom exceptions
-- [ ] Authentication and authorization checks
-- [ ] Logging for debugging and monitoring
-- [ ] Firestore best practices (queries, indexing)
-
-### Service Integration
-- [ ] Proper dependency injection registration
-- [ ] Service locator integration
-- [ ] Interface-based implementation
-- [ ] Singleton pattern for repositories
-
-## Channel Communication
-
-### Before Starting
-Update channel.md:
-```markdown
-### 💾 Data Layer Status
-- **Status:** IN_PROGRESS
-- **Assigned Agent:** [YOUR_ID]
-- **Progress:** 0%
-```
-
-### During Development
-Update progress regularly:
-```markdown
-- **Progress:** [PERCENTAGE]%
-- **Files Created:** [LIST_OF_FILES]
-- **Next Steps:** [CURRENT_WORK]
-```
-
-### After Completion
-Mark as completed:
-```markdown
-### 💾 Data Layer Status
-- **Status:** COMPLETED
-- **Progress:** 100%
-- **Files Created:** [COMPLETE_LIST]
-```
-
-## Dependencies
-
-### Must be completed first:
-- Domain layer models and repository interfaces
-
-### Can work in parallel with:
-- Business logic layer (with coordination)
-
-### Enables after completion:
-- Business logic layer can use repository implementations
-- Complete feature integration
-
-## Output Deliverables
-
-1. **DTO**: `lib/data/dtos/[feature]_dto.dart`
-2. **Generated DTO Files**: `[feature]_dto.freezed.dart` and `[feature]_dto.g.dart`
-3. **Mapper**: `lib/data/mappers/[feature]_mapper.dart`
-4. **Repository Implementation**: `lib/data/repositories/[feature]_repository_impl.dart`
-5. **Updated Service Locator**: Registration in `lib/service_locator.dart`
-6. **Updated Channel**: Progress and completion status in channel.md
-7. **Code Generation**: Run `dart run build_runner build` after implementation
-
-All data components must follow AiGo's patterns with Freezed DTOs, proper JSON annotations, comprehensive error handling, and clean architecture principles.