<?

php

namespace App\Models;

// use Illuminate\Contracts\Auth\MustVerifyEmail;
use App\Enums\UserRole;
use Carbon\Carbon;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\MorphMany;
use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

/**
* Class User
*
* Represents a user in the system, with roles and authentication capabilities.
* Supports soft deletes, UUIDs, and polymorphic notes and comments.
*
* @property string $id UUID identifier for the user record
* @property string $code Unique auto-generated code (e.g., USR-00001)
* @property string $first_name First name of the user
* @property string|null $middle_name Middle name of the user
* @property string|null $last_name Last name of the user
* @property string $username Unique username for authentication
* @property string|null $email Unique email address
* @property string $phone_number Unique phone number
* @property string $password Hashed password
* @property Carbon|null $phone_verified_at Timestamp when phone was verified
* @property Carbon|null $email_verified_at Timestamp when email was verified
* @property Carbon|null $password_changed_at Timestamp when password was last
changed
* @property UserRole $role Role of the user (e.g., EMPLOYEE, MANAGER)
* @property string|null $remember_token Token for "remember me" functionality
* @property Carbon $created_at Timestamp when the record was created
* @property Carbon $updated_at Timestamp when the record was last updated
* @property Carbon|null $deleted_at Timestamp when the record was soft-deleted
*
* @property-read Collection|Contract[] $contracts Contracts associated with this
user
* @property-read Collection|Project[] $managedProjects Projects managed by this
user
* @property-read Collection|Project[] $projects Projects this user is assigned to
via ProjectUser
* @property-read Collection|ProjectUser[] $projectUsers Pivot records linking this
user to projects
* @property-read Collection|Note[] $notes Notes attached to this user
* @property-read Collection|Comment[] $comments Comments attached to this user
*/
class User extends Authenticatable
{
use HasApiTokens, HasFactory, HasUuids, Notifiable, SoftDeletes;
protected $fillable = [
'code',
'first_name',
'middle_name',
'last_name',
'username',
'email',
'phone_number',
'password',
'phone_verified_at',
'email_verified_at',
'password_changed_at',
'role',
];

/**
* The attributes that should be hidden for serialization.
*
* @var list<string>
*/
protected $hidden = [
'password',
'remember_token',
];

/**
* Get the user's full name, with middle name if available.
*
* Usage:
* <pre>
* $user = User::factory()->create();
* $user->full_name; // "John Doe" or "John M Doe"
* </pre>
*/
public function getFullNameAttribute(): string
{
return trim("{$this->first_name} {$this->middle_name} {$this->last_name}");
}

/**
* Scope a query to only include users with a given code.
*
* @return Builder
*
* Example: User::code('USER-001')->first()
*
**/
public function scopeCode($query, string $code): Builder
{
return $query->where('code', $code);
}

/**
* Notes associated with this record as a notable entity.
* Get the notes attached to this user record.
*/
public function notes(): MorphMany
{
 return $this->morphMany(Note::class, 'notable');
}

/**
* Comments associated with this record as a commentable entity.
* Get the comments attached to this user record.
*/
public function comments(): MorphMany
{
return $this->morphMany(Comment::class, 'commentable');
}

/**
* Get the contracts associated with this user.
*
* @return HasMany
*/
public function contracts(): HasMany
{
return $this->hasMany(Contract::class);
}

/**
* Get the projects managed by this user.
*
* @return HasMany
*/
public function managedProjects(): HasMany
{
return $this->hasMany(Project::class, 'manager_id');
}

/**
* Get the projects this user is assigned to.
*
* @return BelongsToMany
*/
public function projects(): BelongsToMany
{
return $this->belongsToMany(Project::class, 'project_users')
->using(ProjectUser::class)
->withPivot(['id', 'code', 'approval_status', 'is_locked', 'locked_by',
'created_by', 'updated_by'])
->withTimestamps();
}

/**
* Get the pivot records linking this user to projects.
*
* @return HasMany
*/
public function projectUsers(): HasMany
{
return $this->hasMany(ProjectUser::class);
}

/**
* Get the attributes that should be cast.
*
 * @return array<string, string>
*/
protected function casts(): array
{
return [
'email_verified_at' => 'datetime',
'password' => 'hashed',
'phone_verified_at' => 'datetime',
'password_changed_at' => 'datetime',
'role' => UserRole::class,
];
}