Purchase Order V1 — Implementation Plan

Purchase Order V1 — Implementation Plan

Branch: nail60/purchase-order-exploration (arda-frontend-app) Figma Prototype: Purchase Order MVP — Prototype Figma Reference (Order Sidebar): Arda MVP 2.0 Hi-Fi Mockups — node 3791-158620

---

Overview

Convert the order queue from a manual list into an AG Grid with native vendor grouping, then add a resizable sidebar panel for creating and editing purchase orders directly from selected queue items.

Core Flow

1. Order Queue (AG Grid) — Items in REQUESTING state, grouped by vendor by default
2. Select items — User selects line items from a vendor group
3. Create Order (Sidebar) — Selected items populate a new draft order in a right sidebar panel
4. Edit Order — All fields editable. Consider whether changes should propagate back to item/vendor records
5. Confirm & Send — Based on order mechanism, generate the appropriate output:
   • EMAIL → Pre-populated email with PDF attachment
   • ONLINE → Shopping cart or link list for vendor website
   • IN_STORE → Printable shopping checklist
   • PHONE → Contact info + structured item list
   • PURCHASE_ORDER → Formal PO PDF
   • RFQ → Request for quote document
6. Complete → Cards transition to REQUESTED → IN_PROCESS. Order moves to receiving.

Note: A single vendor may have multiple order mechanisms. That complexity is deferred to a later prototype.

---

Phase 1: Convert Order Queue to AG Grid

Goal: Replace the manual list/group rendering in order-queue/page.tsx with <ArdaGrid> using native row grouping by vendor.

Step 1.1 — Define order queue column defs

• Create src/app/order-queue/orderQueueColumnDefs.ts
• Columns: checkbox, image thumbnail, item name, SKU, qty, unit, unit price, order method, supplier (with rowGroup: true), location, waiting time (color-coded cell renderer)
• Reuse patterns from columnPresets.tsx — custom cell renderers for status badges, action buttons

Step 1.2 — Create OrderQueueAGGrid component

• Create src/app/order-queue/OrderQueueAGGrid.tsx
• Wrap <ArdaGrid> with order-queue-specific config
• Feed flat OrderItem[] array — let AG Grid handle grouping
• Enable Enterprise row grouping (groupDisplayType: 'groupRows', default group by supplier)
• Row selection with checkboxes (multi-select)
• Toolbar: search filter, group-by toggle (Supplier / Order Method / None), “Create order from selected” button
• Expose onCreateOrder(selectedItems: OrderItem[]) callback

Step 1.3 — Integrate into order-queue page

• Replace the manual group rendering in page.tsx with <OrderQueueAGGrid>
• Keep existing tabs (Ready to Order / In Progress / Previously Ordered)
• Keep existing Redux data fetching — just change the rendering layer
• Wire selection state to enable/disable “Create order” button

API changes needed: None for this phase — same data, different rendering.

---

Phase 2: Order Sidebar Panel

Goal: Build a resizable right sidebar panel for creating/editing orders, matching the Figma reference.

Step 2.1 — Create OrderPanel component

• Create src/components/orders/OrderPanel.tsx
• Resizable right sidebar (not modal) — use CSS resize or a drag handle. Push the width of the main content area rather than overlap.
• Default width ~480px, min 380px, max 700px
• Slide-in animation matching ItemDetailsPanel pattern
• Sections from Figma:
  • Header: “Purchase order” title + close (✕) button
  • Order type: Dropdown defaulted to whatever the vendor is set to. Updates vendor order type if null. Defaults to online.
    • EMAIL
    • ONLINE
    • IN_STORE
    • PHONE
    • PURCHASE_ORDER
    • RFQ
  • Tabs: “Item details” / “Cards” toggle (leave these out of the implementation for now.)
  • To field: Supplier dropdown typeahead (pre-filled from selected group) for now this dropdown will show all suppliers. If the user selects a new supplier that does not exist for all items in the list, show a pop up that asks if the user would like to add this supplier to all the items. If the user says no then it is a one-off action for this specific order. If the user says yes, update all the items to have this supplier.
  • Deliver by: Date picker (optional)
  • Deliver to: Address textarea (pre-filled from tenant/org settings) (Optional)
  • Order sheet: Compact line items table (Item, SKU(Editable), Note (editable), Qty(Editable), Unit(Editable), Cost/Ea(Editable), Cost(Editable))
  • Taxes, Fees, and Discounts: Secondary line items section (All are editable and optional. Eventually we will want to save the history of these to the vendor)
  • Footer: Cancel / Preview / Send button if email (with dropdown for “Save as draft”), “Create PDF” if PO, “Create cart” if online vendor has API associated, “Create shopping list” if online store, “Create shopping list” if in-store, “Create Order script” if phone, “Create Quote request” if RFQ

Step 2.2 — Create order form types

• Create src/types/purchase-order.ts (or extend src/types/order.ts)
• OrderDraft — header fields (supplier, deliverBy, deliverTo, notes, terms)
• OrderDraftLine — item ref, qty, unit, unitPrice, lineTotal, notes, cardRef
• OrderDraftSummary — subtotal, tax, shipping, discount, total

Step 2.3 — Create OrderSheet sub-component

• Create src/components/orders/OrderSheet.tsx
• Small AG Grid or simple table for line items (matching Figma: Item, SKU, Note, Qty, Unit, Cost/Ea, Cost)
• Editable cells for Qty and Cost/Ea
• Checkbox selection + “Remove” and ”+ Add item” actions
• Auto-calculate line costs and subtotal

Step 2.4 — Create Redux slice for order drafts

• Create src/store/slices/orderDraftSlice.ts
• State: currentDraft: OrderDraft | null, isOrderPanelOpen, draftLines: OrderDraftLine[]
• Actions: openOrderPanel, closeOrderPanel, setDraftHeader, addLine, removeLine, updateLine, clearDraft

Step 2.5 — Wire Order Queue → Order Panel

• “Create order from selected” button calls openOrderPanel with selected items
• Pre-populate: supplier from group, lines from selected items (qty from card reorder qty, price from item unitCost)
• Items in the grid that are in the current draft get dimmed + “(in order)” label

API changes needed:

• POST /v1/order/order/from-kanban-cards exists but may need updates for the draft flow
• For MVP mock: create src/mocks/handlers/orders.ts with handlers for create/update/submit order
• Future: order persistence endpoint for drafts (POST /v1/order/order with status DRAFT)

---

Phase 3: Mock Data & Handlers

Step 3.1 — Create order mock data

• Create src/mocks/data/mockOrders.ts
• Sample orders in various states (DRAFT, SUBMITTED, COMPLETED)
• Based on existing Order type from src/types/order.ts

Step 3.2 — Create order mock handlers

• Create src/mocks/handlers/orders.ts
• POST /api/arda/order/order/from-kanban-cards — create order from card IDs
• GET /api/arda/order/order/:id — get order by ID
• PUT /api/arda/order/order/:id — update order draft
• POST /api/arda/order/order/:id/event/submit — submit order

---

File Creation Order

#	File	Purpose
1	src/app/order-queue/orderQueueColumnDefs.ts	AG Grid column definitions
2	src/app/order-queue/OrderQueueAGGrid.tsx	AG Grid wrapper component
3	src/app/order-queue/page.tsx	Update to use AG Grid
4	src/types/purchase-order.ts	Order draft types
5	src/store/slices/orderDraftSlice.ts	Redux state for order drafts
6	src/store/hooks/useOrderDraft.ts	Hook for order draft state
7	src/store/rootReducer.ts	Register new slice
8	src/components/orders/OrderPanel.tsx	Resizable sidebar panel
9	src/components/orders/OrderSheet.tsx	Line items table
10	src/mocks/data/mockOrders.ts	Mock order data
11	src/mocks/handlers/orders.ts	Mock API handlers
12	src/mocks/handlers/index.ts	Register new handlers

---

Potential API Changes to Flag

#	Change	Context	Severity
1	Order draft mode	POST /v1/order/order/from-kanban-cards creates a full order. May need a “draft” mode that doesn’t immediately transition cards to REQUESTED.	Medium
2	Draft persistence	No explicit draft save endpoint documented. May need POST /v1/order/order with status: DRAFT + PUT /v1/order/order/:id for updates.	Medium
3	Deliver-by date	Not in current Order type. May need backend field addition.	Low
4	Taxes/fees/discounts	Not in current OrderLine type. May need separate line type or extension.	Low (defer)
5	Order mechanism on order	Current Order doesn’t store the order mechanism. It’s on the item’s Supply record. May want to denormalize onto the order for the confirmation flow.	Low

---

Design References

Figma Prototype Screens

Screen	Description
0. Flow Overview	Annotated flow diagram
1. Order Queue (AG Grid)	Grouped by vendor, selectable rows, “Create order from selected”
2. Order Detail (Full Page)	Header form + AG Grid line items, editable in DRAFT
2b. Order Queue + Sidebar	Split view with drag-drop order panel
3. Email Output	Email preview + action cards (Copy, PDF, Mail, Mark Sent)
3b. Online Output	Shopping list with vendor links and “Open All”
3c. In-Store Checklist	Printable checklist with Print/Send to Phone

Existing Figma Mockups (Incomplete, not source of truth)

Lean heavily on card-based layouts. Current direction favors AG Grid tables for desktop.

File: JJJ5Yb7t8hMe2LfCX0W5gQ

Frame	Node ID	Description
Order Queue	1672-158565	Order queue card grouping by supplier
Order Sheet	1558-292390	Order sheet / PO line items view
PO Detail	3429-204955	Purchase order detail view
PO Creation	1530-112479	PO creation flow
Order Sidebar	3791-158620	Primary reference for sidebar panel
Receiving	3174-151727	Receiving workflow
Receiving Detail	3326-490169	Receiving detail / shipment view
Fulfillment	3948-81328	Card fulfillment flow
Order Confirm	1567-292958	Order confirmation
Order Submit	1567-292978	Order submission
Order History	1567-310866	Order history view