lti-api/internal/common/service/fifo_stock_v2/RFC.md

RFC Ringkas: FIFO Stock V2

Tujuan

fifo_stock_v2 adalah engine FIFO baru berbasis konfigurasi Flag Group + Jalur yang berjalan paralel dengan v1 tanpa memutus kompatibilitas stock_allocations, HPP, dan closing/reporting existing.

Prinsip

• V1 tidak dihapus, V2 jalan paralel.
• Semua operasi transactional.
• FIFO sorting deterministic lintas tabel.
• Default over-consume ALLOW (pending), exception dapat BLOCK.
• Reflow idempotent.
• Recalculate bisa memperbaiki drift product_warehouses.qty.

Komponen

• fifo_stock_v2_flag_groups: master grouping flag produk.
• fifo_stock_v2_flag_members: pemetaan flag -> group.
• fifo_stock_v2_traits: trait sort per table:date_column (+ optional join date source).
• fifo_stock_v2_route_rules: rule per flag_group + lane + function + table.
• fifo_stock_v2_overconsume_rules: policy pending/over-consume.
• fifo_stock_v2_operation_log: idempotency + audit operasi.
• fifo_stock_v2_reflow_runs + checkpoints + shadow allocations: bulk reflow resumable/observable.

API Service

• Gather: union cross-table berdasarkan route rules + trait sorting.
• Allocate: alokasi lot FIFO ke usable.
• Rollback: batalkan alokasi aktif.
• Reflow: rollback penuh lalu allocate ulang (idempotent).
• Recalculate: rekonsiliasi qty warehouse dari ledger FIFO.

Deterministic Sorting

Urutan gather:

1. sort_at ASC (dari trait date_column)
2. sort_priority ASC
3. source_table ASC
4. source_id ASC

Fallback waktu: 1970-01-01 00:00:00+00 bila tanggal null.

Compat Strategy

• Tetap menulis ke stock_allocations dengan tambahan metadata:
  • engine_version (v1/v2)
  • flag_group_code
  • function_code
  • idempotency_key
• Query lama yang bergantung stockable_type/usable_type tetap berjalan.

Migration Strategy

1. Deploy schema + seed v2.
2. Aktifkan shadow-run comparator v1 vs v2.
3. Canary cutover per flag group.
4. Full cutover jika parity aman.
5. Jalankan bulk reflow existing data.

Acceptance Criteria Singkat

• Parity mismatch terkendali pada aggregate + detail alokasi.
• Tidak ada regression closing/HPP.
• Drift qty warehouse turun signifikan pasca reflow.
• Rollback via feature flag memungkinkan kembali ke v1.