appiq-solution 1.1.0 → 1.3.0

package/flutter/punkt.claude/punkt.claude/commands/feature-integration.md

@@ -0,0 +1,493 @@
+# Feature Integration Development Command
+
+Completes feature integration by connecting all layers, updating service locator, and ensuring complete functionality.
+
+**Usage:** `feature-integration [FEATURE_NAME] [FEATURE_DESCRIPTION]`
+
+**Example:** `feature-integration 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 ALL other layers are completed
+   - ✅ Domain Layer (entities, repositories)
+   - ✅ Data Layer (models, implementations)
+   - ✅ Business Logic Layer (RiverPod providers, Freezed states)
+   - ✅ UI Layer (screens, components)
+   - ✅ Localization (all 5 languages)
+3. **Update Channel**: Mark Integration status as "IN_PROGRESS" and assign agent
+
+## Implementation Process
+
+### Phase 1: Service Locator Integration
+
+1. **Update Dependency Injection** (`lib/core/di/service_locator.dart`):
+   ```dart
+   // Add to existing service registration
+   void _registerRepositories() {
+     // Existing repositories...
+     
+     // [Feature Name] Repository
+     sl.registerLazySingleton<[FeatureName]Repository>(
+       () => [FeatureName]RepositoryImpl(
+         remoteDataSource: sl<[FeatureName]RemoteDataSource>(),
+         localDataSource: sl<[FeatureName]LocalDataSource>(),
+       ),
+     );
+   }
+   
+   void _registerDataSources() {
+     // Existing data sources...
+     
+     // [Feature Name] Data Sources
+     sl.registerLazySingleton<[FeatureName]RemoteDataSource>(
+       () => [FeatureName]RemoteDataSourceImpl(),
+     );
+     
+     sl.registerLazySingleton<[FeatureName]LocalDataSource>(
+       () => [FeatureName]LocalDataSourceImpl(
+         prefs: sl<SharedPreferences>(),
+       ),
+     );
+   }
+   
+   void _registerBlocs() {
+     // Existing blocs...
+     
+     // [Feature Name] Cubit
+     sl.registerFactory<[FeatureName]Cubit>(
+       () => [FeatureName]Cubit(
+         repository: sl<[FeatureName]Repository>(),
+       ),
+     );
+   }
+   ```
+
+### Phase 2: Navigation Integration
+
+2. **Update Route Configuration** (add to existing navigation setup):
+   ```dart
+   // Add to route configuration file
+   class AppRoutes {
+     // Existing routes...
+     
+     static const String [featureName] = '/[feature-name]';
+     static const String [featureName]Detail = '/[feature-name]/detail';
+     static const String [featureName]Create = '/[feature-name]/create';
+     static const String [featureName]Edit = '/[feature-name]/edit';
+   }
+   
+   // Add to route generation
+   Route<dynamic> generateRoute(RouteSettings settings) {
+     switch (settings.name) {
+       // Existing routes...
+       
+       case AppRoutes.[featureName]:
+         return MaterialPageRoute(
+           builder: (_) => BlocProvider(
+             create: (context) => sl<[FeatureName]Cubit>()..loadItems(),
+             child: const [FeatureName]Screen(),
+           ),
+           settings: settings,
+         );
+         
+       case AppRoutes.[featureName]Detail:
+         final itemId = settings.arguments as String;
+         return MaterialPageRoute(
+           builder: (_) => BlocProvider(
+             create: (context) => sl<[FeatureName]Cubit>()..loadItemById(itemId),
+             child: [FeatureName]DetailScreen(itemId: itemId),
+           ),
+           settings: settings,
+         );
+         
+       // Add other feature routes...
+     }
+   }
+   ```
+
+### Phase 3: Main Application Integration
+
+3. **Update Main App Widget** (if needed):
+   ```dart
+   // Add to existing app configuration
+   class MyApp extends StatelessWidget {
+     @override
+     Widget build(BuildContext context) {
+       return MultiBlocProvider(
+         providers: [
+           // Existing providers...
+           
+           // Add [Feature Name] Cubit if needed globally
+           BlocProvider<[FeatureName]Cubit>(
+             create: (context) => sl<[FeatureName]Cubit>(),
+           ),
+         ],
+         child: MaterialApp(
+           // Existing configuration...
+         ),
+       );
+     }
+   }
+   ```
+
+### Phase 4: Navigation Menu Integration
+
+4. **Update Navigation/Menu System** (if feature needs menu access):
+   ```dart
+   // Add to existing navigation drawer, bottom nav, or sidebar
+   
+   // Example for sidebar integration
+   ListTile(
+     leading: Icon(Icons.[feature_icon]),
+     title: Text(l10n.[featureName]Title),
+     onTap: () {
+       Navigator.of(context).pushNamed(AppRoutes.[featureName]);
+     },
+   ),
+   
+   // Example for bottom navigation
+   BottomNavigationBarItem(
+     icon: Icon(Icons.[feature_icon]),
+     label: l10n.[featureName]Title,
+   ),
+   ```
+
+### Phase 5: Permissions & Security Integration
+
+5. **Add Security Checks** (if needed):
+   ```dart
+   // Add to existing permission checks
+   class PermissionService {
+     // Existing permissions...
+     
+     Future<bool> can[FeatureName]Access() async {
+       // Implement permission logic
+       return await checkUserPermission('[feature_name]_access');
+     }
+     
+     Future<bool> can[FeatureName]Create() async {
+       return await checkUserPermission('[feature_name]_create');
+     }
+     
+     Future<bool> can[FeatureName]Edit() async {
+       return await checkUserPermission('[feature_name]_edit');
+     }
+     
+     Future<bool> can[FeatureName]Delete() async {
+       return await checkUserPermission('[feature_name]_delete');
+     }
+   }
+   ```
+
+### Phase 6: Analytics Integration
+
+6. **Add Analytics Tracking** (if analytics system exists):
+   ```dart
+   // Add to existing analytics service
+   class AnalyticsService {
+     // Existing events...
+     
+     void track[FeatureName]Viewed() {
+       trackEvent('[feature_name]_viewed');
+     }
+     
+     void track[FeatureName]Created() {
+       trackEvent('[feature_name]_created');
+     }
+     
+     void track[FeatureName]Updated() {
+       trackEvent('[feature_name]_updated');
+     }
+     
+     void track[FeatureName]Deleted() {
+       trackEvent('[feature_name]_deleted');
+     }
+     
+     void track[FeatureName]Searched(String query) {
+       trackEvent('[feature_name]_searched', parameters: {
+         'query': query,
+       });
+     }
+   }
+   ```
+
+### Phase 7: Search Integration
+
+7. **Add to Global Search** (if global search exists):
+   ```dart
+   // Add to existing search service
+   abstract class SearchService {
+     // Existing search methods...
+     
+     Future<List<SearchResult>> search[FeatureName](String query);
+   }
+   
+   class SearchServiceImpl implements SearchService {
+     // Existing implementations...
+     
+     @override
+     Future<List<SearchResult>> search[FeatureName](String query) async {
+       final repository = sl<[FeatureName]Repository>();
+       final result = await repository.searchItems(query);
+       
+       return result.fold(
+         (failure) => [],
+         (items) => items.map((item) => SearchResult(
+           id: item.id,
+           title: item.title,
+           subtitle: item.description,
+           type: '[feature_name]',
+           route: AppRoutes.[featureName]Detail,
+           arguments: item.id,
+         )).toList(),
+       );
+     }
+   }
+   ```
+
+### Phase 8: State Persistence Integration
+
+8. **Add State Persistence** (if needed):
+   ```dart
+   // Add to existing state persistence
+   class AppStateManager {
+     // Existing state management...
+     
+     Future<void> save[FeatureName]State([FeatureName]State state) async {
+       final repository = sl<[FeatureName]Repository>();
+       await repository.saveState(state);
+     }
+     
+     Future<[FeatureName]State?> restore[FeatureName]State() async {
+       final repository = sl<[FeatureName]Repository>();
+       final result = await repository.restoreState();
+       return result.fold(
+         (failure) => null,
+         (state) => state as [FeatureName]State?,
+       );
+     }
+   }
+   ```
+
+### Phase 9: Background Services Integration
+
+9. **Add Background Processing** (if needed):
+   ```dart
+   // Add to existing background service
+   class BackgroundSyncService {
+     // Existing sync methods...
+     
+     Future<void> sync[FeatureName]Data() async {
+       try {
+         final repository = sl<[FeatureName]Repository>();
+         final result = await repository.syncWithRemote();
+         
+         result.fold(
+           (failure) => logger.e('Failed to sync [feature name]: $failure'),
+           (syncCount) => logger.i('Synced $syncCount [feature name] items'),
+         );
+       } catch (e) {
+         logger.e('Error syncing [feature name]: $e');
+       }
+     }
+   }
+   ```
+
+### Phase 10: Widget Export Integration
+
+10. **Create Feature Exports** (for easy importing):
+    ```dart
+    // Create lib/presentation/screens/[feature]/[feature]_exports.dart
+    // Screens
+    export '[feature]_screen.dart';
+    export '[feature]_detail_screen.dart';
+    
+    // Components
+    export 'components/[feature]_card.dart';
+    export 'components/[feature]_list.dart';
+    
+    // Widgets
+    export 'widgets/[feature]_widget.dart';
+    
+    // Create lib/presentation/bloc/[feature]/[feature]_exports.dart
+    export '[feature]_cubit.dart';
+    export '[feature]_state.dart';
+    
+    // Create lib/domain/[feature]_exports.dart
+    export 'entities/[feature]_entity.dart';
+    export 'repositories/[feature]_repository.dart';
+    
+    // Create lib/data/[feature]_exports.dart
+    export 'models/[feature]_model.dart';
+    export 'repositories/[feature]_repository_impl.dart';
+    export 'datasources/[feature]_remote_data_source.dart';
+    export 'datasources/[feature]_local_data_source.dart';
+    ```
+
+### Phase 11: Testing Integration
+
+11. **Integration Testing Setup**:
+    ```dart
+    // Add to existing integration tests
+    void main() {
+      group('[FeatureName] Integration Tests', () {
+        setUp(() async {
+          // Setup test environment
+          await setupServiceLocator();
+        });
+        
+        testWidgets('Should display [feature name] screen', (tester) async {
+          await tester.pumpWidget(MyApp());
+          await tester.pumpAndSettle();
+          
+          // Navigate to feature
+          await tester.tap(find.text(l10n.[featureName]Title));
+          await tester.pumpAndSettle();
+          
+          // Verify screen is displayed
+          expect(find.byType([FeatureName]Screen), findsOneWidget);
+        });
+        
+        testWidgets('Should create new [feature name] item', (tester) async {
+          // Implementation...
+        });
+        
+        // Add more integration tests...
+      });
+    }
+    ```
+
+### Phase 12: Performance Monitoring Integration
+
+12. **Add Performance Monitoring**:
+    ```dart
+    // Add to existing performance monitoring
+    class PerformanceMonitor {
+      // Existing metrics...
+      
+      void track[FeatureName]LoadTime(Duration loadTime) {
+        trackMetric('[feature_name]_load_time', loadTime.inMilliseconds);
+      }
+      
+      void track[FeatureName]SearchTime(Duration searchTime) {
+        trackMetric('[feature_name]_search_time', searchTime.inMilliseconds);
+      }
+      
+      void track[FeatureName]CacheHitRate(double hitRate) {
+        trackMetric('[feature_name]_cache_hit_rate', hitRate);
+      }
+    }
+    ```
+
+## Quality Checklist
+
+### Integration Completeness
+- [ ] Service locator properly configured
+- [ ] Navigation routes working
+- [ ] BlocProvider setup correctly
+- [ ] Dependencies injected properly
+- [ ] Error handling integrated
+
+### Feature Functionality
+- [ ] All CRUD operations working
+- [ ] Search functionality integrated
+- [ ] Caching working properly
+- [ ] Offline support functional
+- [ ] Real-time updates (if applicable)
+
+### Performance
+- [ ] No memory leaks detected
+- [ ] Smooth navigation transitions
+- [ ] Fast loading times
+- [ ] Efficient caching
+- [ ] Background operations optimized
+
+### User Experience
+- [ ] Consistent with app design
+- [ ] Proper loading states
+- [ ] Error messages user-friendly
+- [ ] Accessibility features working
+- [ ] Multi-language support complete
+
+### Security & Permissions
+- [ ] Proper permission checks
+- [ ] Secure data handling
+- [ ] Authentication integration
+- [ ] Authorization working
+- [ ] Data validation complete
+
+## Final Validation
+
+### Comprehensive Testing
+1. **Manual Testing**:
+   - Test all user workflows
+   - Verify offline functionality
+   - Test error scenarios
+   - Check performance under load
+   - Test on different screen sizes
+
+2. **Automated Testing**:
+   - Unit tests pass
+   - Integration tests pass
+   - Widget tests pass
+   - End-to-end tests pass
+
+3. **Quality Assurance**:
+   - Code review completed
+   - Performance benchmarks met
+   - Security review passed
+   - Accessibility audit passed
+   - Localization testing completed
+
+## Channel Communication
+
+### Before Starting
+Update channel.md:
+```markdown
+### 🔧 Integration Status
+- **Status:** IN_PROGRESS
+- **Assigned Agent:** [YOUR_ID]
+- **Progress:** 0%
+```
+
+### During Development
+Update progress regularly:
+```markdown
+- **Progress:** [PERCENTAGE]%
+- **Components Integrated:** [LIST]
+- **Next Steps:** [CURRENT_WORK]
+```
+
+### After Completion
+Mark as completed and update final status:
+```markdown
+### 🔧 Integration Status
+- **Status:** COMPLETED
+- **Progress:** 100%
+
+## Final Feature Status: ✅ COMPLETE
+- All layers implemented and integrated
+- Full functionality tested
+- Ready for production
+```
+
+## Dependencies
+
+### Must be completed first:
+- All other layers (Domain, Data, Business Logic, UI, Localization)
+
+### Final deliverable:
+- Complete, production-ready feature
+
+## Output Deliverables
+
+1. **Updated Service Locator**: Proper dependency injection setup
+2. **Navigation Integration**: Routes and navigation working
+3. **App Integration**: Feature accessible through app interface
+4. **Testing Suite**: Comprehensive test coverage
+5. **Performance Monitoring**: Metrics and monitoring integrated
+6. **Documentation**: Updated channel.md with final status
+7. **Export Files**: Clean imports and exports for feature modules
+
+The feature should be completely functional, tested, and ready for production use with full integration into the existing application architecture.