Use Case Documentation

Overview

The service management module implements comprehensive business logic for managing bookable services within the Bee O'clock platform. The module follows Clean Architecture principles and CQRS pattern to separate command and query responsibilities while maintaining clear business logic boundaries.

Core Use Cases

1. Get Paged Services Use Case

Purpose: Retrieves a paginated list of services for a tenant with optional search and filtering capabilities.

Location: GetPagedServicesUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • pagination: ServicePaginationDto - Pagination and search parameters

Business Logic:

  1. Validates actor permissions (READ_SERVICE)

  2. Applies search phrase filtering if provided

  3. Executes paginated query through CQRS query bus

  4. Returns paginated result with services and metadata

Search Functionality:

  • Searches across service titles and descriptions

  • Supports multilingual content search

  • Case-insensitive phrase matching

  • Efficient indexing for performance

Output: PaginationResponseDto<ServiceDto>

2. Get Service by ID Use Case

Purpose: Retrieves detailed information about a specific service including all configuration and presentation data.

Location: GetServiceUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • serviceId: string - Unique identifier of the service

Business Logic:

  1. Validates actor permissions (READ_SERVICE)

  2. Retrieves service from repository through query bus

  3. Throws ServiceNotFoundException if service not found

  4. Returns complete service data with all related information

Data Population:

  • Populates language versions

  • Includes duration and pricing options

  • Loads presentation media

  • Includes scheduling information

Output: ServiceDto

3. Create Service Use Case

Purpose: Creates a new service with comprehensive validation and configuration setup.

Location: CreateServiceUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • service: ServiceDto - Service data to create

Business Logic:

  1. Validates actor permissions (CREATE_SERVICE)

  2. Validates service data structure and content

  3. Ensures language versions are provided

  4. Validates duration versions and pricing

  5. Checks business rules compliance

  6. Creates service through command bus

  7. Publishes service created event

  8. Returns created service ID

Validation Rules:

  • At least one language version required

  • Valid duration and pricing configuration

  • Proper color format validation

  • Media file format validation

  • Business-specific constraints

Event Publishing:

  • Emits ServiceCreatedEvent for downstream processing

  • Triggers cache invalidation

  • Notifies integration systems

Output: string (Service ID)

4. Update Service Use Case

Purpose: Updates an existing service with comprehensive validation and change tracking.

Location: UpdateServiceUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • serviceId: string - ID of service to update

  • update: ServiceDto - Updated service data

Business Logic:

  1. Validates actor permissions (EDIT_SERVICE)

  2. Retrieves existing service for comparison

  3. Validates update data and business rules

  4. Ensures critical data integrity

  5. Executes update through command bus

  6. Publishes service updated event

  7. Handles cache invalidation

Update Validation:

  • Cannot remove all language versions

  • Cannot remove all duration versions

  • Validates pricing changes

  • Ensures media consistency

  • Checks scheduling conflicts

Change Tracking:

  • Maintains audit trail

  • Tracks field-level changes

  • Preserves historical data

  • Enables rollback capabilities

Output: void

5. Delete Service Use Case

Purpose: Safely deletes a service with comprehensive validation and dependency checking.

Location: DeleteServiceUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • serviceId: string - ID of service to delete

Business Logic:

  1. Validates actor permissions (DELETE_SERVICE)

  2. Checks service exists

  3. Validates no active orders reference service

  4. Validates no active appointments

  5. Performs soft delete (archive)

  6. Publishes service deleted event

  7. Handles cleanup of related data

Safety Validations:

  • Cannot delete services with active bookings

  • Cannot delete services referenced in orders

  • Cannot delete services with pending payments

  • Validates business continuity

Cleanup Process:

  • Archives service data

  • Maintains historical references

  • Cleans up caches

  • Notifies dependent systems

Output: { deletedCount: number }

6. Update Service Banners Use Case

Purpose: Manages service banner images and media presentation.

Location: UpdateServiceBannersUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • serviceId: string - ID of service to update

  • media: any - Media metadata

  • file: Express.Multer.File - Uploaded image file

Business Logic:

  1. Validates actor permissions (CREATE_SERVICE)

  2. Validates file format and size

  3. Processes image upload

  4. Updates service presentation

  5. Optimizes images for different sizes

  6. Updates service media references

File Processing:

  • Validates image formats (JPEG, PNG, WebP)

  • Enforces file size limits

  • Generates thumbnails

  • Optimizes for web delivery

  • Handles storage integration

Output: MediaDto (uploaded media information)

7. Delete Service Banner Use Case

Purpose: Removes specific banner images from service presentation.

Location: DeleteServiceBannerUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • serviceId: string - ID of service

  • bannerId: string - ID of banner to delete

Business Logic:

  1. Validates actor permissions (CREATE_SERVICE)

  2. Validates banner exists for service

  3. Removes banner from service presentation

  4. Deletes media files from storage

  5. Updates service presentation data

Storage Cleanup:

  • Removes files from storage

  • Cleans up thumbnails

  • Updates CDN references

  • Maintains data consistency

Output: { deletedCount: number }

8. Update Service Required Resources Use Case

Purpose: Manages resource requirements for service delivery.

Location: UpdateServiceRequiredResourcesUseCase

Input Parameters:

  • ctx: TenantActorContext - Context with tenant and actor information

  • serviceId: string - ID of service

  • requiredResources: RequiredResourceDto[] - Resource requirements

Business Logic:

  1. Validates actor permissions (EDIT_SERVICE)

  2. Validates resource references exist

  3. Validates resource quantities

  4. Updates service resource requirements

  5. Handles resource availability checking

Resource Validation:

  • Ensures resources exist in system

  • Validates quantity requirements

  • Checks resource availability

  • Validates business constraints

Output: void

Permission Requirements

All service management use cases require specific permissions validated through PermissionValidatorUseCase:

  • READ_SERVICE: Required for viewing services

  • CREATE_SERVICE: Required for creating services and managing media

  • EDIT_SERVICE: Required for updating services and resources

  • DELETE_SERVICE: Required for deleting services

Error Handling

Common Exceptions

  • ServiceNotFoundException: When service ID doesn't exist

  • ServiceCreationException: When service creation validation fails

  • ServiceUpdationException: When service update validation fails

  • ServiceDeletionException: When service cannot be deleted

  • MediaUploadException: When media upload fails

  • ResourceNotFoundException: When required resource doesn't exist

Error Response Pattern

All use cases follow consistent error handling:

  1. Log errors with context and stack trace

  2. Preserve original error for debugging

  3. Throw domain-specific exceptions

  4. Handle transaction rollback automatically

  5. Provide meaningful error messages

Business Rules

Service Creation Rules

  1. Language Requirements: At least one language version mandatory

  2. Duration Configuration: Valid duration and pricing required

  3. Presentation: Color format validation and media constraints

  4. Scheduling: Schedule validation and conflict checking

  5. Resource Requirements: Valid resource references

Service Update Rules

  1. Data Integrity: Cannot remove all language/duration versions

  2. Active Bookings: Cannot modify services with active appointments

  3. Pricing Changes: Proper validation for price updates

  4. Media Management: File format and size validation

  5. Resource Updates: Availability and constraint checking

Service Deletion Rules

  1. Dependency Checking: Cannot delete services with active references

  2. Soft Delete: Services are archived, not physically removed

  3. Data Preservation: Historical data maintained for reporting

  4. Cleanup Process: Proper cleanup of related data

Media Management Rules

  1. File Formats: Only JPEG, PNG, WebP allowed

  2. File Size: Maximum 10MB per file

  3. Image Processing: Automatic optimization and thumbnail generation

  4. Storage Management: Efficient storage and CDN integration

Integration Points

Event Publishing

  • ServiceCreatedEvent: Published when service is created

  • ServiceUpdatedEvent: Published when service is updated

  • ServiceDeletedEvent: Published when service is deleted

  • MediaUploadedEvent: Published when media is uploaded

Cache Management

  • Automatic cache invalidation on mutations

  • Cache keys: GET_SERVICE, GET_PAGED_SERVICES, GET_PUBLIC_SERVICES

  • Uses distributed caching for performance

  • TTL-based cache expiration

External Services

  • Storage Service: For media file management

  • Image Processing: For thumbnail generation

  • CDN Integration: For media delivery optimization

  • Search Service: For enhanced search capabilities

Performance Considerations

Query Optimization

  • Indexed searches for pagination

  • Efficient phrase search implementation

  • Optimized loading of related data

  • Proper query result caching

Media Processing

  • Asynchronous image processing

  • Multiple size generation

  • Efficient storage utilization

  • CDN integration for delivery

Caching Strategy

  • Multi-level caching approach

  • Cache warming for popular services

  • Intelligent cache invalidation

  • Performance monitoring

Testing Strategy

Unit Tests

  • Mock all external dependencies

  • Test business logic in isolation

  • Cover all error scenarios

  • Validate permission checks

  • Test validation rules

Integration Tests

  • Test with real database

  • Validate transaction behavior

  • Test event publishing

  • Cache integration testing

  • Media upload testing

End-to-End Tests

  • Full workflow testing

  • API endpoint validation

  • File upload and processing

  • Permission integration testing

  • Performance benchmarking

Monitoring and Observability

Metrics Collection

  • Use case execution times

  • Error rates and types

  • Cache hit ratios

  • Media processing metrics

  • Resource utilization

Logging Strategy

  • Structured logging with correlation IDs

  • Business event logging

  • Error tracking with context

  • Performance monitoring

  • Security audit logging

Health Checks

  • Database connectivity

  • Storage service availability

  • Cache system health

  • External service dependencies

  • Business rule validation

Future Enhancements

Planned Features

  1. Advanced Search: Elasticsearch integration for complex queries

  2. AI Recommendations: Machine learning for service suggestions

  3. Dynamic Pricing: Time-based and demand-based pricing

  4. Service Templates: Reusable service configuration templates

  5. Bulk Operations: Mass service management capabilities

Technical Improvements

  1. Event Sourcing: Complete audit trail with event streams

  2. Microservice Split: Separate media and core service management

  3. GraphQL API: Enhanced query capabilities

  4. Real-time Updates: WebSocket integration for live updates

  5. Advanced Analytics: Service performance and usage analytics

Security Considerations

Data Protection

  • PII handling in service descriptions

  • Secure media storage and access

  • Role-based access control

  • Audit logging for compliance

Input Validation

  • Comprehensive validation rules

  • SQL injection prevention

  • File upload security

  • Cross-site scripting protection

Business Logic Security

  • Permission validation at use case level

  • Resource access validation

  • Multi-tenant data isolation

  • Rate limiting and abuse prevention

PreviousInterface DocumentationNextDatabase Schema

Last updated

Was this helpful?