Purchase Order Hub
It is marked BETA on the page itself, and A2Z-F160 is recorded as BROKEN in
docs/audit/07_MASTER_FEATURE_INVENTORY.md. It now says so plainly instead of showing you the
wrong rows: it renders "This screen has no data source yet" and lists nothing.
Until 2026-08-23 it listed port-agent contacts and stamped each one AI TAG: PURCHASE ORDER.
The filter was "source purpose contains PO or Order", and "po" is a substring of port-agent — 378
of them in production. Not one purchase order was ever on this screen.
Do not use it as a record of incoming orders. Client POs that arrive by email are handled through the RFQ intake and the RFQs screen.
What it is
It presents itself as a monitor for purchase orders arriving from clients by email — "Monitoring incoming Purchase Orders from client emails via AI".
It has no source of purchase orders, and shows nothing. address_book is a table of contacts;
purchase orders are not in it, and no source_purpose value in this database denotes one. The
eleven values in production are Peripheral Capture, Sender Profile, supply_inbox_sweep,
equasis-manager, port-agent, archive-leadmine, purchase_inbox_sweep, faran_inbox_sweep,
zakir_inbox_sweep, bridgemail_pending and null.
The old filter matched "PO" or "Order" anywhere in that text, case-insensitively. The only value it
actually hit was port-agent — because "port" contains "po" — so the screen listed 378 port agents
and labelled each one a purchase order. Showing nothing is the accurate answer until the screen is
rebuilt against real inbound POs, or retired.
Who can open it
- The page sits under the
/salesprefix, so whileFEATURE_GRANULAR_RBACis on it needs thesales.quotationsfeature grant, the same one that covers quotations and negotiations. - Reading needs
operatoror above. - Pressing 🔍 Scan Inbox needs
admin— that is the privileged part, because it reaches a real mailbox.
Until 2026-08-23 reading required admin while the page was published to anyone with
sales.quotations, so a sales account opened it and got a bare permission error with nothing on
screen explaining why.
Before you start
Opening the page does not touch the mailbox. The inbox scan runs only when you press 🔍 Scan Inbox, and a scan failure is reported to you rather than logged and swallowed.
Until 2026-08-23 merely loading the page ran an inbox sync over the most recent 15 messages, and a failed sync was silent — the screen then listed whatever was already in the address book and looked exactly as it does on success.
Every control on the page
| Control | What it does |
|---|---|
| 🔍 Scan Inbox | Runs the inbox sync over the most recent 15 messages, then re-queries. Reads 🔄 Scanning... while it works, and is disabled entirely while there is no configured source. Needs admin |
| Open contact | Opens the address book. It replaced a Review Items button that had no click handler at all; there is no per-row review screen to open |
The table — four columns, none of them sortable or filterable:
| Column | What it shows |
|---|---|
| Date | When the contact record was created — not when any order was placed |
| Sender / Vessel | The contact's name, and under it the vessel, or Shore-based when there is none |
| Subject / Order Reference | The email subject the contact was found in, or No Subject, and under it the fixed label AI TAG: PURCHASE ORDER — which is printed on every row regardless of what the row is |
| Action | Open contact |
At most 50 rows are ever shown, newest first. There is no paging, so anything past 50 is invisible with nothing to say so.
States:
- Fetching latest Purchase Orders... with a 📥 while the first load runs.
- This screen has no data source yet with a 🚧, which is what it shows today.
- All caught up! with a 🍵 and "No new Purchase Orders detected in the recent logs." — reserved for a configured source that genuinely returned nothing. It used to be shown for both cases, so an unwired screen read as a healthy pipeline.
- A red ⚠️ strip carrying the server's message when the call fails — this is what a non-admin sees.
What it writes
The screen itself writes nothing. Its single call is a GET.
That GET does write, though. /api/agent/po-sync runs the address-book inbox sync before
reading, which files newly-seen contacts into address_book. So loading this page can add contacts,
even though nothing on it says so and there is no confirmation step.
The read itself is address_book, filtered on source_purpose, newest first, capped at 50.
When it goes wrong
A red error strip instead of a table. Almost always the role check: the data needs the admin
role. Sales and operations accounts get this even though the page opened.
"All caught up!" when you know a PO arrived. Expected. This screen does not look at orders, and the inbox scan behind it may have failed silently. Look at RFQs instead.
Rows that are clearly not purchase orders. Expected — see the matching note above.
Review Items does nothing. Confirmed defect, not a fault on your machine.
Related screens
- RFQs — where client requests that arrive by email actually land.
- Address Book — the table this screen is really reading.
- Address Book — Pending — the reviewed queue for contacts the sync found but would not file on its own.
- Purchase Orders — outbound LPOs on suppliers, which is a different thing entirely from this screen's subject.