<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

/**
 * LeadershipAchievement Model
 *
 * Represents an achievement or accomplishment by a leader during their term.
 * Linked to a LeadershipHistory record.
 *
 * @property int $id
 * @property int $leadership_history_id
 * @property string $achievement_description
 * @property \Illuminate\Support\Carbon $achievement_date
 * @property \Illuminate\Support\Carbon|null $created_at
 * @property \Illuminate\Support\Carbon|null $updated_at
 */
class LeadershipAchievement extends Model
{
    use HasFactory;

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'leadership_history_id',
        'achievement_description',
        'achievement_date',
    ];

    /**
     * The attributes that should be cast.
     *
     * @var array<string, string>
     */
    protected $casts = [
        'achievement_date' => 'date',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];

    /**
     * Get the leadership history record for this achievement.
     *
     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo
     */
    public function leadershipHistory()
    {
        return $this->belongsTo(LeadershipHistory::class);
    }

    /**
     * Get the leader (user) through the leadership history.
     *
     * Chain: leadership_achievements.leadership_history_id
     *        → leadership_histories.id
     *        → leadership_histories.user_id → users.id
     *
     * hasOneThrough(FinalModel, IntermediateModel, firstKey, secondKey, localKey, secondLocalKey)
     *   firstKey      = FK on intermediate table pointing back to this model's table
     *   secondKey     = FK on final table (users.id is PK, so we use 'id')
     *   localKey      = this model's key used to match firstKey
     *   secondLocalKey = intermediate model's key used to match secondKey
     *
     * @return \Illuminate\Database\Eloquent\Relations\HasOneThrough
     */
    public function leader()
    {
        return $this->hasOneThrough(
            User::class,              // Final model
            LeadershipHistory::class, // Intermediate model
            'id',                     // FK on leadership_histories matching localKey below
            'id',                     // FK on users (PK)
            'leadership_history_id',  // Local key on leadership_achievements
            'user_id'                 // Key on leadership_histories pointing to users
        );
    }

    /**
     * Get formatted achievement date.
     *
     * @return string
     */
    public function getFormattedDateAttribute(): string
    {
        return $this->achievement_date->format('F j, Y');
    }

    /**
     * Scope to order by achievement date.
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @param string $direction
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeOrderByDate($query, string $direction = 'desc')
    {
        return $query->orderBy('achievement_date', $direction);
    }
}
