> For the complete documentation index, see [llms.txt](https://docs.beeoclock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beeoclock.com/services/business-profile/usecase.md).

# Use Case Documentation

## Overview

This document describes the business use cases and application layer logic for the Business Profile Management module. Each use case encapsulates business rules, permissions, and orchestrates the interaction between domain entities, repositories, media services, and external integrations.

## Architecture Pattern

The module follows the CQRS (Command Query Responsibility Segregation) pattern with the following structure:

* **Use Cases**: Application layer orchestrating business logic
* **Commands**: Write operations (Create, Update, Media Operations)
* **Queries**: Read operations (Get Profile, Get Settings)
* **Domain Entities**: Business logic and validation
* **Value Objects**: Settings and configuration objects
* **Media Management**: File upload and storage operations

## Core Use Cases

### 1. GetBusinessProfileUseCase

**Purpose:** Retrieves the complete business profile for the authenticated tenant.

**Input:** `GetBusinessProfileParams`

```typescript
{
  ctx: TenantActorContext
}
```

**Output:** `BusinessProfileDto`

**Business Rules:**

1. User must have `READ_BUSINESS_PROFILE` permission
2. Returns null if profile not found or access denied
3. Profile includes all related media assets
4. Populates nested settings objects

**Process Flow:**

1. Validate user permissions using `PermissionValidatorUseCase`
2. Execute `GetBusinessProfileByIdentifierQuery` via query bus
3. Transform persistence model to DTO
4. Return complete profile with all nested objects

**Permission Matrix:**

* **Any scope**: Can read business profile they have access to
* Tenant isolation enforced at query level

**Error Scenarios:**

* Insufficient permissions → Returns `null` with warning log
* Profile not found → Returns `null`
* Database errors → Logged and re-thrown

**Caching:** Results are cached using `BusinessCacheKeys.GET_BUSINESS_PROFILE`

***

### 2. UpdateBusinessProfileUseCase

**Purpose:** Updates the complete business profile with comprehensive validation.

**Input:** `UpdateBusinessProfileParams`

```typescript
{
  ctx: TenantActorContext,
  profile: BusinessProfileDto
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. Validates all nested settings objects
3. Preserves existing media references if not provided
4. Updates only provided fields (partial updates supported)
5. Validates business name if provided
6. Validates addresses, contacts, and schedules

**Process Flow:**

1. Validate user permissions
2. Execute `UpdateBusinessProfileCommand` via command bus
3. Command handler validates domain rules
4. Transform DTO to domain entity
5. Validate nested value objects (BookingSettings, BusinessSettings, etc.)
6. Persist changes to database
7. Clear relevant cache entries

**Domain Validation Rules:**

```typescript
// Core validation in BusinessProfile.create()
if (!props.name) {
  validationErrors.push('Name is required.');
}

BusinessProfile.validateBusinessSettings(props.businessSettings, validationErrors);
BusinessProfile.validateBookingSettings(props.bookingSettings, validationErrors);
BusinessProfile.validateSchedules(props.schedules, validationErrors);
BusinessProfile.validateContacts(props.contacts, validationErrors);
BusinessProfile.validateSocialNetworkLinks(props.socialNetworkLinks, validationErrors);
BusinessProfile.validateAddresses(props.addresses, validationErrors);
```

**Cache Invalidation:** Clears `BusinessCacheKeys.GET_BUSINESS_PROFILE`

***

### 3. UpdateBusinessPaymentSettingsUseCase

**Purpose:** Updates only the payment settings portion of the business profile.

**Input:** `UpdateBusinessPaymentSettingsParams`

```typescript
{
  ctx: TenantActorContext,
  settings: PaymentSettingsDto
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. Validates payment gateway configurations
3. Tests payment gateway connections if credentials provided
4. Supports multiple payment providers (Stripe, PayPal, Square)
5. Validates currency settings and tax configurations

**Process Flow:**

1. Validate user permissions
2. Execute `UpdateBusinessPaymentSettingsCommand`
3. Validate payment provider settings
4. Test gateway connections (optional)
5. Update payment settings in profile
6. Clear relevant caches

**Payment Gateway Validation:**

* **Stripe**: Validates API keys and webhook secrets
* **PayPal**: Validates client ID and secret
* **Square**: Validates application ID and access token

**Error Scenarios:**

* Invalid payment credentials → `PaymentSettingsValidationException`
* Gateway connection test failure → Warning logged, settings saved
* Unsupported currency → `InvalidCurrencyException`

***

## Media Management Use Cases

### 4. UpdateClientLogoUseCase

**Purpose:** Uploads and sets a new business logo image.

**Input:** `UpdateClientLogoParams`

```typescript
{
  ctx: TenantActorContext,
  file: Express.Multer.File
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. File must be valid image format (JPEG, PNG, WebP)
3. File size must not exceed configured limits (5MB)
4. Deletes existing logo if present
5. Generates thumbnails automatically
6. Updates business profile with new media reference

**Process Flow:**

1. Validate user permissions
2. Validate file format and size
3. Upload file to media service
4. Generate thumbnail variants
5. Execute `UpsertClientLogoCommand`
6. Delete previous logo media
7. Update business profile reference
8. Clear media and profile caches

**File Validation:**

```typescript
// Supported formats
const supportedFormats = ['image/jpeg', 'image/png', 'image/webp'];

// Size limits
const maxLogoSize = 5 * 1024 * 1024; // 5MB

// Recommended dimensions
const recommendedDimensions = { width: 200, height: 200 };
```

***

### 5. DeleteClientLogoUseCase

**Purpose:** Removes the current business logo.

**Input:** `DeleteClientLogoParams`

```typescript
{
  ctx: TenantActorContext
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. Removes logo reference from business profile
3. Deletes media files from storage
4. Maintains audit trail of deletion

**Process Flow:**

1. Validate user permissions
2. Get current business profile
3. Execute `DeleteClientLogoCommand`
4. Remove media files from storage
5. Update business profile (remove logo reference)
6. Clear relevant caches

***

### 6. UpdateClientBannerUseCase

**Purpose:** Uploads and updates a specific banner image.

**Input:** `UpdateClientBannerParams`

```typescript
{
  ctx: TenantActorContext,
  bannerItemId: string,
  file: Express.Multer.File
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. File must be valid image format
3. File size must not exceed banner limits (10MB)
4. Supports multiple banners per business
5. Banner dimensions optimized for promotional display

**Process Flow:**

1. Validate user permissions
2. Validate file and banner item ID
3. Upload new banner image
4. Execute `UpsertClientBannerItemCommand`
5. Update banner in business profile
6. Clear relevant caches

**Banner Specifications:**

* **Recommended dimensions**: 1200x400px (landscape)
* **Maximum file size**: 10MB
* **Supported formats**: JPEG, PNG, WebP
* **Use cases**: Promotional content, service showcases

***

### 7. UpdateClientGalleryUseCase

**Purpose:** Uploads and updates a specific gallery image.

**Input:** `UpdateClientGalleryParams`

```typescript
{
  ctx: TenantActorContext,
  galleryItemId: string,
  file: Express.Multer.File
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. Supports various image dimensions
3. File size limit of 8MB
4. Gallery images showcase business work
5. Maintains original aspect ratios

**Process Flow:**

1. Validate user permissions
2. Validate file and gallery item ID
3. Upload new gallery image
4. Generate multiple thumbnail sizes
5. Execute `UpsertClientGalleryItemCommand`
6. Update gallery in business profile
7. Clear relevant caches

***

### 8. DeleteClientBannerItemUseCase

**Purpose:** Removes a specific banner image from the business profile.

**Input:** `DeleteClientBannerItemParams`

```typescript
{
  ctx: TenantActorContext,
  bannerItemId: string
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. Banner item must exist in the business profile
3. Removes both file and reference
4. Maintains banner ordering after deletion

**Process Flow:**

1. Validate user permissions
2. Verify banner item exists
3. Execute `DeleteClientBannerItemCommand`
4. Remove media files from storage
5. Update business profile (remove banner reference)
6. Clear relevant caches

***

### 9. DeleteClientGalleryItemUseCase

**Purpose:** Removes a specific gallery image from the business profile.

**Input:** `DeleteClientGalleryItemParams`

```typescript
{
  ctx: TenantActorContext,
  galleryItemId: string
}
```

**Output:** `void`

**Business Rules:**

1. User must have `EDIT_BUSINESS_PROFILE` permission
2. Gallery item must exist in the business profile
3. Removes both file and reference
4. Maintains gallery organization after deletion

**Process Flow:**

1. Validate user permissions
2. Verify gallery item exists
3. Execute `DeleteClientGalleryItemCommand`
4. Remove media files from storage
5. Update business profile (remove gallery reference)
6. Clear relevant caches

***

## Customer-Facing Use Cases

### 10. GetPublicBusinessProfileUseCase

**Purpose:** Retrieves public business profile information for customers browsing or booking services.

**Input:** `GetPublicBusinessProfileParams`

```typescript
{
  businessUsername?: string,
  businessId?: string,
  includeSchedules?: boolean,
  includeGallery?: boolean
}
```

**Output:** `PublicBusinessProfileDto`

**Business Rules:**

1. No authentication required (public endpoint)
2. Only returns published business profiles
3. Filters sensitive internal information
4. Includes customer-relevant information only
5. Respects privacy settings configured by business
6. Returns operating hours and contact information
7. Includes public media assets (logo, banners, gallery)

**Process Flow:**

1. Identify business by username or ID
2. Execute `GetPublicBusinessProfileQuery`
3. Verify profile is published and active
4. Filter sensitive business information
5. Include only customer-facing data
6. Transform to public DTO format
7. Apply privacy settings filter
8. Return sanitized profile data

**Public Data Included:**

* Business name and description
* Public contact information
* Business addresses and locations
* Operating hours and schedules
* Public media assets (logo, banners, gallery)
* Published services and features
* Public social media links
* Customer booking settings

**Excluded Data:**

* Internal business settings
* Payment gateway configurations
* Administrative panel settings
* Internal notification settings
* Private contact information
* Financial information
* Analytics data

**Caching:** Results cached using `PublicBusinessCacheKeys.GET_PUBLIC_PROFILE`

***

### 11. GetBusinessAvailabilityInfoUseCase

**Purpose:** Retrieves business availability information for customer booking interface.

**Input:** `GetBusinessAvailabilityInfoParams`

```typescript
{
  businessId: string,
  timezone?: string,
  dateRange?: {
    startDate: Date,
    endDate: Date
  }
}
```

**Output:** `BusinessAvailabilityDto`

**Business Rules:**

1. No authentication required (public endpoint)
2. Returns current operating status
3. Includes regular and special schedules
4. Considers business timezone settings
5. Shows next available booking times
6. Respects booking advance time limits
7. Considers booking settings and rules

**Process Flow:**

1. Validate business ID and date range
2. Execute `GetBusinessAvailabilityQuery`
3. Calculate current operating status
4. Process regular and special schedules
5. Apply booking time restrictions
6. Calculate next available slots
7. Transform to availability DTO
8. Apply customer timezone conversion

**Availability Information:**

* Current operating status (open/closed)
* Today's operating hours
* Weekly schedule summary
* Special hours and holidays
* Next available booking time
* Booking advance time limits
* Break periods and unavailable times

***

### 12. GetBusinessContactInfoUseCase

**Purpose:** Retrieves public contact information for customer communication.

**Input:** `GetBusinessContactInfoParams`

```typescript
{
  businessId: string
}
```

**Output:** `BusinessContactInfoDto`

**Business Rules:**

1. No authentication required (public endpoint)
2. Returns only public contact information
3. Respects privacy settings
4. Includes preferred contact methods
5. Shows business addresses and locations
6. Includes social media links

**Process Flow:**

1. Validate business ID
2. Execute `GetBusinessContactInfoQuery`
3. Filter for public contact information
4. Apply privacy settings
5. Include location and address data
6. Transform to contact DTO format

**Contact Information Included:**

* Public phone numbers
* Public email addresses
* Business addresses with maps integration
* Website and social media links
* Preferred contact methods
* Business hours for contact

***

### 13. GetBusinessMediaGalleryUseCase

**Purpose:** Retrieves business media gallery for customer viewing.

**Input:** `GetBusinessMediaGalleryParams`

```typescript
{
  businessId: string,
  includeMetadata?: boolean,
  thumbnailSize?: 'small' | 'medium' | 'large'
}
```

**Output:** `BusinessMediaGalleryDto`

**Business Rules:**

1. No authentication required (public endpoint)
2. Returns published media only
3. Includes optimized images for web display
4. Supports multiple thumbnail sizes
5. Maintains image aspect ratios
6. Includes alt text for accessibility

**Process Flow:**

1. Validate business ID and parameters
2. Execute `GetBusinessMediaGalleryQuery`
3. Filter for published media assets
4. Generate appropriate thumbnail URLs
5. Include metadata if requested
6. Transform to media gallery DTO

**Media Assets Included:**

* Business logo with multiple sizes
* Published banner images
* Gallery images with thumbnails
* Optimized URLs for different screen sizes
* Alt text and descriptions
* Image metadata (if requested)

***

### 14. SearchPublicBusinessProfilesUseCase

**Purpose:** Allows customers to search for businesses by various criteria.

**Input:** `SearchPublicBusinessProfilesParams`

```typescript
{
  searchQuery?: string,
  location?: {
    latitude: number,
    longitude: number,
    radiusKm: number
  },
  businessType?: string,
  services?: string[],
  openNow?: boolean,
  sortBy?: 'distance' | 'name' | 'rating',
  pagination?: {
    page: number,
    limit: number
  }
}
```

**Output:** `SearchBusinessProfilesResultDto`

**Business Rules:**

1. No authentication required (public endpoint)
2. Only searches published business profiles
3. Supports location-based search with radius
4. Filters by business type and services
5. Can filter for currently open businesses
6. Supports pagination for large result sets
7. Includes distance calculation for location searches

**Process Flow:**

1. Validate search parameters
2. Execute `SearchPublicBusinessProfilesQuery`
3. Apply published profile filter
4. Process location-based filtering
5. Apply business type and service filters
6. Filter for operating hours if requested
7. Sort results by specified criteria
8. Apply pagination
9. Transform to search results DTO

**Search Capabilities:**

* Text search across business names and descriptions
* Geographic search with radius filtering
* Business type and category filtering
* Service-based filtering
* Operating hours filtering
* Distance-based sorting
* Relevance-based result ranking

***

### 15. GetBusinessBookingSettingsUseCase

**Purpose:** Retrieves customer-relevant booking settings for the booking interface.

**Input:** `GetBusinessBookingSettingsParams`

```typescript
{
  businessId: string
}
```

**Output:** `CustomerBookingSettingsDto`

**Business Rules:**

1. No authentication required (public endpoint)
2. Returns customer-facing booking settings only
3. Excludes internal business configuration
4. Includes booking rules and restrictions
5. Shows payment requirements
6. Includes mandatory customer information fields

**Process Flow:**

1. Validate business ID
2. Execute `GetBusinessBookingSettingsQuery`
3. Filter for customer-relevant settings
4. Exclude internal configuration
5. Transform to customer booking settings DTO

**Customer Booking Settings:**

* Advance booking time limits
* Payment requirements and methods
* Mandatory customer information fields
* Booking confirmation settings
* Cancellation policies
* Special booking rules and restrictions

***

### 16. ValidateBusinessAccessUseCase

**Purpose:** Validates customer access to business profile and services.

**Input:** `ValidateBusinessAccessParams`

```typescript
{
  businessId: string,
  customerContext?: CustomerContext
}
```

**Output:** `BusinessAccessValidationDto`

**Business Rules:**

1. No authentication required (public endpoint)
2. Validates business profile is published and active
3. Checks for any access restrictions
4. Validates business operating status
5. Considers geographic restrictions if applicable

**Process Flow:**

1. Validate business ID
2. Execute `ValidateBusinessAccessQuery`
3. Check business publication status
4. Verify business is active
5. Check for access restrictions
6. Validate geographic limitations
7. Transform to access validation DTO

**Access Validation:**

* Business profile published status
* Business active/inactive status
* Geographic access restrictions
* Operating hours validation
* Service availability status
* Customer eligibility checks

***

## Command Handlers

### CreateBusinessProfileHandler

**Responsibilities:**

1. Domain entity creation and validation
2. Settings object validation (BookingSettings, BusinessSettings)
3. Database persistence with tenant ID
4. Cache invalidation

**Key Operations:**

```typescript
// Create and validate booking settings
const bookingSettingsOrError = BookingSettings.create(bookingSettings);
const businessSettingsOrError = BusinessSettings.create(businessSettings);

// Create domain entity with validation
const businessProfileDomain = BusinessProfile.create({
  ...command.params,
  bookingSettings: BookingSettingsMap.toPersistence(bookingSettingsOrError.getValue()),
  businessSettings: BusinessSettingsMap.toPersistence(businessSettingsOrError.getValue())
});

// Persist to database
await this.sharedUnitOfWork.businessProfile.createItemWithId(
  BusinessProfileMap.toPersistence(businessProfileDomain.getValue())
);
```

### UpdateBusinessProfileHandler

**Responsibilities:**

1. Profile validation and transformation
2. Nested settings validation
3. Partial update handling
4. Cache invalidation

### UpdateBusinessPaymentSettingsHandler

**Responsibilities:**

1. Payment settings validation
2. Gateway configuration testing
3. Selective payment settings update
4. Financial compliance validation

### Media Command Handlers

#### UpsertClientLogoHandler

**Responsibilities:**

1. Media reference management
2. Previous logo cleanup
3. Profile reference update
4. Cache invalidation

#### DeleteClientLogoHandler

**Responsibilities:**

1. Media file deletion
2. Profile reference removal
3. Cleanup operations

***

## Query Handlers

### GetBusinessProfileHandler

**Responsibilities:**

1. Profile retrieval with population
2. Media reference resolution
3. Nested settings population
4. Cache management

**Population Strategy:**

```typescript
// Populate media references
const profile = await this.model
  .findOne({ _id: tenantId })
  .populate('logo')
  .populate('banners')
  .populate('gallery')
  .exec();
```

### GetBusinessProfileByIdentifierHandler

**Responsibilities:**

1. Identifier-based lookup
2. Username or tenant ID resolution
3. Profile transformation
4. Cache optimization

### GetBusinessSettingsHandler

**Responsibilities:**

1. Settings-specific queries
2. Lightweight responses
3. Settings validation
4. Performance optimization

### Customer-Facing Query Handlers

#### GetPublicBusinessProfileHandler

**Responsibilities:**

1. Public profile data filtering
2. Privacy settings application
3. Customer-safe data transformation
4. Public cache management

**Data Filtering Strategy:**

```typescript
// Filter sensitive data for public consumption
const publicProfile = {
  name: profile.name,
  description: profile.description,
  addresses: profile.addresses.filter(addr => addr.isPublic),
  contacts: profile.contacts.filter(contact => contact.isPublic),
  schedules: profile.schedules,
  logo: profile.logo,
  banners: profile.banners.filter(banner => banner.isPublished),
  gallery: profile.gallery.filter(item => item.isPublished),
  socialNetworkLinks: profile.socialNetworkLinks.filter(link => link.isPublic)
};
```

#### SearchPublicBusinessProfilesHandler

**Responsibilities:**

1. Complex search query processing
2. Geospatial distance calculations
3. Multi-criteria filtering
4. Result ranking and pagination

**Search Implementation:**

```typescript
// MongoDB aggregation pipeline for complex search
const pipeline = [
  // Text search stage
  {
    $match: {
      $text: { $search: searchQuery },
      isPublished: true,
      isActive: true
    }
  },
  // Geospatial filtering if location provided
  ...(location ? [{
    $geoNear: {
      near: { type: "Point", coordinates: [location.longitude, location.latitude] },
      distanceField: "distance",
      maxDistance: location.radiusKm * 1000,
      spherical: true
    }
  }] : []),
  // Additional filtering stages
  {
    $match: {
      ...(businessType && { businessType }),
      ...(services && { services: { $in: services } })
    }
  },
  // Sorting and pagination
  { $sort: getSortCriteria(sortBy) },
  { $skip: (pagination.page - 1) * pagination.limit },
  { $limit: pagination.limit }
];
```

#### GetBusinessAvailabilityHandler

**Responsibilities:**

1. Real-time availability calculation
2. Schedule processing and validation
3. Timezone conversion
4. Booking rules application

**Availability Calculation:**

```typescript
// Calculate current availability status
const calculateAvailability = (schedules: ISchedule[], currentTime: Date, timezone: string) => {
  const currentLocal = convertToTimezone(currentTime, timezone);
  const currentDay = currentLocal.getDay();
  const currentTimeOfDay = formatTimeOfDay(currentLocal);

  const todaySchedule = schedules.find(s => s.dayOfWeek === currentDay && s.isActive);
  
  if (!todaySchedule) {
    return { isOpen: false, nextAvailable: calculateNextAvailable(schedules, currentLocal) };
  }

  const isCurrentlyOpen = isTimeInRange(currentTimeOfDay, todaySchedule.openTime, todaySchedule.closeTime);
  
  return {
    isOpen: isCurrentlyOpen,
    todayHours: todaySchedule,
    nextAvailable: isCurrentlyOpen ? null : calculateNextAvailable(schedules, currentLocal)
  };
};
```

***

## Domain Validation Rules

### Business Profile Entity Validation

1. **Name Validation**: Required for profile identification
2. **Settings Validation**: All nested settings must pass validation
3. **Media Validation**: File format and size constraints
4. **Address Validation**: Complete address requirements
5. **Contact Validation**: Email, phone format validation
6. **Schedule Validation**: Time format and logic validation
7. **Social Network Validation**: URL format and platform validation

```typescript
// Core validation methods
static validateBusinessSettings(businessSettings: IBusinessSettings, validationErrors: string[]) {
  const result = BusinessSettings.validate(businessSettings);
  if (result.isFailureResult()) {
    validationErrors.push(`BusinessSettings are invalid: ${result.errorValue()}`);
  }
}

static validateBookingSettings(bookingSettings: IBookingSettings, validationErrors: string[]) {
  const result = BookingSettings.validate(bookingSettings);
  if (result.isFailureResult()) {
    validationErrors.push(`BookingSettings are invalid: ${result.errorValue()}`);
  }
}

static validateContacts(contacts: IContact[], validationErrors: string[]) {
  if (contacts && contacts.length > 0) {
    contacts.forEach((contact, index) => {
      const result = Contact.create(contact);
      if (result.isFailureResult()) {
        validationErrors.push(`Contact at index ${index} is invalid: ${result.errorValue()}`);
      }
    });
  }
}
```

***

## Settings Management

### Business Settings Value Object

**Responsibilities:**

* Timezone and locale configuration
* Currency and language settings
* Date/time format preferences
* Email language configuration

**Validation Rules:**

* Valid IANA timezone identifiers
* Supported currency codes
* Available language codes
* Consistent base language settings

### Booking Settings Value Object

**Responsibilities:**

* Customer booking configuration
* Auto-action settings
* Payment requirements
* Mandatory attendee properties

**Validation Rules:**

* Logical earliest/latest booking times
* Valid payment requirement configurations
* Supported attendee property combinations

### Payment Settings Value Object

**Responsibilities:**

* Payment gateway configurations
* Supported payment methods
* Currency and tax settings
* Provider-specific settings

**Validation Rules:**

* Valid API credentials for each provider
* Supported currency combinations
* Tax rate and calculation validations

***

## Media Management Integration

### Media Service Integration

**File Upload Process:**

1. File validation (format, size, dimensions)
2. Upload to cloud storage
3. Thumbnail generation
4. Database reference creation
5. Cache invalidation

**File Deletion Process:**

1. Database reference removal
2. Storage file deletion
3. Thumbnail cleanup
4. Cache invalidation

**Media Types:**

* **Logo**: Single square image, multiple sizes generated
* **Banners**: Multiple landscape images for promotions
* **Gallery**: Multiple images showcasing business work

***

## Cache Management

### Cache Keys and Strategy

* `GET_BUSINESS_PROFILE`: Complete profile cache
* `GET_BUSINESS_SETTINGS`: Settings-specific cache
* `GET_CLIENT_LOGO`: Logo media cache
* `GET_CLIENT_BANNERS`: Banner collection cache
* `GET_CLIENT_GALLERY`: Gallery collection cache
* `GET_PUBLIC_PROFILE`: Public business profile cache
* `GET_PUBLIC_AVAILABILITY`: Business availability cache
* `GET_PUBLIC_CONTACT_INFO`: Public contact information cache
* `SEARCH_PUBLIC_PROFILES`: Business search results cache

### Invalidation Strategy

* **Profile Updates**: Invalidates `GET_BUSINESS_PROFILE` and `GET_PUBLIC_PROFILE`
* **Settings Updates**: Invalidates specific settings caches and public availability
* **Media Updates**: Invalidates media-specific caches and public profile
* **Publication Changes**: Invalidates all public-facing caches
* **Cascade Invalidation**: Profile changes invalidate related public caches

### Cache Decorators

```typescript
@DeleteCache([
  BusinessCacheKeys.GET_BUSINESS_PROFILE,
  BusinessCacheKeys.GET_BUSINESS_SETTINGS,
  PublicBusinessCacheKeys.GET_PUBLIC_PROFILE,
  PublicBusinessCacheKeys.GET_PUBLIC_AVAILABILITY
])
```

### Public Cache Strategies

**Public Profile Cache:**

* Longer TTL (30 minutes) for stable public data
* Invalidated on profile publication changes
* Separate cache namespace for public data

**Availability Cache:**

* Shorter TTL (5 minutes) for real-time data
* Invalidated on schedule changes
* Time-based cache keys for different time periods

**Search Cache:**

* Medium TTL (15 minutes) for search results
* Location-based cache partitioning
* Invalidated on new business publications

***

## Permission Integration

### Permission Validation

All use cases integrate with the `PermissionValidatorUseCase`:

```typescript
await this.permissionValidator.execute({
  actor: ctx.actor,
  requiredPermissions: [ModulePermissionEnum.EDIT_BUSINESS_PROFILE],
});
```

### Required Permissions

* **READ\_BUSINESS\_PROFILE**: View business profile information
* **EDIT\_BUSINESS\_PROFILE**: Modify any aspect of business profile
* **PUBLIC\_ACCESS**: No authentication required (customer-facing endpoints)

### Access Patterns

1. **Read Operations**: Require READ permission (internal) or PUBLIC\_ACCESS (customer)
2. **Update Operations**: Require EDIT permission
3. **Media Operations**: Require EDIT permission
4. **Settings Updates**: Require EDIT permission
5. **Public Operations**: No authentication required but respect privacy settings

### Customer Access Patterns

**Public Endpoints (No Authentication):**

* Get public business profile
* Search public business profiles
* Get business availability information
* Get public contact information
* Get business media gallery
* Get customer booking settings
* Validate business access

**Privacy Filtering:**

* Public endpoints automatically filter sensitive data
* Respect business privacy settings
* Only show published and active content
* Geographic restrictions applied when configured

***

## Error Handling

### Exception Types

1. **BusinessProfileNotFoundException**: Profile not found
2. **BusinessClientCreationException**: Profile creation errors
3. **PaymentSettingsValidationException**: Payment configuration errors
4. **MediaUploadException**: File upload errors
5. **SettingsValidationException**: Settings validation errors
6. **BusinessNotPublishedException**: Business profile not published for public access
7. **BusinessAccessDeniedException**: Geographic or other access restrictions
8. **InvalidSearchCriteriaException**: Invalid search parameters
9. **PublicDataFilterException**: Error filtering public data

### Error Logging

All use cases implement comprehensive error logging:

```typescript
catch (error) {
  this.logger.error('Error updating business profile', error);
  throw error;
}
```

### Customer-Specific Error Handling

**Public Endpoint Errors:**

* Return sanitized error messages to customers
* Log detailed errors for internal monitoring
* Graceful degradation for partial data availability
* Fallback mechanisms for unavailable services

**Privacy Error Handling:**

* Never expose internal business data in errors
* Return generic "not found" for inaccessible data
* Respect privacy settings in error responses

***

## Testing Considerations

### Unit Testing

* Mock dependencies (CommandBus, QueryBus, MediaService)
* Test permission scenarios
* Validate business rules
* Test file upload/deletion scenarios
* Validate settings objects independently

### Integration Testing

* Test with real database and file storage
* Verify cache behavior
* Test multi-tenant isolation
* Validate media file operations

### Example Test Scenarios

1. **Profile Management**: Create, update, retrieve profiles
2. **Settings Validation**: Test all settings objects validation
3. **Media Operations**: Upload, update, delete media files
4. **Permission Tests**: Verify access control
5. **Cache Tests**: Verify cache invalidation works correctly
6. **Error Handling**: Test exception scenarios
7. **Multi-tenant**: Verify tenant isolation
8. **Public Access**: Test customer-facing endpoints without authentication
9. **Privacy Filtering**: Verify sensitive data is filtered in public responses
10. **Search Functionality**: Test business search with various criteria
11. **Availability Calculation**: Test real-time availability logic
12. **Geographic Search**: Test location-based business discovery

### Customer Use Case Testing

**Public Endpoint Testing:**

```typescript
describe('Public Business Profile Access', () => {
  it('should return public profile without authentication', async () => {
    const result = await getPublicBusinessProfile({ businessId: 'test-business' });
    expect(result).not.toContain('paymentSettings');
    expect(result).not.toContain('internalNotes');
  });

  it('should filter unpublished media from public response', async () => {
    const result = await getBusinessMediaGallery({ businessId: 'test-business' });
    result.gallery.forEach(item => {
      expect(item.isPublished).toBe(true);
    });
  });

  it('should calculate availability correctly across timezones', async () => {
    const result = await getBusinessAvailability({ 
      businessId: 'test-business',
      timezone: 'America/New_York'
    });
    expect(result.isOpen).toBeDefined();
    expect(result.nextAvailable).toBeDefined();
  });
});
```

**Search Testing:**

```typescript
describe('Business Search', () => {
  it('should find businesses within specified radius', async () => {
    const result = await searchPublicBusinessProfiles({
      location: { latitude: 40.7128, longitude: -74.0060, radiusKm: 5 },
      sortBy: 'distance'
    });
    result.businesses.forEach(business => {
      expect(business.distance).toBeLessThanOrEqual(5000); // meters
    });
  });

  it('should filter by business type and services', async () => {
    const result = await searchPublicBusinessProfiles({
      businessType: 'restaurant',
      services: ['delivery', 'takeout']
    });
    result.businesses.forEach(business => {
      expect(business.businessType).toBe('restaurant');
      expect(business.services).toContain('delivery');
    });
  });
});
```

***

## Business Workflow Integration

### Profile Setup Workflow

1. **Initial Creation**: Create basic profile during business registration
2. **Information Completion**: Add addresses, contacts, schedules
3. **Settings Configuration**: Configure booking and business settings
4. **Media Upload**: Add logo, banners, gallery images
5. **Publication**: Set profile as published for client visibility

### Settings Management Workflow

1. **Business Settings**: Core operational parameters
2. **Booking Settings**: Customer interaction configuration
3. **Payment Settings**: Financial transaction setup
4. **Notification Settings**: Communication preferences
5. **Panel Settings**: Administrative interface customization

### Media Management Workflow

1. **Logo Management**: Single primary business identifier
2. **Banner Management**: Multiple promotional images
3. **Gallery Management**: Portfolio of business work
4. **Media Optimization**: Automatic resizing and compression
5. **Storage Management**: Cloud storage with CDN delivery

***

## Performance Considerations

### Query Optimization

* Use selective field projection
* Implement proper indexing
* Optimize media population queries
* Cache frequently accessed data

### Media Optimization

* Automatic image compression
* Multiple thumbnail sizes
* CDN delivery for global performance
* Lazy loading for large galleries

### Cache Strategy

* Profile-level caching for complete data
* Component-level caching for settings
* Media-specific caching for assets
* Intelligent cache invalidation