sims-hq/docs/13-SPEC-PURCHASE-ENTRY.md

Purchase Entry — /purchases/entry Implementation Spec

Scope: back-office web (React + @sims/ui + @sims/scanning + store-server API). Everything below is implementable today against the current tree. Key discovery: apps/store-server/src/repos-purchase.ts already exists (commitPurchase, lastCosts, listPurchases) with purchase/purchase_line tables in db.ts, but nothing is wired into api.ts and the page at /purchases/entry is a registry wireframe. This spec turns that into the real screen.

Files touched (master list)

• NEW apps/backoffice/src/pages/PurchaseEntry.tsx — the screen
• apps/backoffice/src/main.tsx — add '/purchases/entry': PurchaseEntry to CUSTOM (auto-overrides the registry wireframe)
• apps/backoffice/src/api.ts — client fns: getSuppliers, createSupplier, checkInvoice, getLastCosts, getTaxClasses, postPurchase, getPurchases
• apps/store-server/src/api.ts — NEW routes (listed in §6)
• apps/store-server/src/repos-purchase.ts — findPurchase(), invoice-no normalization, outbox row, printed-total columns
• apps/store-server/src/repos.ts — generalize createCustomer → createParty(db, tenantId, {name, kind, phone?, gstin?, stateCode?})
• apps/store-server/src/db.ts — 2 new columns on purchase, later label_job (see §6)
• packages/billing-engine — NEW exported computePurchase(lines) so client and server share one math (same-engine idiom as computeBill; repos-purchase.ts:lineMath refactors to call it)

---

1. Screen layout (zones)

┌──────────────────────────────────────────────────────────────────────────────┐
│ HEADER STRIP (collapses to one line after date; Alt+E reopens)               │
│ Supplier ▌amu…  → [HUL Distributor ▾]   Invoice no [HD/2651]  Date [08-07]   │
│ ⚠ dup: "HD/2651 already entered 04-Jul"        chip: Interstate (IGST)       │
├──────────────────────────────────────────────┬───────────────────────────────┤
│ ┌──────────────────────────────────────────┐ │ ITEM CARD (P1 right rail)     │
│ │ SCAN / TYPE ▌  (the sacred line, again)  │ │ Amul Butter 500g              │
│ └──────────────────────────────────────────┘ │ Stock 9 · MRP 310             │
│ #  Item              Qty   Cost   MRP  Mgn% Amt │ Last costs (this supplier) │
│ 1  Amul Butter 500g   24  261.90  310  11%  6.6k│  261.90 04-Jul             │
│ 2  Amul Cheese 200g   12  112.50↑ 135  9%⚠ 1.4k│  259.80 12-Jun             │
│    cursor stops: Qty → Cost (→MRP per profile)  │  258.00 28-May             │
├──────────────────────────────────────────────┴───────────────────────────────┤
│ FOOTER  Lines 2 · Qty 36 | Taxable 7,912.80 · GST 395.64 · TOTAL ₹8,308.44   │
│         Printed total [________]  Δ —          [Ctrl+Enter] Check & Post     │
└──────────────────────────────────────────────────────────────────────────────┘

Keymap (page-scoped, one useEffect keydown handler exactly like BillingScreen.tsx:200)

Key	Action
Enter	Confirm field / advance cell (item → qty → cost → [MRP] → scan box)
Esc	Back one level: cell → scan box → (empty) header summary; never deletes a line
Ctrl+Enter	Post flow: totals-check overlay → price-update overlay → commit
n* prefix + scan/code	Qty multiplier (24* + scan = qty 24), via existing parseEntry
↑ / ↓	Select grid line (when scan box empty) / navigate type-ahead lists
F2	Edit Qty of selected line
Del, Del	Remove selected line (first Del arms inline "Del again to remove", 2 s timeout)
Tab / Shift+Tab	Visit every cell including profile-skipped ones (MRP, later Disc/Free)
Alt+E	Reopen header strip to edit supplier/invoice/date
F1	Keymap cheat-sheet overlay

Focus doctrine: identical sentinel to POS — the active input's onBlur refocuses itself via setTimeout(0) unless an overlay is open (copy the pattern at BillingScreen.tsx:264). No toast/dialog ever fires system-initiated; all errors render inline in the zone they belong to. Back office may normally toast, but this page adopts the counter creed per 09-UX §3.2.

---

2. P0 — the working fast path (ship first)

P0-1 · Supplier type-ahead with create-new

Behavior. On mount, fetch suppliers once (GET /parties?kind=supplier — exists) and focus the supplier field. Each keystroke filters client-side with the same startsWith-first ranking as BillingScreen.tsx:search(); dropdown shows top 8 (name + GSTIN + last-purchase date from GET /purchases cache). ↑/↓ + Enter picks and advances focus to Invoice No. Last-used supplier id is remembered in localStorage['pe.lastSupplier'] and pre-selected on mount — Enter alone accepts it (distributor stacks). No match on Enter → inline panel "Create supplier ‘Amul Agy’ — [Enter] create · [Esc] retype"; second Enter opens a 2-field micro-form (Name prefilled from typed text, GSTIN optional with checksum validation via @sims/domain/gstin); Enter saves and advances. Keystrokes. Existing supplier: 3 chars + Enter = 4. Repeat supplier: 1. Create: name + Enter×3 (+ GSTIN typing). Focus. Mount → supplier. After first line exists the header is read-only (Alt+E to edit; editing supplier after lines exist re-runs the last-cost prefetch and re-flags cost chips). Edge cases. GSTIN state (first 2 chars) ≠ store.state_code → render "Interstate (IGST)" chip (display-only in P0; split stored in P1-6). Duplicate supplier names allowed, disambiguated by GSTIN in the dropdown. Touches. PurchaseEntry.tsx; server: generalize repos.ts:createCustomer → createParty and extend POST /parties in api.ts:112 to accept kind|gstin|stateCode — small NEW server change (route exists, currently hardcodes 'customer').

P0-2 · Invoice no + date + duplicate-invoice warning

Behavior. Invoice no: free text, normalized trim().toUpperCase(). On Enter → fire NEW GET /purchases/check?supplierId=&invoiceNo=; if hit, red inline notice under the field: "Already entered 04-Jul · ₹8,150 · 12 lines — posting will be rejected (E-7301)". The warning never blocks typing lines (the server hard-rejects at post anyway via the existing UNIQUE(tenant_id, supplier_id, invoice_no) + 409 at repos-purchase.ts:58). Date defaults to today; Enter accepts; accepts 0807, 08/07, 08-07-2026. After date-Enter the header collapses to a one-line summary and focus lands in the scan box. Keystrokes. invoice chars + Enter + Enter = typing + 2. Edge cases. Future invoice date → amber inline "dated tomorrow?" (accepted on second Enter). Same normalization applied inside commitPurchase so hd/2651 and HD/2651 cannot double-post — add invoiceNo = input.invoiceNo.trim().toUpperCase() at repos-purchase.ts:41. Touches. PurchaseEntry.tsx; NEW repo fn findPurchase(db, tenantId, supplierId, invoiceNo) in repos-purchase.ts + NEW route in api.ts.

P0-3 · Line grid — one scan/type box, POS grammar, Enter-advances-cell

Behavior. The entry box reuses parseEntry + WedgeDetector from @sims/scanning verbatim (same wiring as BillingScreen.tsx:112,260): digits ≥8 → barcode lookup, <8 → item code, letters → fuzzy search (top-8 dropdown, ↑/↓ + Enter; single hit adds immediately), 24* prefix → qty multiplier. Item cache = GET /items loaded at mount (2k rows today; move to server-side q= when catalogs grow). On resolve, append line {item, qty: pending ?? 1, costPaise: supplierLast ?? last ?? undefined, mrpPaise: item.mrpPaise} from the last-cost dict (P0 prefetch: NEW GET /purchases/last-costs?supplierId= wiring the existing lastCosts() repo fn) and move focus into the line's Qty cell. Cell flow: type digits (typing replaces prefill; bare Enter keeps it) → Enter → Cost (₹ with paise, prefilled last cost; bare Enter accepts) → Enter → back to scan box. MRP is Tab-reachable but not an Enter stop in the default column profile (purchases.column_profile setting row; a pharmacy profile later adds Batch/Expiry stops — P2). Tax per line resolves client-side from item.taxClassCode via resolveTaxClass(taxClasses, code, invoiceDate) (NEW trivial GET /tax-classes route wiring existing listTaxClasses). Line amount/tax math calls the shared computePurchase (§6) so the footer equals the server to the paisa. Cost-changed highlight. If entered cost differs from supplierLast beyond purchases.cost_warn_pct (setting row; default 0 = any change), render an amber chip in the row: ↑ ₹2.10 vs 04-Jun. Never a dialog — the price decision batches to post time (P0-4). Margin column recomputes live: landed = cost × (1 + rateBp/10000); margin% = (salePrice − landed) / salePrice. Below purchases.margin_floor_pct → amber cell, never blocks. Keystrokes/line. Scan(0) + qty digits + Enter + Enter = qty + 2 when cost unchanged; +cost digits when changed. Meets the ≤5 keys/line budget. Edge cases.

• Re-scan of an item already on the grid: merge (+addQty), flash row, focus its Qty cell.
• Scan burst landing in a Qty/Cost cell (purchaser scans without refocusing): cells also feed a page-level WedgeDetector; a burst that terminates inside a cell commits the cell with its prior value and resolves the code as a new line — the wedge suffix Enter must never write barcode digits into Qty.
• Unknown barcode: inline panel under the scan box "Unknown code … [Enter] Quick-create · [Esc] skip" → 4-field micro-form (Name, Cost, MRP, GST class defaulting store slab) → existing POST /items with status:'draft' → line added; lands on the Items "incomplete" worklist.
• Loose/KG item (unit.decimals=3): Qty accepts 12.500. Scale label (2x EAN): not meaningful for purchases — inline hint "scale label — enter by item code".
• Qty ≤ 0 / non-integer cost: red cell, Enter refused; server re-validates (repos-purchase.ts:42-47). Cost 0: allowed (free goods) but amber.
• ↑/↓ from an empty scan box selects grid rows; F2/Del act on the selection. Touches. PurchaseEntry.tsx; NEW routes GET /purchases/last-costs, GET /tax-classes in api.ts.

P0-4 · Consolidated price/MRP update prompt (at post, never mid-entry)

Behavior. During the post flow, lines where (a) cost changed vs supplierLast, or (b) entered MRP ≠ item.mrpPaise, populate one overlay grid: Item · cost old→new · current sale · suggested sale · checkbox (default ON). Suggested sale preserves the item's previous margin: round₹(newLanded / (1 − oldMargin%)), capped at MRP when MRP exists (Legal Metrology, issue GST-15). Space toggles a row, ↑/↓ moves, typing overrides the suggestion, Enter confirms all → checked rows set newSalePricePaise/newMrpPaise on the line inputs. The server side already exists: commitPurchase applies them with ITEM_PRICE_UPDATE audit rows (repos-purchase.ts:89-97). Keystrokes. Usually 1 (Enter accepts all). Esc returns to the grid without posting. Edge cases. Item whose sale price would drop below new landed cost → row pre-checked with red margin; suggested never exceeds MRP. Touches. PurchaseEntry.tsx only.

P0-5 · Footer totals + "supplier's printed total" cross-check

Behavior. Footer renders live Taxable / GST / Total from computePurchase. Ctrl+Enter opens the totals-check overlay: one numeric field "Bill total as printed on the paper" (autofocused). Enter compares against computed total: within purchases.total_tolerance (setting; default 99 paise) → proceed to P0-4 overlay → commit. Mismatch → red line Printed 8,320.00 · Computed 8,308.44 · Δ +11.56 with ranked hints (largest line by value, line count) and two keys: [F2] Add other charges ₹11.56 (fills otherChargesPaise, delta recheck passes) · [Esc] back to lines. Explicit [F10] Post anyway records the mismatch (printed_total_paise stored; PURCHASE_TOTAL_MISMATCH audit row). This is the manual sibling of the Purchase Inbox verdict math (09-UX §3.4). Keystrokes. Ctrl+Enter + printed digits + Enter (+1 Enter in P0-4) — the entire close ceremony is ~digits+3. Touches. PurchaseEntry.tsx; schema: ALTER TABLE purchase ADD COLUMN printed_total_paise INTEGER; ADD COLUMN other_charges_paise INTEGER NOT NULL DEFAULT 0 in db.ts (dev DB is disposable — recreate or ship the ALTERs); commitPurchase total check becomes taxable + tax + otherCharges === clientTotalPaise and persists both columns — NEW server change.

P0-6 · Post — single action, one server transaction

Behavior. After the two overlays, client calls NEW POST /purchases with {storeId, supplierId, invoiceNo, invoiceDate, businessDate: today, lines[], otherChargesPaise, printedTotalPaise?, clientTotalPaise}. On 200: green inline notice "Posted · AA/912 · ₹8,308.44 · 42 units into stock", grid clears, supplier stays selected, focus → Invoice No (next bill from the same distributor stack is 2 fields away). On 409 duplicate: red notice, nothing cleared. On engine-mismatch 409: red notice "totals disagree — refresh tax data (E-7302)"; cart kept. Server transaction (single db.transaction, repos-purchase.ts:68 — mostly exists):

1. Insert purchase header (+ NEW printed/other-charges columns) — exists
2. Insert purchase_line rows — exists
3. stock_movement rows, reason='PURCHASE', qty_delta=+qty per line — exists (stock IN; derived stock, invariant I4)
4. Item sale_price_paise/mrp_paise updates + ITEM_PRICE_UPDATE audit per changed line — exists
5. PURCHASE_COMMIT audit row — exists
6. NEW: outbox envelope row — parity with commitBill (repos.ts:174-177); currently missing from commitPurchase, violating the D14 dormant-outbox discipline. Same shape, doc_type='PURCHASE'.
7. Label-queue note → P1-3. Supplier ledger credit → P2-2 (no ledger tables exist yet — do not fake it). Duplicate rejection: pre-check + UNIQUE — exists. Validation (qty > 0, integer cost, non-empty invoice) — exists. Touches. api.ts (route + sess() for tenant/user, mirroring r.post('/bills') at api.ts:119), repos-purchase.ts (items 6, printed-total), db.ts.

P0-7 · Shared purchase math in the engine

Behavior. Export computePurchase(lines: {qty, unitCostPaise, taxRateBp}[]): {perLine: {taxablePaise, taxPaise, totalPaise}[], totals} from @sims/billing-engine with exactly the rounding at repos-purchase.ts:33-37 (Math.round(qty*cost), Math.round(taxable*bp/10000)). lineMath refactors to call it; PurchaseEntry.tsx imports it for the footer. This is what makes the 409 agreement check honest rather than a paisa-drift trap. Touches. packages/billing-engine/src/ (new file + index export, + golden test), repos-purchase.ts.

---

3. P1 — makes it pleasant at 200 lines/day

• P1-1 Right-rail item card. On cell focus, show item photo-less card: stock on hand (existing stockView), current sale/MRP, live margin, last 3 costs from this supplier with dates. NEW GET /purchases/cost-history?itemId=&supplierId= → NEW repo fn (SELECT unit_cost_paise, p.invoice_date FROM purchase_line pl JOIN purchase p … ORDER BY p.created_at_wall DESC LIMIT 3). Touches: repos-purchase.ts, api.ts, PurchaseEntry.tsx aside. Zero keystrokes — pure glanceability.
• P1-2 Free-qty column + column profiles. ALTER TABLE purchase_line ADD COLUMN free_qty REAL NOT NULL DEFAULT 0; stock movement becomes qty + free_qty; landed-cost math divides by total units. Enter-stop set driven by purchases.column_profile setting row (kirana: Qty+Cost; adds Free/Disc/MRP per profile).
• P1-3 Label queue on post. NEW table label_job(id, tenant_id, store_id, item_id, qty, mrp_paise, source_doc_id, status, created_at_wall). After a successful post, if any line had new MRP or a draft item: inline prompt "Print labels for 5 new/changed items? [Enter] queue · [Esc] skip", quantities defaulting to received qty → NEW POST /label-jobs (bulk). /catalog/labels page reads them (replaces registry sample rows). Commit of jobs happens outside the purchase transaction (prompt is post-post); each job row is trivially idempotent to re-create.
• P1-4 Disc% column. ALTER TABLE purchase_line ADD COLUMN disc_bp INTEGER NOT NULL DEFAULT 0; computePurchase extends: taxable = round(qty*cost*(1−disc_bp/10000)). Enter stop only in profiles that include it.
• P1-5 Crash-proof draft. Journal the in-progress entry to localStorage['pe.draft'] on every line commit; on mount with a draft present, inline banner "Resume AA/912 (14 lines)? [Enter] resume · [Esc] discard". A 180-line invoice must survive a browser crash. No server.
• P1-6 Local/Interstate tax split. Derive supply_type from supplier state_code vs store; store cgst/sgst/igst split on purchase (3 columns) — prerequisite for GSTR-2B recon and ITC reporting. Engine change in computePurchase mirrors computeBill's split.
• P1-7 Purchase List goes live. Wire existing listPurchases → NEW GET /purchases; replace the /purchases/list registry entry with a live page (pattern-copy BillsPage in live.tsx); row click → read-only detail drawer rendering payload lines + audit chip. "New purchase" button → navigate /purchases/entry.

4. P2 — deliberate deferrals

• P2-1 Batch/expiry cells (pharmacy profile) — needs batch tables; POS batch-picking doesn't exist yet either.
• P2-2 Supplier ledger credit in the post transaction + Suppliers ledger tab — blocked on accounting tables.
• P2-3 Internal PI doc number via doc_series (doc_type='PURCHASE') so the list shows PI-000212 instead of supplier invoice no; reuse the series block in commitBill (repos.ts:139-151).
• P2-4 RCM flag per line (freight defaults on) — GST-12 self-invoice machinery.
• P2-5 Pack/unit conversion (CASE(24) → PCS) from a pack master; until then purchasers enter stocking units.
• P2-6 Tax-inclusive-cost toggle per supplier (some local bills print inclusive costs).
• P2-7 Telemetry: keys/line and seconds/line emitted per posted purchase (09-UX §3.8 budget: ≤5 keys, ≤8 s) — land with the shared telemetry sink.

---

5. NEW server endpoints (all in apps/store-server/src/api.ts, behind requireAuth)

Route	Backing fn	Status
POST /purchases	commitPurchase	repo EXISTS — wire route (P0)
GET /purchases	listPurchases	repo EXISTS — wire route (P0/P1-7)
GET /purchases/last-costs?supplierId=	lastCosts	repo EXISTS — wire route (P0)
GET /purchases/check?supplierId=&invoiceNo=	findPurchase	NEW repo fn (P0)
GET /tax-classes	listTaxClasses	repo EXISTS — wire route (P0)
POST /parties accepts kind/gstin/stateCode	createParty	generalize existing (P0)
GET /purchases/cost-history?itemId=&supplierId=	NEW repo fn	P1
POST /label-jobs + GET /label-jobs	NEW repo fns	P1

Table shapes. purchase and purchase_line already exist in db.ts:95-109. Deltas:

-- P0
ALTER TABLE purchase ADD COLUMN printed_total_paise INTEGER;          -- as typed from the paper, NULL if skipped
ALTER TABLE purchase ADD COLUMN other_charges_paise INTEGER NOT NULL DEFAULT 0;
-- P1
ALTER TABLE purchase_line ADD COLUMN free_qty REAL NOT NULL DEFAULT 0;
ALTER TABLE purchase_line ADD COLUMN disc_bp INTEGER NOT NULL DEFAULT 0;
CREATE TABLE label_job (
  id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL, store_id TEXT NOT NULL,
  item_id TEXT NOT NULL, qty INTEGER NOT NULL, mrp_paise INTEGER,
  source_doc_id TEXT, status TEXT NOT NULL DEFAULT 'queued', created_at_wall TEXT NOT NULL
);

Last-cost lookup needs no new table — it derives from purchase_line join purchase (idx idx_pline_item exists). Note for scale: lastCosts currently full-scans all purchase lines per call (repos-purchase.ts:110-114); acceptable now, add ORDER BY … LIMIT per item via a window query when purchases exceed ~50k lines.

---

6. Keystroke count — realistic 3-line invoice (Amul Agency, AA/912, dated today)

Line 1: 24 butter, cost unchanged. Line 2: 12 cheese, cost changed to 312.50. Line 3: 6 milk powder, cost unchanged, new MRP 310. Scans = 0 keys by convention.

Step	Keys	Count
Supplier amu + Enter	a m u ↵	4
Invoice no AA/912 + Enter	6 + ↵	7
Date (today) Enter	↵	1
L1: scan · 24 ↵ · ↵ (cost prefill ok)		4
L2: scan · 12 ↵ · 312.5 ↵		9
L3: scan · 6 ↵ · ↵ · Tab 310 ↵		8
Post: Ctrl+Enter · printed 8964.5 ↵		8
Price-update overlay: Enter (accept both suggestions)	↵	1
Total	3 scans	42 keys

~14 keys of once-per-invoice overhead; steady-state 4–9 keys/line — inside the published "~5 keys/line, 12-line bill ≈ 85 keystrokes" budget from 09-UX §3.2, and every one of those keys is Enter, digits, or Tab on the numpad side of the keyboard.