appiq-solution 1.4.8 → 1.5.0

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

@@ -1,430 +0,0 @@
-# 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.