appiq-solution 1.4.8 → 1.5.0

package/flutter/punkt.claude/New Folder With Items/commands/feature-business-logic.md

@@ -1,551 +0,0 @@
-# Business Logic Layer Development Command
-
-Develops the business logic layer (Cubits/State Management) for a feature following VoicePilot architectural patterns.
-
-**Usage:** `feature-business-logic [FEATURE_NAME] [FEATURE_DESCRIPTION]`
-
-**Example:** `feature-business-logic project-favorites "Allow users to mark projects as favorites and view them in a separate list"`
-
-## Pre-Execution Checklist
-
-1. **Check Channel Status**: Read `/Users/vapps-it/Projects/voicepilot/.claude/channel.md`
-2. **Verify Dependencies**: Ensure architecture analysis is completed
-3. **Update Channel**: Mark Business Logic Layer status as "IN_PROGRESS" and assign agent
-4. **Check Blockers**: Verify no blockers are preventing business logic development
-
-## Implementation Process
-
-### Phase 1: Analysis & Planning
-
-1. **Study Existing Cubit Patterns**:
-   - Analyze `lib/presentation/bloc/` structure
-   - Study existing cubit implementations and state management
-   - Review `BaseCubitMixin` usage patterns
-   - Check error handling and logging patterns
-   - Understand state class structures with Equatable
-
-2. **Define State Requirements**:
-   - Identify all possible states (loading, loaded, error, initial)
-   - Plan state transitions and data flow
-   - Define error scenarios and handling
-   - Plan loading states and user feedback
-   - Identify caching and offline scenarios
-
-3. **Update Channel**: Add business logic requirements to channel.md
-
-### Phase 2: State Class Implementation
-
-1. **Create State File** (`lib/presentation/bloc/[feature]/[feature]_state.dart`):
-   ```dart
-   import 'package:equatable/equatable.dart';
-   import 'package:projectpilot/domain/entities/[feature]_entity.dart';
-   
-   enum [FeatureName]Status {
-     initial,
-     loading,
-     loaded,
-     error,
-     refreshing,
-   }
-   
-   class [FeatureName]State extends Equatable {
-     final [FeatureName]Status status;
-     final List<[FeatureName]Entity> items;
-     final [FeatureName]Entity? selectedItem;
-     final String? errorMessage;
-     final bool isFromCache;
-     final bool hasReachedEnd;
-     final int currentPage;
-     
-     const [FeatureName]State({
-       this.status = [FeatureName]Status.initial,
-       this.items = const [],
-       this.selectedItem,
-       this.errorMessage,
-       this.isFromCache = false,
-       this.hasReachedEnd = false,
-       this.currentPage = 1,
-     });
-     
-     // Factory constructors for different states
-     const [FeatureName]State.initial() : this();
-     
-     const [FeatureName]State.loading()
-         : this(status: [FeatureName]Status.loading);
-     
-     const [FeatureName]State.loaded({
-       required List<[FeatureName]Entity> items,
-       bool isFromCache = false,
-       bool hasReachedEnd = false,
-       int currentPage = 1,
-     }) : this(
-             status: [FeatureName]Status.loaded,
-             items: items,
-             isFromCache: isFromCache,
-             hasReachedEnd: hasReachedEnd,
-             currentPage: currentPage,
-           );
-     
-     const [FeatureName]State.error({
-       required String message,
-       List<[FeatureName]Entity> items = const [],
-     }) : this(
-             status: [FeatureName]Status.error,
-             errorMessage: message,
-             items: items,
-           );
-     
-     const [FeatureName]State.refreshing({
-       required List<[FeatureName]Entity> items,
-     }) : this(
-             status: [FeatureName]Status.refreshing,
-             items: items,
-           );
-     
-     // Convenience getters
-     bool get isInitial => status == [FeatureName]Status.initial;
-     bool get isLoading => status == [FeatureName]Status.loading;
-     bool get isLoaded => status == [FeatureName]Status.loaded;
-     bool get hasError => status == [FeatureName]Status.error;
-     bool get isRefreshing => status == [FeatureName]Status.refreshing;
-     bool get isEmpty => items.isEmpty && isLoaded;
-     bool get hasData => items.isNotEmpty;
-     
-     // CopyWith method
-     [FeatureName]State copyWith({
-       [FeatureName]Status? status,
-       List<[FeatureName]Entity>? items,
-       [FeatureName]Entity? selectedItem,
-       String? errorMessage,
-       bool? isFromCache,
-       bool? hasReachedEnd,
-       int? currentPage,
-     }) {
-       return [FeatureName]State(
-         status: status ?? this.status,
-         items: items ?? this.items,
-         selectedItem: selectedItem ?? this.selectedItem,
-         errorMessage: errorMessage ?? this.errorMessage,
-         isFromCache: isFromCache ?? this.isFromCache,
-         hasReachedEnd: hasReachedEnd ?? this.hasReachedEnd,
-         currentPage: currentPage ?? this.currentPage,
-       );
-     }
-     
-     @override
-     List<Object?> get props => [
-           status,
-           items,
-           selectedItem,
-           errorMessage,
-           isFromCache,
-           hasReachedEnd,
-           currentPage,
-         ];
-   }
-   ```
-
-### Phase 3: Cubit Implementation
-
-1. **Create Cubit File** (`lib/presentation/bloc/[feature]/[feature]_cubit.dart`):
-   ```dart
-   import 'package:flutter_bloc/flutter_bloc.dart';
-   import 'package:projectpilot/core/mixins/base_cubit_mixin.dart';
-   import 'package:projectpilot/domain/entities/[feature]_entity.dart';
-   import 'package:projectpilot/domain/repositories/[feature]_repository.dart';
-   import '[feature]_state.dart';
-   
-   class [FeatureName]Cubit extends Cubit<[FeatureName]State> 
-       with BaseCubitMixin<[FeatureName]State> {
-     final [FeatureName]Repository _repository;
-     
-     [FeatureName]Cubit({
-       required [FeatureName]Repository repository,
-     }) : _repository = repository,
-          super(const [FeatureName]State.initial());
-   
-     /// Load all items with caching fallback
-     Future<void> loadItems({bool forceRefresh = false}) async {
-       if (state.isLoading) return;
-       
-       await executeRepositoryOperation<List<[FeatureName]Entity>>(
-         operation: () => _repository.getItems(forceRefresh: forceRefresh),
-         onSuccess: (items) {
-           safeEmit([FeatureName]State.loaded(
-             items: items,
-             isFromCache: !forceRefresh,
-           ));
-         },
-         operationName: 'loadItems',
-         loadingState: const [FeatureName]State.loading(),
-         errorStateBuilder: (message) => [FeatureName]State.error(
-           message: message,
-           items: state.items, // Preserve existing items on error
-         ),
-       );
-     }
-     
-     /// Refresh items (pull-to-refresh)
-     Future<void> refreshItems() async {
-       if (state.isRefreshing) return;
-       
-       safeEmit([FeatureName]State.refreshing(items: state.items));
-       
-       await executeRepositoryOperation<List<[FeatureName]Entity>>(
-         operation: () => _repository.getItems(forceRefresh: true),
-         onSuccess: (items) {
-           safeEmit([FeatureName]State.loaded(
-             items: items,
-             isFromCache: false,
-           ));
-         },
-         operationName: 'refreshItems',
-         errorStateBuilder: (message) => [FeatureName]State.error(
-           message: message,
-           items: state.items,
-         ),
-       );
-     }
-     
-     /// Load item by ID
-     Future<void> loadItemById(String itemId) async {
-       await executeRepositoryOperation<[FeatureName]Entity>(
-         operation: () => _repository.getItemById(itemId),
-         onSuccess: (item) {
-           // Update the selected item in state
-           safeEmit(state.copyWith(selectedItem: item));
-         },
-         operationName: 'loadItemById_$itemId',
-         errorStateBuilder: (message) => state.copyWith(
-           errorMessage: message,
-         ),
-       );
-     }
-     
-     /// Create new item
-     Future<void> createItem({
-       required String title,
-       Map<String, dynamic>? additionalData,
-     }) async {
-       await executeRepositoryOperation<[FeatureName]Entity>(
-         operation: () => _repository.createItem(
-           title: title,
-           additionalData: additionalData,
-         ),
-         onSuccess: (newItem) {
-           final updatedItems = [newItem, ...state.items];
-           safeEmit(state.copyWith(
-             items: updatedItems,
-             selectedItem: newItem,
-           ));
-         },
-         operationName: 'createItem',
-         errorStateBuilder: (message) => state.copyWith(
-           errorMessage: message,
-         ),
-       );
-     }
-     
-     /// Update existing item
-     Future<void> updateItem([FeatureName]Entity item) async {
-       await executeRepositoryOperation<[FeatureName]Entity>(
-         operation: () => _repository.updateItem(item),
-         onSuccess: (updatedItem) {
-           final updatedItems = state.items.map((existingItem) {
-             return existingItem.id == updatedItem.id 
-                 ? updatedItem 
-                 : existingItem;
-           }).toList();
-           
-           safeEmit(state.copyWith(
-             items: updatedItems,
-             selectedItem: state.selectedItem?.id == updatedItem.id 
-                 ? updatedItem 
-                 : state.selectedItem,
-           ));
-         },
-         operationName: 'updateItem_${item.id}',
-         errorStateBuilder: (message) => state.copyWith(
-           errorMessage: message,
-         ),
-       );
-     }
-     
-     /// Delete item
-     Future<void> deleteItem(String itemId) async {
-       await executeRepositoryOperation<void>(
-         operation: () => _repository.deleteItem(itemId),
-         onSuccess: (_) {
-           final updatedItems = state.items
-               .where((item) => item.id != itemId)
-               .toList();
-           
-           safeEmit(state.copyWith(
-             items: updatedItems,
-             selectedItem: state.selectedItem?.id == itemId 
-                 ? null 
-                 : state.selectedItem,
-           ));
-         },
-         operationName: 'deleteItem_$itemId',
-         errorStateBuilder: (message) => state.copyWith(
-           errorMessage: message,
-         ),
-       );
-     }
-     
-     /// Load more items (pagination)
-     Future<void> loadMoreItems() async {
-       if (state.hasReachedEnd || state.isLoading) return;
-       
-       await executeRepositoryOperation<List<[FeatureName]Entity>>(
-         operation: () => _repository.getItems(
-           page: state.currentPage + 1,
-           limit: 20,
-         ),
-         onSuccess: (newItems) {
-           if (newItems.isEmpty) {
-             safeEmit(state.copyWith(hasReachedEnd: true));
-             return;
-           }
-           
-           final allItems = [...state.items, ...newItems];
-           safeEmit(state.copyWith(
-             items: allItems,
-             currentPage: state.currentPage + 1,
-             hasReachedEnd: newItems.length < 20,
-           ));
-         },
-         operationName: 'loadMoreItems_page${state.currentPage + 1}',
-         errorStateBuilder: (message) => state.copyWith(
-           errorMessage: message,
-         ),
-       );
-     }
-     
-     /// Search items
-     Future<void> searchItems(String query) async {
-       if (query.trim().isEmpty) {
-         await loadItems();
-         return;
-       }
-       
-       await executeRepositoryOperation<List<[FeatureName]Entity>>(
-         operation: () => _repository.searchItems(query),
-         onSuccess: (items) {
-           safeEmit([FeatureName]State.loaded(
-             items: items,
-             isFromCache: false,
-           ));
-         },
-         operationName: 'searchItems_$query',
-         loadingState: const [FeatureName]State.loading(),
-         errorStateBuilder: (message) => [FeatureName]State.error(
-           message: message,
-           items: state.items,
-         ),
-       );
-     }
-     
-     /// Clear error state
-     void clearError() {
-       if (state.hasError) {
-         safeEmit(state.copyWith(
-           status: [FeatureName]Status.loaded,
-           errorMessage: null,
-         ));
-       }
-     }
-     
-     /// Select item
-     void selectItem([FeatureName]Entity? item) {
-       safeEmit(state.copyWith(selectedItem: item));
-     }
-     
-     /// Clear cache and reload
-     Future<void> clearCacheAndReload() async {
-       await executeRepositoryOperation<void>(
-         operation: () => _repository.clearCache(),
-         onSuccess: (_) => loadItems(forceRefresh: true),
-         operationName: 'clearCacheAndReload',
-         errorStateBuilder: (message) => state.copyWith(
-           errorMessage: message,
-         ),
-       );
-     }
-   }
-   ```
-
-### Phase 4: Advanced Features Implementation
-
-1. **Implement Additional Business Logic Methods**:
-   - Batch operations (bulk update, delete)
-   - Advanced filtering and sorting
-   - Offline-first capabilities
-   - Background sync operations
-   - Real-time updates handling
-
-2. **Error Handling Specialization**:
-   ```dart
-   /// Handle specific business errors
-   void _handleBusinessError(dynamic error) {
-     if (error is ValidationException) {
-       safeEmit(state.copyWith(
-         errorMessage: 'Validation failed: ${error.message}',
-       ));
-     } else if (error is NetworkException) {
-       safeEmit(state.copyWith(
-         errorMessage: 'Network error. Please check your connection.',
-       ));
-     } else {
-       safeEmit(state.copyWith(
-         errorMessage: 'An unexpected error occurred.',
-       ));
-     }
-   }
-   ```
-
-### Phase 5: Performance Optimization
-
-1. **Implement Debouncing for Search**:
-   ```dart
-   Timer? _searchDebounce;
-   
-   void searchItemsDebounced(String query) {
-     _searchDebounce?.cancel();
-     _searchDebounce = Timer(const Duration(milliseconds: 500), () {
-       searchItems(query);
-     });
-   }
-   
-   @override
-   Future<void> close() {
-     _searchDebounce?.cancel();
-     return super.close();
-   }
-   ```
-
-2. **Implement Optimistic Updates**:
-   ```dart
-   Future<void> updateItemOptimistic([FeatureName]Entity item) async {
-     // Apply update immediately
-     final updatedItems = state.items.map((existingItem) {
-       return existingItem.id == item.id ? item : existingItem;
-     }).toList();
-     
-     safeEmit(state.copyWith(items: updatedItems));
-     
-     // Then sync with backend
-     try {
-       await _repository.updateItem(item);
-     } catch (error) {
-       // Revert on error
-       await loadItems(forceRefresh: true);
-       rethrow;
-     }
-   }
-   ```
-
-### Phase 6: State Persistence
-
-1. **Implement State Hydration** (if needed):
-   ```dart
-   /// Save current state to local storage
-   Future<void> saveState() async {
-     await executeRepositoryOperation<void>(
-       operation: () => _repository.saveState(state),
-       onSuccess: (_) => logger.d('State saved successfully'),
-       operationName: 'saveState',
-       errorStateBuilder: (message) => state,
-     );
-   }
-   
-   /// Restore state from local storage
-   Future<void> restoreState() async {
-     await executeRepositoryOperation<[FeatureName]State>(
-       operation: () => _repository.restoreState(),
-       onSuccess: (savedState) => safeEmit(savedState),
-       operationName: 'restoreState',
-       errorStateBuilder: (message) => state,
-     );
-   }
-   ```
-
-## Quality Checklist
-
-### State Management
-- [ ] All state transitions properly handled
-- [ ] Equatable implemented correctly
-- [ ] Convenience getters added
-- [ ] CopyWith method implemented
-- [ ] Immutable state objects
-
-### Business Logic
-- [ ] BaseCubitMixin used correctly
-- [ ] Error handling comprehensive
-- [ ] Loading states implemented
-- [ ] Caching strategies implemented
-- [ ] Performance optimizations added
-
-### Code Quality
-- [ ] Follows existing cubit patterns
-- [ ] Proper logging implemented
-- [ ] Resource cleanup in close()
-- [ ] Null safety compliance
-- [ ] Documentation comments added
-
-### Integration
-- [ ] Repository interface followed
-- [ ] Proper dependency injection
-- [ ] Error types handled correctly
-- [ ] State persistence (if needed)
-
-## Channel Communication
-
-### Before Starting
-Update channel.md:
-```markdown
-### 🧠 Business Logic 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
-### 🧠 Business Logic Layer Status
-- **Status:** COMPLETED
-- **Progress:** 100%
-- **Files Created:** [COMPLETE_LIST]
-```
-
-## Dependencies
-
-### Must be completed first:
-- Architecture analysis
-
-### Can work in parallel with:
-- Domain layer (with coordination)
-- UI layer (with coordination)
-
-### Enables after completion:
-- UI layer integration
-- Integration layer
-
-## Output Deliverables
-
-1. **State Class**: `lib/presentation/bloc/[feature]/[feature]_state.dart`
-2. **Cubit Class**: `lib/presentation/bloc/[feature]/[feature]_cubit.dart`
-3. **Export File**: `lib/presentation/bloc/[feature]/[feature]_bloc.dart` (if needed)
-4. **Updated Channel**: Progress and completion status in channel.md
-
-All business logic must follow the BaseCubitMixin pattern and integrate seamlessly with the existing architecture.