buckets/tests/Unit/PipelineAllocationServiceTest.php

<?php

namespace Tests\Unit;

use App\Enums\BucketAllocationTypeEnum;
use App\Enums\BucketTypeEnum;
use App\Models\Bucket;
use App\Models\Scenario;
use App\Services\Projection\PipelineAllocationService;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class PipelineAllocationServiceTest extends TestCase
{
    use RefreshDatabase;

    private PipelineAllocationService $service;

    private Scenario $scenario;

    protected function setUp(): void
    {
        parent::setUp();
        $this->service = new PipelineAllocationService;
        $this->scenario = Scenario::factory()->create();
    }

    // ──────────────────────────────────────────────────────
    // Guard clauses
    // ──────────────────────────────────────────────────────

    public function test_returns_empty_collection_when_no_buckets(): void
    {
        $draws = $this->service->allocateInflow($this->scenario, 100000);

        $this->assertEmpty($draws);
    }

    public function test_returns_empty_collection_when_amount_is_zero(): void
    {
        $this->createNeedBucket(50000, priority: 1);

        $draws = $this->service->allocateInflow($this->scenario, 0);

        $this->assertEmpty($draws);
    }

    public function test_returns_empty_collection_when_amount_is_negative(): void
    {
        $this->createNeedBucket(50000, priority: 1);

        $draws = $this->service->allocateInflow($this->scenario, -10000);

        $this->assertEmpty($draws);
    }

    // ──────────────────────────────────────────────────────
    // Even mode — base phase
    // ──────────────────────────────────────────────────────

    public function test_even_mode_splits_evenly_across_need_buckets(): void
    {
        // 3 need buckets, $500 base each, $900 income → $300 each
        $b1 = $this->createNeedBucket(50000, priority: 1);
        $b2 = $this->createNeedBucket(50000, priority: 2);
        $b3 = $this->createNeedBucket(50000, priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 90000);

        $this->assertCount(3, $draws);
        $this->assertDrawAmount($draws, $b1->id, 30000);
        $this->assertDrawAmount($draws, $b2->id, 30000);
        $this->assertDrawAmount($draws, $b3->id, 30000);
    }

    public function test_even_mode_redistributes_when_bucket_fills_up(): void
    {
        // Bucket A: $200 base, Bucket B: $500 base, Bucket C: $500 base
        // $900 income → even share = $300 each → A caps at $200, excess $100 redistributed
        // B and C get $300 + $50 = $350 each
        $a = $this->createNeedBucket(20000, priority: 1);
        $b = $this->createNeedBucket(50000, priority: 2);
        $c = $this->createNeedBucket(50000, priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 90000);

        $this->assertCount(3, $draws);
        $this->assertDrawAmount($draws, $a->id, 20000);
        $this->assertDrawAmount($draws, $b->id, 35000);
        $this->assertDrawAmount($draws, $c->id, 35000);
    }

    public function test_even_mode_needs_filled_before_wants(): void
    {
        // 2 need buckets ($500 base each), 1 want bucket ($500 base)
        // $800 income → needs get $400 each (even split), wants get $0
        $n1 = $this->createNeedBucket(50000, priority: 1);
        $n2 = $this->createNeedBucket(50000, priority: 2);
        $w1 = $this->createWantBucket(50000, priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 80000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n1->id, 40000);
        $this->assertDrawAmount($draws, $n2->id, 40000);
    }

    public function test_even_mode_wants_filled_after_needs_base(): void
    {
        // 1 need ($300 base), 2 wants ($500 base each)
        // $1000 income → need gets $300 (base), wants split remaining $700 = $350 each
        $n = $this->createNeedBucket(30000, priority: 1);
        $w1 = $this->createWantBucket(50000, priority: 2);
        $w2 = $this->createWantBucket(50000, priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 100000);

        $this->assertCount(3, $draws);
        $this->assertDrawAmount($draws, $n->id, 30000);
        $this->assertDrawAmount($draws, $w1->id, 35000);
        $this->assertDrawAmount($draws, $w2->id, 35000);
    }

    public function test_even_mode_remainder_cents_go_to_highest_priority(): void
    {
        // 3 need buckets, $500 base each, $100 income → $33/$33/$34 or similar
        // intdiv(10000, 3) = 3333, remainder = 1 → first bucket gets 3334
        $b1 = $this->createNeedBucket(50000, priority: 1);
        $b2 = $this->createNeedBucket(50000, priority: 2);
        $b3 = $this->createNeedBucket(50000, priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 10000);

        $this->assertCount(3, $draws);
        $this->assertDrawAmount($draws, $b1->id, 3334);
        $this->assertDrawAmount($draws, $b2->id, 3333);
        $this->assertDrawAmount($draws, $b3->id, 3333);
    }

    public function test_even_mode_fewer_cents_than_buckets(): void
    {
        // 3 need buckets, 2 cents income → first 2 get 1 cent each, third gets nothing
        $b1 = $this->createNeedBucket(50000, priority: 1);
        $b2 = $this->createNeedBucket(50000, priority: 2);
        $b3 = $this->createNeedBucket(50000, priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 2);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $b1->id, 1);
        $this->assertDrawAmount($draws, $b2->id, 1);
    }

    // ──────────────────────────────────────────────────────
    // Priority mode — base phase
    // ──────────────────────────────────────────────────────

    public function test_priority_mode_fills_highest_priority_first(): void
    {
        $scenario = Scenario::factory()->priority()->create();

        $n1 = $this->createNeedBucket(50000, priority: 1, scenarioId: $scenario->id);
        $n2 = $this->createNeedBucket(50000, priority: 2, scenarioId: $scenario->id);
        $w1 = $this->createWantBucket(50000, priority: 3, scenarioId: $scenario->id);

        // $800 → need1 gets $500, need2 gets $300, want gets $0
        $draws = $this->service->allocateInflow($scenario, 80000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n1->id, 50000);
        $this->assertDrawAmount($draws, $n2->id, 30000);
    }

    public function test_priority_mode_needs_before_wants(): void
    {
        $scenario = Scenario::factory()->priority()->create();

        $n1 = $this->createNeedBucket(50000, priority: 1, scenarioId: $scenario->id);
        $n2 = $this->createNeedBucket(30000, priority: 2, scenarioId: $scenario->id);
        $w1 = $this->createWantBucket(50000, priority: 3, scenarioId: $scenario->id);

        // $1000 → need1 $500, need2 $300, want1 gets remaining $200
        $draws = $this->service->allocateInflow($scenario, 100000);

        $this->assertCount(3, $draws);
        $this->assertDrawAmount($draws, $n1->id, 50000);
        $this->assertDrawAmount($draws, $n2->id, 30000);
        $this->assertDrawAmount($draws, $w1->id, 20000);
    }

    // ──────────────────────────────────────────────────────
    // Buffer phases
    // ──────────────────────────────────────────────────────

    public function test_base_filled_before_buffer(): void
    {
        // Need: $500 base, 0.5x buffer → $750 effective capacity
        // $2000 income → base phase: $500, buffer phase: $250, overflow: $1250
        $n = $this->createNeedBucket(50000, priority: 1, buffer: 0.5);
        $overflow = $this->createOverflowBucket(priority: 2);

        $draws = $this->service->allocateInflow($this->scenario, 200000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n->id, 75000); // base $500 + buffer $250
        $this->assertDrawAmount($draws, $overflow->id, 125000);
    }

    public function test_need_buffer_filled_before_want_buffer(): void
    {
        // Need: $500 base, 1x buffer → $1000 effective
        // Want: $500 base, 1x buffer → $1000 effective
        // $1800 → need base $500, want base $500, need buffer $500, want gets $300 buffer
        $n = $this->createNeedBucket(50000, priority: 1, buffer: 1.0);
        $w = $this->createWantBucket(50000, priority: 2, buffer: 1.0);

        $draws = $this->service->allocateInflow($this->scenario, 180000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n->id, 100000); // full: base + buffer
        $this->assertDrawAmount($draws, $w->id, 80000);  // base $500 + $300 buffer
    }

    public function test_priority_mode_buffer_fills_by_priority(): void
    {
        $scenario = Scenario::factory()->priority()->create();

        // Need1: $300 base, 1x buffer → $600 effective
        // Need2: $300 base, 1x buffer → $600 effective
        // $1000 income
        $n1 = $this->createNeedBucket(30000, priority: 1, buffer: 1.0, scenarioId: $scenario->id);
        $n2 = $this->createNeedBucket(30000, priority: 2, buffer: 1.0, scenarioId: $scenario->id);

        $draws = $this->service->allocateInflow($scenario, 100000);

        // Phase 1 (needs base, priority): n1=$300, n2=$300, remaining=$400
        // Phase 3 (needs buffer, priority): n1 buffer=$300, n2 gets $100, remaining=$0
        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n1->id, 60000); // full base + full buffer
        $this->assertDrawAmount($draws, $n2->id, 40000); // full base + $100 buffer
    }

    public function test_no_buffer_when_multiplier_is_zero(): void
    {
        // Need: $500 base, 0x buffer → $500 effective
        // $800 → need gets $500, overflow gets $300
        $n = $this->createNeedBucket(50000, priority: 1, buffer: 0);
        $overflow = $this->createOverflowBucket(priority: 2);

        $draws = $this->service->allocateInflow($this->scenario, 80000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n->id, 50000);
        $this->assertDrawAmount($draws, $overflow->id, 30000);
    }

    public function test_partially_filled_bucket_respects_existing_balance(): void
    {
        // Need: $500 base, already has $300 → only $200 space in base phase
        $n = $this->createNeedBucket(50000, priority: 1, startingAmount: 30000);
        $overflow = $this->createOverflowBucket(priority: 2);

        $draws = $this->service->allocateInflow($this->scenario, 80000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n->id, 20000);
        $this->assertDrawAmount($draws, $overflow->id, 60000);
    }

    // ──────────────────────────────────────────────────────
    // Overflow
    // ──────────────────────────────────────────────────────

    public function test_overflow_captures_remainder(): void
    {
        $n = $this->createNeedBucket(30000, priority: 1);
        $overflow = $this->createOverflowBucket(priority: 2);

        $draws = $this->service->allocateInflow($this->scenario, 100000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n->id, 30000);
        $this->assertDrawAmount($draws, $overflow->id, 70000);
    }

    public function test_all_buckets_full_everything_to_overflow(): void
    {
        $n = $this->createNeedBucket(10000, priority: 1, startingAmount: 10000); // already full
        $w = $this->createWantBucket(10000, priority: 2, startingAmount: 10000); // already full
        $overflow = $this->createOverflowBucket(priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 50000);

        $this->assertCount(1, $draws);
        $this->assertDrawAmount($draws, $overflow->id, 50000);
    }

    // ──────────────────────────────────────────────────────
    // Edge cases
    // ──────────────────────────────────────────────────────

    public function test_no_need_buckets_goes_straight_to_wants(): void
    {
        $w1 = $this->createWantBucket(50000, priority: 1);
        $w2 = $this->createWantBucket(50000, priority: 2);

        $draws = $this->service->allocateInflow($this->scenario, 60000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $w1->id, 30000);
        $this->assertDrawAmount($draws, $w2->id, 30000);
    }

    public function test_single_need_bucket_gets_all_up_to_capacity(): void
    {
        $n = $this->createNeedBucket(50000, priority: 1);

        $draws = $this->service->allocateInflow($this->scenario, 30000);

        $this->assertCount(1, $draws);
        $this->assertDrawAmount($draws, $n->id, 30000);
    }

    public function test_allocates_to_single_need_bucket_with_buffer(): void
    {
        // $500 base, 1x buffer → $1000 effective, $1000 income → gets all
        $n = $this->createNeedBucket(50000, priority: 1, buffer: 1.0);

        $draws = $this->service->allocateInflow($this->scenario, 100000);

        $this->assertCount(1, $draws);
        $this->assertDrawAmount($draws, $n->id, 100000);
    }

    public function test_skips_buckets_with_zero_allocation_value(): void
    {
        $zero = $this->createNeedBucket(0, priority: 1);
        $normal = $this->createNeedBucket(30000, priority: 2);

        $draws = $this->service->allocateInflow($this->scenario, 20000);

        $this->assertCount(1, $draws);
        $this->assertDrawAmount($draws, $normal->id, 20000);
    }

    public function test_non_fixed_limit_buckets_are_skipped_in_phases(): void
    {
        // Percentage bucket as need → gets nothing (no meaningful cap in phased distribution)
        Bucket::factory()->create([
            'scenario_id' => $this->scenario->id,
            'type' => BucketTypeEnum::NEED,
            'allocation_type' => BucketAllocationTypeEnum::PERCENTAGE,
            'allocation_value' => 2500,
            'starting_amount' => 0,
            'priority' => 1,
        ]);
        $overflow = $this->createOverflowBucket(priority: 2);

        $draws = $this->service->allocateInflow($this->scenario, 50000);

        $this->assertCount(1, $draws);
        $this->assertDrawAmount($draws, $overflow->id, 50000);
    }

    public function test_surplus_is_lost_when_no_overflow_bucket(): void
    {
        // $500 income, only $300 capacity → $200 surplus has nowhere to go
        $n = $this->createNeedBucket(30000, priority: 1);

        $draws = $this->service->allocateInflow($this->scenario, 50000);

        $this->assertCount(1, $draws);
        $this->assertDrawAmount($draws, $n->id, 30000);
        // Remaining $200 is silently dropped — no overflow bucket to catch it
    }

    public function test_priority_order_respected_regardless_of_creation_order(): void
    {
        $scenario = Scenario::factory()->priority()->create();

        // Create in reverse priority order
        $b3 = $this->createNeedBucket(10000, priority: 10, scenarioId: $scenario->id);
        $b1 = $this->createNeedBucket(20000, priority: 1, scenarioId: $scenario->id);
        $b2 = $this->createNeedBucket(15000, priority: 5, scenarioId: $scenario->id);

        $draws = $this->service->allocateInflow($scenario, 25000);

        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $b1->id, 20000);
        $this->assertDrawAmount($draws, $b2->id, 5000);
    }

    // ──────────────────────────────────────────────────────
    // Full pipeline integration
    // ──────────────────────────────────────────────────────

    public function test_full_pipeline_even_mode(): void
    {
        // Need1: $500 base, 0.5x buffer → $750 effective
        // Need2: $200 base, no buffer → $200 effective
        // Want1: $400 base, no buffer → $400 effective
        // Overflow
        // $900 income — not enough to fill everything
        $n1 = $this->createNeedBucket(50000, priority: 1, buffer: 0.5);
        $n2 = $this->createNeedBucket(20000, priority: 2);
        $w1 = $this->createWantBucket(40000, priority: 3);
        $overflow = $this->createOverflowBucket(priority: 4);

        $draws = $this->service->allocateInflow($this->scenario, 90000);

        // Phase 1 (needs base, even): n1=$500 (capped), n2=$200 (capped), remaining=$200
        // Phase 2 (wants base, even): w1=$200 (partial of $400), remaining=$0

        $this->assertCount(3, $draws);
        $this->assertDrawAmount($draws, $n1->id, 50000);  // $500 base
        $this->assertDrawAmount($draws, $n2->id, 20000);  // $200 base
        $this->assertDrawAmount($draws, $w1->id, 20000);  // partial $200 of $400
    }

    public function test_full_pipeline_priority_mode(): void
    {
        $scenario = Scenario::factory()->priority()->create();

        // Need1: $500 base, 0.5x buffer → $750 effective
        // Need2: $400 base, no buffer → $400 effective
        // Want1: $300 base, no buffer → $300 effective
        // Overflow
        // $600 income — not enough to fill all need bases
        $n1 = $this->createNeedBucket(50000, priority: 1, buffer: 0.5, scenarioId: $scenario->id);
        $n2 = $this->createNeedBucket(40000, priority: 2, scenarioId: $scenario->id);
        $w1 = $this->createWantBucket(30000, priority: 3, scenarioId: $scenario->id);
        $overflow = $this->createOverflowBucket(priority: 4, scenarioId: $scenario->id);

        $draws = $this->service->allocateInflow($scenario, 60000);

        // Phase 1 (needs base, priority): n1=$500, n2=$100, remaining=$0
        // Even mode would split $600/2=$300 each — priority concentrates on n1 first
        $this->assertCount(2, $draws);
        $this->assertDrawAmount($draws, $n1->id, 50000);
        $this->assertDrawAmount($draws, $n2->id, 10000);
    }

    public function test_even_and_priority_modes_produce_different_results(): void
    {
        // 2 need buckets: $500 and $300 base, $600 income
        // Even: $300 each → both fit. n1=$300, n2=$300.
        // Priority: n1 gets $500, n2 gets $100.
        $n1Even = $this->createNeedBucket(50000, priority: 1);
        $n2Even = $this->createNeedBucket(30000, priority: 2);

        $evenDraws = $this->service->allocateInflow($this->scenario, 60000);

        $this->assertCount(2, $evenDraws);
        $this->assertDrawAmount($evenDraws, $n1Even->id, 30000); // even: $300 each
        $this->assertDrawAmount($evenDraws, $n2Even->id, 30000);

        // Same setup with priority mode
        $priorityScenario = Scenario::factory()->priority()->create();
        $n1Prio = $this->createNeedBucket(50000, priority: 1, scenarioId: $priorityScenario->id);
        $n2Prio = $this->createNeedBucket(30000, priority: 2, scenarioId: $priorityScenario->id);

        $prioDraws = $this->service->allocateInflow($priorityScenario, 60000);

        $this->assertCount(2, $prioDraws);
        $this->assertDrawAmount($prioDraws, $n1Prio->id, 50000); // priority: fills first
        $this->assertDrawAmount($prioDraws, $n2Prio->id, 10000); // gets remainder
    }

    public function test_full_pipeline_flows_through_all_five_phases(): void
    {
        // Need: $200 base, 1x buffer → $400 effective
        // Want: $100 base, 1x buffer → $200 effective
        // Overflow
        // $800 income → enough to fill everything and hit overflow
        $n = $this->createNeedBucket(20000, priority: 1, buffer: 1.0);
        $w = $this->createWantBucket(10000, priority: 2, buffer: 1.0);
        $overflow = $this->createOverflowBucket(priority: 3);

        $draws = $this->service->allocateInflow($this->scenario, 80000);

        // Phase 1 (needs base): n=$200, remaining=$600
        // Phase 2 (wants base): w=$100, remaining=$500
        // Phase 3 (needs buffer): n=$200 buffer, remaining=$300
        // Phase 4 (wants buffer): w=$100 buffer, remaining=$200
        // Phase 5 (overflow): $200
        $this->assertCount(3, $draws);
        $this->assertDrawAmount($draws, $n->id, 40000);       // $200 base + $200 buffer
        $this->assertDrawAmount($draws, $w->id, 20000);       // $100 base + $100 buffer
        $this->assertDrawAmount($draws, $overflow->id, 20000); // remainder
    }

    // ──────────────────────────────────────────────────────
    // Helpers
    // ──────────────────────────────────────────────────────

    private function createNeedBucket(
        int $allocationValue,
        int $priority,
        float $buffer = 0,
        int $startingAmount = 0,
        ?int $scenarioId = null,
    ): Bucket {
        return Bucket::factory()->need()->fixedLimit($allocationValue)->create([
            'scenario_id' => $scenarioId ?? $this->scenario->id,
            'priority' => $priority,
            'buffer_multiplier' => $buffer,
            'starting_amount' => $startingAmount,
        ]);
    }

    private function createWantBucket(
        int $allocationValue,
        int $priority,
        float $buffer = 0,
        int $startingAmount = 0,
        ?int $scenarioId = null,
    ): Bucket {
        return Bucket::factory()->want()->fixedLimit($allocationValue)->create([
            'scenario_id' => $scenarioId ?? $this->scenario->id,
            'priority' => $priority,
            'buffer_multiplier' => $buffer,
            'starting_amount' => $startingAmount,
        ]);
    }

    private function createOverflowBucket(int $priority, ?int $scenarioId = null): Bucket
    {
        return Bucket::factory()->overflow()->create([
            'scenario_id' => $scenarioId ?? $this->scenario->id,
            'priority' => $priority,
        ]);
    }

    private function assertDrawAmount($draws, int $bucketId, int $expectedAmount): void
    {
        $draw = $draws->first(fn ($d) => $d->bucket_id === $bucketId);
        $this->assertNotNull($draw, "No draw found for bucket {$bucketId}");
        $this->assertEquals($expectedAmount, $draw->amount, "Draw amount mismatch for bucket {$bucketId}");
    }
}