docs: update README to reflect current codebase (phases 1-4 complete)
This commit is contained in:
120
README.md
120
README.md
@@ -1,11 +1,13 @@
|
|||||||
# CPAS Violation Tracker
|
# CPAS Violation Tracker
|
||||||
|
|
||||||
Single-container Dockerized web app for CPAS violation documentation.
|
Single-container Dockerized web app for CPAS violation documentation and workforce standing management.
|
||||||
Built with React + Vite (frontend), Node.js + Express (backend), SQLite (database).
|
Built with **React + Vite** (frontend), **Node.js + Express** (backend), **SQLite** (database), and **Puppeteer** (PDF generation).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## The only requirement on your machine: Docker Desktop
|
## The only requirement on your machine: Docker Desktop
|
||||||
|
|
||||||
Everything else — Node.js, npm, React build — happens inside Docker.
|
Everything else — Node.js, npm, React build, Chromium for PDF — happens inside Docker.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -41,17 +43,87 @@ docker stop cpas-tracker && docker rm cpas-tracker
|
|||||||
docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker
|
docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Company Dashboard
|
||||||
|
- Live table of all employees sorted by active CPAS points (highest risk first)
|
||||||
|
- Summary stat cards: total employees, elite standing (0 pts), with active points, at-risk count, highest active score
|
||||||
|
- **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
|
||||||
|
|
||||||
|
### Violation Form
|
||||||
|
- Select existing employee or enter new employee by name
|
||||||
|
- **Employee intelligence**: shows current CPAS standing badge and 90-day violation count before submitting
|
||||||
|
- Violation type dropdown grouped by category; shows prior 90-day counts inline
|
||||||
|
- **Recidivist auto-escalation**: if an employee has prior violations of the same type, points slider auto-sets to maximum per policy
|
||||||
|
- Repeat offense badge with prior count displayed
|
||||||
|
- 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
|
||||||
|
- One-click PDF download immediately after submission
|
||||||
|
|
||||||
|
### Employee Profile Modal
|
||||||
|
- Full violation history with resolution status
|
||||||
|
- Negate / restore individual violations (soft delete with resolution type + notes)
|
||||||
|
- Hard delete option for data entry errors
|
||||||
|
- PDF download for any historical violation record
|
||||||
|
|
||||||
|
### CPAS Tier System
|
||||||
|
|
||||||
|
| Points | Tier | Label |
|
||||||
|
|--------|------|-------|
|
||||||
|
| 0–4 | 0–1 | Elite Standing |
|
||||||
|
| 5–9 | 1 | Realignment |
|
||||||
|
| 10–14 | 2 | Administrative Lockdown |
|
||||||
|
| 15–19 | 3 | Verification |
|
||||||
|
| 20–24 | 4 | Risk Mitigation |
|
||||||
|
| 25–29 | 5 | Final Decision |
|
||||||
|
| 30+ | 6 | Separation |
|
||||||
|
|
||||||
|
Scores are computed over a **rolling 90-day window** (negated violations excluded).
|
||||||
|
|
||||||
|
### PDF Generation
|
||||||
|
- Puppeteer + system Chromium (bundled in Docker image)
|
||||||
|
- Generated on-demand per violation via `GET /api/violations/:id/pdf`
|
||||||
|
- Filename: `CPAS_<EmployeeName>_<IncidentDate>.pdf`
|
||||||
|
- PDF captures prior active points **at the time of the incident** (snapshot stored on insert)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Reference
|
||||||
|
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | `/api/health` | Health check |
|
||||||
|
| GET | `/api/employees` | List all employees |
|
||||||
|
| POST | `/api/employees` | Create or upsert employee |
|
||||||
|
| 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) |
|
||||||
|
| PATCH | `/api/violations/:id/negate` | Negate a violation (soft delete + resolution record) |
|
||||||
|
| PATCH | `/api/violations/:id/restore` | Restore a negated violation |
|
||||||
|
| DELETE | `/api/violations/:id` | Hard delete a violation |
|
||||||
|
| GET | `/api/violations/:id/pdf` | Download violation PDF |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
cpas-violation-tracker/
|
cpas/
|
||||||
├── Dockerfile # Multi-stage: builds React + runs Express
|
├── Dockerfile # Multi-stage: builds React + runs Express w/ Chromium
|
||||||
├── .dockerignore
|
├── .dockerignore
|
||||||
├── package.json # Backend (Express) deps
|
├── package.json # Backend (Express) deps
|
||||||
├── server.js # API + static file server
|
├── server.js # API + static file server
|
||||||
├── db/
|
├── db/
|
||||||
│ ├── schema.sql # Tables + 90-day score view
|
│ ├── schema.sql # Tables + 90-day active score view
|
||||||
│ └── database.js # SQLite connection
|
│ └── database.js # SQLite connection (better-sqlite3)
|
||||||
|
├── pdf/
|
||||||
|
│ └── generator.js # Puppeteer PDF generation
|
||||||
└── client/ # React frontend (Vite)
|
└── client/ # React frontend (Vite)
|
||||||
├── package.json
|
├── package.json
|
||||||
├── vite.config.js
|
├── vite.config.js
|
||||||
@@ -60,14 +132,36 @@ cpas-violation-tracker/
|
|||||||
├── main.jsx
|
├── main.jsx
|
||||||
├── App.jsx
|
├── App.jsx
|
||||||
├── data/
|
├── data/
|
||||||
│ └── violations.js # All CPAS violation definitions
|
│ └── violations.js # All CPAS violation definitions + groups
|
||||||
|
├── hooks/
|
||||||
|
│ └── useEmployeeIntelligence.js # Score + history hook
|
||||||
└── components/
|
└── components/
|
||||||
└── ViolationForm.jsx
|
├── 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
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
Three 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)
|
||||||
|
- **`active_cpas_scores`** (view) — sum of points for non-negated violations in rolling 90 days, grouped by employee
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Phases
|
## Phases
|
||||||
|
|
||||||
- [x] Phase 1 — Container scaffold, SQLite schema, base React form
|
- [x] Phase 1 — Container scaffold, SQLite schema, base React form
|
||||||
- [ ] Phase 2 — Employee history, prior violation highlighting
|
- [x] Phase 2 — Employee history, prior violation highlighting, recidivist point auto-suggest
|
||||||
- [ ] Phase 3 — Puppeteer PDF generation
|
- [x] Phase 3 — Puppeteer PDF generation
|
||||||
- [ ] Phase 4 — Dashboard, CPAS scores, tier warnings
|
- [x] Phase 4 — Dashboard, CPAS scores, tier warnings, at-risk badges
|
||||||
- [ ] Phase 5 — Recidivist point auto-suggest
|
- [ ] Phase 5 — Recidivist point auto-suggest refinements / additional reporting
|
||||||
|
|||||||
Reference in New Issue
Block a user