Purchase Order V1

Status: In Progress — Requirements and design in progress Project directory: workspace/projects/mvp2/13-purchase-order-v1/

Goal

Deliver the initial release of the Purchase Order feature, enabling the full procurement workflow from Order Queue to supplier communication and receiving.

Procurement Workflow

Three personas participate in the PO workflow:

1. Inventory Manager / Shop Worker — adds Kanban Cards to the Order Queue (REQUESTING).
2. Procurement Manager — reviews the Order Queue, creates and submits Purchase Orders, generates PDF for vendor communication.
3. Receiving Clerk — receives shipments against submitted POs, completing the replenishment cycle.

Card State Transitions

PO V1 drives card state transitions through PO lifecycle actions:

PO Action	Backend Event	Card Transition
Create PO / add cards	accept	REQUESTING to REQUESTED
Submit PO	start-processing	REQUESTED to IN_PROCESS
Submit and Release	receive	REQUESTED to FULFILLED
Receive against PO	receive	IN_PROCESS to FULFILLED

READY and FULFILLING states remain bypassed and are reserved for a future Loops feature.

Full Feature Scope

1. Order Queue — grouped view by Vendor + Order Mechanism with “Order All” / “Order Selected” actions.
2. PO Creation — from Order Queue cards or from Items; side panel with vendor fields, PO header, aggregated lines.
3. PO Editing — full editability of header, lines, quantities; add/remove free-form lines.
4. PO Submission — validate, advance card states, persist PO.
5. PDF Generation — via Documint; opens PDF in new window; copies email body to clipboard.
6. Receiving — receive shipments against submitted POs, advance card states to FULFILLED.
7. Submit and Release — shortcut for companies without formal receiving.

Descope Floor

If the full scope cannot be delivered on schedule, the minimum release is:

• Order Queue to side panel to edit to Generate PDF (export-only, no persistence).
• No receiving workflow.
• No vendor management UI (typeahead + free entry only).
• No advanced pricing/tax/shipping calculations.

Open Design Questions

#	Topic
DQ-001	PO number: auto-generated vs user-entered
DQ-002	Order Queue snapshot vs live sync while side panel is open
DQ-003	Card exclusion from PO: select in queue vs remove in panel
DQ-004	Order quantities and editability
DQ-005	Vendor typeahead source (must be compatible vendors common to all items in the PO)
DQ-006	PO persistence strategy: export-only floor vs full persistence

Architectural Note

The current backend OrderFromCardsService creates orders from cards but does not fire the accept event, so the REQUESTING to REQUESTED transition does not happen. This is a gap that must be closed in the backend implementation.

The implementation must adopt the Update Propagation pattern (observer/notification approach) rather than the current “update on read” enrichment pattern.