Skip to main content

PCR Lifecycle

This page documents the complete PCR (Procedure Change Request) lifecycle from creation through signature collection to completion.

State Machine​

  Originator creates PCR
  status: "pending"
         │
         ▼
  ┌─────────────────────────────┐
  │  Signature Collection       │
  │                             │
  │  1. Change Originator       │
  │  2. VP Fleet Management     │
  │  3. HSEQ Coordinator        │
  │  4. Group HSEQ Manager      │
  │  5. Director HSEQ           │
  │  6. President               │
  │                             │
  │  + Affected Party Signatures│
  └─────────────┬───────────────┘
                │
         All signed
                │
                ▼
  status: "finished"

Step-by-Step Walkthrough​

1. PCR Creation​

User action: Navigate to Initiate PCR and fill out the creation form.

Frontend path:

  • Page: src/app/dashboard/pcr/create/page.tsx
  • Form: src/features/pcrForms/components/initationPcr.tsx

Form contains three sections:

Originator form fields:

  • Is this a new suggestion? (Yes/No)
  • Is this a procedure change? (Yes/No)
  • Is it safety critical? (Yes/No)
  • Manual/Procedure reference (rich text)
  • Suggestion details (rich text)
  • Reason for change (rich text)
  • Peer review status
  • Attachments

Affected Parties table:

  • Dynamic rows added by the originator
  • Each row: Name (user selector), Signature (blank), Comments (blank)

Signatures table:

  • Pre-populated with six fixed roles (listed above)
  • Only Signature and Comments columns are editable later

API call: POST /api/pcr

Backend flow:

  1. Reads user identity from JWT
  2. Counts existing PCRs to generate serial number ({count}-{year})
  3. Creates PCR document with status: "pending"
  4. Sends initiation emails:
    • All users with role VP Fleet Management
    • All admin users
    • All affected party members

2. Signature Collection​

After creation, the PCR appears in the tracking view. Signatures are collected one at a time in the defined order.

Frontend path:

  • Tracking page: src/app/dashboard/main/allPcr/page.tsx
  • PCR card: src/features/allPcr/components/singlePcrDisplay.tsx

Signing logic (at src/features/allPcr/utils/pcrShowUtils.ts):

calculateDisabledSignatures()  → Determines which fields are locked
shouldUserSign()               → Checks if current user is next signer
getNextPendingSignature()      → Returns the next role needing a signature

When a user signs:

  1. Frontend calls POST /api/pcr/signatures with the updated signatures array
  2. Backend processes the update:
    • Preserves existing signatures at their array positions
    • Validates that comments-only entries (no signature) are treated as unsigned
    • Determines the next signer using getNextSigningRole()
    • Sends an email notification to the next signer via sendNextSignatureEmail()
  3. Frontend updates the local state

Affected party signatures:

Affected parties sign independently via POST /api/pcr/affectedParties. Each affected party member can sign when they access the PCR.

3. Completion​

Trigger: Both conditions must be met:

  1. All six signature roles have signed
  2. All affected party members have signed

Backend logic (in both /api/pcr/signatures and /api/pcr/affectedParties):

// Check if all signatures and affected parties are done
const allSignaturesDone = updatedPcr.signatures.every(
  (sig) => sig.Signature !== false && sig.Signature !== null
);
const allAffectedPartiesDone = updatedPcr.affectedParties.every(
  (party) => party.Signature !== false && party.Signature !== null
);

if (allSignaturesDone && allAffectedPartiesDone) {
  updatedPcr.status = "finished";
  // Send completion emails
}

On completion:

  • PCR status is set to "finished"
  • Completion emails are sent to the originator and all admin users

PCR Tracking View​

The tracking view (AllPcrWrapper.tsx) provides:

Filters:

FilterOptions
StatusAll, Completed, In Progress
RoleAll, Originator, Affected Party
Date rangeStart date to end date
SearchSerial number, originator name

Each PCR card shows:

  • Serial number and creation date
  • Originator information
  • Status badge (in progress / completed)
  • Expandable view with:
    • Form data preview (rendered via BooleanTablePcr)
    • Affected parties table with signature status
    • Signatures table with signing progress
    • Chat access

Cloning​

PCRs can be cloned from the tracking view. The clone:

  • Copies all form data and affected parties
  • Resets all signatures to unsigned
  • Generates a new serial number
  • Stores reference to the original PCR
  • Starts at status: "pending"