Files
cal.diy/packages/features/booking-audit/README.md
T
2802310268 feat: Add infrastructure for no-show audit integration (#27187)
* feat: Add infrastructure for no-show audit integration

- Add Prisma migrations for SYSTEM source and NO_SHOW_UPDATED audit action
- Add NoShowUpdatedAuditActionService with array-based attendeesNoShow schema
- Update BookingAuditActionServiceRegistry to include NO_SHOW_UPDATED
- Update BookingAuditTaskConsumer and BookingAuditViewerService
- Add AttendeeRepository methods for no-show queries
- Update IAuditActionService interface with values array support
- Update locales with no-show audit translation keys

Co-Authored-By: [email protected] <[email protected]>

* fix: Add NO_SHOW_UPDATED to BookingAuditAction and SYSTEM to ActionSource types

Co-Authored-By: [email protected] <[email protected]>

* fix: Remove HOST_NO_SHOW_UPDATED and ATTENDEE_NO_SHOW_UPDATED from BookingAuditAction type to match Prisma schema

Co-Authored-By: [email protected] <[email protected]>

* fix: Update BookingAuditActionSchema to use NO_SHOW_UPDATED instead of HOST_NO_SHOW_UPDATED and ATTENDEE_NO_SHOW_UPDATED

Co-Authored-By: [email protected] <[email protected]>

* refactor: Remove deprecated no-show audit services and unify to NoShowUpdatedAuditActionService

- Delete HostNoShowUpdatedAuditActionService and AttendeeNoShowUpdatedAuditActionService
- Update BookingAuditProducerService.interface.ts to use queueNoShowUpdatedAudit
- Update BookingAuditTaskerProducerService.ts to use queueNoShowUpdatedAudit
- Update BookingEventHandlerService.ts to use onNoShowUpdated
- Add integration tests for NoShowUpdatedAuditActionService

Co-Authored-By: [email protected] <[email protected]>

* fix: Add data migration step for deprecated no-show enum values

Addresses Cubic AI review feedback (confidence 9/10): The migration now
includes an UPDATE statement to convert existing records using the
deprecated 'host_no_show_updated' or 'attendee_no_show_updated' enum
values to the new unified 'no_show_updated' value before the type cast.
This prevents migration failures if any existing data uses the old values.

Co-Authored-By: unknown <>

* fix: Use CASE expression in USING clause for enum migration

Fixes PostgreSQL error 'unsafe use of new value of enum type' by avoiding
the ADD VALUE statement and instead using a CASE expression in the ALTER
TABLE USING clause to convert deprecated enum values (host_no_show_updated,
attendee_no_show_updated) to the new unified value (no_show_updated) during
the type conversion.

Co-Authored-By: unknown <>

* fix: Replace hardcoded color with semantic text-success class

Co-Authored-By: [email protected] <[email protected]>

* fix: Remove color class completely from display fields

Co-Authored-By: [email protected] <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-01-29 08:47:26 -03:00

240 lines
10 KiB
Markdown

# Booking Audit System
## Overview
The Booking Audit System tracks all actions and changes related to bookings in Cal.com. The architecture is built around two core tables (`AuditActor` and `BookingAudit`) that work together to maintain a complete, immutable audit trail.
## Database Architecture
### Core Tables
1. **AuditActor**: Stores information about entities that perform actions on bookings. Maintains historical records even after users are deleted.
2. **BookingAudit**: Stores audit records for all booking-related actions.
### Key Design Decisions
**AuditActor Table:**
- Uses UUID primary keys for distributed system compatibility
- Soft references to `User` (via `userUuid`) and `Attendee` (via `attendeeId`) without foreign key constraints
- Audit trail persists independently even after users/attendees are deleted
- Unique constraints prevent duplicate audit actors
- Supports actor types: USER, GUEST, ATTENDEE, SYSTEM, APP
- Identity fields (email, phone, name) can be anonymized when source records are deleted
**BookingAudit Table:**
- Uses UUID v7 primary keys for time-sortable IDs
- `bookingUid` stored as plain string (no foreign key) to preserve audit trail after booking deletion
- `onDelete: Restrict` prevents actor deletion if audit records exist
- Explicit `timestamp` field represents business event time (may differ from `createdAt` if processed asynchronously)
- `operationId` required field for correlating audit logs from a single user action across different audit types (BookingAudit, UserAudit, etc.)
- JSON `data` field stores action-specific contextual data
- Indexed for efficient queries by `bookingUid`, `actorId`, `timestamp`, and `operationId`
**Protecting the Audit Trail:**
- Database rejects deletion of `AuditActor` records with associated `BookingAudit` records
- When a `User` is deleted, their `AuditActor` record persists with `userUuid` set to null
## Actor Types
- **USER**: Registered Cal.com users
- **GUEST**: Non-registered users (typically booking guests)
- **ATTENDEE**: Guests who have an Attendee record associated with a booking
- **SYSTEM**: Automated system actions
## Source and Actor Design Pattern
The booking audit system uses two complementary fields:
### Source: The Channel
**`source`** identifies how the action was initiated:
- **WEBAPP**: Cal.com web application
- **API_V1**: API v1 endpoint
- **API_V2**: API v2 endpoint
- **WEBHOOK**: External webhook (e.g., Stripe)
- **SYSTEM**: Background job (e.g., Tasker's task, trigger.dev job for automatic no-show detection)
- **UNKNOWN**: Source cannot be determined
### Actor: The Entity
**`actor`** identifies who or what performed the action:
- **User Actor**: Registered Cal.com user
- **Guest Actor**: Non-registered guest
- **Attendee Actor**: Attendee associated with a booking
- **System Actor**: Automated system action (generic or named for specific webhooks/services)
This separation enables clear compliance trails, easier debugging, better analytics, and security by distinguishing user-initiated vs automated actions.
## Audit Actions
The system tracks various booking actions including:
- **CREATED**: Initial booking creation
- **RESCHEDULED**: Booking time/date changed
- **ACCEPTED**: Booking request approved
- **CANCELLED**: Booking cancelled
- **REJECTED**: Booking request declined
- **RESCHEDULE_REQUESTED**: Request to reschedule
- **ATTENDEE_ADDED**: New attendee added
- **ATTENDEE_REMOVED**: Attendee removed
- **REASSIGNMENT**: Booking reassigned to different host
- **LOCATION_CHANGED**: Meeting location updated
- **NO_SHOW_UPDATED**: Host or attendee no-show status changed
- **SEAT_BOOKED**: Seat reserved in group booking
- **SEAT_RESCHEDULED**: Seat rescheduled in group booking
## Data Structure Pattern
Most audit actions track changes using a consistent structure:
- Each field tracks both old and new values: `{ old: T | null, new: T }`
- `old`: Previous value (null if field didn't exist before)
- `new`: New value after the change
- Complete before/after state captured in every record
**Exception:** The CREATED action captures initial booking state at creation using a flat object with initial values.
## Schema Versioning
The audit system uses per-action versioning. Each action maintains its own schema version independently.
**Benefits:**
- Update one action's schema without affecting others
- Old records handled via discriminated unions (no migration required)
- Strongly-typed schemas for input and storage
**Storage Structure:**
Version stored separately from audit data: `{ version, data: {} }`
## Table Relationships
```
AuditActor (1) ──────< (many) BookingAudit
↑
│ (soft reference, no FK)
├──────────── User (via userUuid)
│ (soft reference, no FK)
└──────────── Attendee (via attendeeId)
```
**Relationship Details:**
1. **AuditActor → BookingAudit**: One-to-Many with FK constraint and `onDelete: Restrict`
2. **AuditActor → User**: Soft reference (no FK) - nullable to preserve audits after user deletion
3. **AuditActor → Attendee**: Soft reference (no FK) - nullable to preserve audits after attendee deletion
## Indexing Strategy
**AuditActor Table:**
- Indexed on `email`, `userUuid`, `attendeeId` for fast lookups
- Indexed on `pseudonymizedAt` for compliance cleanup jobs
**BookingAudit Table:**
- Indexed on `bookingUid` (primary query pattern)
- Indexed on `actorId` (secondary query pattern)
- Indexed on `timestamp` (time-based sorting and filtering)
- Indexed on `operationId` (correlating multi-booking operations)
## Special Actors
**SYSTEM Actor:**
- Fixed UUID representing automated actions
- Used for automated status changes, system-generated meeting URLs, scheduled operations
- Single instance across the entire system
- No userUuid, attendeeId, email, or phone
## Design Principles
### 1. Immutability
Audit records are append-only. Once created, they are never modified or deleted. This ensures complete historical accuracy and a tamper-proof audit trail.
### 2. Historical Preservation
Actor information is preserved even after source records are deleted. AuditActor records persist with anonymized identity fields. The audit trail remains complete and queryable even after user/attendee deletion.
### 3. Flexibility
The JSON `data` field provides schema flexibility for action-specific context without database schema changes. Backward compatible with versioning.
### 4. Traceability
Every action is fully traceable with who (actor), what (action), when (timestamp), and contextual data.
### 5. Integrity
Database constraints ensure data quality through foreign keys, `onDelete: Restrict` protection, unique constraints, and strategic indexes.
### 6. Reality Over Enforcement
The audit system records actual state, not expected state. It captures what actually happened without enforcing business rules:
- Store actual values from the database
- Record all actions, including anomalies
- Business logic layer enforces rules; audit layer records faithfully
**Benefits:**
- Shows real system behavior including anomalies
- Easier debugging
- No silent failures
### 7. Compliance & Data Privacy
**GDPR & HIPAA Compliance:**
- AuditActor records persist with PII fields nullified when users are deleted
- Maintains immutable audit trail as required by HIPAA §164.312(b)
- GDPR Article 17 compliance through anonymization: `userUuid`, `email`, `phone`, `name` set to null
- Application-level logic handles retention policies
### 8. Queue Privacy
**Zero PII in Queue:**
The audit system works with third-party queue providers without exposing PII:
- **UserActor**: Only `userUuid` is queued
- **AttendeeActor**: Only `attendeeId` is queued
- **GuestActor**: Actor record created before queueing; only `actorId` is queued
**Benefits:**
- Safe to use third-party queue providers
- GDPR and HIPAA compliant
- Audit trail remains complete even if queue is compromised
## Service Architecture
**BookingEventHandlerService** is the primary entry point for tracking booking changes. It:
1. Receives booking events from various parts of the application
2. Queues audit tasks via BookingAuditProducerService
3. Handles other side effects such as webhooks and notifications
**Queue Payload Structure:**
- `bookingUid`: String identifier for the booking
- `actor`: ID-only actor object (`userUuid`, `attendeeId`, or `actorId`)
- `organizationId`: Number (for feature flag checks)
- `action`: Enum value (e.g., "CREATED", "CANCELLED")
- `operationId`: Required string for correlating related audit logs
- `data`: Action-specific data
- `timestamp`: Number (milliseconds since epoch)
- `source`: Action source (API_V1, API_V2, WEBAPP, WEBHOOK, SYSTEM, UNKNOWN)
**BookingAuditTaskConsumer** processes audit records:
- Validates queue payload structure
- Resolves actor IDs to AuditActor records
- Routes to appropriate action service for data validation and formatting
- Creates immutable audit records in BookingAudit table
## Operation ID
The `operationId` field correlates audit logs that result from a single user action affecting multiple bookings or across different audit types (BookingAudit, UserAudit, etc.).
**Benefits:**
- Easy to identify all audits from a single user action
- Track bulk vs individual operations
- Improved debugging and understanding of action scope
- Indexed field for fast lookups
## Summary
The Booking Audit System provides a robust, scalable architecture for tracking all booking-related actions:
- **Complete Audit Trail**: Every action tracked with full context
- **Historical Preservation**: Data retained even after deletions through PII anonymization
- **Flexible Schema**: JSON data supports evolution without migrations
- **Strong Integrity**: Database constraints ensure data quality
- **Performance**: Strategic indexes, UUID v7 for time-sortable IDs
- **HIPAA & GDPR Compliant**: Immutable audit records, anonymized actors
- **Reality-Based Recording**: Captures actual state for debugging
- **Independent Audit Trail**: Persists after booking deletion
- **Operation Correlation**: Links related audit logs across different audit types
This architecture supports compliance requirements, debugging, analytics, and provides transparency for users and administrators.