Workflows

Step-by-step user workflows, migrated from the original UI/UX spec (Docs/DESIGN.md, now retired). For the screen list see Pages and Navigation; for the status graph see PO Lifecycle.

Submit a purchase order (Technical / Manning)

Click New PO in the sidebar.
Select Cost Centre (Vessel) and Accounting Code.
Add line items — type a name to search the catalogue; previous vendor prices appear as hints.
Optionally attach documents and fill in Terms & Conditions.
Click Submit for Approval → Manager is emailed; status shows "Under Review" on My Orders.
If the manager requests edits: the PO shows EDITS_REQUESTED with the note; edit and resubmit.
If the manager requests a vendor ID: select a vendor and submit; the PO returns to the manager queue.
On approval: you're emailed and the PO appears in the Accounts payment queue.

Approve a purchase order (Manager)

Open Approvals; see the pending count.
Click Review on a PO; read line items, vendor, documents, notes.
Optionally Edit to adjust quantities/prices/GST or change vendor/vessel/account inline (logged as MANAGER_LINE_EDIT).
Choose an action:
- Approve → moves to the Accounts payment queue.
- Approve with Note → same, with a note visible to the submitter.
- Request Edits → write a note; PO returns to the submitter.
- Request Vendor ID → PO returns to the submitter to select a vendor.
- Reject → write a reason; PO is closed permanently.

A vendor must be assigned before approval, and only verified vendors may be assigned. See Roles and Permissions.

Process a payment (Accounts)

Open Payments; see cards for MGR_APPROVED POs.
Send for Payment → notifies submitter and manager.
When the bank/finance confirms, Mark as Paid (capturing the compulsory payment date — no future dates) → notifies all parties. Partial payments loop via PARTIALLY_PAID until fully settled.
The submitter can now upload a delivery receipt.

Confirm receipt (Technical / Manning)

Goods are delivered to the vessel/site.
Open the PO detail (status PAID_DELIVERED).
Confirm Receipt → upload the delivery receipt and optionally add notes.
Submit → PO is CLOSED (or PARTIALLY_CLOSED for a partial receipt); accounts and manager are notified.

Look up a vendor by GSTIN (Manager / Admin)

Open the Add/Edit Vendor form.
Type the 15-digit GSTIN and click Look up → a CAPTCHA image loads from the GST microservice.
Type the 6-digit CAPTCHA and click Verify → the form auto-fills legal name, address, and pincode.
Save; location is geocoded silently from the pincode for distance sorting.

Detail: Vendors and GST Lookup.

Source items by proximity (Manager)

Open Items → click an item name.
See all vendors that supply it with their last quoted price.
Select a site from the "Sort by distance from" dropdown.
The table re-sorts by proximity; distance shows per row; the closest vendor is marked ★ and the cheapest is tagged Cheapest.
Add to Cart on the desired vendor row.

Create a PO from the cart (Manager / Technical)

Add items to the cart from item detail pages.
Open Cart; adjust quantities, remove items, select a delivery site.
Create PO → opens New PO pre-filled with the cart line items and vendor.
Fill in title, cost centre, accounting code; submit normally.

Track inventory at a site (Manager / Admin)

Open Sites → click a site.
View the current-stock bar chart and the 30-day consumption line chart.
Use Log Consumption to record a daily drawdown (product, date, quantity, note). See Inventory and Catalogue.

Import a PO from Excel (Manager / SuperUser / Admin)

Open Import PO and upload a Pelagia-format .xlsx.
The parser extracts line items, vendor, and quotation details; the company is auto-detected and the vessel auto-matched by code.
The PO is saved directly as CLOSED (a historical record), auto-creating the vendor and any unknown products. See Purchase Orders.

Export PO history (Auditor / Manager)

Open History; apply filters (date range, cost centre, one or more statuses).
Export PDF or Export CSV → downloads the matching POs (up to ~200).

User stories (priority reference)

From the original spec (Docs/01-design-document.md §8); IDs are referenced by the Test Plan. P0 = must-have, P1 = should-have.

Submitter (Technical / Manning)

ID	Story	Pri
S-01	Create a PO with line items and attach documents	P0
S-02	Save a PO as draft before submitting	P0
S-03	Submit a draft PO for approval	P0
S-04	Receive email when my PO is approved/rejected	P0
S-05	View status and history of all my POs	P0
S-06	Provide a vendor ID when requested	P0
S-07	Edit and resubmit when edits are requested	P0
S-08	Confirm receipt and upload a receipt to close a PO	P0

Manager

ID	Story	Pri
M-01	See all POs awaiting my approval	P0
M-02	Approve / reject / request edits	P0
M-03	Add a note when approving or rejecting	P0
M-04	Flag a PO for vendor-ID verification	P0
M-05	View spend analytics by cost centre and month	P1
M-06	Export a full PO history report (CSV/PDF)	P1

Accounts

ID	Story	Pri
A-01	See all manager-approved POs ready for payment	P0
A-02	Mark a PO as paid with a reference	P0
A-03	Receive email when a PO enters my payment queue	P0

Admin

ID	Story	Pri
AD-01	Create, edit, deactivate user accounts	P0
AD-02	Manage cost centres, accounting codes, vendors	P0
AD-03	Manage the product catalogue	P1

Non-goals (out of scope)

Mobile-native app (web is desktop-first), public-facing pages, self-registration / generic OAuth, a vendor self-service portal, and automated bank/payment-gateway integration (payment is marked manually).

Pelagia Portal (PPMS)

Home

Overview

Build & Run

System

Product

Planned

Quality

Ops

Engineering

Tech Debt

Pelagia Portal (PPMS) — internal purchase-order management. Self-hosted on pms1, live at pms.pelagiamarine.com. This wiki tracks the shipped product; authoritative sources are the repo code, App/CLAUDE.md, Docs/, and CHANGELOG.md.