Phased category-aware distribution with settings #17

New issue

Closed

opened 2026-03-21 16:20:44 +01:00 by myrmidex · 0 comments

myrmidex commented

2026-03-21 16:20:44 +01:00

Owner

Problem

Currently PipelineAllocationService distributes income in a single priority-ordered pass across all buckets, ignoring bucket type (need/want). The type field is purely cosmetic. Users need income to flow through categories in phases: needs first, then wants, then buffers, then overflow.

Distribution phases

Income flows through these phases in order:

Needs to base — fill all need buckets to their allocation_value
Wants to base — fill all want buckets to their allocation_value
Needs to buffer — fill need buckets to their buffered capacity (allocation_value * (1 + buffer_multiplier))
Wants to buffer — fill want buckets to their buffered capacity
Overflow — remainder goes to the overflow bucket

If money runs out at any phase, stop.

Division mode (per-scenario setting)

Within each phase, how money is split across buckets in the group:

Even split (default): each bucket in the group receives the same amount, up to its remaining capacity. If one fills up, redistribute its excess to the others.
Priority order: fill highest-priority bucket first to capacity, then the next, etc. (current behavior but scoped to the phase)

Scope

Scenario model: Add distribution_mode field (enum: even, priority, default even)
Migration: Add column to scenarios table
PipelineAllocationService: Rewrite allocation logic for phased category-aware distribution with configurable division mode
Settings UI: Add a scenario settings section explaining the two modes with clear descriptions
Tests: Cover both modes, all phases, edge cases (insufficient funds, empty categories, partial fills)
Preview endpoint: Should reflect the new logic automatically (already calls the service)

Acceptance criteria

Default (even): $3000 income with 3 need buckets ($500 each) → each gets $500, then wants phase starts
Priority mode: $800 income with 3 need buckets ($500 each, priorities 1/2/3) → bucket 1 gets $500, bucket 2 gets $300, bucket 3 gets $0
Buffers only fill after all base amounts in both categories are filled
Settings UI clearly explains the choice
Preview shows correct distribution per selected mode

## Problem Currently `PipelineAllocationService` distributes income in a single priority-ordered pass across all buckets, ignoring bucket type (need/want). The `type` field is purely cosmetic. Users need income to flow through categories in phases: needs first, then wants, then buffers, then overflow. ## Distribution phases Income flows through these phases in order: 1. **Needs to base** — fill all need buckets to their `allocation_value` 2. **Wants to base** — fill all want buckets to their `allocation_value` 3. **Needs to buffer** — fill need buckets to their buffered capacity (`allocation_value * (1 + buffer_multiplier)`) 4. **Wants to buffer** — fill want buckets to their buffered capacity 5. **Overflow** — remainder goes to the overflow bucket If money runs out at any phase, stop. ## Division mode (per-scenario setting) Within each phase, how money is split across buckets in the group: - **Even split** (default): each bucket in the group receives the same amount, up to its remaining capacity. If one fills up, redistribute its excess to the others. - **Priority order**: fill highest-priority bucket first to capacity, then the next, etc. (current behavior but scoped to the phase) ## Scope - **Scenario model**: Add `distribution_mode` field (enum: `even`, `priority`, default `even`) - **Migration**: Add column to scenarios table - **PipelineAllocationService**: Rewrite allocation logic for phased category-aware distribution with configurable division mode - **Settings UI**: Add a scenario settings section explaining the two modes with clear descriptions - **Tests**: Cover both modes, all phases, edge cases (insufficient funds, empty categories, partial fills) - **Preview endpoint**: Should reflect the new logic automatically (already calls the service) ## Acceptance criteria - Default (even): $3000 income with 3 need buckets ($500 each) → each gets $500, then wants phase starts - Priority mode: $800 income with 3 need buckets ($500 each, priorities 1/2/3) → bucket 1 gets $500, bucket 2 gets $300, bucket 3 gets $0 - Buffers only fill after all base amounts in both categories are filled - Settings UI clearly explains the choice - Preview shows correct distribution per selected mode