@appiq/flutter-workflow 1.2.0 → 1.4.0

package/templates/additional_cubit_req.md

@@ -0,0 +1,357 @@
+# Additional Cubit Requirements - State Management Integration
+
+This template defines additional state management requirements, provider setup, and integration patterns for your feature.
+
+## State Management Architecture
+
+### Cubit Integration Pattern
+```dart
+// Feature-specific state management structure
+lib/features/{feature}/presentation/cubit/
+├── {feature}_cubit.dart           // Main cubit implementation
+├── {feature}_state.dart           // State definitions
+└── {feature}_event.dart           // Events (if using BLoC pattern)
+```
+
+### Global State Dependencies
+- [ ] Authentication state integration
+- [ ] User role state management  
+- [ ] Theme/settings state access
+- [ ] Navigation state coordination
+- [ ] Network connectivity state
+- [ ] Offline/online state management
+
+## Provider Setup Requirements
+
+### Main App Provider Configuration
+```dart
+// Add to main.dart MultiBlocProvider
+MultiBlocProvider(
+  providers: [
+    // Existing providers...
+    BlocProvider<{Feature}Cubit>(
+      create: (context) => GetIt.instance<{Feature}Cubit>(),
+    ),
+    // Additional feature dependencies...
+  ],
+  child: MyApp(),
+)
+```
+
+### Dependency Injection Setup
+```dart
+// Add to dependency injection configuration
+void configureDependencies() {
+  // Repository registration
+  getIt.registerLazySingleton<{Feature}Repository>(
+    () => {Feature}RepositoryImpl(
+      remoteDataSource: getIt(),
+      localDataSource: getIt(),
+      networkInfo: getIt(),
+    ),
+  );
+
+  // Use case registration
+  getIt.registerLazySingleton(() => Get{Feature}UseCase(getIt()));
+  getIt.registerLazySingleton(() => Create{Feature}UseCase(getIt()));
+  getIt.registerLazySingleton(() => Update{Feature}UseCase(getIt()));
+  getIt.registerLazySingleton(() => Delete{Feature}UseCase(getIt()));
+
+  // Cubit registration
+  getIt.registerFactory<{Feature}Cubit>(
+    () => {Feature}Cubit(
+      get{Feature}UseCase: getIt(),
+      create{Feature}UseCase: getIt(),
+      update{Feature}UseCase: getIt(),
+      delete{Feature}UseCase: getIt(),
+    ),
+  );
+}
+```
+
+## State Initialization Requirements
+
+### Initial State Setup
+```dart
+class {Feature}Cubit extends Cubit<{Feature}State> {
+  {Feature}Cubit({
+    required this.get{Feature}UseCase,
+    required this.create{Feature}UseCase,
+    required this.update{Feature}UseCase,
+    required this.delete{Feature}UseCase,
+  }) : super(const {Feature}State.initial());
+
+  // Initialize feature data on cubit creation
+  Future<void> initialize() async {
+    emit(state.copyWith(status: {Feature}Status.loading));
+    
+    try {
+      final result = await get{Feature}UseCase.call(NoParams());
+      result.fold(
+        (failure) => emit(state.copyWith(
+          status: {Feature}Status.error,
+          errorMessage: failure.message,
+        )),
+        (data) => emit(state.copyWith(
+          status: {Feature}Status.loaded,
+          items: data,
+        )),
+      );
+    } catch (e) {
+      emit(state.copyWith(
+        status: {Feature}Status.error,
+        errorMessage: 'Unexpected error occurred',
+      ));
+    }
+  }
+}
+```
+
+### Widget Integration Pattern
+```dart
+class {Feature}Page extends StatefulWidget {
+  @override
+  _State createState() => _State();
+}
+
+class _State extends State<{Feature}Page> {
+  late {Feature}Cubit cubit;
+
+  @override
+  void initState() {
+    super.initState();
+    cubit = context.read<{Feature}Cubit>();
+    // Initialize cubit data
+    cubit.initialize();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocConsumer<{Feature}Cubit, {Feature}State>(
+      listener: (context, state) {
+        // Handle side effects (navigation, snackbars, etc.)
+        if (state.status == {Feature}Status.error) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(content: Text(state.errorMessage ?? 'Error occurred')),
+          );
+        }
+      },
+      builder: (context, state) {
+        return Scaffold(
+          body: _buildBody(state),
+        );
+      },
+    );
+  }
+}
+```
+
+## Common Integration Issues & Solutions
+
+### Issue 1: Cubit Not Initialized
+**Problem**: `BlocProvider.of() called with a context that does not contain a Cubit`
+**Solution**:
+```dart
+// Ensure proper provider hierarchy
+MaterialApp(
+  home: MultiBlocProvider(
+    providers: [
+      BlocProvider<{Feature}Cubit>(
+        create: (context) => GetIt.instance<{Feature}Cubit>(),
+      ),
+    ],
+    child: {Feature}Page(),
+  ),
+)
+```
+
+### Issue 2: Duplicate Cubit Registration
+**Problem**: Multiple registrations of the same cubit type
+**Solution**:
+```dart
+// Use registerFactory for cubits (new instance per request)
+getIt.registerFactory<{Feature}Cubit>(() => {Feature}Cubit(...));
+
+// Or check if already registered
+if (!getIt.isRegistered<{Feature}Cubit>()) {
+  getIt.registerFactory<{Feature}Cubit>(() => {Feature}Cubit(...));
+}
+```
+
+### Issue 3: State Not Persisting Across Navigation
+**Problem**: State resets when navigating between screens
+**Solution**:
+```dart
+// Use singleton registration for state that should persist
+getIt.registerLazySingleton<{Feature}Cubit>(() => {Feature}Cubit(...));
+
+// Or use global provider at app level
+class MyApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MultiBlocProvider(
+      providers: [
+        BlocProvider<{Feature}Cubit>(
+          create: (context) => GetIt.instance<{Feature}Cubit>(),
+        ),
+      ],
+      child: MaterialApp(...),
+    );
+  }
+}
+```
+
+## Cross-Feature State Communication
+
+### Feature-to-Feature State Updates
+```dart
+class {Feature}Cubit extends Cubit<{Feature}State> {
+  final AuthenticationCubit authCubit;
+  final UserRoleCubit userRoleCubit;
+  late StreamSubscription authSubscription;
+
+  {Feature}Cubit({
+    required this.authCubit,
+    required this.userRoleCubit,
+    // ... other dependencies
+  }) : super(const {Feature}State.initial()) {
+    // Listen to authentication changes
+    authSubscription = authCubit.stream.listen((authState) {
+      if (authState is! AuthenticatedState) {
+        // Clear feature data on logout
+        emit(const {Feature}State.initial());
+      }
+    });
+  }
+
+  @override
+  Future<void> close() {
+    authSubscription.cancel();
+    return super.close();
+  }
+}
+```
+
+### Global State Access Pattern
+```dart
+// Access other cubits from within a cubit
+void updateBasedOnUserRole() {
+  final userRole = userRoleCubit.state.role;
+  
+  switch (userRole) {
+    case UserRole.admin:
+      loadAdminData();
+      break;
+    case UserRole.manager:
+      loadManagerData();
+      break;
+    case UserRole.user:
+      loadUserData();
+      break;
+  }
+}
+```
+
+## Performance Optimization
+
+### Selective State Updates
+```dart
+// Use copyWith efficiently to avoid unnecessary rebuilds
+emit(state.copyWith(
+  status: {Feature}Status.loading,
+  // Only update changed fields
+));
+
+// Use state comparison to prevent duplicate emissions
+void updateItems(List<{Entity}> newItems) {
+  if (!listEquals(state.items, newItems)) {
+    emit(state.copyWith(items: newItems));
+  }
+}
+```
+
+### Memory Management
+```dart
+class {Feature}Cubit extends Cubit<{Feature}State> {
+  final List<StreamSubscription> _subscriptions = [];
+
+  void addSubscription(StreamSubscription subscription) {
+    _subscriptions.add(subscription);
+  }
+
+  @override
+  Future<void> close() {
+    // Cancel all subscriptions
+    for (final subscription in _subscriptions) {
+      subscription.cancel();
+    }
+    _subscriptions.clear();
+    return super.close();
+  }
+}
+```
+
+## Testing Integration
+
+### Cubit Testing Setup
+```dart
+// Test setup with proper mocking
+class MockAuthCubit extends MockCubit<AuthState> implements AuthCubit {}
+class MockUserRoleCubit extends MockCubit<UserRoleState> implements UserRoleCubit {}
+
+void main() {
+  late {Feature}Cubit cubit;
+  late MockAuthCubit mockAuthCubit;
+  late MockUserRoleCubit mockUserRoleCubit;
+
+  setUp(() {
+    mockAuthCubit = MockAuthCubit();
+    mockUserRoleCubit = MockUserRoleCubit();
+    
+    cubit = {Feature}Cubit(
+      authCubit: mockAuthCubit,
+      userRoleCubit: mockUserRoleCubit,
+      // ... other dependencies
+    );
+  });
+
+  tearDown(() {
+    cubit.close();
+  });
+}
+```
+
+## Integration Checklist
+
+### Provider Setup
+- [ ] Cubit registered in dependency injection
+- [ ] Provider added to MultiBlocProvider
+- [ ] Dependencies properly injected
+- [ ] Initialization logic implemented
+
+### State Management
+- [ ] Initial state properly defined
+- [ ] State transitions implemented
+- [ ] Error handling added
+- [ ] Loading states managed
+
+### Cross-Feature Integration
+- [ ] Authentication state integration
+- [ ] User role state access
+- [ ] Global state dependencies resolved
+- [ ] Navigation state coordination
+
+### Performance & Memory
+- [ ] Efficient state updates implemented
+- [ ] Memory leaks prevented (subscriptions canceled)
+- [ ] Unnecessary rebuilds minimized
+- [ ] State persistence strategy defined
+
+### Testing
+- [ ] Unit tests for cubit logic
+- [ ] Integration tests with providers
+- [ ] Mock implementations for dependencies
+- [ ] Error scenario testing
+
+## Notes
+Add any feature-specific state management requirements, custom integration patterns, or special initialization needs.