Hardik
d769cae71e
- Delete /inventory/items/[id] — items expand inline in the list - Move SiteSelect from deleted [id] folder to components/inventory/site-select - Fix admin product detail page import to use new shared path - Fix items-table: Fragment key prop, restore Link import, plain text item names - Fix vendor-items-table: remove broken link to deleted item detail page Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# Pelagia Portal — Design Document
|
||
|
||
## 1. Overview
|
||
|
||
Pelagia Portal is an internal purchase order (PO) management web application for a maritime / vessel-operations company. It digitises the entire PO lifecycle — from a crew member raising a requisition, through manager approval and vendor validation, to accounts payment processing and final receipt confirmation — replacing ad-hoc email chains and spreadsheets with a single, auditable system.
|
||
|
||
---
|
||
|
||
## 2. Goals & Non-Goals
|
||
|
||
### Goals
|
||
- Provide role-specific dashboards and workflows so every actor only sees what is relevant to their job.
|
||
- Enforce a structured, auditable approval chain for every purchase order.
|
||
- Notify all stakeholders at each state transition via email without manual action.
|
||
- Give management real-time spend visibility by vessel, project, and time period.
|
||
- Surface vendor information deficiencies before payment is blocked.
|
||
|
||
### Non-Goals
|
||
- Direct integration with external accounting or ERP software (out of scope for v1).
|
||
- Mobile-native apps (the web app is expected to be accessed on desktop/tablet).
|
||
- Supplier-facing self-service portal.
|
||
- Automated payment processing (Accounts team confirms payment manually).
|
||
|
||
---
|
||
|
||
## 3. Actors & Roles
|
||
|
||
| Role | Description | Key Permissions |
|
||
|---|---|---|
|
||
| **Technical** | Deck / engine crew raising POs for technical vessel needs | Create, edit draft, submit, confirm receipt |
|
||
| **Manning** | Crew-management staff raising POs for manning / crew needs | Same as Technical |
|
||
| **Manager** | Approves or rejects POs; can request edits, add vendor IDs, or directly amend line items during review | Review, approve, reject, request edits, edit line items (versioned), view all POs, history reports |
|
||
| **Accounts** | Processes payment for approved POs | View payment queue, mark as paid, view all POs |
|
||
| **SuperUser** | Elevated user with cross-team operational authority | All Technical + Manning + Manager permissions |
|
||
| **Auditor** | Read-only audit access across all records | View all POs, download audit trail, export reports |
|
||
| **Admin** | System administrator | Manage users, vessels, accounts, vendors; full CRUD on all entities |
|
||
|
||
---
|
||
|
||
## 4. PO Lifecycle & State Machine
|
||
|
||
```
|
||
DRAFT ──(submit)──► SUBMITTED ──(system auto-move)──► MGR_REVIEW
|
||
│
|
||
┌──────────────────────────────────────┤
|
||
│ │ │
|
||
(no vendor ID) (request edits) (reject)
|
||
▼ ▼ ▼
|
||
VENDOR_ID_PENDING EDITS_REQUESTED REJECTED
|
||
│ │
|
||
(ID provided) (resubmit)
|
||
└────────────────────┘
|
||
│
|
||
(approve / approve+note)
|
||
▼
|
||
MGR_APPROVED
|
||
│
|
||
(accounts picks up)
|
||
▼
|
||
SENT_FOR_PAYMENT
|
||
│
|
||
(payment confirmed)
|
||
▼
|
||
PAID_DELIVERED
|
||
│
|
||
(submitter confirms receipt)
|
||
▼
|
||
CLOSED
|
||
```
|
||
|
||
### Allowed State Transitions
|
||
|
||
| From | To | Actor | Trigger |
|
||
|---|---|---|---|
|
||
| DRAFT | SUBMITTED | Technical / Manning / SuperUser | Submit button |
|
||
| SUBMITTED | MGR_REVIEW | System | Auto on submit |
|
||
| MGR_REVIEW | VENDOR_ID_PENDING | Manager | Missing vendor ID |
|
||
| VENDOR_ID_PENDING | MGR_REVIEW | Submitter / Manager | Vendor ID supplied |
|
||
| MGR_REVIEW | EDITS_REQUESTED | Manager | Request edits action |
|
||
| EDITS_REQUESTED | SUBMITTED | Technical / Manning / SuperUser | Resubmit after edits |
|
||
| MGR_REVIEW | REJECTED | Manager | Reject action |
|
||
| MGR_REVIEW | MGR_APPROVED | Manager / SuperUser | Approve or Approve+Note |
|
||
| MGR_APPROVED | SENT_FOR_PAYMENT | Accounts | Pick up payment |
|
||
| SENT_FOR_PAYMENT | PAID_DELIVERED | Accounts | Confirm payment |
|
||
| PAID_DELIVERED | CLOSED | Technical / Manning / SuperUser | Confirm receipt |
|
||
|
||
---
|
||
|
||
## 5. Email Notification Matrix
|
||
|
||
| Event | Notified Parties |
|
||
|---|---|
|
||
| PO submitted | Manager(s), Submitter (confirmation) |
|
||
| Vendor ID requested | Submitter |
|
||
| Vendor ID supplied | Manager |
|
||
| Edits requested | Submitter (includes manager note) |
|
||
| PO resubmitted after edits | Manager |
|
||
| PO approved | Submitter, Accounts (with PO attachment) |
|
||
| PO approved with note | Submitter (with note), Accounts |
|
||
| PO rejected | Submitter (with rejection reason) |
|
||
| Payment sent | Submitter, Manager |
|
||
| Receipt confirmed | Manager, Accounts |
|
||
| PO closed | Submitter, Manager, Accounts |
|
||
|
||
---
|
||
|
||
## 6. Screen Inventory
|
||
|
||
### 6.1 Authentication
|
||
- **Login** — Employee ID / email + password. Role badge hints displayed. No self-registration; accounts provisioned by Admin.
|
||
|
||
### 6.2 Dashboards (role-specific landing pages)
|
||
- **Technical / Manning Dashboard** — My open POs count, pending approvals, completed orders, quick-access "New PO" CTA. Full list of all POs (open and historical) is accessible and each PO is openable from the dashboard.
|
||
- **Manager Dashboard** — Approvals awaiting count, approved POs listing with per-PO expense breakdown (line items + totals), spend by vessel (bar chart), spend by month (bar chart), recent activity feed.
|
||
- **Accounts Dashboard** — Payment queue total value, ready-for-payment item count, recently processed items.
|
||
|
||
### 6.3 PO Creation & Editing
|
||
- **New PO Form** — Multi-section form:
|
||
- Order Info: title, vessel, account, project code, date required
|
||
- Line Items: add / remove rows (description, qty, unit, unit price, total)
|
||
- Vendor: vendor name, vendor ID (optional at creation), contact
|
||
- Documents: drag-and-drop upload, file list with remove
|
||
- Approval Flow: read-only visual showing who will review
|
||
- **Edit PO** — Same form, pre-populated; only available when PO is in DRAFT or EDITS_REQUESTED.
|
||
|
||
### 6.4 Manager Approval
|
||
- **Approval Queue** — Paginated list with search (PO number, vessel, submitter) and filters (date range, vessel). Each row shows PO number, submitter, vessel, amount, days waiting.
|
||
- **PO Detail / Decision View** — Full PO summary, line items, attached documents, vendor info with verification callout (NEW if no ID). 4-action bar: Reject | Request Edits | Approve | Approve + Note.
|
||
|
||
### 6.5 Accounts Payment Queue
|
||
- **Payment Queue** — Approved POs ready for payment. Shows PO summary, total amount, bank / payment ref fields. "Mark as Paid" action.
|
||
|
||
### 6.6 Order Tracking (Submitter)
|
||
- **My Orders** — Card list with live status indicator, progress step-bar, latest manager note, and "Confirm Receipt" CTA when in PAID_DELIVERED.
|
||
|
||
### 6.7 Receipt Confirmation
|
||
- **Receipt Screen** — Upload receipt / invoice image, delivery confirmation checklist, optional notes. Submits to close the PO.
|
||
|
||
### 6.8 Manager History / Reports
|
||
- **History** — Full PO audit list with date, submitter, vessel, status, amount. Export to CSV / PDF. Filter by date range, vessel, status.
|
||
|
||
### 6.9 Administration (Admin role)
|
||
- **User Management** — CRUD for user accounts, role assignment.
|
||
- **Vessel Management** — CRUD for vessels.
|
||
- **Account Management** — CRUD for accounts / cost centres.
|
||
- **Vendor Management** — CRUD for approved vendor registry.
|
||
- **Product Catalogue** — CRUD for products: product code, name, description. Last known unit price and associated vendor are read-only in this view — they are auto-populated when a PO containing that product is marked as paid.
|
||
|
||
---
|
||
|
||
## 7. Design System
|
||
|
||
### 7.1 Colour Palette
|
||
|
||
| Token | Hex | Usage |
|
||
|---|---|---|
|
||
| `primary` | `#2563EB` | Primary actions, active states, links |
|
||
| `primary-dark` | `#1D4ED8` | Hover on primary |
|
||
| `success` | `#16A34A` | Approved, paid, closed states |
|
||
| `warning` | `#D97706` | Pending review, edits requested |
|
||
| `danger` | `#DC2626` | Rejected, destructive actions |
|
||
| `neutral-50` | `#F9FAFB` | Page background |
|
||
| `neutral-100` | `#F3F4F6` | Card / panel background |
|
||
| `neutral-700` | `#374151` | Body text |
|
||
| `neutral-900` | `#111827` | Headings |
|
||
|
||
### 7.2 Typography
|
||
|
||
| Element | Font | Weight | Size |
|
||
|---|---|---|---|
|
||
| Headings (H1–H3) | Inter | 600–700 | 24 / 20 / 16 px |
|
||
| Body | Inter | 400 | 14 px |
|
||
| Labels / captions | Inter | 500 | 12 px |
|
||
| Data / mono values | JetBrains Mono | 400 | 13 px |
|
||
|
||
### 7.3 Component Conventions
|
||
- Cards use `rounded-lg`, `shadow-sm`, 16 px padding.
|
||
- Status badges use pill shape with colour-coded background matching state machine colours.
|
||
- Tables use alternating row shading, sticky header on scroll.
|
||
- Forms use floating labels; validation errors appear below the field in `danger` colour.
|
||
- Action buttons: primary = blue fill, secondary = white with border, danger = red fill.
|
||
|
||
---
|
||
|
||
## 8. User Stories (Priority P0 = must-have, P1 = should-have, P2 = nice-to-have)
|
||
|
||
### Submitter (Technical / Manning)
|
||
| ID | Story | Priority |
|
||
|---|---|---|
|
||
| S-01 | As a submitter, I can create a PO with line items and attach documents. | P0 |
|
||
| S-02 | As a submitter, I can save a PO as draft before submitting. | P0 |
|
||
| S-03 | As a submitter, I can submit a draft PO for manager approval. | P0 |
|
||
| S-04 | As a submitter, I receive an email when my PO is approved or rejected. | P0 |
|
||
| S-05 | As a submitter, I can view the current status and history of all my POs. | P0 |
|
||
| S-06 | As a submitter, I can provide a vendor ID when requested by a manager. | P0 |
|
||
| S-07 | As a submitter, I can edit and resubmit a PO when edits are requested. | P0 |
|
||
| S-08 | As a submitter, I can confirm receipt and upload a receipt document to close a PO. | P0 |
|
||
|
||
### Manager
|
||
| ID | Story | Priority |
|
||
|---|---|---|
|
||
| M-01 | As a manager, I see all POs awaiting my approval in a queue. | P0 |
|
||
| M-02 | As a manager, I can approve, reject, or request edits on a PO. | P0 |
|
||
| M-03 | As a manager, I can add a note when approving or rejecting. | P0 |
|
||
| M-04 | As a manager, I can flag a PO for vendor ID verification. | P0 |
|
||
| M-05 | As a manager, I can view spend analytics by vessel and month. | P1 |
|
||
| M-06 | As a manager, I can export a full PO history report as CSV or PDF. | P1 |
|
||
|
||
### Accounts
|
||
| ID | Story | Priority |
|
||
|---|---|---|
|
||
| A-01 | As an accounts user, I see all manager-approved POs ready for payment. | P0 |
|
||
| A-02 | As an accounts user, I can mark a PO as paid with a reference number. | P0 |
|
||
| A-03 | As an accounts user, I receive email when a new PO enters my payment queue. | P0 |
|
||
|
||
### Admin
|
||
| ID | Story | Priority |
|
||
|---|---|---|
|
||
| AD-01 | As an admin, I can create, edit, and deactivate user accounts. | P0 |
|
||
| AD-02 | As an admin, I can manage vessels, accounts, and vendors. | P0 |
|
||
| AD-03 | As an admin, I can manage the product catalogue (codes, names, descriptions). Last known prices and vendors are automatically updated when a PO is paid. | P1 |
|
||
|
||
---
|
||
|
||
## 9. Accessibility & Internationalisation
|
||
- WCAG 2.1 AA compliance target.
|
||
- All interactive elements keyboard-navigable with visible focus ring.
|
||
- Colour is never the sole conveyor of meaning (icons + labels accompany status colours).
|
||
- English only for v1; i18n architecture (react-i18next) to be wired up but not populated.
|
||
|
||
---
|
||
|
||
## 10. Open Questions
|
||
- Should managers be able to directly edit a PO (bypass submitter) in exceptional circumstances?
|
||
- What is the approval chain for high-value POs — single manager or dual sign-off?
|
||
- Should the vendor registry be editable by managers, or Admin-only?
|
||
- Is SSO (e.g., Azure AD) required for login, or internal credential management is sufficient?
|