appiq-solution 1.2.0 → 1.3.0

package/flutter/punkt.claude/punkt.claude/commands/feature-domain-layer.md

@@ -0,0 +1,537 @@
+# Domain Layer Development Command
+
+Develops the domain layer (Models & Repository Interfaces) for a feature following AiGo Clean Architecture with pure Dart classes.
+
+**Usage:** `feature-domain-layer [FEATURE_NAME] [FEATURE_DESCRIPTION]`
+
+**Example:** `feature-domain-layer 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 Domain Layer status as "IN_PROGRESS" and assign agent
+4. **Check Blockers**: Verify no blockers are preventing domain development
+
+## Implementation Process
+
+### Phase 1: Analysis & Planning
+
+1. **Study Existing Domain Patterns**:
+   - Analyze `lib/domain/models/` structure and patterns (place.dart, user_model.dart, etc.)
+   - Study existing repository interfaces in `lib/domain/repositories/`
+   - Review model relationships and business logic
+   - Follow pure Dart class patterns without external dependencies
+   - No Either/failure patterns - use standard Dart exceptions
+
+2. **Define Domain Requirements**:
+   - Identify core business entities and their properties
+   - Define business rules and validation logic
+   - Plan entity relationships and dependencies
+   - Identify required repository operations
+   - Plan failure scenarios and error types
+
+3. **Update Channel**: Add domain requirements to channel.md
+
+### Phase 2: Entity Implementation
+
+1. **Create Domain Model File** (`lib/domain/models/[feature].dart`):
+   ```dart
+   class [FeatureName] {
+     // Pure Dart class - no external dependencies
+     final String id;
+     final String title;
+     final String? description;
+     final DateTime createdAt;
+     final DateTime updatedAt;
+     final bool isActive;
+     final Map<String, dynamic>? metadata;
+     
+     const [FeatureName]Entity({
+       required this.id,
+       required this.title,
+       this.description,
+       required this.createdAt,
+       required this.updatedAt,
+       this.isActive = true,
+       this.metadata,
+     });
+     
+     /// Business logic: Check if entity is recently created
+     bool get isRecentlyCreated {
+       final now = DateTime.now();
+       final difference = now.difference(createdAt);
+       return difference.inDays < 7;
+     }
+     
+     /// Business logic: Check if entity needs update
+     bool get needsUpdate {
+       final now = DateTime.now();
+       final difference = now.difference(updatedAt);
+       return difference.inDays > 30;
+     }
+     
+     /// Business logic: Get display title
+     String get displayTitle {
+       return title.isNotEmpty ? title : 'Untitled ${runtimeType.toString()}';
+     }
+     
+     /// Business logic: Get formatted creation date
+     String get formattedCreatedAt {
+       final now = DateTime.now();
+       final difference = now.difference(createdAt);
+       
+       if (difference.inDays == 0) {
+         return 'Today';
+       } else if (difference.inDays == 1) {
+         return 'Yesterday';
+       } else if (difference.inDays < 7) {
+         return '${difference.inDays} days ago';
+       } else {
+         return '${createdAt.day}.${createdAt.month}.${createdAt.year}';
+       }
+     }
+     
+     /// Business logic: Validate entity
+     bool isValid() {
+       return id.isNotEmpty && 
+              title.isNotEmpty && 
+              createdAt.isBefore(DateTime.now()) &&
+              updatedAt.isAfter(createdAt);
+     }
+     
+     /// Business logic: Get entity summary
+     String getSummary() {
+       final status = isActive ? 'Active' : 'Inactive';
+       final age = isRecentlyCreated ? 'New' : 'Existing';
+       return '$age $status ${runtimeType.toString()}';
+     }
+     
+     /// Immutability: CopyWith method
+     [FeatureName]Entity copyWith({
+       String? id,
+       String? title,
+       String? description,
+       DateTime? createdAt,
+       DateTime? updatedAt,
+       bool? isActive,
+       Map<String, dynamic>? metadata,
+     }) {
+       return [FeatureName]Entity(
+         id: id ?? this.id,
+         title: title ?? this.title,
+         description: description ?? this.description,
+         createdAt: createdAt ?? this.createdAt,
+         updatedAt: updatedAt ?? this.updatedAt,
+         isActive: isActive ?? this.isActive,
+         metadata: metadata ?? this.metadata,
+       );
+     }
+     
+     /// Immutability: Update with current timestamp
+     [FeatureName]Entity withUpdatedTimestamp() {
+       return copyWith(updatedAt: DateTime.now());
+     }
+     
+     /// Business logic: Deactivate entity
+     [FeatureName]Entity deactivate() {
+       return copyWith(
+         isActive: false,
+         updatedAt: DateTime.now(),
+       );
+     }
+     
+     /// Business logic: Activate entity
+     [FeatureName]Entity activate() {
+       return copyWith(
+         isActive: true,
+         updatedAt: DateTime.now(),
+       );
+     }
+     
+     @override
+     List<Object?> get props => [
+           id,
+           title,
+           description,
+           createdAt,
+           updatedAt,
+           isActive,
+           metadata,
+         ];
+     
+     @override
+     String toString() {
+       return '[FeatureName]Entity(id: $id, title: $title, isActive: $isActive)';
+     }
+   }
+   ```
+
+2. **Add Related Entities** (if needed):
+   - Create additional entities that are part of the feature
+   - Ensure proper relationships between entities
+   - Follow the same patterns for all entities
+
+### Phase 3: Repository Interface Implementation
+
+1. **Create Repository Interface** (`lib/domain/repositories/[feature]_repository.dart`):
+   ```dart
+   import 'package:aigo/domain/models/[feature].dart';
+   
+   abstract class [FeatureName]Repository {
+     /// Get all items with optional pagination
+     Future<List<[FeatureName]>> getItems({
+       int page = 1,
+       int limit = 20,
+       bool forceRefresh = false,
+     });
+     
+     /// Get single item by ID
+     Future<[FeatureName]?> getItemById(String itemId);
+     
+     /// Create new item
+     Future<[FeatureName]> createItem({
+       required String title,
+       String? description,
+       Map<String, dynamic>? metadata,
+       Map<String, dynamic>? additionalData,
+     });
+     
+     /// Update existing item
+     Future<Either<Failure, [FeatureName]Entity>> updateItem(
+       [FeatureName]Entity item,
+     );
+     
+     /// Delete item
+     Future<Either<Failure, void>> deleteItem(String itemId);
+     
+     /// Search items by query
+     Future<Either<Failure, List<[FeatureName]Entity>>> searchItems(
+       String query, {
+       int limit = 20,
+     });
+     
+     /// Filter items by criteria
+     Future<Either<Failure, List<[FeatureName]Entity>>> filterItems({
+       bool? isActive,
+       DateTime? createdAfter,
+       DateTime? createdBefore,
+       List<String>? tags,
+       Map<String, dynamic>? customFilters,
+     });
+     
+     /// Get items by status
+     Future<Either<Failure, List<[FeatureName]Entity>>> getItemsByStatus(
+       bool isActive,
+     );
+     
+     /// Batch operations
+     Future<Either<Failure, List<[FeatureName]Entity>>> createMultipleItems(
+       List<Map<String, dynamic>> itemsData,
+     );
+     
+     Future<Either<Failure, void>> deleteMultipleItems(
+       List<String> itemIds,
+     );
+     
+     Future<Either<Failure, List<[FeatureName]Entity>>> updateMultipleItems(
+       List<[FeatureName]Entity> items,
+     );
+     
+     /// Bulk status update
+     Future<Either<Failure, void>> updateItemsStatus(
+       List<String> itemIds,
+       bool isActive,
+     );
+     
+     /// Cache management
+     Future<Either<Failure, List<[FeatureName]Entity>>> getCachedItems();
+     
+     Future<Either<Failure, void>> clearCache();
+     
+     Future<Either<Failure, void>> saveCachedItems(
+       List<[FeatureName]Entity> items,
+     );
+     
+     /// Synchronization
+     Future<Either<Failure, int>> syncWithRemote();
+     
+     Future<Either<Failure, List<[FeatureName]Entity>>> getPendingSyncItems();
+     
+     Future<Either<Failure, void>> markAsSynced(List<String> itemIds);
+     
+     /// Analytics and statistics
+     Future<Either<Failure, Map<String, dynamic>>> getStatistics();
+     
+     Future<Either<Failure, int>> getItemCount({
+       bool? isActive,
+       DateTime? createdAfter,
+     });
+     
+     /// Export/Import functionality
+     Future<Either<Failure, String>> exportItems({
+       List<String>? itemIds,
+       String format = 'json',
+     });
+     
+     Future<Either<Failure, List<[FeatureName]Entity>>> importItems(
+       String data,
+       String format = 'json',
+     );
+     
+     /// State management
+     Future<Either<Failure, void>> saveState(dynamic state);
+     
+     Future<Either<Failure, dynamic>> restoreState();
+   }
+   ```
+
+### Phase 4: Failure Types Implementation
+
+1. **Add Feature-Specific Failures** (to `lib/domain/failure/failures.dart`):
+   ```dart
+   // Add these to the existing failures.dart file
+   
+   class [FeatureName]NotFoundFailure extends Failure {
+     final String itemId;
+     
+     const [FeatureName]NotFoundFailure({
+       required this.itemId,
+       String? message,
+       StackTrace? stackTrace,
+     }) : super(
+             message: message ?? '[FeatureName] with ID $itemId not found',
+             stackTrace: stackTrace,
+           );
+     
+     @override
+     List<Object?> get props => [itemId, message, stackTrace];
+   }
+   
+   class [FeatureName]ValidationFailure extends Failure {
+     final Map<String, String> fieldErrors;
+     
+     const [FeatureName]ValidationFailure({
+       required this.fieldErrors,
+       String? message,
+       StackTrace? stackTrace,
+     }) : super(
+             message: message ?? 'Validation failed for [FeatureName]',
+             stackTrace: stackTrace,
+           );
+     
+     @override
+     List<Object?> get props => [fieldErrors, message, stackTrace];
+   }
+   
+   class [FeatureName]DuplicateFailure extends Failure {
+     final String duplicateField;
+     final String duplicateValue;
+     
+     const [FeatureName]DuplicateFailure({
+       required this.duplicateField,
+       required this.duplicateValue,
+       String? message,
+       StackTrace? stackTrace,
+     }) : super(
+             message: message ?? 
+                 'Duplicate $duplicateField: $duplicateValue already exists',
+             stackTrace: stackTrace,
+           );
+     
+     @override
+     List<Object?> get props => [duplicateField, duplicateValue, message, stackTrace];
+   }
+   
+   class [FeatureName]PermissionFailure extends Failure {
+     final String action;
+     final String resourceId;
+     
+     const [FeatureName]PermissionFailure({
+       required this.action,
+       required this.resourceId,
+       String? message,
+       StackTrace? stackTrace,
+     }) : super(
+             message: message ?? 
+                 'Permission denied for $action on resource $resourceId',
+             stackTrace: stackTrace,
+           );
+     
+     @override
+     List<Object?> get props => [action, resourceId, message, stackTrace];
+   }
+   ```
+
+### Phase 5: Business Logic Enhancement
+
+1. **Add Advanced Entity Methods**:
+   ```dart
+   // Add to entity class
+   
+   /// Business logic: Compare entities
+   int compareTo([FeatureName]Entity other) {
+     // Primary sort by creation date (newest first)
+     var comparison = other.createdAt.compareTo(createdAt);
+     if (comparison != 0) return comparison;
+     
+     // Secondary sort by title
+     comparison = title.compareTo(other.title);
+     if (comparison != 0) return comparison;
+     
+     // Tertiary sort by ID for consistency
+     return id.compareTo(other.id);
+   }
+   
+   /// Business logic: Check if entity matches search query
+   bool matchesQuery(String query) {
+     final lowerQuery = query.toLowerCase();
+     return title.toLowerCase().contains(lowerQuery) ||
+            (description?.toLowerCase().contains(lowerQuery) ?? false);
+   }
+   
+   /// Business logic: Get entity tags from metadata
+   List<String> get tags {
+     if (metadata == null) return [];
+     final tagsData = metadata!['tags'];
+     if (tagsData is List) {
+       return tagsData.map((tag) => tag.toString()).toList();
+     }
+     return [];
+   }
+   
+   /// Business logic: Add tag to entity
+   [FeatureName]Entity addTag(String tag) {
+     final currentTags = tags;
+     if (currentTags.contains(tag)) return this;
+     
+     final newTags = [...currentTags, tag];
+     final newMetadata = Map<String, dynamic>.from(metadata ?? {});
+     newMetadata['tags'] = newTags;
+     
+     return copyWith(
+       metadata: newMetadata,
+       updatedAt: DateTime.now(),
+     );
+   }
+   
+   /// Business logic: Remove tag from entity
+   [FeatureName]Entity removeTag(String tag) {
+     final currentTags = tags;
+     if (!currentTags.contains(tag)) return this;
+     
+     final newTags = currentTags.where((t) => t != tag).toList();
+     final newMetadata = Map<String, dynamic>.from(metadata ?? {});
+     newMetadata['tags'] = newTags;
+     
+     return copyWith(
+       metadata: newMetadata,
+       updatedAt: DateTime.now(),
+     );
+   }
+   ```
+
+2. **Add Value Objects** (if complex data structures needed):
+   ```dart
+   // Create separate value object files if needed
+   // Example: [feature]_settings.dart, [feature]_configuration.dart
+   ```
+
+### Phase 6: Domain Services (if needed)
+
+1. **Create Domain Service** (`lib/domain/services/[feature]_domain_service.dart`):
+   ```dart
+   abstract class [FeatureName]DomainService {
+     /// Business logic: Validate business rules
+     bool validateBusinessRules([FeatureName]Entity entity);
+     
+     /// Business logic: Calculate derived data
+     Map<String, dynamic> calculateMetrics(List<[FeatureName]Entity> entities);
+     
+     /// Business logic: Apply business transformations
+     [FeatureName]Entity applyBusinessRules([FeatureName]Entity entity);
+   }
+   ```
+
+## Quality Checklist
+
+### Entity Design
+- [ ] Pure domain objects (no framework dependencies)
+- [ ] Immutable with copyWith methods
+- [ ] Rich business logic methods
+- [ ] Proper Equatable implementation
+- [ ] Clear toString implementation
+
+### Repository Interface
+- [ ] Comprehensive CRUD operations
+- [ ] Either return types for all methods
+- [ ] Proper failure handling
+- [ ] Caching and synchronization support
+- [ ] Batch operations included
+
+### Business Logic
+- [ ] Domain rules implemented in entities
+- [ ] Validation logic present
+- [ ] Business calculations included
+- [ ] Entity relationships defined
+- [ ] Value objects for complex data
+
+### Error Handling
+- [ ] Feature-specific failure types
+- [ ] Meaningful error messages
+- [ ] Proper failure inheritance
+- [ ] Rich error context provided
+
+## Channel Communication
+
+### Before Starting
+Update channel.md:
+```markdown
+### 🏗️ Domain 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 and unblock data layer:
+```markdown
+### 🏗️ Domain Layer Status
+- **Status:** COMPLETED
+- **Progress:** 100%
+- **Files Created:** [COMPLETE_LIST]
+
+### 💾 Data Layer Status
+- **Blockers:** [] (UNBLOCKED)
+```
+
+## Dependencies
+
+### Must be completed first:
+- Architecture analysis
+
+### Can work in parallel with:
+- Business logic layer (with coordination)
+- UI layer (with coordination)
+
+### Enables after completion:
+- Data layer implementation
+- Full business logic integration
+
+## Output Deliverables
+
+1. **Entity**: `lib/domain/entities/[feature]_entity.dart`
+2. **Repository Interface**: `lib/domain/repositories/[feature]_repository.dart`
+3. **Failure Types**: Updated `lib/domain/failure/failures.dart`
+4. **Domain Service** (if needed): `lib/domain/services/[feature]_domain_service.dart`
+5. **Updated Channel**: Progress and completion status in channel.md
+
+All domain components must be pure Dart classes, framework-independent, and contain rich business logic following AiGo's clean architecture principles. No external dependencies like Equatable, Freezed, or Either - keep domain layer completely pure.