# Pelagia Portal — Build Progress

Last updated: 2026-05-05

Legend: ✅ Complete · ⚠️ Partial (works but incomplete) · ❌ Not started

---

## Infrastructure & Config

| Item | Status | Notes |
|---|---|---|
| Next.js 15 App Router project | ✅ | Turbopack dev, strict TS |
| Tailwind CSS v4 + design tokens | ✅ | Colour palette matches spec |
| Prisma schema — all models | ✅ | Product, gstRate, piQuotationNo/Date, requisitionNo/Date, placeOfDelivery, tcDelivery/tcDispatch/tcInspection/tcTransitInsurance/tcPaymentTerms/tcOthers, address/gstin/contactMobile on Vendor — all migrated (latest: `structured_tc_fields`) |
| Database seed script | ✅ | 5 users, 3 vessels, 3 accounts, 3 vendors, 3 sample POs, 4 products |
| Dev / production environment split | ✅ | `NODE_ENV` gates R2 vs local storage, Resend vs console log |
| `.env.example` + `.env` / `.env.local` docs | ✅ | README covers full setup |
| README with dev + prod setup guide | ✅ | |
| CI/CD (GitHub Actions) | ❌ | No workflow files yet |

---

## Authentication & Authorisation

| Item | Status | Notes |
|---|---|---|
| Login page (credentials) | ✅ | Email + password, bcrypt hash |
| NextAuth.js v5 session | ✅ | Database sessions, role in JWT |
| Auth middleware (route protection) | ✅ | Redirects unauthenticated to `/login` |
| Role permissions matrix (`lib/permissions.ts`) | ✅ | All 7 roles; `manage_products` added for Admin |
| SSO / Azure AD login | ❌ | Open question — credentials only for v1 |

---

## PO State Machine (`lib/po-state-machine.ts`)

| Item | Status | Notes |
|---|---|---|
| All 10 statuses defined | ✅ | |
| All transitions with role guards | ✅ | |
| `canPerformAction`, `getAvailableActions` helpers | ✅ | |
| `requiresNote` helper | ✅ | |
| Unit tests | ✅ | `tests/unit/po-state-machine.test.ts` |

---

## Email Notifications (`lib/notifier.ts`)

| Item | Status | Notes |
|---|---|---|
| Notifier module (Resend in prod, console in dev) | ✅ | |
| Email templates (all 7 events) | ✅ | React Email components in `/emails/` |
| Notify on PO submitted | ✅ | Notifies managers + submitter (confirmation) |
| Notify on PO approved / rejected / edits requested | ✅ | Per notification matrix |
| Notify on vendor ID requested / provided | ✅ | |
| Notify on payment processed | ✅ | Notifies managers + accounts on processing; submitter + managers on confirmed |
| Notify on receipt confirmed | ✅ | Notifies managers + accounts |

---

## File Storage (`lib/storage.ts`)

| Item | Status | Notes |
|---|---|---|
| Dev local storage (`/api/files/dev/[...key]`) | ✅ | Auth-gated, path-traversal protected |
| Prod Cloudflare R2 presigned URLs | ✅ | Upload + download URL generation |
| Sign API (`/api/files/sign`) | ✅ | Returns `{ uploadUrl, key }` |
| File upload UI on New PO form | ✅ | `FileUploader` component + `uploadAndLinkFiles` utility; PO created first, then files signed+uploaded+linked |
| File upload UI on Receipt form | ✅ | Same pattern, type `"receipt"` |
| Document download links on PO detail | ✅ | `PoDetail` made async; `generateDownloadUrl` called server-side; filenames are clickable links |

---

## Pages & Server Actions

### Login
| Item | Status |
|---|---|
| Login page + credentials form | ✅ |

### Dashboard
| Item | Status | Notes |
|---|---|---|
| Submitter dashboard (stat cards + New PO CTA) | ✅ | Recent orders table; link to My Orders |
| Manager dashboard (stat cards) | ✅ | |
| Manager dashboard — approved POs listing | ✅ | Recent approved/in-progress POs table with vessel, status, amount |
| Manager dashboard — spend by vessel breakdown | ✅ | Recharts bar chart (top 5 vessels) |
| Manager spend-by-vessel bar chart | ✅ | `SpendCharts` component using Recharts |
| Manager spend-by-month bar chart | ✅ | Last 12 months, bar chart |
| Accounts dashboard (stat cards) | ✅ | |
| Auditor / Admin / generic dashboard | ✅ | Single total-count card |

### New PO
| Item | Status | Notes |
|---|---|---|
| Form (title, vessel, account, vendor, project code, date) | ✅ | |
| Line items — UoM dropdown (15 options) | ✅ | Replaces free-text unit field |
| Line items — Size field | ✅ | Optional free-text |
| Line items — GST rate per item (0 / 5 / 12 / 18 / 28%) | ✅ | Default 18%; taxable / GST / grand-total breakdown shown live in editor |
| PI / Quotation No. + Date | ✅ | Separate section on form |
| Vessel / Office Requisition No. + Date | ✅ | Separate section on form |
| Place of Delivery | ✅ | Pre-filled with company delivery address; editable |
| Terms & Conditions — structured fields | ✅ | Fixed line 1 (read-only); separate inputs for Delivery, Dispatch Instructions, Inspection, Transit Insurance, Payment Terms, Others (multiline); all pre-filled with defaults |
| Currency defaults to INR | ✅ | Changed from USD → INR throughout |
| Save as draft | ✅ | |
| Submit for approval (→ MGR_REVIEW) | ✅ | |
| Document file upload | ✅ | Drag-and-drop + click; signed upload after PO creation |

### PO Detail (`/po/[id]`)
| Item | Status | Notes |
|---|---|---|
| Full detail view (info, vendor, line items, activity trail) | ✅ | |
| New fields displayed (PI/Quotation, Requisition, Delivery, Approved By) | ✅ | |
| Line items with GST breakdown (taxable / GST / grand total) | ✅ | |
| Vendor detail (address, GSTIN, contact name + mobile + email) | ✅ | |
| Terms & Conditions block (structured display) | ✅ | Fixed line 1 always shown; each labeled field (Delivery, Dispatch, etc.) on its own line |
| Export PDF button | ✅ | `/api/po/[id]/export?format=pdf` — auto-triggers print dialog; matches Sample_PO layout |
| Export XLSX button | ✅ | `/api/po/[id]/export?format=xlsx` — SheetJS; matches Sample_PO column layout |
| Confirm Receipt CTA (PAID_DELIVERED state) | ✅ | |
| Document download links | ✅ | Clickable links with server-generated presigned/dev URLs |
| Edit PO link (DRAFT / EDITS_REQUESTED) | ✅ | |

### PO Edit (`/po/[id]/edit`)
| Item | Status | Notes |
|---|---|---|
| Edit page | ✅ | Pre-populated form including all new fields |
| Update draft action | ✅ | |
| Resubmit after edits | ✅ | Shows manager note banner + Resubmit button |

### Vendor ID Flow
| Item | Status | Notes |
|---|---|---|
| Request vendor ID action (manager) | ✅ | Sets status to `VENDOR_ID_PENDING` |
| Provide vendor ID UI (submitter / manager) | ✅ | Inline form on PO detail for VENDOR_ID_PENDING |
| Provide vendor ID server action | ✅ | Transitions back to `MGR_REVIEW`, notifies managers |

### Approvals
| Item | Status | Notes |
|---|---|---|
| Approval queue list | ✅ | |
| PO detail + decision view | ✅ | |
| Approve / Approve+Note actions | ✅ | |
| Reject action | ✅ | |
| Request edits action | ✅ | |
| Request vendor ID action | ✅ | |
| Manager edit line items (amber edit mode) | ✅ | Saves original snapshot to POAction; diff shown with strike-through |
| Search / filter (PO number, vessel, submitter, date) | ✅ | URL search params; `ApprovalsSearch` client component |

### Payments
| Item | Status | Notes |
|---|---|---|
| Payment queue list (MGR_APPROVED + SENT_FOR_PAYMENT) | ✅ | |
| Start payment processing (MGR_APPROVED → SENT_FOR_PAYMENT) | ✅ | Step 1 |
| Confirm payment sent with ref (SENT_FOR_PAYMENT → PAID_DELIVERED) | ✅ | Step 2 — auto-updates Product.lastPrice for linked line items |

### My Orders (`/my-orders`)
| Item | Status | Notes |
|---|---|---|
| My Orders page — all POs with open/past grouping | ✅ | Links to individual PO detail; shows manager note inline |

### Receipt Confirmation
| Item | Status | Notes |
|---|---|---|
| Notes + file receipt confirmation | ✅ | Closes PO to `CLOSED`; optional file attachment via `FileUploader` |

### History
| Item | Status | Notes |
|---|---|---|
| All-POs list (latest 200 by default) | ✅ | |
| CSV export | ✅ | Respects active filters |
| PDF export (bulk) | ✅ | Print-optimised HTML page (`/api/reports/export?format=pdf`); auto-triggers browser print dialog |
| Date range filter | ✅ | URL search params; `HistoryFilters` client component |
| Vessel / status filters | ✅ | Same component |

### Admin — User Management
| Item | Status | Notes |
|---|---|---|
| User list | ✅ | |
| Add user form + action | ✅ | `AdminDialog` modal; bcrypt password hash |
| Edit user form + action | ✅ | Optional password change |
| Deactivate / reactivate user | ✅ | Cannot deactivate own account |

### Admin — Vendor Management
| Item | Status | Notes |
|---|---|---|
| Vendor list | ✅ | |
| Add vendor form + action | ✅ | `AdminDialog` modal; sets `isVerified` if vendorId provided |
| Edit vendor form + action | ✅ | Includes address, GSTIN, contact mobile |
| Deactivate / reactivate vendor | ✅ | |

### Admin — Vessel Management
| Item | Status | Notes |
|---|---|---|
| Vessel list page | ✅ | `/admin/vessels` |
| Add vessel form + action | ✅ | Name-only cost centre creation |
| Edit vessel form + action | ✅ | |
| Deactivate / reactivate vessel | ✅ | |

### Admin — Account Management
| Item | Status | Notes |
|---|---|---|
| Account list page | ✅ | `/admin/accounts` |
| Add account form + action | ✅ | Code uniqueness check |
| Edit account form + action | ✅ | |
| Deactivate / reactivate account | ✅ | |

### Admin — Product Catalogue (`/admin/products`)
| Item | Status | Notes |
|---|---|---|
| Product list (code, name, last price, last vendor) | ✅ | Last price/vendor read-only — auto-populated on payment |
| Create product action | ✅ | Code must be unique |
| Toggle active/inactive action | ✅ | |
| Add product form (UI) | ✅ | `AdminDialog` modal wired to existing `createProduct` action |

---

## Type Safety

| Item | Status | Notes |
|---|---|---|
| Discriminated union narrowing in `approval-actions.tsx` | ✅ | Typed as `{ ok: true } \| { error: string } \| undefined`, checked with `"error" in result` |
| Union narrowing in `receipt-form.tsx` | ✅ | |
| Union narrowing in `new-po-form.tsx` | ✅ | |
| Buffer type in `api/files/dev/route.ts` | ✅ | Cast to `Uint8Array` |
| New PO fields in Prisma types | ⚠️ | Migration applied; Prisma client types stale — resolve by restarting dev server and running `pnpm db:generate` |

---

## Testing

| Item | Status | Notes |
|---|---|---|
| Unit: state machine | ✅ | `tests/unit/po-state-machine.test.ts` — 21 tests |
| Unit: permissions | ✅ | `tests/unit/permissions.test.ts` — 11 tests |
| Unit: utility functions | ✅ | `tests/unit/utils.test.ts` — 17 tests (formatCurrency INR, formatDate, generatePoNumber, status labels/variants) |
| Unit: Zod validation schemas | ✅ | `tests/unit/validations.test.ts` — 24 tests (createPoSchema, lineItemSchema, TC fields, defaults) |
| Component: PoStatusBadge | ✅ | `tests/unit/po-status-badge.test.tsx` — 17 tests (all 10 statuses) |
| Component: LineItemsEditor | ✅ | `tests/unit/po-line-items-editor.test.tsx` — 20 tests (add/remove rows, GST calc, totals, read-only, diff mode) |
| Integration: PO creation (S-01, S-02, S-03) | ✅ | `tests/integration/create-po.test.ts` — 9 tests; uses real DB + mocked auth/notifier |
| Integration: Approval actions (M-02, M-03, M-04, S-06, S-07) | ✅ | `tests/integration/approval-actions.test.ts` — 14 tests |
| Integration: Payment actions (A-01, A-02) | ✅ | `tests/integration/payment-actions.test.ts` — 8 tests |
| E2E: authentication flow | ✅ | `tests/e2e/auth.spec.ts` — 6 tests |
| E2E: submitter journey (S-01 to S-08) | ✅ | `tests/e2e/submitter-journey.spec.ts` — 8 tests |
| E2E: manager approvals (M-01 to M-04) | ✅ | `tests/e2e/manager-approvals.spec.ts` — 9 tests |
| E2E: accounts payment (A-01, A-02) | ✅ | `tests/e2e/accounts-payment.spec.ts` — 6 tests |
| E2E: PO export (PDF + XLSX) | ✅ | `tests/e2e/po-export.spec.ts` — 8 tests (buttons, endpoints, content, auth) |
| Accessibility (axe-core + Playwright) | ❌ | Not yet written |

---

## Summary

| Category | Total items tracked | ✅ Done | ⚠️ Partial | ❌ Pending |
|---|---|---|---|---|
| Infrastructure | 8 | 7 | 0 | 1 |
| Auth & Permissions | 5 | 4 | 0 | 1 |
| State Machine | 5 | 5 | 0 | 0 |
| Email Notifications | 7 | 7 | 0 | 0 |
| File Storage | 6 | 6 | 0 | 0 |
| Pages & Actions | 83 | 83 | 0 | 0 |
| Type Safety | 5 | 4 | 1 | 0 |
| Testing | 15 | 14 | 0 | 1 |
| **Total** | **134** | **130 (97%)** | **1 (1%)** | **3 (2%)** |

---

## Remaining Items

1. **Prisma client regeneration** — restart dev server, then `pnpm db:generate` (DLL was locked during the last generate; migration is fully applied, no data loss)
2. **CI/CD** — GitHub Actions workflow: lint, type-check, test, build on PR; deploy on merge
3. **Accessibility tests** — axe-core + Playwright
4. **SSO / Azure AD** — credentials-only for v1; open question for v2

---

## Not in Spec (deferred)

- SSO / Azure AD login
- Discount field on PO
- Account Group / Account Code hierarchy (codes currently flat)
- Cost centre vs vessel distinction (currently same entity)
- Vendor deactivation cascade — warn if vendor has open POs
- Approval queue — show VENDOR_ID_PENDING alongside MGR_REVIEW
- Vendor required before approval can be granted (currently advisory only)