buckets/app/Models/Bucket.php

<?php

namespace App\Models;

use App\Enums\BucketAllocationType;
use Database\Factories\BucketFactory;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;

/**
 * @property int $scenario_id
 * @property Scenario $scenario
 * @property string $name
 * @property int $priority
 */
class Bucket extends Model
{
    /** @use HasFactory<BucketFactory> */
    use HasFactory;

    protected $fillable = [
        'scenario_id',
        'name',
        'priority',
        'sort_order',
        'allocation_type',
        'allocation_value',
    ];

    protected $casts = [
        'priority' => 'integer',
        'sort_order' => 'integer',
        'allocation_value' => 'decimal:2',
    ];

    public function scenario(): BelongsTo
    {
        return $this->belongsTo(Scenario::class);
    }

    /**
     * Get the draws for the bucket.
     * (Will be implemented when Draw model is created)
     */
    public function draws(): HasMany
    {
        // TODO: Implement when Draw model is created
        return $this->hasMany(Draw::class);
    }

    /**
     * Get the outflows for the bucket.
     * (Will be implemented when Outflow model is created)
     */
    public function outflows(): HasMany
    {
        // TODO: Implement when Outflow model is created
        return $this->hasMany(Outflow::class);
    }

    /**
     * Scope to get buckets ordered by priority.
     */
    public function scopeOrderedByPriority($query)
    {
        return $query->orderBy('priority');
    }

    /**
     * Scope to get buckets ordered by sort order for UI display.
     */
    public function scopeOrderedBySortOrder($query)
    {
        return $query->orderBy('sort_order')->orderBy('priority');
    }

    /**
     * Get the current balance of the bucket.
     * For MVP, this will always return 0 as we don't have transactions yet.
     */
    public function getCurrentBalance(): float
    {
        // TODO: Calculate from draws minus outflows when those features are implemented
        return 0.0;
    }

    /**
     * Check if the bucket can accept more money (for fixed_limit buckets).
     */
    public function hasAvailableSpace(): bool
    {
        if ($this->allocation_type !== BucketAllocationType::FIXED_LIMIT) {
            return true;
        }

        return $this->getCurrentBalance() < $this->allocation_value;
    }

    /**
     * Get available space for fixed_limit buckets.
     */
    public function getAvailableSpace(): float
    {
        if ($this->allocation_type !== BucketAllocationType::FIXED_LIMIT) {
            return PHP_FLOAT_MAX;
        }

        return max(0, $this->allocation_value - $this->getCurrentBalance());
    }

    /**
     * Get display label for allocation type.
     */
    public function getAllocationTypeLabel(): string
    {
        return $this->allocation_type->getLabel();
    }

    /**
     * Get formatted allocation value for display.
     */
    public function getFormattedAllocationValue(): string
    {
        return $this->allocation_type->formatValue($this->allocation_value);
    }

    /**
     * Validation rules for bucket creation/update.
     */
    public static function validationRules($scenarioId = null): array
    {
        $rules = [
            'name' => 'required|string|max:255',
            'allocation_type' => 'required|in:' . implode(',', BucketAllocationType::values()),
            'priority' => 'required|integer|min:1',
        ];

        // Add scenario-specific priority uniqueness if scenario ID provided
        if ($scenarioId) {
            $rules['priority'] .= '|unique:buckets,priority,NULL,id,scenario_id,' . $scenarioId;
        }

        return $rules;
    }

    /**
     * Get allocation value validation rules based on type.
     */
    public static function allocationValueRules(BucketAllocationType $allocationType): array
    {
        return $allocationType->getAllocationValueRules();
    }
}