<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

/**
 * Append-only audit trail for promotion / enrollment workflow actions
 * (see plan section 18).
 */
class PromotionAuditLog extends BaseModel
{
    protected $table = 'promotion_audit_log';

    public $timestamps = true;

    public const ACTION_RECORD_CREATED = 'record_created';

    public const ACTION_STATUS_CHANGED = 'status_changed';

    public const ACTION_ELIGIBILITY_EVALUATED = 'eligibility_evaluated';

    public const ACTION_PARENT_NOTIFIED = 'parent_notified';

    public const ACTION_ENROLLMENT_STARTED = 'enrollment_started';

    public const ACTION_ENROLLMENT_STEP_COMPLETED = 'enrollment_step_completed';

    public const ACTION_ENROLLMENT_COMPLETED = 'enrollment_completed';

    public const ACTION_PROMOTION_FINALIZED = 'promotion_finalized';

    public const ACTION_DEADLINE_SET = 'deadline_set';

    public const ACTION_REMINDER_SENT = 'reminder_sent';

    public const ACTION_DEADLINE_EXPIRED = 'deadline_expired';

    public const ACTION_MANUAL_OVERRIDE = 'manual_override';

    protected $fillable = [
        'promotion_id',
        'student_id',
        'user_id',
        'action_type',
        'field',
        'old_value',
        'new_value',
        'notes',
        'performed_at',
    ];

    protected $casts = [
        'promotion_id' => 'integer',
        'student_id' => 'integer',
        'user_id' => 'integer',
        'performed_at' => 'datetime',
    ];

    public function promotion(): BelongsTo
    {
        return $this->belongsTo(StudentPromotionRecord::class, 'promotion_id', 'promotion_id');
    }

    public function actor(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id');
    }

    public function scopeForPromotion(Builder $q, int $promotionId): Builder
    {
        return $q->where('promotion_id', $promotionId);
    }
}