Audit Trail System

class SystemLog < ApplicationRecord
  # Core audit event associations
  belongs_to :owner, polymorphic: true, optional: true      # User who performed action
  belongs_to :trackable, polymorphic: true, optional: true  # Object being tracked
  belongs_to :clinic, optional: true                        # Associated clinic
  belongs_to :clinic_patient, optional: true               # Associated clinic patient
  belongs_to :patient, optional: true                      # Associated patient

  # Key scopes for filtering
  scope :audit_events, -> { where(key: audit_event_keys) }
  scope :for_clinic, ->(clinic_id) { where(clinic_id: clinic_id) }
  scope :for_patient_any, ->(patient_id) { ... }
  scope :date_range, ->(start_date, end_date) { ... }
  scope :by_key, ->(key) { where(key: key) }
  scope :successful, -> { where(event_status: SUCCESS) }
  scope :failed, -> { where(event_status: [FAILURE, UNAUTHORIZED]) }
end

CREATE TABLE system_logs (
  id BIGINT PRIMARY KEY,
  key VARCHAR NOT NULL,                    -- Event type identifier
  owner_id BIGINT,                        -- User who performed action
  owner_type VARCHAR,                     -- User model type
  trackable_id BIGINT,                    -- Associated object ID
  trackable_type VARCHAR,                 -- Associated object type
  clinic_id BIGINT,                       -- Clinic context
  clinic_patient_id BIGINT,               -- Clinic patient context
  patient_id BIGINT,                      -- Patient context
  parameters JSONB,                       -- Additional event data
  description TEXT,                       -- Human-readable description
  event_status VARCHAR DEFAULT 'SUCCESS', -- SUCCESS/FAILURE/UNAUTHORIZED
  user_role VARCHAR,                      -- User role at time of action
  ip_address VARCHAR,                     -- User IP address
  user_agent TEXT,                        -- Browser/device information
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL,
  
  -- Indexes for performance
  INDEX idx_system_logs_audit (key, clinic_id, created_at),
  INDEX idx_system_logs_patient (patient_id, clinic_patient_id),
  INDEX idx_system_logs_owner (owner_type, owner_id)
);

class ClinicExportFile < ApplicationRecord
  belongs_to :clinic
  belongs_to :user
  
  # Export types
  EXPORT_TYPES = %w[AUDIT_TRAIL_REPORT PATIENT_RECORDS_EXPORT]
  
  # Status values
  STATUS_VALUES = %w[PROCESSING FILE_GENERATED FAILED FILE_REMOVED]
end

class AuditTrailsController < ApiController
  # GET /clinics/:clinic_id/audit_trails
  def index
    result = AuditTrails::Fetch.call(params)
    render_result(result, result.success? ? AuditTrailSerializer : nil)
  end

  # POST /clinics/:clinic_id/audit_trails/export
  def export
    result = AuditTrails::Export.call(params)
    render_result result
  end
end

class AdminAuditTrailsController < ApiController
  # GET /admin/audit_trails
  def index
    result = AdminAuditTrailActions::Fetch.call(params)
    render_result(result, result.success? ? AuditTrailSerializer : nil)
  end
end

module AuditTrails
  class Export < BaseInteractor
    def call
      validate_clinic
      validate_export_request    # Date validation, 90-day limit
      save_log                  # Create export record
      queue_export_job          # Async processing
    end
  end
end

{
  "start_date": "2024-01-01",      // Optional: Filter by date range
  "end_date": "2024-01-31",        // Optional: Filter by date range
  "user_id": "12345",              // Optional: Filter by user
  "event_key": "patient.create",   // Optional: Filter by event type
  "status": "success",             // Optional: success/failure/failed
  "patient_id": "67890",           // Optional: Filter by patient
  "page": 1,                       // Optional: Page number (default: 1)
  "per_page": 50                   // Optional: Records per page (max: 200)
}

{
  "success": true,
  "message": "Audit trails fetched successfully",
  "data": {
    "audit_trails": [
      {
        "id": 12345,
        "timestamp": "2024-01-15T10:30:00Z",
        "key": "patient.create",
        "event_status": "SUCCESS",
        "description": "Patient record created",
        "user": {
          "id": 789,
          "name": "Dr. John Smith",
          "type": "Doctor"
        },
        "patient": {
          "id": 456,
          "name": "Jane Doe"
        },
        "resource": {
          "type": "Patient",
          "id": 456
        },
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "device_type": "desktop",
        "parameters": {
          "patient_age": 35,
          "patient_gender": "female"
        }
      }
    ],
    "total_pages": 10,
    "total_records": 500
  }
}

{
  "start_date": "2024-01-01",      // Optional: Export date range
  "end_date": "2024-01-31",        // Optional: Export date range  
  "event_key": "patient.create"    // Optional: Filter by event type
}

{
  "success": true,
  "message": "Audit trail export enqueued",
  "data": {
    "export_id": 123,
    "estimated_completion": "2024-01-15T10:35:00Z"
  }
}

PATIENT_VIEW = 'patient.view'                    # Patient record accessed
PATIENT_UPDATE = 'patient.update'                # Patient information modified
PATIENT_CREATE = 'patient.create'                # New patient registered
PATIENT_DELETE = 'patient.delete'                # Patient record deleted
PATIENT_MEDICAL_RECORD_CREATE = 'patient.medical_record.create'
PATIENT_VITAL_CREATE = 'patient.vital.create'
PATIENT_MEDICATION_CREATE = 'patient.medication.create'

APPOINTMENT_BOOK = 'appointment.book'             # New appointment scheduled
APPOINTMENT_CANCEL = 'appointment.cancel'        # Appointment cancelled
APPOINTMENT_UPDATE = 'appointment.update'        # Appointment modified

CAREPLAN_UPDATE = 'careplan.update'              # Treatment plan modified
CAREPLAN_SEND = 'careplan.send'                  # Prescription sent to patient
CAREPLAN_EMAIL_SEND = 'careplan.email_send'      # Prescription emailed
CAREPLAN_PRINT = 'careplan.print'                # Prescription printed

BILL_CREATE = 'bill.create'                      # Invoice generated
BILL_DELETE = 'bill.delete'                      # Invoice deleted
PAYMENT_CREATE = 'payment.create'                # Payment recorded
PAYMENT_UPDATE = 'payment.update'                # Payment modified
PAYMENT_REFUND = 'payment.refund'                # Payment refunded

AUTH_LOGIN = 'auth.login'                        # Successful login
AUTH_LOGOUT = 'auth.logout'                      # User logout
AUTH_FAILED_LOGIN = 'auth.failed_login'          # Failed login attempt
AUTH_REGISTRATION = 'auth.registration'          # New user registration

AUDIT_EXPORT = 'audit.export'                    # Audit trail exported

# Get recent audit trails for a clinic
curl -X GET \
  "https://api.kulcare.com/clinics/123/audit_trails?page=1&per_page=50" \
  -H "Authorization: Bearer <token>"

# Get patient creation events from last 30 days
curl -X GET \
  "https://api.kulcare.com/clinics/123/audit_trails" \
  -G \
  -d "event_key=patient.create" \
  -d "start_date=2024-01-01" \
  -d "end_date=2024-01-31" \
  -H "Authorization: Bearer <token>"

# Get all failed authentication attempts
curl -X GET \
  "https://api.kulcare.com/clinics/123/audit_trails" \
  -G \
  -d "event_key=auth.failed_login" \
  -d "status=failure" \
  -H "Authorization: Bearer <token>"

# Get audit trails for specific patient
curl -X GET \
  "https://api.kulcare.com/clinics/123/patients/456/audit_trails" \
  -H "Authorization: Bearer <token>"

# Request audit trail export for date range
curl -X POST \
  "https://api.kulcare.com/clinics/123/audit_trails/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "event_key": "patient.create"
  }'

# In a controller or interactor
SystemLog.create!(
  key: SystemLog::PATIENT_CREATE,
  owner: current_user,
  trackable: patient,
  clinic: current_clinic,
  patient: patient,
  event_status: SystemLog::SUCCESS,
  description: "Patient record created successfully",
  parameters: {
    patient_age: patient.age,
    patient_gender: patient.gender,
    registration_source: 'web_portal'
  },
  user_role: current_user.role,
  ip_address: request_info[:ip_address],
  user_agent: request_info[:user_agent]
)

# Get recent login attempts for a clinic
recent_logins = SystemLog.audit_events
                        .for_clinic(clinic.id)
                        .by_key(SystemLog::AUTH_LOGIN)
                        .recent_first
                        .limit(100)

# Get failed actions in date range
failed_actions = SystemLog.audit_events
                         .for_clinic(clinic.id)
                         .failed
                         .date_range(1.week.ago, Time.current)

# Get all patient-related activities
patient_activities = SystemLog.audit_events
                             .for_patient_any(patient.id)
                             .where(key: [
                               SystemLog::PATIENT_VIEW,
                               SystemLog::PATIENT_UPDATE,
                               SystemLog::PATIENT_MEDICAL_RECORD_CREATE
                             ])

# config/settings.yml
audit_trail:
  default_per_page: 50          # Default pagination size
  max_per_page: 200             # Maximum records per page
  export_retention_days: 7      # Days to keep export files
  max_export_days: 90          # Maximum date range for exports
  large_dataset_threshold: 50000 # Threshold for streaming exports

-- Essential indexes for audit trail queries
CREATE INDEX CONCURRENTLY idx_system_logs_clinic_date 
  ON system_logs (clinic_id, created_at DESC);

CREATE INDEX CONCURRENTLY idx_system_logs_patient_activities 
  ON system_logs (patient_id, clinic_patient_id, created_at DESC);

CREATE INDEX CONCURRENTLY idx_system_logs_audit_keys 
  ON system_logs (key) WHERE key IN ('patient.view', 'patient.create', ...);

# config/application.rb
config.active_job.queue_adapter = :sidekiq

# Audit export job configuration
config.active_job.queue_name_prefix = Rails.env

# Configure audit trail mailer
class AuditTrailMailer < ActionMailer::Base
  default from: Settings.mailer.default_from

  def export_ready(export_file)
    @export_file = export_file
    @clinic = export_file.clinic
    
    mail(
      to: export_file.user.email,
      subject: "Audit Trail Export Ready - #{@clinic.name}"
    )
  end
end

# Monitor export job failures
class GenerateAuditTrail < ActiveJob::Base
  rescue_from StandardError do |exception|
    # Log to monitoring system
    Rails.logger.error "Audit export failed: #{exception.message}"
    
    # Alert administrators
    AdminNotificationService.audit_export_failed(exception, export_file)
    
    # Update export record
    export_file.update!(
      status: 'FAILED',
      params: export_file.params.merge('error_message' => exception.message)
    )
  end
end