From 66f59dead3b43670aa600f7225f8fc478a432491 Mon Sep 17 00:00:00 2001 From: jason Date: Sat, 7 Mar 2026 21:44:22 -0600 Subject: [PATCH] docs: update README for acknowledgment signature field, toast notifications, and PDF logo refactor - Moved acknowledgment signature field from Proposed to Completed (Phase 7) - Added toast notification system to Completed (Phase 7) - Updated Violation Form features with acknowledgment section and toasts - Updated Employee Profile Modal features with toast notifications - Added Toast Notification System as standalone feature section - Updated PDF Generation section: logo loaded from disk, ack rendering - Updated Amendable Fields table with acknowledged_by and acknowledged_date - Updated Database Schema section with new violation columns - Updated Project Structure tree with ToastProvider.jsx and template.js description - Updated API reference for POST /api/violations to note new fields --- README.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index fa09458..9e3f23f 100755 --- a/README.md +++ b/README.md @@ -132,18 +132,21 @@ Access the app at `http://10.2.0.14:3001` (or whatever static IP you assigned). - Context-sensitive fields (time, minutes late, amount, location, description) shown only when relevant to violation type - **Tier crossing warning** (TierWarning component): previews what tier the new points would push the employee into before submission - Point slider for discretionary adjustments within the violation's min/max range +- **Employee Acknowledgment section**: optional "received by employee" name and date fields; when filled, the PDF signature block shows the recorded acknowledgment instead of a blank signature line - One-click PDF download immediately after submission +- **Toast notifications**: success/error/warning feedback for form submissions, validation, and PDF downloads ### Employee Profile Modal - Full violation history with resolution status and **amendment count badge** per record - **✎ Edit Employee** button — update name, department, supervisor, or notes inline - **Merge Duplicate** tab — reassign all violations from a duplicate record and delete it -- **Amend** button per active violation — edit non-scoring fields (location, notes, witness, etc.) with a full field-level diff history +- **Amend** button per active violation — edit non-scoring fields (location, notes, witness, acknowledgment, etc.) with a full field-level diff history - Negate / restore individual violations (soft delete with resolution type + notes) - Hard delete option for data entry errors - PDF download for any historical violation record - **Notes & Flags** — free-text notes (e.g. "on PIP", "union member") with quick-add tag buttons; visible in the profile modal without affecting scoring - **Point Expiration Timeline** — shows when each active violation rolls off the 90-day window, with a progress bar, days-remaining countdown, and projected tier-drop indicators +- **Toast notifications** for all actions: negate, restore, delete, amend, PDF download, employee edit ### Audit Log - Append-only log of every write action: employee created/edited/merged, violation logged/amended/negated/restored/deleted @@ -160,6 +163,13 @@ Access the app at `http://10.2.0.14:3001` (or whatever static IP you assigned). - Covers feature map, CPAS tier system, workflow guidance, and roadmap - No external link required; always reflects current deployed version +### Toast Notification System +- Global toast notifications for all user actions across the application +- Four variants: success (green), error (red), warning (gold), info (blue) +- Auto-dismiss with configurable duration and visual progress bar countdown +- Slide-in animation; stacks up to 5 notifications simultaneously +- Consistent dark theme styling matching the rest of the UI + ### CPAS Tier System | Points | Tier | Label | @@ -176,9 +186,11 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude ### PDF Generation - Puppeteer + system Chromium (bundled in Docker image) +- Logo loaded from disk at startup (no hardcoded base64); falls back gracefully if not found - Generated on-demand per violation via `GET /api/violations/:id/pdf` - Filename: `CPAS__.pdf` - PDF captures prior active points **at the time of the incident** (snapshot stored on insert) +- **Acknowledgment rendering**: if the violation has an `acknowledged_by` value, the employee signature block on the PDF shows the recorded name and date with an "Acknowledged" badge; otherwise, blank signature lines are rendered for wet-ink signing --- @@ -195,7 +207,7 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude | GET | `/api/employees/:id/expiration` | Active violation roll-off timeline with days remaining | | PATCH | `/api/employees/:id/notes` | Save employee notes only (shorthand) | | GET | `/api/dashboard` | All employees with active points + violation counts | -| POST | `/api/violations` | Log a new violation | +| POST | `/api/violations` | Log a new violation (accepts `acknowledged_by`, `acknowledged_date`) | | GET | `/api/violations/employee/:id` | Violation history with resolutions + amendment counts | | PATCH | `/api/violations/:id/negate` | Negate a violation (soft delete + resolution record) | | PATCH | `/api/violations/:id/restore` | Restore a negated violation | @@ -219,7 +231,8 @@ cpas/ │ ├── schema.sql # Tables + 90-day active score view │ └── database.js # SQLite connection (better-sqlite3) + auto-migrations ├── pdf/ -│ └── generator.js # Puppeteer PDF generation +│ ├── generator.js # Puppeteer PDF generation +│ └── template.js # HTML template (loads logo from disk, ack signature rendering) └── client/ # React frontend (Vite) ├── package.json ├── vite.config.js @@ -235,7 +248,7 @@ cpas/ ├── CpasBadge.jsx # Tier badge + color logic ├── TierWarning.jsx # Pre-submit tier crossing alert ├── Dashboard.jsx # Company-wide leaderboard + audit log trigger - ├── ViolationForm.jsx # Violation entry form + ├── ViolationForm.jsx # Violation entry form + ack signature fields ├── EmployeeModal.jsx # Employee profile + history modal ├── EditEmployeeModal.jsx # Employee edit + merge duplicate ├── AmendViolationModal.jsx # Non-scoring field amendment + diff history @@ -244,6 +257,7 @@ cpas/ ├── ViolationHistory.jsx # Violation list component ├── ExpirationTimeline.jsx # Per-violation 90-day roll-off countdown ├── EmployeeNotes.jsx # Inline notes editor with quick-add HR tags + ├── ToastProvider.jsx # Global toast notification system + useToast hook └── ReadmeModal.jsx # In-app admin documentation panel ``` @@ -254,7 +268,7 @@ cpas/ Six tables + one view: - **`employees`** — id, name, department, supervisor, **notes** -- **`violations`** — full incident record including `prior_active_points` snapshot at time of logging +- **`violations`** — full incident record including `prior_active_points` snapshot at time of logging, `acknowledged_by` and `acknowledged_date` for employee acknowledgment - **`violation_resolutions`** — resolution type, details, resolved_by (linked to violations) - **`violation_amendments`** — field-level diff log for violation edits; one row per changed field per amendment - **`audit_log`** — append-only record of every write action (action, entity_type, entity_id, performed_by, details, timestamp) @@ -273,6 +287,8 @@ Point values, violation type, and incident date are **immutable** after submissi | `details` | Narrative description | | `submitted_by` | Supervisor who submitted | | `witness_name` | Witness on record | +| `acknowledged_by` | Employee who acknowledged receipt | +| `acknowledged_date` | Date of employee acknowledgment | --- @@ -301,6 +317,8 @@ Point values, violation type, and incident date are **immutable** after submissi | 6 | Employee notes / flags | Free-text notes on employee record with quick-add HR tags; does not affect scoring | | 6 | Point expiration timeline | Per-violation roll-off countdown with tier-drop projections | | 6 | In-app documentation | Admin usage guide and feature map accessible from the navbar | +| 7 | Acknowledgment signature field | "Received by employee" name + date on the violation form; renders on the PDF replacing blank signature lines with recorded acknowledgment | +| 7 | Toast notification system | Global success/error/warning/info notifications for all user actions; auto-dismiss with progress bar; consistent dark theme | --- @@ -315,7 +333,6 @@ Point values, violation type, and incident date are **immutable** after submissi - **Supervisor view** — scoped dashboard showing only the employees under a given supervisor, useful for multi-supervisor environments #### Violation Workflow -- **Acknowledgment signature field** — a "received by employee" name/date field on the violation form that prints on the PDF, replacing the blank signature line - **Draft / pending violations** — save a violation as draft before finalizing, useful when incidents need review before being officially logged - **Bulk violation import** — CSV import for migrating historical records from paper logs or a prior system