Use Case Documentation

Overview

This document outlines the business logic and use case implementations for the Product Management module. All use cases follow Clean Architecture principles with CQRS pattern implementation, comprehensive permission validation, and event-driven architecture for system integration.

Table of Contents

1. Product Use Cases

2. Product Tag Use Cases

3. Product Image Use Cases

4. CQRS Implementation

5. Permission System

6. Event Publishing

7. Error Handling

8. Business Rules

Product Use Cases

CreateProductUseCase

File: common/module/product/product/usecases/create-product.usecase.ts

Creates a new product with comprehensive validation and permission checks.

Implementation

export class CreateProductUseCase implements IUseCase<CreateProductParams, ProductDto> {
  @Inject()
  private readonly commandBus: CommandBus;

  @Inject()
  private readonly queryBus: QueryBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(CreateProductUseCase.name);

  public async execute({ ctx, product }: CreateProductParams): Promise<ProductDto> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.CREATE_PRODUCT],
    });

    // 2. Execute create command through CQRS
    const createdProductId = await this.commandBus.execute(
      new AddProductCommand(ctx.tenantId, product)
    );

    // 3. Return populated product data
    return this.queryBus.execute(
      new GetProductByIdQuery(ctx.tenantId, createdProductId)
    );
  }
}

Business Logic Flow

1. Permission Validation: Validates user has CREATE_PRODUCT permission

2. Command Execution: Dispatches AddProductCommand through command bus

3. Data Retrieval: Queries created product with populated relationships

4. Event Publishing: Automatic event publishing for product creation

5. Response: Returns complete product DTO with all related data

Key Features

• Permission-based Access Control: Validates user permissions before execution

• CQRS Pattern: Separates command (create) from query (read) operations

• Event-Driven: Publishes events for system integration and auditing

• Transaction Management: Ensures data consistency across operations

• Comprehensive Logging: Tracks all operations for debugging and auditing

Business Rules

• User must have CREATE_PRODUCT permission

• Product SKU must be unique within tenant

• At least one language version is required

• Price information is mandatory

• Tags must exist in the system before assignment

GetProductUseCase

File: common/module/product/product/usecases/get-product.usecase.ts

Retrieves a specific product by ID with permission validation.

Implementation

export class GetProductUseCase implements IUseCase<GetProductParams, ProductDto> {
  @Inject()
  private readonly queryBus: QueryBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(GetProductUseCase.name);

  public async execute({ ctx, productId }: GetProductParams): Promise<ProductDto> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.READ_PRODUCT],
    });

    // 2. Execute query with populated data
    return this.queryBus.execute(
      new GetProductByIdQuery(ctx.tenantId, productId)
    );
  }
}

Business Logic Flow

1. Permission Validation: Validates user has READ_PRODUCT permission

2. Query Execution: Retrieves product with populated relationships

3. Data Enrichment: Includes images, tag details, and metadata

4. Response: Returns complete product information

Key Features

• Efficient Data Loading: Optimized queries with relationship population

• Permission Enforcement: Ensures data access security

• Cache Integration: Utilizes caching for frequently accessed products

• Error Handling: Proper error handling for non-existent products

GetPagedProductsUseCase

File: common/module/product/product/usecases/get-paged-products.usecase.ts

Retrieves paginated list of products with advanced filtering capabilities.

Implementation

export class GetPagedProductsUseCase implements IUseCase<GetPagedProductsParams, any> {
  @Inject()
  private readonly queryBus: QueryBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(GetPagedProductsUseCase.name);

  public async execute({ ctx, pagination }: GetPagedProductsParams): Promise<any> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.READ_PRODUCT],
    });

    // 2. Execute paginated query with filtering
    return this.queryBus.execute(
      new GetPagedProductsQuery(ctx.tenantId, pagination)
    );
  }
}

Business Logic Flow

1. Permission Validation: Validates user has READ_PRODUCT permission

2. Query Construction: Builds complex query with filters and pagination

3. Search Execution: Performs text search across multiple language versions

4. Tag Filtering: Applies tag-based filtering with array matching

5. Result Pagination: Returns paginated results with metadata

Advanced Features

• Multi-language Search: Searches across all language versions

• Tag Filtering: Supports multiple tag filtering with AND/OR logic

• Text Search: Full-text search across titles and descriptions

• Performance Optimization: Efficient database queries with proper indexing

• Cache Integration: Caches frequently accessed product lists

Filtering Capabilities

• Text Search: Phrase-based search across product content

• Tag Filtering: Filter by one or more product tags

• Pagination: Configurable page size and navigation

• Sorting: Support for various sorting criteria

UpdateProductUseCase

File: common/module/product/product/usecases/update-product.usecase.ts

Updates an existing product with validation and change tracking.

Implementation

export class UpdateProductUseCase implements IUseCase<UpdateProductParams, ProductDto> {
  @Inject()
  private readonly commandBus: CommandBus;

  @Inject()
  private readonly queryBus: QueryBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(UpdateProductUseCase.name);

  public async execute({ ctx, productId, product }: UpdateProductParams): Promise<ProductDto> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.EDIT_PRODUCT],
    });

    // 2. Execute update command
    await this.commandBus.execute(
      new UpdateProductCommand(ctx.tenantId, productId, product)
    );

    // 3. Return updated product data
    return this.queryBus.execute(
      new GetProductByIdQuery(ctx.tenantId, productId)
    );
  }
}

Business Logic Flow

1. Permission Validation: Validates user has EDIT_PRODUCT permission

2. Existence Check: Verifies product exists and is accessible

3. Change Validation: Validates proposed changes against business rules

4. Command Execution: Applies changes through command pattern

5. Event Publishing: Publishes update events for system integration

6. Response: Returns updated product with fresh data

Business Rules for Updates

• SKU cannot be modified after creation

• At least one language version must remain

• Price changes are tracked for audit purposes

• Tag assignments are validated for existence

• Image references are validated for accessibility

DeleteProductUseCase

File: common/module/product/product/usecases/delete-product.usecase.ts

Performs soft deletion of products with dependency validation.

Implementation

export class DeleteProductUseCase implements IUseCase<DeleteProductParams, void> {
  @Inject()
  private readonly commandBus: CommandBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(DeleteProductUseCase.name);

  public async execute({ ctx, productId }: DeleteProductParams): Promise<void> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.DELETE_PRODUCT],
    });

    // 2. Execute delete command with dependency checking
    return this.commandBus.execute(
      new DeleteProductCommand(ctx.tenantId, productId)
    );
  }
}

Business Logic Flow

1. Permission Validation: Validates user has DELETE_PRODUCT permission

2. Dependency Check: Verifies no active orders reference the product

3. Soft Delete: Marks product as deleted while preserving data

4. Cascade Operations: Handles related data (images, references)

5. Event Publishing: Publishes deletion events for cleanup

6. Audit Logging: Records deletion for compliance and tracking

Dependency Validation

• Checks for active orders containing the product

• Validates no pending reservations reference the product

• Ensures data integrity across the system

• Prevents deletion of products with financial implications

Product Tag Use Cases

CreateProductTagUseCase

File: common/module/product/tag/usecases/create-product-tag.usecase.ts

Creates new product tags for categorization and filtering.

Implementation

export class CreateProductTagUseCase implements IUseCase<CreateProductTagParams, TagDto> {
  @Inject()
  private readonly commandBus: CommandBus;

  @Inject()
  private readonly queryBus: QueryBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(CreateProductTagUseCase.name);

  public async execute({ ctx, tag }: CreateProductTagParams): Promise<TagDto> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.CREATE_PRODUCT_TAG],
    });

    // 2. Execute create command
    const createdTagId = await this.commandBus.execute(
      new AddProductTagCommand(ctx.tenantId, tag)
    );

    // 3. Return created tag
    return this.queryBus.execute(
      new GetProductTagByIdQuery(ctx.tenantId, createdTagId)
    );
  }
}

Business Logic Flow

1. Permission Validation: Validates user has CREATE_PRODUCT_TAG permission

2. Uniqueness Check: Ensures tag name is unique within tenant

3. Command Execution: Creates tag through command pattern

4. Response: Returns created tag with generated ID

Tag Creation Rules

• Tag names must be unique within tenant

• Tag names are case-insensitive

• Special characters are validated and sanitized

• Maximum length constraints are enforced

GetPagedProductTagsUseCase

File: common/module/product/tag/usecases/get-paged-product-tags.usecase.ts

Retrieves paginated list of product tags with search functionality.

Implementation

export class GetPagedProductTagsUseCase implements IUseCase<GetPagedProductTagsParams, any> {
  @Inject()
  private readonly queryBus: QueryBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(GetPagedProductTagsUseCase.name);

  public async execute({ ctx, pagination }: GetPagedProductTagsParams): Promise<any> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.READ_PRODUCT_TAG],
    });

    // 2. Execute paginated query
    return this.queryBus.execute(
      new GetPagedProductTagsQuery(ctx.tenantId, pagination)
    );
  }
}

Features

• Search functionality for tag names

• Efficient pagination for large tag lists

• Usage statistics for each tag

• Sorting by name, creation date, or usage frequency

UpdateProductTagUseCase

File: common/module/product/tag/usecases/update-product-tag.usecase.ts

Updates existing product tags with validation.

Business Logic

1. Permission Validation: Validates EDIT_PRODUCT_TAG permission

2. Uniqueness Check: Ensures updated name doesn't conflict

3. Usage Validation: Checks if tag is currently in use

4. Update Propagation: Updates all products using the tag

5. Cache Invalidation: Clears relevant caches

DeleteProductTagUseCase

File: common/module/product/tag/usecases/delete-product-tag.usecase.ts

Deletes product tags with usage validation.

Business Logic

1. Permission Validation: Validates DELETE_PRODUCT_TAG permission

2. Usage Check: Prevents deletion of tags in use

3. Cascade Options: Offers tag removal from products or prevention

4. Audit Logging: Records tag deletion activities

Product Image Use Cases

UpsertProductImageUseCase

File: common/module/product/product/usecases/upsert-product-image.usecase.ts

Handles product image upload and management operations.

Implementation

export class UpsertProductImageUseCase implements IUseCase<UpsertProductImageParams, MediaDto> {
  @Inject()
  private readonly commandBus: CommandBus;

  @Inject()
  private readonly queryBus: QueryBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(UpsertProductImageUseCase.name);

  public async execute({ ctx, productId, media, file }: UpsertProductImageParams): Promise<MediaDto> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.EDIT_PRODUCT],
    });

    // 2. File validation and processing
    const processedFile = await this.validateAndProcessImage(file);

    // 3. Execute image upsert command
    const imageId = await this.commandBus.execute(
      new UpsertProductImageCommand(ctx.tenantId, productId, media, processedFile)
    );

    // 4. Return media information
    return this.queryBus.execute(
      new GetMediaByIdQuery(ctx.tenantId, imageId)
    );
  }

  private async validateAndProcessImage(file: Express.Multer.File): Promise<ProcessedFile> {
    // File type validation
    if (!this.isValidImageType(file.mimetype)) {
      throw new UnsupportedMediaTypeException('Only JPEG, PNG, and WebP images are supported');
    }

    // File size validation
    if (file.size > MAX_IMAGE_SIZE) {
      throw new PayloadTooLargeException('Image file size exceeds 5MB limit');
    }

    // Image processing (resize, optimize, generate thumbnails)
    return this.imageProcessor.process(file);
  }
}

Business Logic Flow

1. Permission Validation: Validates user has EDIT_PRODUCT permission

2. File Validation: Checks file type, size, and format

3. Image Processing: Resizes, optimizes, and generates thumbnails

4. Upload to CDN: Stores image in CDN with proper naming

5. Database Update: Links image to product in database

6. Cache Invalidation: Clears product caches

7. Response: Returns media information with CDN URLs

Image Processing Features

• Format Validation: Supports JPEG, PNG, and WebP formats

• Size Optimization: Automatic compression and optimization

• Thumbnail Generation: Creates multiple size variants

• CDN Integration: Direct upload to content delivery network

• Metadata Extraction: Extracts image dimensions and properties

DeleteProductImageUseCase

File: common/module/product/product/usecases/delete-product-image.usecase.ts

Handles product image deletion with cleanup.

Implementation

export class DeleteProductImageUseCase implements IUseCase<DeleteProductImageParams, void> {
  @Inject()
  private readonly commandBus: CommandBus;

  @Inject()
  private readonly permissionValidator: PermissionValidatorUseCase;

  private readonly logger = new Logger(DeleteProductImageUseCase.name);

  public async execute({ ctx, productId, id }: DeleteProductImageParams): Promise<void> {
    // 1. Permission validation
    await this.permissionValidator.execute({
      actor: ctx.actor,
      requiredPermissions: [ModulePermissionEnum.EDIT_PRODUCT],
    });

    // 2. Execute delete command with cleanup
    return this.commandBus.execute(
      new DeleteProductImageCommand(ctx.tenantId, productId, id)
    );
  }
}

Business Logic Flow

1. Permission Validation: Validates user has EDIT_PRODUCT permission

2. Image Verification: Confirms image belongs to specified product

3. CDN Cleanup: Removes image files from CDN

4. Database Cleanup: Removes image references from product

5. Cache Invalidation: Clears relevant caches

6. Audit Logging: Records image deletion activity

CQRS Implementation

Command Pattern

The product management module implements CQRS (Command Query Responsibility Segregation) for clear separation of read and write operations.

Commands

• AddProductCommand: Creates new products

• UpdateProductCommand: Modifies existing products

• DeleteProductCommand: Soft deletes products

• UpsertProductImageCommand: Manages product images

• AddProductTagCommand: Creates product tags

Queries

• GetProductByIdQuery: Retrieves single product

• GetPagedProductsQuery: Retrieves paginated product lists

• GetProductTagByIdQuery: Retrieves single tag

• GetPagedProductTagsQuery: Retrieves paginated tag lists

Command Handlers

Each command has a dedicated handler that implements the business logic:

@CommandHandler(AddProductCommand)
export class AddProductCommandHandler implements ICommandHandler<AddProductCommand> {
  constructor(
    @Inject('IProductRepository')
    private readonly productRepository: IProductRepository,
    private readonly eventBus: EventBus
  ) {}

  async execute(command: AddProductCommand): Promise<string> {
    // 1. Validate business rules
    await this.validateProductCreation(command.product);

    // 2. Create product entity
    const product = await this.productRepository.createProduct(command.product);

    // 3. Publish domain events
    await this.eventBus.publish(new ProductCreatedEvent(product));

    return product._id;
  }
}

Query Handlers

Query handlers focus on data retrieval and optimization:

@QueryHandler(GetPagedProductsQuery)
export class GetPagedProductsQueryHandler implements IQueryHandler<GetPagedProductsQuery> {
  constructor(
    @Inject('IProductRepository')
    private readonly productRepository: IProductRepository,
    private readonly cacheService: CacheService
  ) {}

  async execute(query: GetPagedProductsQuery): Promise<PaginationResultValue<ProductDto>> {
    // 1. Check cache first
    const cacheKey = this.buildCacheKey(query);
    const cached = await this.cacheService.get(cacheKey);
    if (cached) return cached;

    // 2. Execute database query
    const result = await this.productRepository.searchProductsWithCriteria(query.criteria);

    // 3. Cache result
    await this.cacheService.set(cacheKey, result, CACHE_TTL);

    return result;
  }
}

Permission System

Permission-Based Access Control

All use cases implement comprehensive permission validation:

interface PermissionValidationParams {
  actor: {
    _id: string;
    permissions: string[];
    roles: string[];
  };
  requiredPermissions: ModulePermissionEnum[];
}

Permission Hierarchy

// Permission levels for products
const PRODUCT_PERMISSIONS = {
  CRUD_PRODUCT: 11000,      // All operations
  READ_PRODUCT: 11001,      // View only
  CREATE_PRODUCT: 11002,    // Create new
  EDIT_PRODUCT: 11003,      // Modify existing
  DELETE_PRODUCT: 11004     // Remove products
};

// Permission levels for tags
const TAG_PERMISSIONS = {
  CRUD_PRODUCT_TAG: 12000,  // All tag operations
  READ_PRODUCT_TAG: 12001,  // View tags
  CREATE_PRODUCT_TAG: 12002,// Create tags
  EDIT_PRODUCT_TAG: 12003,  // Modify tags
  DELETE_PRODUCT_TAG: 12004 // Delete tags
};

Multi-Tenant Security

• Tenant Isolation: All operations are scoped to specific tenants

• Data Segregation: Database queries include tenant filtering

• Permission Scoping: Permissions are validated within tenant context

• Audit Trails: All operations are logged with tenant and user context

Event Publishing

Domain Events

The system publishes events for integration and auditing:

// Product lifecycle events
interface ProductCreatedEvent {
  type: 'ProductCreated';
  tenantId: string;
  productId: string;
  product: ProductDto;
  createdBy: string;
  timestamp: Date;
}

interface ProductUpdatedEvent {
  type: 'ProductUpdated';
  tenantId: string;
  productId: string;
  changes: Partial<ProductDto>;
  updatedBy: string;
  timestamp: Date;
}

interface ProductDeletedEvent {
  type: 'ProductDeleted';
  tenantId: string;
  productId: string;
  deletedBy: string;
  timestamp: Date;
}

Event Handlers

External modules can subscribe to product events:

@EventsHandler(ProductCreatedEvent)
export class ProductCreatedEventHandler implements IEventHandler<ProductCreatedEvent> {
  async handle(event: ProductCreatedEvent) {
    // Update search indexes
    await this.searchService.indexProduct(event.product);
    
    // Send notifications
    await this.notificationService.notifyProductCreated(event);
    
    // Update analytics
    await this.analyticsService.trackProductCreation(event);
  }
}

Error Handling

Exception Types

The system defines specific exceptions for different error scenarios:

// Business logic exceptions
class ProductNotFoundException extends NotFoundException {
  constructor(productId: string) {
    super(`Product with ID ${productId} not found`);
  }
}

class ProductAlreadyExistsException extends ConflictException {
  constructor(sku: string) {
    super(`Product with SKU ${sku} already exists`);
  }
}

class InvalidProductDataException extends BadRequestException {
  constructor(errors: ValidationError[]) {
    super('Product validation failed', errors);
  }
}

// File handling exceptions
class UnsupportedImageTypeException extends UnsupportedMediaTypeException {
  constructor(supportedTypes: string[]) {
    super(`Unsupported image type. Supported: ${supportedTypes.join(', ')}`);
  }
}

class ImageTooLargeException extends PayloadTooLargeException {
  constructor(maxSize: number) {
    super(`Image size exceeds maximum limit of ${maxSize}MB`);
  }
}

Error Recovery

Use cases implement proper error handling and recovery:

public async execute(params: CreateProductParams): Promise<ProductDto> {
  try {
    // Business logic execution
    return await this.performOperation(params);
  } catch (error) {
    // Log error with context
    this.logger.error('Product creation failed', {
      error: error.message,
      stack: error.stack,
      params: this.sanitizeParams(params)
    });

    // Publish error event for monitoring
    await this.eventBus.publish(new ProductOperationFailedEvent(error, params));

    // Re-throw with proper classification
    throw this.classifyError(error);
  }
}

Business Rules

Product Management Rules

Creation Rules

1. SKU Uniqueness: Product SKU must be unique within tenant

2. Language Requirements: At least one language version required

3. Price Validation: Price must be positive with valid currency

4. Tag Validation: All referenced tags must exist

5. Image Limits: Maximum 10 images per product

Update Rules

1. SKU Immutability: SKU cannot be changed after creation

2. Language Preservation: Cannot remove all language versions

3. Active Order Protection: Cannot modify products in active orders

4. Price History: All price changes are tracked for audit

5. Tag Synchronization: Tag updates propagate to all using products

Deletion Rules

1. Soft Delete Only: Products are never physically deleted

2. Dependency Validation: Cannot delete products with active references

3. Order Protection: Products in orders cannot be deleted

4. Audit Preservation: All historical data is maintained

5. Cascade Management: Related images and references are handled

Tag Management Rules

Tag Creation

1. Name Uniqueness: Tag names must be unique within tenant

2. Character Validation: Only alphanumeric and specific special characters

3. Length Limits: Tag names have maximum length constraints

4. Case Insensitivity: Tag names are treated case-insensitively

Tag Usage

1. Referential Integrity: Cannot delete tags in use by products

2. Bulk Operations: Support for efficient bulk tag management

3. Usage Tracking: Track which products use which tags

4. Search Optimization: Tags are indexed for fast filtering

Image Management Rules

Upload Constraints

1. File Types: Only JPEG, PNG, and WebP formats supported

2. Size Limits: Maximum 5MB per image file

3. Dimension Limits: Reasonable minimum and maximum dimensions

4. Count Limits: Maximum 10 images per product

5. Quality Standards: Automatic optimization and compression

Processing Rules

1. Format Conversion: Images may be converted for optimization

2. Thumbnail Generation: Multiple size variants created automatically

3. CDN Integration: Images stored in CDN for global access

4. Metadata Extraction: Image properties extracted and stored

5. Progressive Loading: Support for progressive image loading

Performance Optimization Rules

Caching Strategy

1. Product Data: Frequently accessed products are cached

2. Search Results: Common search results are cached

3. Tag Lists: Tag collections are heavily cached

4. Image URLs: CDN URLs are cached for fast access

5. Cache Invalidation: Smart cache invalidation on updates

Database Optimization

1. Indexing Strategy: Comprehensive indexing for all query patterns

2. Query Optimization: Efficient queries with proper field selection

3. Relationship Loading: Optimized loading of related data

4. Pagination Efficiency: Efficient pagination for large datasets

5. Search Performance: Text search optimization with proper indexes

This use case documentation provides a comprehensive guide to the business logic, implementation patterns, and rules governing the Product Management module, ensuring consistent and reliable operation across all product-related operations.