<?php

namespace App\Models;

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

/**
 * Stock transfer document. Moves inventory from one store to another.
 *
 * Status flow:
 *   `draft`      → editable, stock hasn't moved yet
 *   `in_transit` → stock deducted from source store, not yet received
 *   `received`   → stock added to destination store, document closed
 *   `cancelled`  → if was in_transit, reversal was posted; otherwise discarded
 *
 * Number format: `TRF-YYYY-NNNN`, per-year sequence. Generated by
 * {@see \App\Actions\Inventory\GenerateTransferNumber}.
 */
class StockTransfer extends Model
{
    public const STATUS_DRAFT      = 'draft';
    public const STATUS_IN_TRANSIT = 'in_transit';
    public const STATUS_RECEIVED   = 'received';
    public const STATUS_CANCELLED  = 'cancelled';

    protected $fillable = [
        'number', 'from_store_id', 'to_store_id',
        'transfer_date', 'expected_arrival_date', 'received_date',
        'status', 'notes',
        'created_by', 'updated_by',
    ];

    protected function casts(): array
    {
        return [
            'transfer_date'         => 'date',
            'expected_arrival_date' => 'date',
            'received_date'         => 'date',
        ];
    }

    public function isDraft(): bool     { return $this->status === self::STATUS_DRAFT; }
    public function isInTransit(): bool { return $this->status === self::STATUS_IN_TRANSIT; }
    public function isReceived(): bool  { return $this->status === self::STATUS_RECEIVED; }
    public function isCancelled(): bool { return $this->status === self::STATUS_CANCELLED; }

    /** @param Builder<StockTransfer> $q */
    public function scopeDraft(Builder $q): void      { $q->where('status', self::STATUS_DRAFT); }

    /** @param Builder<StockTransfer> $q */
    public function scopeInTransit(Builder $q): void  { $q->where('status', self::STATUS_IN_TRANSIT); }

    /** @param Builder<StockTransfer> $q */
    public function scopeReceived(Builder $q): void   { $q->where('status', self::STATUS_RECEIVED); }

    /** @param Builder<StockTransfer> $q */
    public function scopeCancelled(Builder $q): void  { $q->where('status', self::STATUS_CANCELLED); }

    /** @return BelongsTo<Store, $this> */
    public function fromStore(): BelongsTo
    {
        return $this->belongsTo(Store::class, 'from_store_id');
    }

    /** @return BelongsTo<Store, $this> */
    public function toStore(): BelongsTo
    {
        return $this->belongsTo(Store::class, 'to_store_id');
    }

    /** @return BelongsTo<User, $this> */
    public function creator(): BelongsTo
    {
        return $this->belongsTo(User::class, 'created_by');
    }

    /** @return BelongsTo<User, $this> */
    public function updater(): BelongsTo
    {
        return $this->belongsTo(User::class, 'updated_by');
    }

    /** @return HasMany<StockTransferItem, $this> */
    public function items(): HasMany
    {
        return $this->hasMany(StockTransferItem::class);
    }
}
