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

{
  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

{
  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:

// 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

{
  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

{
  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:

// 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

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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

{
  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:

// 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:

// 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:

// 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:

// 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:

// 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

// 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

@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:

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:

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:

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:

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