Use Case Documentation

Overview

This document describes the business use cases and application layer logic for the Customer Management module. Each use case encapsulates business rules, permissions, and orchestrates the interaction between domain entities, repositories, and external integrations within the order and payment ecosystem.

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, Delete Customer)

• Queries: Read operations (Get Customer, Search Customers)

• Domain Entities: Business logic and validation

• Value Objects: Customer data and relationship objects

• Integration Services: Order and payment system integration

Core Use Cases

1. CreateCustomerUseCase

Purpose: Creates a new customer record with comprehensive validation and business rule enforcement.

Input: CreateCustomerUseCaseParams

{
  ctx: TenantActorContext,
  customer: CustomerDto
}

Output: string (Customer ID)

Business Rules:

1. User must have CREATE_CUSTOMER permission

2. At least one of firstName, lastName, email, or phone must be provided

3. Email must be valid format if provided

4. Phone must be valid format if provided (automatically normalized)

5. Customer type defaults to 'regular' if not specified

6. No duplicate customers based on email/phone combination

7. Customer is created with 'active' state

Process Flow:

1. Validate user permissions using PermissionValidatorUseCase

2. Validate customer data using CustomerValidator

3. Execute AddRegularCustomerCommand via command bus

4. Command handler validates domain rules and creates entity

5. Persist customer to database with tenant isolation

6. Clear relevant cache entries

7. Publish CustomerAddedMessage event

8. Return generated customer ID

Validation Rules:

// Mandatory field validation
const hasRequiredField = customer.firstName || customer.lastName || 
                        customer.email || customer.phone;
if (!hasRequiredField) {
  throw new ValidationException('At least one field must be filled: phone, email, first name or last name.');
}

// Email format validation
if (customer.email && !isValidEmail(customer.email)) {
  throw new ValidationException('Invalid email format');
}

// Phone format validation and normalization
if (customer.phone) {
  const normalizedPhone = extractNumbers(customer.phone);
  customer.phone = normalizedPhone;
}

Cache Invalidation: Clears CustomerCacheKeys.GET_PAGED_CUSTOMERS

---

2. GetCustomerUseCase

Purpose: Retrieves detailed customer information by ID with permission validation.

Input: GetCustomerUseCaseParams

{
  ctx: TenantActorContext,
  customerId: string
}

Output: CustomerDto

Business Rules:

1. User must have READ_CUSTOMER permission

2. Customer must exist and belong to the authenticated tenant

3. Returns complete customer information including state history

4. Respects tenant data isolation

Process Flow:

1. Validate user permissions

2. Execute GetCustomerByIdQuery via query bus

3. Query handler retrieves customer from repository

4. Transform persistence model to DTO

5. Return customer data or throw exception if not found

Error Scenarios:

• Insufficient permissions → ForbiddenException

• Customer not found → CustomerNotFoundException

• Database errors → Logged and re-thrown

Caching: Results are cached using CustomerCacheKeys.GET_CUSTOMER

---

3. UpdateCustomerUseCase

Purpose: Updates existing customer information with partial update support and validation.

Input: UpdateCustomerUseCaseParams

{
  ctx: TenantActorContext,
  customerId: string,
  update: CustomerDto
}

Output: void

Business Rules:

1. User must have EDIT_CUSTOMER permission

2. Customer must exist and belong to the authenticated tenant

3. Supports partial updates (only provided fields are updated)

4. Email and phone validation applied if provided

5. Customer type can be changed with proper validation

6. Updates increment version number for optimistic locking

Process Flow:

1. Validate user permissions

2. Verify customer exists using GetCustomerByIdQuery

3. Validate update data using CustomerValidator

4. Execute UpdateCustomerCommand via command bus

5. Command handler applies domain validation and updates entity

6. Persist changes with optimistic locking

7. Clear relevant cache entries

8. Publish CustomerUpdatedMessage event

Domain Validation:

// Validate email if provided
if (update.email && !Customer.validateEmail(update.email).isSuccessResult()) {
  throw new ValidationException('Invalid email format');
}

// Validate and normalize phone if provided
if (update.phone) {
  const phoneValidation = Customer.validatePhone(update.phone);
  if (phoneValidation.isFailureResult()) {
    throw new ValidationException(phoneValidation.errorValue());
  }
  update.phone = extractNumbers(update.phone);
}

Cache Invalidation: Clears CustomerCacheKeys.GET_CUSTOMER and CustomerCacheKeys.GET_PAGED_CUSTOMERS

---

4. DeleteCustomerUseCase

Purpose: Soft deletes a customer record with business rule validation.

Input: DeleteCustomerUseCaseParams

{
  ctx: TenantActorContext,
  customerId: string
}

Output: void

Business Rules:

1. User must have DELETE_CUSTOMER permission

2. Customer must exist and belong to the authenticated tenant

3. Performs soft delete (sets state to 'deleted')

4. Validates no active orders exist for the customer

5. Preserves historical data for reporting and compliance

Process Flow:

1. Validate user permissions

2. Verify customer exists

3. Check for active orders or dependencies

4. Execute DeleteCustomerCommand via command bus

5. Command handler performs soft delete

6. Update state history with deletion reason

7. Clear relevant cache entries

8. Publish CustomerDeletedMessage event

Dependency Validation:

// Check for active orders
const activeOrders = await this.orderService.getActiveOrdersByCustomer(customerId);
if (activeOrders.length > 0) {
  throw new BusinessRuleViolationException('Cannot delete customer with active orders');
}

// Check for pending payments
const pendingPayments = await this.paymentService.getPendingPaymentsByCustomer(customerId);
if (pendingPayments.length > 0) {
  throw new BusinessRuleViolationException('Cannot delete customer with pending payments');
}

---

5. GetPagedCustomersUseCase

Purpose: Retrieves paginated customer list with search and filtering capabilities.

Input: GetPagedCustomersUseCaseParams

{
  ctx: TenantActorContext,
  pagination: CustomerPaginationDto
}

Output: PaginationResponseDto<CustomerDto>

Business Rules:

1. User must have READ_CUSTOMER permission

2. Results are filtered by tenant for data isolation

3. Supports text search across name and email fields

4. Supports filtering by customer type and state

5. Implements efficient pagination with cursor support

6. Maximum page size limit enforced

Process Flow:

1. Validate user permissions

2. Validate pagination parameters

3. Execute GetPagedCustomersQuery via query bus

4. Query handler applies filters and pagination

5. Transform results to DTOs

6. Return paginated response with metadata

Search Implementation:

// MongoDB aggregation pipeline for customer search
const pipeline = [
  // Text search stage
  {
    $match: {
      $or: [
        { firstName: { $regex: searchTerm, $options: 'i' } },
        { lastName: { $regex: searchTerm, $options: 'i' } },
        { email: { $regex: searchTerm, $options: 'i' } },
        { $text: { $search: searchTerm } }
      ],
      tenantId: ctx.tenantId,
      state: { $ne: 'deleted' }
    }
  },
  // Customer type filtering
  ...(customerType ? [{ $match: { customerType } }] : []),
  // Sorting and pagination
  { $sort: getSortCriteria(sortBy, sortDirection) },
  { $skip: (page - 1) * limit },
  { $limit: limit }
];

Caching: Results cached using CustomerCacheKeys.GET_PAGED_CUSTOMERS with pagination context

---

Order Integration Use Cases

6. AddAttendeesUseCase

Purpose: Processes customer attendees for order services, creating or updating customer records as needed.

Input: AddAttendeesCommand

{
  tenantId: string,
  attendees: AttendantDto[]
}

Output: AttendantDto[] (Processed attendees with customer IDs)

Business Rules:

1. Creates regular customers for attendees with email/phone

2. Reuses existing customers when found by email/phone match

3. Marks first-time visitors based on order history

4. Validates attendee information against business settings

5. Maintains customer snapshots in order data

Process Flow:

1. Iterate through provided attendees

2. For each attendee with contact information:

   • Search for existing customer by email/phone

   • If found, use existing customer and mark firstTime: false

   • If not found, create new regular customer

   • Validate customer data meets business requirements

3. Create customer snapshots for order persistence

4. Return processed attendee list with customer references

Customer Matching Logic:

// Find existing customer by email or phone
const existingCustomer = await this.sharedUnitOfWork.customers.findCustomerByEmailOrPhone(
  attendant.customer?.email,
  attendant.customer?.phone
);

if (existingCustomer) {
  // Use existing customer
  attendantDtoArray.push({
    object: 'AttendantDto',
    customer: CustomerMap.toDto({ ...existingCustomer, customerType: CustomerTypeEnum.regular }),
    firstTime: false
  });
} else {
  // Create new regular customer
  const regularCustomer = Customer.createRegular({
    _id: attendant?.customer?._id,
    customerType: CustomerTypeEnum.regular,
    email: attendant.customer?.email,
    firstName: attendant.customer?.firstName,
    lastName: attendant.customer?.lastName,
    phone: attendant.customer?.phone,
  });

  if (regularCustomer.isSuccessResult()) {
    const persistenceCustomer = CustomerMap.toPersistence(regularCustomer.getValue());
    const createdCustomer = await this.sharedUnitOfWork.customers.createCustomer(persistenceCustomer);
    
    attendantDtoArray.push({
      object: 'AttendantDto',
      customer: CustomerMap.toDto(createdCustomer),
      firstTime: true
    });
  }
}

---

7. AddPublicAttendeesUseCase

Purpose: Processes customer information from public order creation with flexible customer handling.

Input: AddPublicAttendeesCommand

{
  tenantId: string,
  attendees: PublicAttendantDto[]
}

Output: AttendantDto[]

Business Rules:

1. Handles anonymous and unregistered customers

2. Creates minimal customer records for public orders

3. Validates mandatory attendee properties per business settings

4. Supports guest checkout scenarios

5. Maintains privacy for public customers

Process Flow:

1. Validate attendee information against business booking settings

2. For each public attendee:

   • Check if customer exists by contact information

   • Create unregistered customer if sufficient information provided

   • Create anonymous customer for minimal information

   • Apply business mandatory property requirements

3. Return processed attendee list for order creation

Mandatory Property Validation:

// Validate mandatory attendee properties
const mandatoryProperties = bookingSettings.mandatoryAttendeeProperties || [AttendeePropertyEnum.email];

attendees.forEach((attendee, index) => {
  const missingProperties = mandatoryProperties.filter(prop =>
    attendee[prop] === undefined || attendee[prop] === null || attendee[prop] === ''
  );

  if (missingProperties.length > 0) {
    throw new ValidationException(
      `Attendee #${index + 1} is missing mandatory properties: ${missingProperties.join(', ')}`
    );
  }
});

---

Payment Integration Use Cases

8. ProcessPaymentCustomerUseCase

Purpose: Handles customer information during payment processing with customer creation as needed.

Input: ProcessPaymentCustomerParams

{
  tenantId: string,
  payerInfo: CustomerDto,
  actor: ActorDto
}

Output: CustomerDto (Processed payer information)

Business Rules:

1. Creates customer record for payment if not exists

2. Validates payer information for payment processing

3. Maintains customer snapshots in payment records

4. Supports guest payment scenarios

5. Links payment history to customer records

Process Flow:

1. Validate payer information format

2. Search for existing customer by email/phone

3. If customer exists, update payment-relevant information

4. If customer doesn't exist, create new customer record

5. Return customer information for payment processing

Payment Customer Creation:

// Check if customer exists for payment
const existingCustomer = await this.sharedUnitOfWork.customers.findCustomerByEmailOrPhone(
  payment.payer.email,
  payment.payer.phone
);

if (!existingCustomer) {
  // Create customer for payment
  const customerDomain = Customer.createRegular(
    CustomerMap.toPersistenceFromDto(payment.payer)
  );

  if (customerDomain.isSuccessResult()) {
    await this.sharedUnitOfWork.customers.createCustomer(payment.payer);
  }
}

---

Query Handlers

GetCustomerByIdHandler

Responsibilities:

1. Customer retrieval with tenant filtering

2. State validation and access control

3. Data transformation to DTO format

4. Cache management and optimization

Implementation:

async execute(query: GetCustomerByIdQuery): Promise<CustomerDto | null> {
  try {
    const customer = await this.sharedUnitOfWork.customers.findCustomerById(
      query.customerId,
      query.tenantId
    );

    if (!customer) {
      return null;
    }

    // Validate customer state
    if (customer.state === 'deleted') {
      return null;
    }

    return CustomerMap.toDto(customer);
  } catch (error) {
    this.logger.error(`Error getting customer by id: ${query.customerId}`, error);
    throw error;
  }
}

GetPagedCustomersHandler

Responsibilities:

1. Advanced filtering and search implementation

2. Efficient pagination with cursor support

3. Sort optimization and index utilization

4. Result transformation and metadata

Search Strategy:

// MongoDB search implementation
const searchFilter = query.search ? {
  $or: [
    { firstName: { $regex: query.search, $options: 'i' } },
    { lastName: { $regex: query.search, $options: 'i' } },
    { email: { $regex: query.search, $options: 'i' } },
    { 
      $expr: {
        $regexMatch: {
          input: { $concat: ['$firstName', ' ', '$lastName'] },
          regex: query.search,
          options: 'i'
        }
      }
    }
  ]
} : {};

const filter = {
  tenantId: query.tenantId,
  state: { $ne: 'deleted' },
  ...searchFilter,
  ...(query.customerType && { customerType: query.customerType })
};

IsCustomerExistHandler

Responsibilities:

1. Duplicate customer detection

2. Email and phone uniqueness validation

3. Performance-optimized existence checks

4. Multi-field search support

Existence Check:

async execute(query: IsCustomerExistQuery): Promise<boolean> {
  const filter: any = { tenantId: query.tenantId, state: { $ne: 'deleted' } };
  
  const orConditions = [];
  if (query.email) orConditions.push({ email: query.email });
  if (query.phone) orConditions.push({ phone: extractNumbers(query.phone) });
  
  if (orConditions.length > 0) {
    filter.$or = orConditions;
  }
  
  const count = await this.model.countDocuments(filter);
  return count > 0;
}

---

Command Handlers

AddRegularCustomerHandler

Responsibilities:

1. Domain entity creation and validation

2. Business rule enforcement

3. Database persistence with tenant ID

4. Event publishing and cache invalidation

Customer Creation Process:

async execute(command: AddRegularCustomerCommand): Promise<string> {
  try {
    // Create domain entity with validation
    const customerDomain = Customer.createRegular({
      ...command.customer,
      customerType: CustomerTypeEnum.regular
    });

    if (customerDomain.isFailureResult()) {
      throw new CustomerCreationException(customerDomain.errorValue());
    }

    // Convert to persistence model
    const persistenceModel = CustomerMap.toPersistence(customerDomain.getValue());
    persistenceModel.tenantId = command.tenantId;

    // Persist to database
    const createdCustomer = await this.sharedUnitOfWork.customers.createCustomer(persistenceModel);

    // Publish event
    await this.messageQueueService.sendMessage(
      new CustomerAddedMessage({
        tenantId: command.tenantId,
        customer: CustomerMap.toDto(createdCustomer),
        createdBy: { /* actor info */ },
        timestamp: new Date().toISOString()
      })
    );

    return createdCustomer._id.toString();
  } catch (error) {
    this.logger.error('Error creating customer', error);
    throw new CustomerCreationException(error.message);
  }
}

UpdateCustomerHandler

Responsibilities:

1. Customer existence validation

2. Partial update processing

3. Domain validation enforcement

4. Optimistic locking support

DeleteCustomerHandler

Responsibilities:

1. Soft delete implementation

2. Dependency validation

3. State history maintenance

4. Cleanup operations

---

Domain Validation Rules

Customer Entity Validation

// Customer creation validation
static create(props: ICustomer): Result<Customer> {
  const validationErrors: string[] = [];

  // Validate mandatory fields
  const requiredFields: (keyof ICustomer)[] = ['firstName', 'lastName', 'phone', 'email', 'customerType'];
  const fieldValidation = this.validateMandatoryFields(props, requiredFields);
  if (fieldValidation.isFailureResult()) {
    validationErrors.push(fieldValidation.errorValue());
  }

  // Validate email format
  const emailValidation = this.validateEmail(props.email);
  if (emailValidation.isFailureResult()) {
    validationErrors.push(emailValidation.errorValue());
  }

  // Validate phone format
  const phoneValidation = this.validatePhone(props.phone);
  if (phoneValidation.isFailureResult()) {
    validationErrors.push(phoneValidation.errorValue());
  }

  if (validationErrors.length > 0) {
    return Result.fail<Customer>(validationErrors.join('\n'));
  }

  // Normalize phone number
  if (props.phone) {
    props.phone = extractNumbers(props.phone);
  }

  return Result.ok(new Customer(props));
}

// Regular customer validation (stricter rules)
static createRegular(props: ICustomer): Result<Customer> {
  const validationErrors: string[] = [];

  // Validate mandatory fields for regular customers
  const requiredFields: (keyof ICustomer)[] = ['phone', 'email'];
  const fieldValidation = this.validateMandatoryFields(props, requiredFields);
  if (fieldValidation.isFailureResult()) {
    validationErrors.push(fieldValidation.errorValue());
  }

  const emailValidation = this.validateEmail(props.email);
  if (emailValidation.isFailureResult()) {
    validationErrors.push(emailValidation.errorValue());
  }

  const phoneValidation = this.validatePhone(props.phone);
  if (phoneValidation.isFailureResult()) {
    validationErrors.push(phoneValidation.errorValue());
  }

  if (validationErrors.length > 0) {
    return Result.fail<Customer>(validationErrors.join('\n'));
  }

  // Set customer type and normalize phone
  props.customerType = CustomerTypeEnum.regular;
  if (props.phone) {
    props.phone = extractNumbers(props.phone);
  }

  return Result.ok(new Customer(props));
}

Validation Helper Methods

// Email validation
private static validateEmail(email?: string): Result<void> {
  if (email && !/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(email)) {
    return Result.fail<void>('Invalid email format: ' + email);
  }
  return Result.ok();
}

// Phone validation
private static validatePhone(phone?: string): Result<void> {
  if (phone && !/^(\+?\d{1,3}[-.\s]?)?(\(?\d{1,4}\)?[-.\s]?)?\d{1,4}[-.\s]?\d{1,4}[-.\s]?\d{1,9}$/.test(phone)) {
    return Result.fail<void>('Invalid phone number format: ' + phone);
  }
  return Result.ok();
}

// Mandatory fields validation
private static validateMandatoryFields(props: ICustomer, fields: (keyof ICustomer)[]): Result<void> {
  const hasAtLeastOneProperty = fields.some(field => 
    props[field] !== undefined && props[field] !== '' && props[field] !== null
  );
  
  return hasAtLeastOneProperty ? 
    Result.ok() : 
    Result.fail<void>('At least one of the following properties must be provided: ' + fields.join(', '));
}

---

Cache Management

Cache Keys and Strategy

// Cache key definitions
export enum CustomerCacheKeys {
  GET_CUSTOMER = 'customer:get',
  GET_PAGED_CUSTOMERS = 'customer:paged',
  CUSTOMER_SEARCH = 'customer:search',
  CUSTOMER_VALIDATION = 'customer:validation'
}

// Cache TTL settings
const CACHE_TTL = {
  CUSTOMER_DETAILS: 300,    // 5 minutes
  CUSTOMER_LIST: 60,        // 1 minute  
  SEARCH_RESULTS: 180,      // 3 minutes
  VALIDATION_RESULTS: 600   // 10 minutes
};

Cache Invalidation Strategy

// Customer update invalidates related caches
@DeleteCache([
  CustomerCacheKeys.GET_CUSTOMER,
  CustomerCacheKeys.GET_PAGED_CUSTOMERS,
  CustomerCacheKeys.CUSTOMER_SEARCH
])
async updateCustomer(command: UpdateCustomerCommand): Promise<void> {
  // Update implementation
}

// Smart cache invalidation based on changes
private async invalidateCustomerCaches(tenantId: string, customerId: string, changedFields: string[]) {
  // Always invalidate customer detail cache
  await this.cacheService.delete(`${CustomerCacheKeys.GET_CUSTOMER}:${tenantId}:${customerId}`);
  
  // Invalidate search cache if searchable fields changed
  const searchableFields = ['firstName', 'lastName', 'email'];
  if (changedFields.some(field => searchableFields.includes(field))) {
    await this.cacheService.deletePattern(`${CustomerCacheKeys.CUSTOMER_SEARCH}:${tenantId}:*`);
  }
  
  // Invalidate paged results cache
  await this.cacheService.deletePattern(`${CustomerCacheKeys.GET_PAGED_CUSTOMERS}:${tenantId}:*`);
}

---

Permission Integration

Permission Validation

All customer use cases integrate with the PermissionValidatorUseCase:

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

Required Permissions

• READ_CUSTOMER: View customer information and lists

• CREATE_CUSTOMER: Create new customer records

• EDIT_CUSTOMER: Modify existing customer information

• DELETE_CUSTOMER: Delete customer records

Permission Matrix

Operation	Permission	Scope	Notes
Get Customer	READ_CUSTOMER	Tenant	Read access to customer data
Get Paged Customers	READ_CUSTOMER	Tenant	List and search customers
Create Customer	CREATE_CUSTOMER	Tenant	Create new customer records
Update Customer	EDIT_CUSTOMER	Tenant	Modify customer information
Delete Customer	DELETE_CUSTOMER	Tenant	Soft delete customer records
Add Attendees	EDIT_CUSTOMER	Tenant	Process order attendees

---

Error Handling

Exception Types

// Customer-specific exceptions
export class CustomerNotFoundException extends NotFoundException {
  constructor(customerId: string) {
    super(`Customer not found: ${customerId}`);
  }
}

export class CustomerCreationException extends BadRequestException {
  constructor(message: string) {
    super(`Customer creation failed: ${message}`);
  }
}

export class CustomerAlreadyExistsException extends ConflictException {
  constructor(field: string, value: string) {
    super(`Customer already exists with ${field}: ${value}`);
  }
}

export class CustomerValidationException extends BadRequestException {
  constructor(errors: string[]) {
    super(`Customer validation failed: ${errors.join(', ')}`);
  }
}

Error Logging

All use cases implement comprehensive error logging:

catch (error) {
  this.logger.error('Error in customer operation', {
    operation: 'createCustomer',
    tenantId: ctx.tenantId,
    customerId: customer._id,
    error: error.message,
    stack: error.stack
  });
  throw error;
}

---

Testing Considerations

Unit Testing

describe('CreateCustomerUseCase', () => {
  test('should create customer with valid data', async () => {
    const customer = {
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      phone: '[phone]'
    };

    const customerId = await createCustomerUseCase.execute({
      ctx: mockContext,
      customer
    });

    expect(customerId).toBeDefined();
    expect(mockCommandBus.execute).toHaveBeenCalledWith(
      expect.any(AddRegularCustomerCommand)
    );
  });

  test('should validate mandatory fields', async () => {
    const invalidCustomer = {};

    await expect(
      createCustomerUseCase.execute({
        ctx: mockContext,
        customer: invalidCustomer
      })
    ).rejects.toThrow('At least one field must be filled');
  });

  test('should validate email format', async () => {
    const customer = {
      firstName: 'John',
      email: 'invalid-email'
    };

    await expect(
      createCustomerUseCase.execute({
        ctx: mockContext,
        customer
      })
    ).rejects.toThrow('Invalid email format');
  });
});

Integration Testing

describe('Customer Integration Tests', () => {
  test('should create customer and retrieve by ID', async () => {
    // Create customer
    const customerId = await createCustomerUseCase.execute({
      ctx: testContext,
      customer: testCustomerData
    });

    // Retrieve customer
    const retrievedCustomer = await getCustomerUseCase.execute({
      ctx: testContext,
      customerId
    });

    expect(retrievedCustomer._id).toBe(customerId);
    expect(retrievedCustomer.email).toBe(testCustomerData.email);
  });

  test('should handle order attendee creation', async () => {
    const attendees = [{
      customer: {
        firstName: 'Jane',
        lastName: 'Smith',
        email: '[email protected]'
      }
    }];

    const processedAttendees = await commandBus.execute(
      new AddAttendeesCommand(tenantId, attendees)
    );

    expect(processedAttendees).toHaveLength(1);
    expect(processedAttendees[0].customer._id).toBeDefined();
    expect(processedAttendees[0].firstTime).toBe(true);
  });
});

---

Business Workflow Integration

Customer Lifecycle Workflow

1. Customer Creation: Initial customer registration or first order

2. Profile Completion: Adding additional information and preferences

3. Order Association: Linking customers to orders as payers and attendees

4. Payment Processing: Customer information in payment records

5. Relationship Management: Ongoing customer interaction and updates

Order Integration Workflow

1. Attendee Processing: Convert order attendees to customer records

2. Customer Matching: Find existing customers or create new ones

3. Snapshot Creation: Preserve customer data in order records

4. First-Time Detection: Mark new customers for special handling

5. History Tracking: Maintain customer order history

Payment Integration Workflow

1. Payer Identification: Link payment to customer record

2. Customer Creation: Create customer if not exists for payment

3. Payment History: Track customer payment patterns

4. Billing Information: Manage customer billing preferences

---

Performance Considerations

Database Optimization

1. Indexing Strategy: Optimize for common query patterns

2. Query Optimization: Efficient filtering and sorting

3. Batch Processing: Handle bulk customer operations

4. Connection Pooling: Manage database connections efficiently

Query Patterns

// Optimized customer search with indexes
db.customer.createIndex({ 
  tenantId: 1, 
  email: 1 
}, { 
  sparse: true 
});

db.customer.createIndex({ 
  tenantId: 1, 
  phone: 1 
}, { 
  sparse: true 
});

db.customer.createIndex({
  tenantId: 1,
  firstName: 'text',
  lastName: 'text',
  email: 'text'
});

// Compound index for pagination
db.customer.createIndex({
  tenantId: 1,
  state: 1,
  createdAt: -1
});

Memory Management

1. Selective Field Projection: Load only required fields

2. Streaming Results: Handle large result sets efficiently

3. Cache Optimization: Balance memory usage and performance

4. Connection Management: Proper resource cleanup

---

Security Considerations

Data Protection

1. PII Handling: Secure processing of personal information

2. Encryption: Protect sensitive customer data

3. Access Logging: Track customer data access

4. Data Retention: Comply with retention policies

Privacy Compliance

1. GDPR Support: Data portability and deletion rights

2. Consent Management: Track customer consent preferences

3. Data Minimization: Store only necessary information

4. Audit Trail: Complete change history for compliance

Access Control

1. Permission Validation: Enforce role-based access

2. Tenant Isolation: Strict multi-tenant data separation

3. Rate Limiting: Prevent abuse and DoS attacks

4. Input Validation: Sanitize all customer inputs

---

Business Rules Summary

Customer Data Rules

1. Mandatory Information: At least one identifying field required

2. Data Validation: Email and phone format validation

3. Normalization: Phone numbers stored in normalized format

4. Uniqueness: Prevent duplicate customers per tenant

5. State Management: Soft deletion preserves historical data

Order Integration Rules

1. Attendee Matching: Smart customer matching by email/phone

2. Customer Creation: Automatic customer creation for orders

3. Snapshot Preservation: Historical customer data in orders

4. First-Time Tracking: Identify new customer visits

5. Multi-Attendee Support: Multiple customers per order service

Business Logic Rules

1. Tenant Isolation: Complete data separation per business

2. Permission Enforcement: Role-based operation access

3. Cache Consistency: Proper cache invalidation on updates

4. Event Publishing: Async notification of customer changes

5. Error Recovery: Graceful handling of validation and system errors

---

Future Enhancements

Planned Features

1. Customer Segmentation: Advanced customer categorization

2. Preference Management: Detailed customer preferences

3. Communication History: Track all customer interactions

4. Analytics Integration: Customer behavior analysis

5. Loyalty Programs: Customer loyalty and rewards

6. Marketing Automation: Automated customer communication

Scalability Improvements

1. Read Replicas: Optimize read performance

2. Sharding Strategy: Handle large customer datasets

3. Event Sourcing: Complete audit trail with events

4. CQRS Optimization: Separate read/write models

5. Microservice Decomposition: Split by business domains

---

Summary

The Customer Management use cases provide a comprehensive foundation for handling customer operations within the Bee O'clock ecosystem. Key capabilities include:

• Complete Customer Lifecycle: From creation to deletion with validation

• Order Integration: Seamless customer handling in order processing

• Payment Integration: Customer information in payment workflows

• Advanced Search: Efficient customer discovery and management

• Multi-Tenant Security: Proper data isolation and access control

• Performance Optimization: Caching and efficient query patterns

• Business Rule Enforcement: Comprehensive validation and business logic

• Event-Driven Architecture: Async communication for scalability

The use cases support complex business scenarios while maintaining high performance, data integrity, and security standards across the customer management domain.