City10/app/Models/User.php

<?php

namespace App\Models;

use Database\Factories\UserFactory;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\HasOne;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

/**
 * Application user entity.
 *
 * Supports role based access control (admin/user) and records the
 * acceptance of versioned legal documents (Terms, Privacy, Cookies)
 * required by the Brazilian LGPD.
 */
#[Fillable(['name', 'email', 'password', 'role', 'status', 'locale', 'is_active'])]
#[Hidden(['password', 'remember_token'])]
class User extends Authenticatable
{
    /** @use HasFactory<UserFactory> */
    use HasApiTokens, HasFactory, Notifiable;

    /**
     * Role granted to platform administrators.
     *
     * @var string
     */
    public const ROLE_ADMIN = 'admin';

    /**
     * Role granted to regular citizens of the virtual city.
     *
     * @var string
     */
    public const ROLE_USER = 'user';

    /**
     * Account registered but not yet approved by an administrator.
     *
     * @var string
     */
    public const STATUS_PENDING = 'pending';

    /**
     * Account approved and able to enter the platform.
     *
     * @var string
     */
    public const STATUS_ACTIVE = 'active';

    /**
     * Account blocked by an administrator.
     *
     * @var string
     */
    public const STATUS_BANNED = 'banned';

    /**
     * In-world character belonging to this user.
     *
     * @return HasOne<Character, $this>
     */
    public function character(): HasOne
    {
        return $this->hasOne(Character::class);
    }

    /**
     * Stores owned by this user.
     *
     * @return HasMany<Store, $this>
     */
    public function stores(): HasMany
    {
        return $this->hasMany(Store::class, 'owner_id');
    }

    /**
     * Legal consents recorded for this user.
     *
     * @return HasMany<UserConsent, $this>
     */
    public function consents(): HasMany
    {
        return $this->hasMany(UserConsent::class);
    }

    /**
     * Legal documents this user has accepted.
     *
     * @return BelongsToMany<LegalDocument, $this>
     */
    public function acceptedDocuments(): BelongsToMany
    {
        return $this->belongsToMany(LegalDocument::class, 'user_consents')
            ->withPivot(['accepted_at', 'ip_address', 'user_agent', 'source'])
            ->withTimestamps();
    }

    /**
     * Determine whether the user holds administrator privileges.
     */
    public function isAdmin(): bool
    {
        return $this->role === self::ROLE_ADMIN;
    }

    /**
     * Determine whether the account has been approved by an administrator.
     */
    public function isApproved(): bool
    {
        return $this->status === self::STATUS_ACTIVE;
    }

    /**
     * Check whether the user accepted every current legal document version.
     */
    public function hasAcceptedCurrentTerms(): bool
    {
        $currentIds = LegalDocument::query()->where('is_current', true)->pluck('id');

        if ($currentIds->isEmpty()) {
            return true;
        }

        $acceptedIds = $this->consents()->pluck('legal_document_id');

        return $currentIds->diff($acceptedIds)->isEmpty();
    }

    /**
     * Keep the legacy is_active flag mirrored from status on save.
     */
    protected static function booted(): void
    {
        static::saving(function (self $user): void {
            $user->is_active = $user->status === self::STATUS_ACTIVE;
        });
    }

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