From 0a8b6e44d8e9d6876ec81996df32691f2855f6b4 Mon Sep 17 00:00:00 2001 From: jason Date: Sat, 7 Mar 2026 09:40:34 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20update=20README=20=E2=80=94=20mark=20ro?= =?UTF-8?q?admap=20items=20complete,=20add=20new=20features,=20update=20sc?= =?UTF-8?q?hema=20and=20API=20reference?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 78 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 54 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 451eddd..8a9d576 100755 --- a/README.md +++ b/README.md @@ -53,6 +53,7 @@ docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker - **At-risk badge**: flags employees within 2 points of the next tier escalation - Search/filter by name, department, or supervisor - Click any employee name to open their full profile modal +- **📋 Audit Log** button — filterable, paginated view of all system write actions ### Violation Form - Select existing employee or enter new employee by name @@ -66,11 +67,24 @@ docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker - One-click PDF download immediately after submission ### Employee Profile Modal -- Full violation history with resolution status +- Full violation history with resolution status and **amendment count badge** per record +- **✎ Edit Employee** button — update name, department, or supervisor 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 - Negate / restore individual violations (soft delete with resolution type + notes) - Hard delete option for data entry errors - PDF download for any historical violation record +### Audit Log +- Append-only log of every write action: employee created/edited/merged, violation logged/amended/negated/restored/deleted +- Filterable by entity type (employee / violation) and action +- Paginated with load-more; accessible from the Dashboard toolbar + +### Violation Amendment +- Edit submitted violations' non-scoring fields without delete-and-resubmit +- Point values, violation type, and incident date are immutable +- Every change is stored as a field-level diff (old → new value) with timestamp and actor + ### CPAS Tier System | Points | Tier | Label | @@ -100,14 +114,19 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude | GET | `/api/health` | Health check | | GET | `/api/employees` | List all employees | | POST | `/api/employees` | Create or upsert employee | +| PATCH | `/api/employees/:id` | Edit employee name, department, or supervisor | +| POST | `/api/employees/:id/merge` | Merge duplicate employee into target; reassigns all violations | | GET | `/api/employees/:id/score` | Get active CPAS score for employee | | GET | `/api/dashboard` | All employees with active points + violation counts | | POST | `/api/violations` | Log a new violation | -| GET | `/api/violations/employee/:id` | Get violation history for employee (with resolutions) | +| GET | `/api/violations/employee/:id` | Get violation history for employee (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 | +| PATCH | `/api/violations/:id/amend` | Amend non-scoring fields with field-level diff logging | +| GET | `/api/violations/:id/amendments` | Get amendment history for a violation | | DELETE | `/api/violations/:id` | Hard delete a violation | | GET | `/api/violations/:id/pdf` | Download violation PDF | +| GET | `/api/audit` | Paginated audit log (filterable by entity_type, entity_id) | --- @@ -115,16 +134,16 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude ``` cpas/ -├── Dockerfile # Multi-stage: builds React + runs Express w/ Chromium +├── Dockerfile # Multi-stage: builds React + runs Express w/ Chromium ├── .dockerignore -├── package.json # Backend (Express) deps -├── server.js # API + static file server +├── package.json # Backend (Express) deps +├── server.js # API + static file server ├── db/ -│ ├── schema.sql # Tables + 90-day active score view -│ └── database.js # SQLite connection (better-sqlite3) +│ ├── schema.sql # Tables + 90-day active score view +│ └── database.js # SQLite connection (better-sqlite3) + auto-migrations ├── pdf/ -│ └── generator.js # Puppeteer PDF generation -└── client/ # React frontend (Vite) +│ └── generator.js # Puppeteer PDF generation +└── client/ # React frontend (Vite) ├── package.json ├── vite.config.js ├── index.html @@ -132,28 +151,33 @@ cpas/ ├── main.jsx ├── App.jsx ├── data/ - │ └── violations.js # All CPAS violation definitions + groups + │ └── violations.js # All CPAS violation definitions + groups ├── hooks/ │ └── useEmployeeIntelligence.js # Score + history hook └── components/ - ├── CpasBadge.jsx # Tier badge + color logic - ├── TierWarning.jsx # Pre-submit tier crossing alert - ├── Dashboard.jsx # Company-wide leaderboard - ├── ViolationForm.jsx # Violation entry form - ├── EmployeeModal.jsx # Employee profile + history modal - ├── NegateModal.jsx # Negate/resolve violation dialog - └── ViolationHistory.jsx # Violation list component + ├── 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 + ├── EmployeeModal.jsx # Employee profile + history modal + ├── EditEmployeeModal.jsx # Employee edit + merge duplicate + ├── AmendViolationModal.jsx # Non-scoring field amendment + diff history + ├── AuditLog.jsx # Filterable audit log panel + ├── NegateModal.jsx # Negate/resolve violation dialog + └── ViolationHistory.jsx # Violation list component ``` --- ## Database Schema -Three tables + one view: +Six tables + one view: - **`employees`** — id, name, department, supervisor - **`violations`** — full incident record including `prior_active_points` snapshot at time of logging - **`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) - **`active_cpas_scores`** (view) — sum of points for non-negated violations in rolling 90 days, grouped by employee --- @@ -177,26 +201,33 @@ Three tables + one view: | 4 | Tier crossing warning | Pre-submit alert when new points push employee to next tier | | 4 | Employee profile modal | Full history, negate/restore, hard delete, per-record PDF download | | 4 | Negate & restore | Soft-delete violations with resolution type + notes, fully reversible | +| 5 | Employee edit / merge | Update employee name/dept/supervisor; merge duplicate records without losing history | +| 5 | Violation amendment | Edit non-scoring fields with field-level audit trail | +| 5 | Audit log | Append-only log of all system writes; filterable panel in the dashboard | --- -### 🔲 Proposed +### 📋 In Progress + +#### Reporting & Visibility +- **Expiration timeline** — per-employee view showing which active violations roll off the 90-day window and when; lets supervisors anticipate tier drops before they happen +- **Employee notes / flags** — free-text notes attached to an employee record (e.g. "on PIP", "union member") visible in the profile modal without affecting scoring + +--- + +### 💡 Proposed #### Reporting & Analytics - **Violation trends chart** — line/bar chart of violations per day/week/month, filterable by department or supervisor; useful for identifying systemic patterns vs. individual incidents - **Department heat map** — grid view showing violation density and average CPAS score by department; helps supervisors identify team-level risk -- **Expiration timeline** — visual showing which active violations will roll off the 90-day window and when, so supervisors can anticipate tier drops - **CSV / Excel export** — bulk export of violations or dashboard data for external reporting or payroll integration #### Employee Management -- **Employee edit / merge** — ability to update employee name, department, or supervisor without losing history; merge duplicate records created by name typos - **Supervisor view** — scoped dashboard showing only the employees under a given supervisor, useful for multi-supervisor environments -- **Employee notes / flags** — free-text notes attached to an employee record (e.g. "on PIP", "union member") visible in the profile modal without affecting scoring #### 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 -- **Violation amendment** — edit a submitted violation's details (not points) with an audit trail, rather than delete-and-resubmit - **Bulk violation import** — CSV import for migrating historical records from paper logs or a prior system #### Notifications & Escalation @@ -206,7 +237,6 @@ Three tables + one view: #### Infrastructure & Ops - **Multi-user auth** — simple login with role-based access (admin, supervisor, read-only); currently the app has no auth and is assumed to run on a trusted internal network -- **Audit log** — immutable log of all creates, negates, restores, and deletes with timestamp and acting user, stored separately from the violations table - **Automated DB backup** — cron job or Docker health hook to snapshot `/data/cpas.db` to a mounted backup volume or remote location on a schedule - **Dark/light theme toggle** — the UI is currently dark-only; a toggle would improve usability in bright environments