Table of Contents

Crewing User Stories

Epic A — Requisitions (vacancy management)
Epic B — Candidate intake
Epic C — Recruitment pipeline (vetting)
Epic D — Onboarding
Epic E — Crew records & documents
Epic F — PPE issue register
Epic G — Leave & attendance
Epic H — Appraisal
Epic I — Office verification
Epic J — Payroll / wage report
Epic K — Sign-off & experience
Epic L — Reference data & admin
Epic M — Cross-cutting

Suggested delivery order

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Crewing User Stories

Authoritative build spec: Crewing Implementation Spec carries the full reconciled instructions (codebase changes, roles/nav matrices, screen spec). This page is the requirement backlog, aligned with that spec.

Backlog for the Crewing Module, grouped into epics. Format: As a <role>, I want <capability>, so that <value> + acceptance criteria (AC). IDs are stable references for PRs/issues.

Epic A — Requisitions (vacancy management)

A1 — Auto-requisition on sign-off As an MPO, I want a requisition raised automatically when a crew member signs off, so that no vacancy goes untracked.

AC1: signing off an assignment creates a Requisition(OPEN, autoRaised) for the same rank + vessel.
AC2: the requisition records the reason (EOC / medical / termination / other).
AC3: the MPO receives an email + in-app notification.
AC4: a CrewAction(REQUISITION_RAISED) is written.

A2 — Manual requisition As an MPO / Manager, I want to raise a requisition manually (e.g. planned leave), so that I can pre-empt a gap.

AC1: I select vessel, rank, reason, needed-by date, and min-experience criteria.
AC2: the requisition appears in the MPO shortlist queue.

A2b — Request relief cover (site staff) As site staff, I want to flag a foreseen cover gap (I cannot raise requisitions myself), so that the office can act on it.

AC1: I submit a relief request (vessel, rank, reason, note) → ReliefRequest(OPEN).
AC2: it appears in the office "Relief requests from sites" list; the MPO/Manager convert it into a requisition (status CONVERTED).

A3 — Requisition list & detail As an MPO/Manager, I want a filterable list of requisitions by vessel/rank/status, so that I can prioritise sourcing.

AC1: filters for status, vessel, rank, reason, needed-by.
AC2: each row shows candidate count and days open.

A4 — Cancel requisition As a Manager, I want to cancel a requisition with a reason, so that withdrawn vacancies don't clutter the pipeline.

AC1: only non-FILLED requisitions can be cancelled.
AC2: reason is required and audited.

A5 — Auto-requisition on leave clash As the system, I want a requisition raised automatically when an approved leave clashes (a rank drops below its required strength on a vessel/site), so that the cover gap is owned immediately.

AC1: approving a leave that overlaps others for the same rank below required strength creates a Requisition(OPEN, reason=LEAVE, autoRaised).
AC2: the MPO is notified (email + in-app) and the clash is highlighted on the planner.
AC3: a CrewAction(REQUISITION_RAISED) is written.

Epic B — Candidate intake

B1 — Public application with CV As a candidate, I want to apply on the Pelagia site and upload my CV, so that I'm considered without re-typing everything.

AC1: the form accepts personal details + CV upload (signed upload to storage).
AC2: the CV is parsed for age, vessel type, current/past rank, experience.
AC3: parsed fields pre-fill a draft I can correct before submitting.
AC4: if parsing fails, I can enter all fields manually (intake never blocks).
AC5: submission creates a CrewMember(PROSPECT) + application(s).

B2 — MPO manual candidate upload As an MPO, I want to add a candidate and their CV directly, so that walk-ins/referrals enter the same pipeline.

AC1: same parse-or-manual flow as B1.
AC2: the candidate is attachable to one or more open requisitions.

B3 — Ex-hand recognition As an MPO, I want ex-hands flagged and preferred in shortlisting, so that proven crew are surfaced first.

AC1: candidates matching an existing CrewMember(EX_HAND) are tagged.
AC2: ex-hands sort above new candidates by default.
AC3: ex-hand experience/documents are pre-populated from history.

Epic C — Recruitment pipeline (vetting)

C1 — Shortlist to a requisition As an MPO, I want to shortlist candidates against a requisition, so that vetting can begin.

AC1: shortlisting moves the requisition to SHORTLISTING and the application to SHORTLISTED.

C2 — Competency check As an MPO, I want to record a competency result against the rank's minimum criteria, so that unqualified candidates are filtered early.

AC1: pass advances to document verification; fail → REJECTED + remarks.

C3 — Document verification (vetting) As an MPO, I want to verify a candidate's seafarer documents during vetting, so that only documented candidates proceed.

AC1: missing/expired required docs (per rank) block advancement.
AC2: result recorded as an APPLICATION_GATE.

C4 — Experience check As an MPO, I want to verify experience (vessel type, time-in-rank, total duration) against the requisition's criteria, so that the candidate fits the seat.

AC1: criteria comparison shown; shortfall flagged.

C5 — Reference check As an MPO, I want to record reference-check outcomes, so that prior conduct is confirmed.

AC1: at least one reference result recorded before proposal.

C6 — Salary agreement As an MPO, I want to record an agreed salary structure (basic, victualing, allowances), so that the proposal has terms.

AC1: structure captured; visible only to office roles (not site staff).

C7 — Proposal & interview As an MPO, I want to propose to the candidate and record an interview result, so that selection is informed.

AC1: everyone is interviewed by default; the MPO records the result.
AC2: for a returning ex-hand the interview is waived only with Manager approval — the MPO requests the waiver (request_interview_waiver), a Manager approves it (approve_interview_waiver), then interviewWaived is set. There is no automatic waiver.

C8 — Selection / rejection with remarks As an MPO (records) and Manager (approves), I want to select or reject with remarks, so that the decision and its reason are on record.

AC1: rejection requires remarks.
AC2: selection requires all prior gates cleared.
AC3: selection is Manager-approved — the MPO records the interview result; the Manager approves the salary structure and the selection.

C9 — Pipeline board As an MPO, I want a board showing each candidate's stage per requisition, so that I can see the funnel at a glance.

AC1: columns map to ApplicationStage; cards show candidate + last gate.

Epic D — Onboarding

D1 — Approve salary structure & candidate list As a Manager, I want to approve the proposed salary structure and selected candidate, so that onboarding can proceed.

AC1: onboarding is blocked until the structure is MANAGER_APPROVED.

D2 — Joining formalities & onboard As an MPO/Manager, I want to complete joining formalities and onboard the candidate, so that they become an employee.

AC1: a contract letter is attached; salary confirmed.
AC2: onboarding creates a CrewAssignment(ACTIVE), assigns an employeeId, and sets CrewMember.status = EMPLOYEE.
AC3: the filled requisition flips to FILLED.

D3 — Onboarding side-effects As the system, I want onboarding to start salary, victualing, attendance, experience, PF and PPE in one transaction, so that nothing is missed.

AC1: all six are initialised atomically.
AC2: a single CrewAction(ONBOARDED) records the created IDs in metadata.

Epic E — Crew records & documents

E1 — Crew directory & profile As an MPO, I want a crew directory with a per-member profile, so that I can find anyone's records.

AC1: profile groups documents, bank, EPF, next-of-kin, emergency, PPE, experience, appraisals.

E2 — Upload seafarer documents As site staff, I want to upload role-based documents (STCW, Aadhaar, PAN, passport, CDC, COC, photo, licence, medical fitness), so that the office can verify them.

AC1: required set is driven by rank (RankDocRequirement); driver requires a driving licence.
AC2: documents store issue/expiry dates; uploads start PENDING.

E3 — Document expiry warnings As an MPO, I want upcoming-expiry warnings, so that crew don't sail on expired documents.

AC1: docs expiring within N days are flagged on the profile and a queue.

E4 — Bank / EPF / next-of-kin / emergency As site staff, I want to record bank details, EPF (UAN/Aadhaar), next-of-kin and emergency contacts, so that payroll and welfare are covered.

AC1: bank account number stored masked/encrypted; site staff see it view-only.
AC2: contract letter is view-only-except-salary for site staff.

Epic F — PPE issue register

F1 — Capture sizes As site staff, I want to record boiler-suit and safety-shoe sizes, so that the right kit is issued.

AC1: size is captured on the relevant PPE issue.

F2 — Issue PPE kit As site staff, I want to issue PPE items (boiler suit, shoes, helmet, vest, gloves, mask, goggles, tiffin, torch, walkie-talkie), so that issuance is logged.

AC1: each issue records item, quantity, size?, date, issuer.
AC2: (flag on) optionally decrements site ItemInventory.

F3 — Returns As site staff, I want to record PPE returns, so that the register is current.

AC1: a returnedDate closes the issue.

Epic G — Leave & attendance

G1 — Site leave planner As site staff / Manager, I want a planner showing every crew member's contract span and leaves on one timeline, so that I can plan cover. (The MPO has no leave access.)

AC1: timeline per site with contract bars + leave bars.
AC2: overlapping absences for the same rank are highlighted (a clash below required strength auto-raises a requisition — see A5).

G2 — Apply for leave (for a crew member) As the Site in-charge, I want to apply for leave on behalf of a crew member (apply-only; crew are not portal users), so that the office can approve it.

AC1: I select the crew member's assignment, dates and type; status starts APPLIED.
AC2: site staff cannot self-approve (no decide_leave).

G3 — Decide leave As a Manager, I want to approve/reject leave with a note, so that the planner stays accurate (the MPO has no leave role).

AC1: approval moves the assignment to ON_LEAVE for the period.
AC2: if the approval creates a clash (the rank falls below required strength for the overlap), a backfill requisition is auto-raised — see A5.

G4 — Record attendance As site staff, I want to record daily attendance, so that wages can be computed.

AC1: one row per assignment per day; statuses present/absent/half/leave/sign-off.
AC2: no verification gate (operational).
AC3: attendance is visible to site staff and the Manager only — the MPO has no attendance access.

Epic H — Appraisal

H1 — Raise appraisal As a PM (site staff), I want to raise an appraisal for a crew member, so that performance is recorded.

AC1: appraisal starts DRAFT, submits to SUBMITTED.

H2 — Verify appraisal As an MPO, I want to verify a submitted appraisal, so that the Manager reviews vetted input.

AC1: verify → MPO_VERIFIED; return → REJECTED + remarks.

H3 — Approve appraisal As a Manager, I want to approve a verified appraisal, so that it's final.

AC1: only MPO_VERIFIED appraisals can be approved.

Epic I — Office verification

I1 — MPO verification queue As an MPO, I want a queue of pending site records (documents, PPE, leave, next-of-kin), so that I can verify everything except attendance.

AC1: verify sets VERIFIED + me as verifiedBy; reject returns with remarks.
AC2: attendance never appears in this queue — the MPO has no attendance access (it is the Manager's to review).

I2 — Accounts bank/EPF verification As Accounts, I want to verify bank details and EPF (UAN/Aadhaar vs EPFO), so that payments go to the right verified account.

AC1: only Accounts can verify bank/EPF.
AC2: EPFO check result is recorded.

Epic J — Payroll / wage report

J1 — Generate wage report As a Manager (or month-end job), I want a per-site wage report (crew × salary × days-attended + victualing), so that Accounts can pay.

AC1: one WageLine per active assignment; lineTotal computed.
AC2: attendance gaps flagged before generation.

J2 — Approve & send As a Manager, I want to approve the report and send it to Accounts, so that disbursement is authorised.

AC1: MANAGER_APPROVED → SENT_TO_ACCOUNTS.

J3 — Accounts view & export As Accounts, I want to view and export the wage report (XLSX/PDF), so that I can disburse.

AC1: export reuses the PO export mechanism.

Epic K — Sign-off & experience

K1 — Sign off crew As site staff / MPO, I want to sign off a crew member, so that the tour closes cleanly.

AC1: assignment → SIGNED_OFF with signOffDate.
AC2: an EXPERIENCE_RECORD is appended (vessel type, rank, duration).
AC3: a backfill requisition is auto-raised (links to A1).

K2 — Experience history As an MPO, I want a crew member's accumulated experience on file, so that ex-hand vetting is instant.

AC1: internal tours appear automatically; declared experience can be added.

Epic L — Reference data & admin

L1 — Manage ranks As an Admin/Manager, I want to manage the rank hierarchy, so that requisitions and the org chart are correct.

AC1: ranks form a self-hierarchy with category + isSeafarer.

L2 — Manage rank document requirements As an Admin/Manager, I want to set which documents each rank requires, so that vetting and uploads enforce the right set.

AC1: e.g. driver → driving licence; deck/engine → STCW/CDC/COC/medical.

Epic M — Cross-cutting

M1 — Crewing dashboard As a Manager, I want crewing stat cards (open requisitions, candidates in pipeline, expiring documents, crew on leave), so that I see status at a glance.

M2 — Notifications As any actor, I want email + in-app notifications on the events relevant to me (requisition raised, proposal, appraisal verified, wage report ready), so that I act promptly.

M3 — Audit trail As an Auditor, I want every crewing transition recorded with actor/time/note, so that the process is fully traceable.

AC1: CrewAction rows for all lifecycle and verification events.

M4 — Feature flag As an operator, I want the crewing surface behind NEXT_PUBLIC_CREWING_ENABLED, so that it can be rolled out gradually.

Suggested delivery order

Reference data (L1, L2) + data model + permissions.
Requisitions (A) + sign-off/experience (K).
Candidate intake (B) + pipeline (C) + onboarding (D).
Crew records (E), PPE (F), leave/attendance (G).
Verification (I), appraisal (H).
Payroll (J), dashboard/notifications (M).

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.