# Distributor Intelligence

React/TypeScript concept preview for Nordic Distribution, a fictional ChiaoGoo distributor serving Norway and Sweden. Published alongside Needle Supplier Intelligence. All commercial data, store names, distributor assignments and NOK prices are synthetic. No live integrations, order placement, reservations or outbound messaging.

## Views

- Overview: wholesale shipment value, confirmed incoming, store replenishment and supply exceptions.
- Incoming from ChiaoGoo: delivery line status, ETA, quantity, market allocation, NOK purchase value and the store proposals each receipt supports. Editable incoming scenarios update the whole workspace.
- Warehouse inventory: stock, reservations, free quantity, incoming and proposed allocation by market / exact variant.
- Suggested replenishment: store-specific calculations grouped by market and store. Editable target cover, safety and delivery lead time, store stock scenarios, transparent arithmetic, supply split and downloadable proposals.
- Store network: sharing coverage and direct navigation to each store's replenishment.

Both supplied logos, corrected favicon, typography, components and sticky tab navigation match the supplier dashboard. Mobile navigation scrolls horizontally. The supplier dashboard remains in USD; this distributor workspace uses NOK throughout.

## Calculation and allocation

Store daily demand = observed net retail units / observed days. Target = daily demand × (route lead + target cover + safety). Subtract available store stock (on hand minus reserved) and confirmed incoming due within lead + cover. Check delivery boundaries for intervening deficits; floor at zero, then apply MOQ and pack rounding. Show shortages before the route's normal arrival separately.

Evidence gates withhold calculations for stale/missing data, absent consent, invalid mappings, incomplete sales history, invalid quantities and overdue store receipts. Warehouse stock must also be valid and no older than three days before supply is allocated.

Allocate the calculated need across ALL stores before display filtering. Priority is the earliest projected physical stockout within each store's horizon, including its already-confirmed receipts; ties use the record ID. Each market / variant has a separate inventory allocation. Existing reservations are deducted once. Full packs are allocated first from free warehouse stock, then from confirmed/in-transit ChiaoGoo receipts due in 0–28 days. A receipt's remainder is shared once across stores. Sub-pack future receipts can combine; sub-pack on-hand leftovers are conservatively left unallocated. Missing warehouse evidence yields unverified supply, never a claimed zero balance.

Later supply is an indicative scenario: supplier ETA + store route lead. Store need is calculated at the normal route lead; recalculate demand before committing a later delivery. Incoming is not stock on hand until received and checked. Delayed, overdue, unconfirmed and out-of-window supplier receipts are excluded from the supply preview. No wholesale shipment forecast is also subtracted from these same units.

NOK purchase values use fictional supplier costs excluding freight/duties and VAT. NOK store proposals use fictional wholesale selling prices excluding VAT. Prices are not converted from the supplier dashboard's USD samples. Suggestions are not revenue or committed orders.

## State and integration

All edits are in-memory scenarios, resettable and lost on reload. URL query `view` supports overview, incoming, inventory, replenishment and stores. Filters change the visible scope; they do not release stock allocated to hidden stores. CSVs include supply direction, evidence inputs, calculated need, availability and NOK values. No persistence or backend is claimed.

Production integration requires authorized distributor/store mappings, exact variant identifiers, price lists and currencies, market/warehouse pool identity, reservations, confirmed receipt dates, stock/retail freshness and completeness, and server-side atomic reservations with store approval. Recompute before committing an order. Avoid duplicate existing-store incoming and warehouse reservations.

## Build and validation

`npm install`, `npm run build`, `npm test` (Node with TypeScript stripping support). `build.mjs` bundles React with esbuild and writes the static index. An optional NEEDLE_BUILD_DEPS path supports the workspace's existing compatible dependencies.

Checks cover stock calculation, reservations, zero demand, evidence gates, timing gaps, minimum/pack rounding, confirmed/late/unconfirmed receipt exclusion, allocation conservation, deterministic urgency including existing store receipts, stock pool separation, combined receipt packs, NOK totals and CSV shape. Browser QA covered desktop and 390px mobile, sticky navigation, delivery-status scenarios, store stock edits, store filtering, proposal review, warehouse display and export interaction.

Source: src/main.tsx, src/planning.ts, src/replenishment.ts and src/model.ts. Static assets are local. Snapshot: 22 November 2026.
