@appiq/flutter-workflow 1.2.0 → 1.4.0

package/templates/additional_domain_req.md

@@ -0,0 +1,431 @@
+# Additional Domain Requirements - Business Logic Extensions
+
+This template defines additional domain layer requirements, complex business rules, and domain service integrations.
+
+## Advanced Business Rules
+
+### Complex Validation Logic
+```dart
+class {Entity} extends Equatable {
+  final String id;
+  final String name;
+  final {EntityStatus} status;
+  final DateTime createdAt;
+  final DateTime? updatedAt;
+
+  const {Entity}({
+    required this.id,
+    required this.name,
+    required this.status,
+    required this.createdAt,
+    this.updatedAt,
+  });
+
+  // Advanced business rule validation
+  ValidationResult validateBusinessRules() {
+    final errors = <String>[];
+
+    // Custom business validation logic
+    if (name.trim().length < 3) {
+      errors.add('Name must be at least 3 characters long');
+    }
+
+    if (status == {EntityStatus}.archived && updatedAt == null) {
+      errors.add('Archived entities must have an updated timestamp');
+    }
+
+    // Time-based business rules
+    if (createdAt.isAfter(DateTime.now())) {
+      errors.add('Creation date cannot be in the future');
+    }
+
+    return ValidationResult(
+      isValid: errors.isEmpty,
+      errors: errors,
+    );
+  }
+
+  // Business logic for state transitions
+  {Entity} markAsCompleted() {
+    if (status == {EntityStatus}.completed) {
+      throw DomainException('Entity is already completed');
+    }
+
+    if (status == {EntityStatus}.archived) {
+      throw DomainException('Cannot complete archived entity');
+    }
+
+    return copyWith(
+      status: {EntityStatus}.completed,
+      updatedAt: DateTime.now(),
+    );
+  }
+}
+```
+
+### Cross-Entity Business Rules
+```dart
+class {Feature}DomainService {
+  // Complex business logic involving multiple entities
+  Future<Either<Failure, {ResultEntity}>> processComplexOperation({
+    required {Entity1} entity1,
+    required {Entity2} entity2,
+    required List<{Entity3}> entities3,
+  }) async {
+    // Validate cross-entity business rules
+    final validation = _validateCrossEntityRules(entity1, entity2, entities3);
+    if (!validation.isValid) {
+      return Left(ValidationFailure(validation.errors.join(', ')));
+    }
+
+    // Execute complex business logic
+    try {
+      final result = _executeBusinessLogic(entity1, entity2, entities3);
+      return Right(result);
+    } catch (e) {
+      return Left(DomainFailure('Business operation failed: ${e.toString()}'));
+    }
+  }
+
+  ValidationResult _validateCrossEntityRules(
+    {Entity1} entity1,
+    {Entity2} entity2,
+    List<{Entity3}> entities3,
+  ) {
+    final errors = <String>[];
+
+    // Example: Entity1 and Entity2 compatibility check
+    if (entity1.type != entity2.compatibleType) {
+      errors.add('Entity1 type is not compatible with Entity2');
+    }
+
+    // Example: Quantity validation across entities
+    final totalQuantity = entities3.fold(0, (sum, e) => sum + e.quantity);
+    if (totalQuantity > entity1.maxCapacity) {
+      errors.add('Total quantity exceeds maximum capacity');
+    }
+
+    // Example: Status consistency check
+    if (entity1.isActive && entities3.any((e) => !e.isValid)) {
+      errors.add('Active Entity1 cannot contain invalid Entity3 items');
+    }
+
+    return ValidationResult(
+      isValid: errors.isEmpty,
+      errors: errors,
+    );
+  }
+}
+```
+
+## Advanced Use Cases
+
+### Workflow Management Use Case
+```dart
+class Manage{Feature}WorkflowUseCase {
+  final {Feature}Repository repository;
+  final {Feature}DomainService domainService;
+  final NotificationService notificationService;
+
+  const Manage{Feature}WorkflowUseCase({
+    required this.repository,
+    required this.domainService,
+    required this.notificationService,
+  });
+
+  Future<Either<Failure, WorkflowResult>> execute({
+    required String workflowId,
+    required WorkflowAction action,
+    required Map<String, dynamic> context,
+  }) async {
+    try {
+      // Load current workflow state
+      final workflowResult = await repository.getWorkflow(workflowId);
+      if (workflowResult.isLeft()) {
+        return workflowResult.fold((l) => Left(l), (r) => throw Exception());
+      }
+
+      final workflow = workflowResult.getOrElse(() => throw Exception());
+
+      // Validate action is allowed in current state
+      final validationResult = domainService.validateWorkflowTransition(
+        workflow: workflow,
+        action: action,
+        context: context,
+      );
+
+      if (!validationResult.isValid) {
+        return Left(ValidationFailure(validationResult.errors.join(', ')));
+      }
+
+      // Execute workflow transition
+      final updatedWorkflow = domainService.executeWorkflowTransition(
+        workflow: workflow,
+        action: action,
+        context: context,
+      );
+
+      // Persist updated workflow
+      final saveResult = await repository.saveWorkflow(updatedWorkflow);
+      if (saveResult.isLeft()) {
+        return saveResult.fold((l) => Left(l), (r) => throw Exception());
+      }
+
+      // Send notifications if required
+      if (updatedWorkflow.requiresNotification) {
+        await notificationService.sendWorkflowNotification(updatedWorkflow);
+      }
+
+      return Right(WorkflowResult(
+        workflow: updatedWorkflow,
+        previousState: workflow.state,
+        newState: updatedWorkflow.state,
+        executedAt: DateTime.now(),
+      ));
+
+    } catch (e) {
+      return Left(DomainFailure('Workflow execution failed: ${e.toString()}'));
+    }
+  }
+}
+```
+
+### Batch Processing Use Case
+```dart
+class BatchProcess{Feature}UseCase {
+  final {Feature}Repository repository;
+  final {Feature}DomainService domainService;
+
+  Future<Either<Failure, BatchResult>> execute({
+    required List<String> entityIds,
+    required BatchOperation operation,
+    required Map<String, dynamic> parameters,
+  }) async {
+    final results = <String, Either<Failure, {Entity}>>[];
+    final errors = <String>[];
+
+    // Process entities in batches to manage memory
+    const batchSize = 50;
+    for (int i = 0; i < entityIds.length; i += batchSize) {
+      final batch = entityIds.skip(i).take(batchSize).toList();
+      
+      // Load batch entities
+      final entitiesResult = await repository.getEntitiesByIds(batch);
+      if (entitiesResult.isLeft()) {
+        errors.add('Failed to load batch ${i ~/ batchSize + 1}');
+        continue;
+      }
+
+      final entities = entitiesResult.getOrElse(() => []);
+
+      // Process each entity in the batch
+      for (final entity in entities) {
+        try {
+          final processedEntity = await _processEntity(entity, operation, parameters);
+          results[entity.id] = Right(processedEntity);
+        } catch (e) {
+          results[entity.id] = Left(DomainFailure(e.toString()));
+          errors.add('Failed to process entity ${entity.id}: $e');
+        }
+      }
+    }
+
+    return Right(BatchResult(
+      totalProcessed: results.length,
+      successCount: results.values.where((r) => r.isRight()).length,
+      errorCount: results.values.where((r) => r.isLeft()).length,
+      results: results,
+      errors: errors,
+    ));
+  }
+}
+```
+
+## Domain Events System
+
+### Domain Event Definition
+```dart
+abstract class DomainEvent extends Equatable {
+  final String eventId;
+  final DateTime occurredAt;
+  final String aggregateId;
+  final int aggregateVersion;
+
+  const DomainEvent({
+    required this.eventId,
+    required this.occurredAt,
+    required this.aggregateId,
+    required this.aggregateVersion,
+  });
+}
+
+class {Entity}CreatedEvent extends DomainEvent {
+  final {Entity} entity;
+
+  const {Entity}CreatedEvent({
+    required this.entity,
+    required String eventId,
+    required DateTime occurredAt,
+    required String aggregateId,
+    required int aggregateVersion,
+  }) : super(
+          eventId: eventId,
+          occurredAt: occurredAt,
+          aggregateId: aggregateId,
+          aggregateVersion: aggregateVersion,
+        );
+
+  @override
+  List<Object> get props => [entity, eventId, occurredAt, aggregateId, aggregateVersion];
+}
+```
+
+### Aggregate Root with Events
+```dart
+abstract class AggregateRoot<T> extends Equatable {
+  final String id;
+  final int version;
+  final List<DomainEvent> _domainEvents = [];
+
+  AggregateRoot({
+    required this.id,
+    required this.version,
+  });
+
+  List<DomainEvent> get domainEvents => List.unmodifiable(_domainEvents);
+
+  void addDomainEvent(DomainEvent event) {
+    _domainEvents.add(event);
+  }
+
+  void clearDomainEvents() {
+    _domainEvents.clear();
+  }
+
+  void markEventsAsCommitted() {
+    _domainEvents.clear();
+  }
+}
+
+class {Entity}Aggregate extends AggregateRoot<{Entity}> {
+  final {Entity} entity;
+
+  {Entity}Aggregate({
+    required this.entity,
+    required String id,
+    required int version,
+  }) : super(id: id, version: version);
+
+  {Entity}Aggregate update{Entity}({
+    required String name,
+    required {EntityStatus} status,
+  }) {
+    final updatedEntity = entity.copyWith(
+      name: name,
+      status: status,
+      updatedAt: DateTime.now(),
+    );
+
+    // Add domain event
+    addDomainEvent({Entity}UpdatedEvent(
+      entity: updatedEntity,
+      previousEntity: entity,
+      eventId: const Uuid().v4(),
+      occurredAt: DateTime.now(),
+      aggregateId: id,
+      aggregateVersion: version + 1,
+    ));
+
+    return {Entity}Aggregate(
+      entity: updatedEntity,
+      id: id,
+      version: version + 1,
+    );
+  }
+
+  @override
+  List<Object> get props => [entity, id, version];
+}
+```
+
+## Advanced Repository Patterns
+
+### Specification Pattern for Complex Queries
+```dart
+abstract class Specification<T> {
+  bool isSatisfiedBy(T candidate);
+  Specification<T> and(Specification<T> other);
+  Specification<T> or(Specification<T> other);
+  Specification<T> not();
+}
+
+class {Entity}ActiveSpecification extends Specification<{Entity}> {
+  @override
+  bool isSatisfiedBy({Entity} candidate) {
+    return candidate.status == {EntityStatus}.active;
+  }
+}
+
+class {Entity}CreatedAfterSpecification extends Specification<{Entity}> {
+  final DateTime date;
+
+  {Entity}CreatedAfterSpecification(this.date);
+
+  @override
+  bool isSatisfiedBy({Entity} candidate) {
+    return candidate.createdAt.isAfter(date);
+  }
+}
+
+// Extended repository interface
+abstract class {Feature}Repository {
+  Future<Either<Failure, List<{Entity}>>> findBySpecification(
+    Specification<{Entity}> specification,
+  );
+  
+  Future<Either<Failure, PaginatedResult<{Entity}>>> findPaginatedBySpecification(
+    Specification<{Entity}> specification,
+    PaginationParams pagination,
+  );
+}
+```
+
+## Integration Requirements Checklist
+
+### Business Logic Complexity
+- [ ] Complex validation rules implemented
+- [ ] Cross-entity business rules defined
+- [ ] State transition logic validated
+- [ ] Business invariants enforced
+- [ ] Domain services for complex operations
+
+### Use Case Extensions  
+- [ ] Workflow management use cases
+- [ ] Batch processing capabilities
+- [ ] Transaction management
+- [ ] Event-driven architecture
+- [ ] Saga pattern implementation (if needed)
+
+### Domain Events
+- [ ] Domain event definitions
+- [ ] Aggregate root with event support
+- [ ] Event publishing mechanism
+- [ ] Event handlers for side effects
+- [ ] Event store integration (if needed)
+
+### Advanced Patterns
+- [ ] Specification pattern for queries
+- [ ] Domain service implementations
+- [ ] Value object validations
+- [ ] Repository extensions
+- [ ] Unit of work pattern (if needed)
+
+### Performance Considerations
+- [ ] Batch processing for large datasets
+- [ ] Lazy loading strategies
+- [ ] Caching mechanisms
+- [ ] Query optimization patterns
+- [ ] Memory management for large aggregates
+
+## Notes
+Add any feature-specific domain requirements, complex business rules, or architectural patterns needed for your application.

package/templates/additional_ui_req.md

@@ -0,0 +1,205 @@
+# Additional UI Requirements - Role-Based Access Control
+
+This template defines role-specific UI implementations and access controls for your feature.
+
+## Role Definitions
+
+### Admin Role
+**Access Level**: Full system access
+**UI Elements**:
+- [ ] Admin dashboard with system statistics
+- [ ] User management interface (create, edit, delete users)
+- [ ] System configuration panels
+- [ ] Advanced analytics and reporting
+- [ ] Role assignment interface
+- [ ] Security logs and audit trails
+
+**Restricted Elements**:
+- None - full access
+
+### Manager Role  
+**Access Level**: Department/team management access
+**UI Elements**:
+- [ ] Team dashboard with team metrics
+- [ ] Team member management (view, edit team members)
+- [ ] Department-specific reporting
+- [ ] Approval workflows interface
+- [ ] Team scheduling and task assignment
+
+**Restricted Elements**:
+- [ ] System-wide configuration (admin only)
+- [ ] User role changes (admin only)
+- [ ] Global system analytics (admin only)
+
+### User Role
+**Access Level**: Standard user access
+**UI Elements**:
+- [ ] Personal dashboard with user-specific data
+- [ ] Profile management (edit own profile)
+- [ ] Task list and personal workflows
+- [ ] Basic reporting (own data only)
+- [ ] Standard feature access
+
+**Restricted Elements**:
+- [ ] User management (manager/admin only)
+- [ ] System configuration (admin only)
+- [ ] Other users' data (unless shared)
+- [ ] Administrative functions
+
+### Guest Role
+**Access Level**: Limited read-only access
+**UI Elements**:
+- [ ] Public information display
+- [ ] Basic feature demonstration
+- [ ] Registration/login prompts
+- [ ] Public content consumption
+
+**Restricted Elements**:
+- [ ] Any personal data access
+- [ ] Modification capabilities
+- [ ] Internal system information
+
+## Screen-Specific Access Control
+
+### Login/Authentication Screens
+```dart
+// Role-based redirect after authentication
+switch (userRole) {
+  case UserRole.admin:
+    // Navigate to admin dashboard
+    break;
+  case UserRole.manager:
+    // Navigate to manager dashboard
+    break;
+  case UserRole.user:
+    // Navigate to user dashboard
+    break;
+  case UserRole.guest:
+    // Navigate to public content
+    break;
+}
+```
+
+### Dashboard Implementation
+- **Admin Dashboard**: System overview, all metrics, user management
+- **Manager Dashboard**: Team metrics, team management, approvals
+- **User Dashboard**: Personal metrics, tasks, profile
+- **Guest Dashboard**: Public information, registration prompts
+
+### Navigation Structure
+```yaml
+Admin Navigation:
+  - Dashboard
+  - User Management
+  - System Settings
+  - Reports & Analytics
+  - Security & Logs
+
+Manager Navigation:
+  - Team Dashboard
+  - Team Management
+  - Team Reports
+  - Approvals
+  - Schedule
+
+User Navigation:
+  - Personal Dashboard
+  - My Tasks
+  - My Profile
+  - My Reports
+
+Guest Navigation:
+  - Public Content
+  - Features Overview
+  - Login/Register
+```
+
+## UI Component Visibility Rules
+
+### Conditional Widget Display
+```dart
+// Example role-based widget visibility
+if (userRole == UserRole.admin || userRole == UserRole.manager) {
+  // Show management tools
+  return ManagementToolsWidget();
+}
+
+if (userRole != UserRole.guest) {
+  // Show authenticated user content
+  return AuthenticatedContentWidget();
+}
+
+// Show guest content
+return GuestContentWidget();
+```
+
+### Button/Action Availability
+- **Create**: Admin, Manager (for their scope)
+- **Edit**: Admin, Manager (for their scope), User (own data)
+- **Delete**: Admin, Manager (for their scope), User (own data, limited)
+- **View**: Based on data ownership and role permissions
+
+## Data Access Patterns
+
+### API Endpoint Access by Role
+```yaml
+Admin Endpoints:
+  - /api/admin/* (all admin functions)
+  - /api/users/* (all user data)
+  - /api/system/* (system configuration)
+
+Manager Endpoints:
+  - /api/teams/{teamId}/* (team data)
+  - /api/users/team/{teamId} (team members)
+  - /api/reports/team/{teamId} (team reports)
+
+User Endpoints:
+  - /api/users/{userId} (own profile)
+  - /api/tasks/user/{userId} (own tasks)
+  - /api/reports/user/{userId} (own reports)
+
+Guest Endpoints:
+  - /api/public/* (public information)
+  - /api/auth/* (authentication)
+```
+
+## Error Handling for Unauthorized Access
+
+### Permission Denied Screens
+- **Graceful Degradation**: Show alternative content instead of errors
+- **Clear Messaging**: Explain why access is restricted
+- **Upgrade Prompts**: Suggest role upgrades where appropriate
+- **Alternative Actions**: Provide allowed alternatives
+
+### Security Considerations
+- [ ] Never expose role checking logic in client-side code
+- [ ] Always validate permissions on backend
+- [ ] Log unauthorized access attempts
+- [ ] Implement session timeout for sensitive roles
+- [ ] Use secure token-based authentication
+
+## Implementation Checklist
+
+### UI Implementation
+- [ ] Role-based navigation menus implemented
+- [ ] Conditional widget rendering based on roles
+- [ ] Role-specific dashboard layouts created
+- [ ] Permission-based button/action visibility
+- [ ] Graceful handling of unauthorized access
+
+### Security Implementation  
+- [ ] Backend permission validation for all endpoints
+- [ ] Secure role assignment and validation
+- [ ] Session management with appropriate timeouts
+- [ ] Audit logging for role-based actions
+- [ ] Regular security review of role permissions
+
+### Testing
+- [ ] Unit tests for role-based UI logic
+- [ ] Integration tests for role-based workflows
+- [ ] Security testing for unauthorized access attempts
+- [ ] User experience testing for each role
+- [ ] Performance testing with role-based data loading
+
+## Notes
+Add any additional role-specific requirements, custom permissions, or special access patterns needed for your application.