Use Case Documentation

Overview

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

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)

• Queries: Read operations (Get, List)

• Domain Entities: Business logic and validation

• Events: Asynchronous notifications

Use Cases

1. CreateAbsenceUseCase

Purpose: Creates a new absence record with proper validation and permission checking.

Input: CreateAbsenceUseCaseParams

{
  ctx: TenantActorContext,
  absence: AbsenceDto
}

Output: void

Business Rules:

1. User must have CREATE_ABSENCE permission

2. Users with OWN scope can only create absences for themselves

3. Absence must have valid date range (end > start)

4. Must specify either entireBusiness: true or at least one member

5. Timezone must be provided

Process Flow:

1. Validate user permissions using PermissionValidatorUseCase

2. Check scope restrictions for member assignments

3. Execute CreateAbsenceCommand via command bus

4. Command handler validates domain rules

5. Persist absence to database

6. Emit AbsenceCreatedMessage for notifications

7. Clear relevant cache entries

Permission Matrix:

• OWN scope: Can only create absences where the actor is in the members list

• ANY scope: Can create any absence within the tenant

Error Scenarios:

• Insufficient permissions → AccessPermissionException

• Invalid domain data → AbsenceDomainError

• Database errors → Logged and re-thrown

---

2. GetAbsenceUseCase

Purpose: Retrieves a specific absence by ID with proper access control.

Input: GetAbsenceUseCaseParams

{
  ctx: TenantActorContext,
  absenceId: string
}

Output: AbsenceDto | null

Business Rules:

1. User must have READ_ABSENCE permission

2. Users with OWN scope can only view their own absences or business-wide absences

3. Returns null if absence not found or access denied

Process Flow:

1. Validate user permissions

2. Execute GetAbsenceByIdQuery via query bus

3. Check access rights based on permission scope

4. Return absence data or null if unauthorized

Access Control Logic:

// Business-wide absences are visible to all authorized users
if (absence.entireBusiness) return absence;

// Check if user has access to non-business-wide absence
const hasAccess = scope === PermissionScopeEnum.ANY || 
                  absence.members.some(member => member._id === ctx.actor.issuerId);

return hasAccess ? absence : null;

Caching: Results are cached using AbsenceCacheKeys.GET_ABSENCE

---

3. GetPagedAbsencesUseCase

Purpose: Retrieves a paginated list of absences with filtering and access control.

Input: GetPagedAbsencesUseCaseParams

{
  ctx: TenantActorContext,
  pagination: AbsencePaginationDto
}

Output: PaginationResponseDto<AbsenceDto>

Business Rules:

1. User must have READ_ABSENCE permission

2. Users with OWN scope only see their own absences and business-wide absences

3. Users with ANY scope see all absences within the tenant

4. Returns empty result if no permissions

Process Flow:

1. Validate permissions with fallback to empty result

2. Apply scope-based filtering

3. Execute paginated query

4. Return formatted pagination response

Scope-based Filtering:

• OWN scope: Filter to show only absences where user is a member or business-wide absences

• ANY scope: Show all absences within the tenant

Caching: Results can be cached using AbsenceCacheKeys.GET_PAGED_ABSENCES

---

4. UpdateAbsenceUseCase

Purpose: Updates an existing absence with validation and access control.

Input: UpdateAbsenceUseCaseParams

{
  ctx: TenantActorContext,
  absenceId: string,
  update: AbsenceDto
}

Output: void

Business Rules:

1. User must have EDIT_ABSENCE permission

2. Absence must exist and be accessible

3. Users can only update absences they have access to

4. Domain validation rules apply (dates, assignments, etc.)

Process Flow:

1. Validate user permissions

2. Fetch existing absence

3. Check access rights using assertActorHasAccessToAbsence

4. Execute UpdateAbsenceCommand

5. Domain validation and persistence

6. Emit AbsenceUpdatedMessage

7. Clear cache entries

Access Validation:

function assertActorHasAccessToAbsence(options: {
  actorMemberId: string;
  absence: AbsenceDto;
  scope: PermissionScopeEnum;
  action: string;
  logger: Logger;
}): void {
  const hasAccess = absence.entireBusiness || 
                    scope === PermissionScopeEnum.ANY ||
                    absence.members.some(m => m._id.toString() === actorMemberId);
  
  if (!hasAccess) {
    throw new AccessPermissionException(`You can only ${action} your own absences`);
  }
}

---

5. DeleteAbsenceUseCase

Purpose: Soft deletes an absence record by updating its state history.

Input: DeleteAbsenceUseCaseParams

{
  ctx: TenantActorContext,
  absenceId: string
}

Output: void

Business Rules:

1. User must have DELETE_ABSENCE permission

2. Absence must exist and be accessible

3. Performs soft delete (state history update)

4. Cannot delete already deleted absences

Process Flow:

1. Validate user permissions

2. Fetch absence to verify existence and access

3. Check access rights

4. Execute DeleteAbsenceCommand

5. Update state history to 'deleted'

6. Emit AbsenceDeletedMessage

7. Clear cache entries

Soft Delete Implementation:

• Absences are not physically removed from the database

• State history is updated with EntityStateEnum.deleted

• Deleted absences are filtered out in queries

• Maintains audit trail and referential integrity

---

Command Handlers

CreateAbsenceHandler

Responsibilities:

1. Domain entity creation and validation

2. Database persistence

3. Event emission

4. Cache invalidation

Key Operations:

// Create domain entity with validation
const absence: IAbsence = AbsenceMap.toPersistenceFromDto(command.absenceDto);
const absenceDomain = Absence.create(absence);

// Persist to database
const createdAbsence = await this.sharedUnitOfWork.absences.createItem(
  AbsenceMap.toPersistence(absenceDomain.getValue())
);

// Emit event
await this.messageQueueService.emitEvent(new AbsenceCreatedMessage({
  tenantId: command.tenantId,
  absence: AbsenceMap.toDto(createdAbsence)
}));

UpdateAbsenceHandler

Responsibilities:

1. Domain validation of updates

2. Database update operation

3. Event emission

4. Cache invalidation

DeleteAbsenceHandler

Responsibilities:

1. Fetch existing absence

2. Create domain object

3. Update state history

4. Persist changes

5. Event emission

---

Query Handlers

GetAbsenceByIdHandler

Responsibilities:

1. Database query execution

2. Result transformation

3. Cache management

Caching Strategy:

• Uses @Cached decorator with AbsenceCacheKeys.GET_ABSENCE

• Cache key includes tenant ID for multi-tenancy

• Automatically invalidated on updates/deletes

GetPagedAbsenceHandler

Responsibilities:

1. Build query filters

2. Execute paginated database query

3. Transform results

4. Return pagination metadata

Query Building:

// Build aggregation pipeline
const pipeline = [
  { $match: matchConditions },
  { $lookup: memberLookup },
  { $skip: (page - 1) * pageSize },
  { $limit: pageSize }
];

---

Domain Validation Rules

Absence Entity Validation

1. ID Validation: Must be valid ObjectId

2. Date Validation: Start date must be before end date

3. Type Validation: Must be valid AbsenceTypeEnum value

4. Timezone Validation: Must be provided

5. Assignment Validation: Must have either entireBusiness=true or at least one member

// Core validation in Absence.create()
if (new Date(props.start) >= new Date(props.end)) {
  validationErrors.push('End date must be greater than start date');
}

if (!props.entireBusiness && props.members.length === 0) {
  validationErrors.push('Absence must have at least one member assigned or be for the entire business');
}

---

Event-Driven Architecture

Message Types

1. AbsenceCreatedMessage: Published when a new absence is created

2. AbsenceUpdatedMessage: Published when an absence is modified

3. AbsenceDeletedMessage: Published when an absence is deleted

Event Consumers

AbsenceConsumer (Panel Service):

• Receives AMQP messages

• Transforms to WebSocket messages

• Broadcasts to connected clients

AbsenceCacheConsumer (Cache Service):

• Receives cache invalidation events

• Clears relevant cache entries

• Maintains cache consistency

WebSocket Integration

Real-time notifications are sent to connected clients:

// Example WebSocket message
const wsMessage: AbsenceCreatedWsMessage = {
  type: 'absence-created',
  payload: { absence: createdAbsence }
};

this.webSocket.sendMessage(tenantId, wsMessage);

---

Permission Integration

Permission Validation

All use cases integrate with the PermissionValidatorUseCase:

const { scope } = await this.permissionValidatorUseCase.execute({
  actor: ctx.actor,
  requiredPermissions: [ModulePermissionEnum.CREATE_ABSENCE],
});

Permission Scopes

• PermissionScopeEnum.OWN: Limited to user's own data

• PermissionScopeEnum.ANY: Access to all tenant data

Access Patterns

1. Create: Users can only create absences they're assigned to (OWN scope)

2. Read: Users can view their absences + business-wide absences

3. Update/Delete: Users can only modify absences they have access to

---

Cache Management

Cache Keys

• GET_ABSENCE: Individual absence cache

• GET_PAGED_ABSENCES: Paginated list cache

Invalidation Strategy

• Create: Invalidates GET_PAGED_ABSENCES

• Update: Invalidates both GET_ABSENCE and GET_PAGED_ABSENCES

• Delete: Invalidates both cache keys

Cache Decorators

@DeleteCache([
  AbsenceCacheKeys.GET_ABSENCE,
  AbsenceCacheKeys.GET_PAGED_ABSENCES
])

---

Error Handling

Exception Types

1. AccessPermissionException: Permission-related errors

2. AbsenceDomainError: Domain validation errors

3. AbsenceCreationException: Creation-specific errors

4. AbsenceUpdationException: Update-specific errors

Error Logging

All use cases implement comprehensive error logging:

catch (error) {
  this.logger.error('Error creating absence', error);
  throw error;
}

---

Testing Considerations

Unit Testing

• Mock dependencies (CommandBus, QueryBus, PermissionValidator)

• Test permission scenarios

• Validate business rules

• Test error conditions

Integration Testing

• Test with real database

• Verify event emission

• Test cache behavior

• Validate multi-tenancy

Example Test Scenarios

1. Permission Tests: Verify OWN vs ANY scope behavior

2. Validation Tests: Test domain validation rules

3. Access Control Tests: Verify users can only access appropriate data

4. Event Tests: Verify correct events are emitted

5. Cache Tests: Verify cache invalidation works correctly