appiq-solution 1.1.0 → 1.3.0

package/flutter/punkt.claude/punkt.claude/commands/feature-business-logic.md

@@ -0,0 +1,430 @@
+# Business Logic Layer Development Command
+
+Develops the business logic layer (RiverPod Providers/State Management) for a feature following AiGo architectural patterns with @riverpod annotations.
+
+**Usage:** `feature-business-logic [FEATURE_NAME] [FEATURE_DESCRIPTION]`
+
+**Example:** `feature-business-logic 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 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 RiverPod Patterns**:
+   - Analyze `lib/views/*/providers/` structure
+   - Study existing provider implementations with @riverpod annotations
+   - Review provider code generation patterns (*.g.dart files)
+   - Check AsyncValue error handling and loading patterns
+   - Understand Freezed state class structures
+
+2. **Define State Requirements**:
+   - Identify all possible states using AsyncValue<T> for async operations
+   - Plan state transitions with Freezed copyWith patterns
+   - Define error scenarios with AsyncError handling
+   - Plan loading states with AsyncLoading
+   - Plan local state management patterns
+
+3. **Update Channel**: Add business logic requirements to channel.md
+
+### Phase 2: Freezed State Class Implementation
+
+1. **Create State File** (`lib/views/[feature]/providers/states/[feature]_state.dart`):
+   ```dart
+   import 'package:freezed_annotation/freezed_annotation.dart';
+   import 'package:aigo/domain/models/[feature].dart';
+   
+   part '[feature]_state.freezed.dart';
+   
+   @freezed
+   abstract class [FeatureName]State with _$[FeatureName]State {
+     const factory [FeatureName]State({
+       @Default(false) bool isLoading,
+       @Default(false) bool isRefreshing,
+       String? error,
+       @Default([]) List<[FeatureName]> items,
+       [FeatureName]? selectedItem,
+       @Default(1) int currentPage,
+       @Default(false) bool hasReachedEnd,
+       @Default(false) bool isFromCache,
+       @Default({}) Map<String, dynamic> filters,
+     }) = _[FeatureName]State;
+   }
+   ```
+
+### Phase 3: RiverPod Provider Implementation
+
+1. **Create Provider File** (`lib/views/[feature]/providers/[feature]_provider.dart`):
+   ```dart
+   import 'package:riverpod_annotation/riverpod_annotation.dart';
+   import 'package:aigo/domain/repositories/[feature]_repository.dart';
+   import 'package:aigo/service_locator.dart';
+   import 'package:aigo/core/utils/logger.dart';
+   import 'states/[feature]_state.dart';
+   
+   part '[feature]_provider.g.dart';
+   
+   @riverpod
+   class [FeatureName] extends _$[FeatureName] {
+     @override
+     [FeatureName]State build() {
+       // Initialize and auto-load data
+       _initialize();
+       return const [FeatureName]State();
+     }
+     
+     late final [FeatureName]Repository _repository = getIt<[FeatureName]Repository>();
+     
+     Future<void> _initialize() async {
+       // Auto-load initial data
+       await loadItems();
+     }
+     
+     /// Load items with loading state management
+     Future<void> loadItems({bool forceRefresh = false}) async {
+       try {
+         state = state.copyWith(
+           isLoading: !forceRefresh,
+           isRefreshing: forceRefresh,
+           error: null,
+         );
+         
+         final items = await _repository.getItems(
+           page: 1,
+           limit: 20,
+           forceRefresh: forceRefresh,
+         );
+         
+         state = state.copyWith(
+           isLoading: false,
+           isRefreshing: false,
+           items: items,
+           currentPage: 1,
+           hasReachedEnd: items.length < 20,
+         );
+       } catch (error, stackTrace) {
+         Logger().e('Error loading [feature] items', error, stackTrace);
+         state = state.copyWith(
+           isLoading: false,
+           isRefreshing: false,
+           error: error.toString(),
+         );
+       }
+     }
+     
+     /// Load more items for pagination
+     Future<void> loadMoreItems() async {
+       if (state.isLoading || state.hasReachedEnd) return;
+       
+       try {
+         state = state.copyWith(isLoading: true);
+         
+         final newItems = await _repository.getItems(
+           page: state.currentPage + 1,
+           limit: 20,
+         );
+         
+         state = state.copyWith(
+           isLoading: false,
+           items: [...state.items, ...newItems],
+           currentPage: state.currentPage + 1,
+           hasReachedEnd: newItems.length < 20,
+         );
+       } catch (error, stackTrace) {
+         Logger().e('Error loading more [feature] items', error, stackTrace);
+         state = state.copyWith(
+           isLoading: false,
+           error: error.toString(),
+         );
+       }
+     }
+     
+     /// Select a specific item
+     void selectItem([FeatureName]? item) {
+       state = state.copyWith(selectedItem: item);
+     }
+     
+     /// Add a new item
+     Future<void> addItem({
+       required String title,
+       String? description,
+       Map<String, dynamic>? metadata,
+     }) async {
+       try {
+         state = state.copyWith(isLoading: true, error: null);
+         
+         final newItem = await _repository.createItem(
+           title: title,
+           description: description,
+           metadata: metadata,
+         );
+         
+         state = state.copyWith(
+           isLoading: false,
+           items: [newItem, ...state.items],
+         );
+       } catch (error, stackTrace) {
+         Logger().e('Error adding [feature] item', error, stackTrace);
+         state = state.copyWith(
+           isLoading: false,
+           error: error.toString(),
+         );
+       }
+     }
+     
+     /// Update an existing item
+     Future<void> updateItem([FeatureName] item) async {
+       try {
+         state = state.copyWith(isLoading: true, error: null);
+         
+         final updatedItem = await _repository.updateItem(item);
+         
+         final updatedItems = state.items.map((existingItem) {
+           return existingItem.id == updatedItem.id ? updatedItem : existingItem;
+         }).toList();
+         
+         state = state.copyWith(
+           isLoading: false,
+           items: updatedItems,
+           selectedItem: state.selectedItem?.id == updatedItem.id ? updatedItem : state.selectedItem,
+         );
+       } catch (error, stackTrace) {
+         Logger().e('Error updating [feature] item', error, stackTrace);
+         state = state.copyWith(
+           isLoading: false,
+           error: error.toString(),
+         );
+       }
+     }
+     
+     /// Delete an item
+     Future<void> deleteItem(String itemId) async {
+       try {
+         state = state.copyWith(isLoading: true, error: null);
+         
+         await _repository.deleteItem(itemId);
+         
+         final updatedItems = state.items.where((item) => item.id != itemId).toList();
+         
+         state = state.copyWith(
+           isLoading: false,
+           items: updatedItems,
+           selectedItem: state.selectedItem?.id == itemId ? null : state.selectedItem,
+         );
+       } catch (error, stackTrace) {
+         Logger().e('Error deleting [feature] item', error, stackTrace);
+         state = state.copyWith(
+           isLoading: false,
+           error: error.toString(),
+         );
+       }
+     }
+     
+     /// Search items
+     Future<void> searchItems(String query) async {
+       if (query.isEmpty) {
+         await loadItems();
+         return;
+       }
+       
+       try {
+         state = state.copyWith(isLoading: true, error: null);
+         
+         final items = await _repository.searchItems(query);
+         
+         state = state.copyWith(
+           isLoading: false,
+           items: items,
+           hasReachedEnd: true, // Search results don't have pagination
+         );
+       } catch (error, stackTrace) {
+         Logger().e('Error searching [feature] items', error, stackTrace);
+         state = state.copyWith(
+           isLoading: false,
+           error: error.toString(),
+         );
+       }
+     }
+     
+     /// Apply filters
+     Future<void> applyFilters(Map<String, dynamic> filters) async {
+       try {
+         state = state.copyWith(
+           isLoading: true,
+           error: null,
+           filters: filters,
+         );
+         
+         final items = await _repository.filterItems(
+           customFilters: filters,
+         );
+         
+         state = state.copyWith(
+           isLoading: false,
+           items: items,
+           hasReachedEnd: true, // Filtered results don't have pagination
+         );
+       } catch (error, stackTrace) {
+         Logger().e('Error applying [feature] filters', error, stackTrace);
+         state = state.copyWith(
+           isLoading: false,
+           error: error.toString(),
+         );
+       }
+     }
+     
+     /// Clear filters and reload
+     Future<void> clearFilters() async {
+       state = state.copyWith(filters: {});
+       await loadItems();
+     }
+     
+     /// Clear error state
+     void clearError() {
+       state = state.copyWith(error: null);
+     }
+     
+     /// Refresh data
+     Future<void> refresh() async {
+       await loadItems(forceRefresh: true);
+     }
+   }
+   ```
+
+### Phase 4: Additional Providers (if needed)
+
+1. **Create Async Providers for specific operations**:
+   ```dart
+   // For fetching a single item
+   @riverpod
+   Future<[FeatureName]?> [featureName]ById([FeatureName]ByIdRef ref, String id) async {
+     final repository = getIt<[FeatureName]Repository>();
+     return await repository.getItemById(id);
+   }
+   
+   // For computed state
+   @riverpod
+   List<[FeatureName]> filtered[FeatureName]s(Filtered[FeatureName]sRef ref) {
+     final state = ref.watch([featureName]Provider);
+     final searchQuery = ref.watch(searchQueryProvider);
+     
+     if (searchQuery.isEmpty) return state.items;
+     
+     return state.items.where((item) => 
+       item.title.toLowerCase().contains(searchQuery.toLowerCase())
+     ).toList();
+   }
+   ```
+
+### Phase 5: Error Handling Enhancement
+
+1. **Add comprehensive error handling**:
+   ```dart
+   // Add to provider class
+   
+   /// Handle errors with user-friendly messages
+   String _handleError(dynamic error) {
+     if (error is NetworkException) {
+       return 'Network connection error. Please check your internet connection.';
+     } else if (error is ServerException) {
+       return 'Server error. Please try again later.';
+     } else if (error is ValidationException) {
+       return 'Invalid data. Please check your input.';
+     } else {
+       return 'An unexpected error occurred. Please try again.';
+     }
+   }
+   
+   /// Retry failed operations
+   Future<void> retryLastOperation() async {
+     if (state.error != null) {
+       await loadItems(forceRefresh: true);
+     }
+   }
+   ```
+
+## Quality Checklist
+
+### Provider Implementation
+- [ ] Uses @riverpod annotation for code generation
+- [ ] Proper dependency injection with GetIt
+- [ ] Comprehensive error handling with user-friendly messages
+- [ ] Loading states for all async operations
+- [ ] Proper state immutability with Freezed copyWith
+
+### State Management
+- [ ] Freezed state class with proper defaults
+- [ ] All state changes are immutable
+- [ ] Clear state structure with logical grouping
+- [ ] Proper null safety implementation
+
+### Business Logic
+- [ ] CRUD operations implemented
+- [ ] Pagination support
+- [ ] Search and filter functionality
+- [ ] Error recovery mechanisms
+- [ ] Logging for debugging
+
+### Code Generation
+- [ ] build_runner dependencies in pubspec.yaml
+- [ ] Proper part files for code generation
+- [ ] All generated files (.g.dart, .freezed.dart) ignored in git
+
+## 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
+- Domain layer models and repositories
+
+### Can work in parallel with:
+- UI layer (with coordination)
+- Data layer (with coordination)
+
+### Enables after completion:
+- UI layer can consume providers
+- State management integration
+- Code generation with build_runner
+
+## Output Deliverables
+
+1. **State Classes**: `lib/views/[feature]/providers/states/[feature]_state.dart`
+2. **Provider**: `lib/views/[feature]/providers/[feature]_provider.dart`
+3. **Generated Files**: `[feature]_provider.g.dart` and `[feature]_state.freezed.dart`
+4. **Updated Channel**: Progress and completion status in channel.md
+5. **Code Generation**: Run `dart run build_runner build` after implementation
+
+All providers must follow AiGo's RiverPod patterns with proper error handling, loading states, and immutable state management using Freezed.