appiq-solution 1.4.8 → 1.5.0

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

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