# Needle Supplier Intelligence

ChiaoGoo is the example brand for an interactive supplier dashboard. This is a separate frontend preview alongside the existing Permin dashboard. The Distributor dashboard is future work.

## Views and behaviour

- Consumer demand: market and needle-type filtering, category drill-down, searchable/sortable variants, product detail and CSV export.
- Distribution coverage: mapped versus reporting stores, stock-feed freshness, sample territory assignments and market drill-down. Retail turnover is never labelled distributor or supplier revenue.
- Suggested replenishment: ChiaoGoo-to-distributor replenishment is the default, grouped by distributor and separately allocated market inventory. Distributor-to-store replenishment appears as a separate supporting view. The two demand streams are never summed. Targets, safety days and lead times are adjustable; calculation evidence, input scenarios and detailed CSV briefs are available.
- Stock opportunities: distinct low-stock, store-request, availability-interest, new-stockist and stale-data states. Low-stock cards link to the calculated replenishment view. Territory and consent determine whether a manual store-request or new-stockist brief can be prepared. Briefs can be edited, removed and exported, and persist in browser storage under `kh-needle-briefs-v1`. No communications or orders are sent.
- Demand forecast: 4/8/12-week horizons and lower/base/higher scenarios; inspectable history/forecast bars; variant-level forecasts and CSV export. No extrapolation beyond reporting stores, and no production recommendation without upstream inventory and orders.

All commercial data, distributor names, territory assignments and product identifiers are fictional. Real product family names are used only as illustrative context. The 1,000-store fixture is not a verified account roster. The prototype has no backend authentication or live commercial data.

## Implementation

React 18 + TypeScript; build output is static `index.html`, `app.js`, CSS and fonts. Shared visual language follows the existing supplier preview (ES Allianz, lime/purple accents, rounded outlined panels and responsive tables).

Install the declared dependencies, then run `npm run build` and `npm test` (Node 22.6+ for the model verification). `build.mjs` supports an optional `NEEDLE_BUILD_DEPS` directory for a compatible existing Vite/esbuild dependency installation. The checked-in static output can be served directly.

Included fonts are existing user-supplied trial assets; retain the project's font licensing arrangements.

## Data integration contract

Replace fixtures in `src/model.ts` with authorised feeds. Product identity must use verified supplier SKUs and GTIN/EAN where present, including size, needle/cable length, material, connector class and whether the saleable item is a set, pair or individual tool. Set sales are counted once, not as the number of included tips.

All monetary amounts in the dashboard and exports are USD. The fixture uses illustrative USD unit prices, not a live currency conversion. Replenishment quantities are saleable units; no supplier prices are inferred from retail prices.

Store sales should distinguish completed purchases, cancellations and returns, tax basis, currency and reporting period. Supply verified conversion rates for multi-currency reporting. Coverage needs a stable denominator, freshness and product-scope eligibility. Missing data is unknown, not zero demand.

The current forecast is observed units / 4 weeks × horizon × scenario factor, rounded per variant. It excludes sign-ups and wholesale requests, which could otherwise duplicate demand already observed in retail sales. Historical weekly bars use an illustrative split that reconciles to the 28-day total. Needles are durable/reusable; pattern requirements are not new product purchases.

Replace demo distributor routing with active territorial/product authorisations and each store's existing distributor relationship. Store consent and data-sharing policies must be enforced server-side. Brand access should be aggregated by default. Never expose distributor contracts or store purchasing terms based solely on frontend filtering. No assumption of exclusive territories is encoded by this concept.

The manufacturer production workflow requires distributor stock, inbound shipments, confirmed purchase orders, manufacturer inventory, production lead times and batch constraints. The replenishment view now has separate fictional distributor stock and outbound-shipment fixtures. These support distributor replenishment planning; manufacturer production instructions still require manufacturer stock, capacity and confirmed orders.

## Verification

- TypeScript check and static build.
- Model assertions for market aggregation, product filters, coverage totals, scenario arithmetic, consent gating and territory routing.
- Browser checks for market/type filtering, draft creation with edited quantity, reload persistence, CSV contents, draft removal, forecast interaction and responsive layout.

The preview library contains the built page and this source ZIP. It does not establish a live supplier account or send any business communication.


## Replenishment calculation and supply levels

`src/replenishment.ts` owns the pure calculation, fixtures, grouping and CSV shape; `src/ReplenishmentView.tsx` owns the view.

- Supplier level: ChiaoGoo supplies distributors. Rate = distributor units shipped to stores / observed days. Available stock and confirmed inbound receipts belong to the distributor; lead time is ChiaoGoo to distributor. Inventory shown by market must be a separately allocated pool. A shared warehouse balance must never be repeated for each territory; unallocated records are withheld.
- Supporting store level: distributors supply stores. Rate = observed retail sales / observed days. Stock and inbound receipts belong to the store; lead time is distributor to store. Store demand is not automatically added to distributor outbound history, since this would count demand twice.
- All feeds and distributor assignments are fictional. The detailed record samples are subsets, not a roster of the whole network. No distributor-facing dashboard is implemented.

Let rate = units / observed days, L = lead days, C = target cover after arrival, S = safety days, and H = L + C. Available = on hand minus reserved. Credit confirmed receipts due between day 0 and H. Unconfirmed receipts and those after H are excluded. Overdue confirmed receipts block calculation until reconciled.

Net need = max(0, rate × (H + S) − available − credited receipts). Check the projected requirement at L, immediately before each later delivery, and at H; increase the net need when a late receipt conceals an earlier deficit. This timing buffer holds the planned stock balance after the new replenishment arrives. Flag any projected physical shortage before L separately; a normal replenishment cannot resolve that earlier gap.

For positive raw need, apply the inventory pool / variant minimum and round up to its pack multiple. For zero demand/need, suggest zero even with a minimum order. Aggregate rounded quantities; never offset one location's shortage against another location's surplus. Display withheld data as unknown, not zero. Export the supply level, all inputs, assumptions, unrounded need, timing buffer, rounded result and exclusion reasons.

Require whole nonnegative quantities, valid pack/minimum constraints, at least 14 complete days of history, and stock/sales feeds no older than 3 days. Withhold suggestions for invalid evidence, missing stock, unverified mappings, missing consent, duplicate receipt IDs, or overdue inbound deliveries. A recommendation still requires recipient agreement and source stock/capacity confirmation; it never creates an order.

Scenario input edits remain local to this view and reset when it is reopened or reloaded. Existing browser-saved opportunity briefs remain a separate workflow and are not added to calculated replenishment totals.

`verify-replenishment.mjs` covers arithmetic, reservations, incoming timing, overdue data, early shortages, safety, lead overrides, minimums, pack rounding, group reconciliation, supply-level separation and CSV shape.

The user-supplied ChiaoGoo logo is in `assets/chiaogoo-logo.png`. The five-view navigation remains sticky at the top of the viewport on desktop and mobile. Switching tabs while scrolled positions the new content below the navigation.

The masthead uses the original user-supplied Krafthub logo in `assets/krafthub-logo.png`.

The page favicon and touch icon use the supplied Krafthub icon in `assets/krafthub-favicon.png`.
