Phase 4 Wire-up Kickoff Plan — Imports (PO) + DCA + Optional Fees¶

Why a wire-up phase¶

Ivan's skeleton put the cost-engine and the schema in place but stopped at the service layer. After the skeleton merged, an operator still cannot:

1. Log a Purchase Order — no admin API, no UI; the import_batch rows exist in the DB but there is no way to create them outside psql / seed scripts.
2. See costs recalculate when fees arrive — recomputeBatchCosts is a workflow, but nothing triggers it automatically. A fee row inserted via raw SQL leaves the per-unit costs stale.
3. Hand off received units to Medusa inventory — the import_batch_item.qty_received column is set in code but never propagates to inventory_level.stocked_quantity. Units stay "bought but not sellable."
4. Capture late fees correctly — the merchant's actual workflow ("we may pay off the fees very late on and just want to log the Purchase Order first") needs an explicit batch_adjustment path so already-sold units pick up the COGS delta.

The wire-up phase closes that gap.

Scope: the three stated goals¶

The merchant locked three goals during 2026-05-15 scoping:

1. Purchase Order Module (Imports) — operators can create/edit/close POs from the dashboard.
2. DCA for Imports — per-unit landed cost recalculates automatically when fees / adjustments change.
3. Optional fees — POs can be logged (and even closed) before any fees are entered; late fees flow through correctly without manual rework on already-sold units.

These goals map to slices A–E + G below. Slice F (consolidation) and the other Phase 4 entities listed in data-model.md §4.2 (order_status_event, sales_channel_config, tcg_channel_listing.is_listed, the refund workflow split) are deferred — they are part of broader Phase 4 but do not block the three stated goals.

Design decisions¶

All three were locked via direct conversation with the merchant on 2026-05-15.

1. recomputeBatchCosts fires via Medusa subscriber (not from UI mutation handlers)¶

A subscriber listens to:

• import_batch_fee insert / update / delete
• batch_adjustment insert

…and calls recomputeBatchCosts(batch_id) automatically. The batch_id is read from the changed row.

This resolves the open question Ivan flagged in Phase 4 Findings §6.

2. Inventory hand-off is a manual operator button (not status-transition-driven)¶

A "Receive into inventory" button on the PO detail page pushes import_batch_item.qty_received into inventory_level.stocked_quantity for the linked Medusa variant. The button is gated on PO status being at least arrived.

The receive workflow is idempotent: clicking twice does not double-stock the warehouse (it writes the absolute qty_received, not a delta).

3. Fee-less PO close is allowed; "Fees pending" badge surfaces uncertainty¶

A PO can transition all the way to closed with zero import_batch_fee rows. The PO list view surfaces closed · fees pending as a visual badge so operators do not forget to log fees later.

When the late fee arrives weeks/months after close:

1. Operator opens the closed PO and adds the fee row.
2. The Decision-1 subscriber fires recomputeBatchCosts(batch_id).
3. For each import_batch_item on the batch, effective_cost_per_unit_sgd is rewritten.
4. For every already-sold unit (any batch_allocation row pointing at the batch's items), the recompute workflow auto-creates a batch_adjustment with reason=forgotten_fee and cost_delta_per_unit = new_cost − old_cost. This is what makes the late-fee story end-to-end correct — already-sold units' COGS picks up the delta without rewriting historical batch_allocation.cost_per_unit_at_allocation.

This matches the merchant's stated workflow verbatim: "we may pay off the fees very late on and just want to log the Purchase Order first."

Slice scope¶

Deferred (out of scope for this wire-up)¶

Open question deferred to Slice G¶

Which Q1 2026 batch is the spreadsheet-parity reference? Ivan's findings flagged this. Candidate criteria (per Phase 4 Findings §6):

• Closed status
• At least one import_batch_fee row
• At least one import_batch_contributor row
• No consolidation events (consolidation is deferred, so a batch that needed it would not parity-test cleanly)

Pick happens at Slice G time. Operator can scan Q1 2026 ExzenTCG - Imports.csv + ... - Additional Import Fees.csv once and call out the chosen batch number.

PR sequence¶

Slice B does not get its own PR — its scope (badge + late-fee adjustment) is split between PR-1 (the adjustment auto-creation) and PR-3 (the badge UI).

Anti-patterns (do not re-introduce)¶

• Don't write to batch_allocation.cost_per_unit_at_allocation after creation. That column is the audit-faithful snapshot of "what did the books say at sale time." Post-hoc corrections go through batch_adjustment rows; the recompute workflow handles the math.
• Don't store derived profit anywhere. computeOrderLineProfit is query-time on purpose. A profit column would drift the moment a batch_adjustment lands and would be impossible to keep correct under concurrent recomputes.
• Don't call recomputeBatchCosts from admin route handlers. Decision 1 picks subscribers; route handlers should mutate the underlying row and let the event-bus do the rest. Exception: the manual "Force recompute" button on the PO detail page is allowed and explicitly intended.
• Don't auto-fire inventory hand-off from a status-transition subscriber. Decision 2 keeps the receive step explicit. If the operator workflow becomes "click receive every time" → tedious, the right fix is a config flag, not a silent subscriber.
• Don't introduce a fees_expected: boolean column to gate PO close. Decision 3 rules this out — operator can close with zero fees and add them later; the badge surfaces the state without schema change.
• Don't move consolidation_event / order_status_event / sales_channel_config into this wire-up. They are explicitly deferred. If a slice's design starts pulling them in, that is a signal to stop and re-scope.

Exit criteria¶

The wire-up phase closes when:

1. Goal #1 working end-to-end: operator creates a PO from the dashboard, adds line items, transitions through draft → ordered → paid → in_transit → arrived, and clicks "Receive into inventory"; units appear in Medusa inventory_level.stocked_quantity and are sellable.
2. Goal #2 working end-to-end: operator adds a fee to a PO via the dashboard; recomputeBatchCosts fires automatically; the line items' effective_cost_per_unit_sgd reflects the new fee.
3. Goal #3 working end-to-end: operator closes a PO with no fees; PO list shows "Fees pending" badge; operator adds a fee weeks later; a batch_adjustment(reason=forgotten_fee) row is auto-created for any already-sold units on that batch.
4. Slice G parity test passes: the chosen Q1 2026 reference batch, when re-imported through the new admin flow, produces effective_cost_per_unit_sgd matching the spreadsheet's "Total Cost Per Unit (SGD)" column.

Implementation references¶

• Phase 4 Wire-up Implementation Plan — PR-by-PR file lists, test scope, and step-by-step.
• Phase 4 Findings — what the skeleton shipped + the three open questions this plan resolves.
• Data Model — column-level reference for the existing 7 tables + the deferred entities.
• Server module: apps/server/src/modules/dca/ — service.ts, services/cost-allocation-strategies.ts, the seven models, and the recompute-batch-costs workflow.
• Dashboard surfaces to create: apps/dashboard/app/(shell)/imports/ (new section, sibling to /orders and /connectors).