lti-api/docs/farm_stock_attribution_design.md

Farm Stock Attribution Design Note

Goal

Allow farm-level physical stock to be used directly by kandang-level operations without forcing transfers, while keeping kandang attribution, FIFO-v2 compatibility, traceability, and HPP/COGS intact.

Core Model

• Physical stock stays on the real product_warehouse_id that was consumed or received.
• Kandang attribution comes from the transaction or allocation path, not from product_warehouses.project_flock_kandang_id.
• Existing kandang-bound warehouses remain valid for historical and current kandang-only flows.
• Shared farm warehouses must stay shareable; application code must stop silently converting them into kandang-owned warehouses.

Attribution Rules

• recording_stocks: consumer kandang is the parent recordings.project_flock_kandangs_id; physical stock source remains recording_stocks.product_warehouse_id.
• recording_depletions: source kandang is the recording kandang and is stored explicitly for compatibility; physical source remains source_product_warehouse_id, destination stock remains product_warehouse_id.
• recording_eggs: producer kandang is the recording kandang and is stored explicitly for compatibility; physical stock remains product_warehouse_id, which may be a farm warehouse.
• marketing_delivery_products: outbound kandang attribution comes from active stock_allocations to PROJECT_FLOCK_POPULATION, RECORDING_DEPLETION, or RECORDING_EGG, with product-warehouse kandang ownership only as a fallback for historical/non-FIFO rows.

Reporting and HPP

• Feed and OVK cost attribution should continue to follow recording-level consumption plus FIFO allocations to incoming stock.
• Egg and live-bird sales attribution should be derived from stock_allocations back to the originating kandang transactions or populations.
• Queries that filter or group by kandang must use explicit transaction attribution or FIFO allocation provenance, not warehouse ownership, when pooled farm stock is involved.

Live-Data Safety

• Schema changes are additive and nullable.
• Historical rows are backfilled only when attribution is deterministic from existing rows.
• No FIFO-v2 route-rule behavior is changed unless the current code is only resyncing or constraining allocation metadata around already-created FIFO allocations.