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
|
||||
|
||||
Single-container Dockerized web app for CPAS violation documentation.
|
||||
Built with React + Vite (frontend), Node.js + Express (backend), SQLite (database).
|
||||
Single-container Dockerized web app for CPAS violation documentation and workforce standing management.
|
||||
Built with **React + Vite** (frontend), **Node.js + Express** (backend), **SQLite** (database), and **Puppeteer** (PDF generation).
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
cpas-violation-tracker/
|
||||
├── Dockerfile # Multi-stage: builds React + runs Express
|
||||
cpas/
|
||||
├── Dockerfile # Multi-stage: builds React + runs Express w/ Chromium
|
||||
├── .dockerignore
|
||||
├── package.json # Backend (Express) deps
|
||||
├── server.js # API + static file server
|
||||
├── db/
|
||||
│ ├── schema.sql # Tables + 90-day score view
|
||||
│ └── database.js # SQLite connection
|
||||
│ ├── schema.sql # Tables + 90-day active score view
|
||||
│ └── database.js # SQLite connection (better-sqlite3)
|
||||
├── pdf/
|
||||
│ └── generator.js # Puppeteer PDF generation
|
||||
└── client/ # React frontend (Vite)
|
||||
├── package.json
|
||||
├── vite.config.js
|
||||
@@ -60,14 +132,36 @@ cpas-violation-tracker/
|
||||
├── main.jsx
|
||||
├── App.jsx
|
||||
├── data/
|
||||
│ └── violations.js # All CPAS violation definitions
|
||||
│ └── violations.js # All CPAS violation definitions + groups
|
||||
├── hooks/
|
||||
│ └── useEmployeeIntelligence.js # Score + history hook
|
||||
└── 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
|
||||
|
||||
- [x] Phase 1 — Container scaffold, SQLite schema, base React form
|
||||
- [ ] Phase 2 — Employee history, prior violation highlighting
|
||||
- [ ] Phase 3 — Puppeteer PDF generation
|
||||
- [ ] Phase 4 — Dashboard, CPAS scores, tier warnings
|
||||
- [ ] Phase 5 — Recidivist point auto-suggest
|
||||
- [x] Phase 2 — Employee history, prior violation highlighting, recidivist point auto-suggest
|
||||
- [x] Phase 3 — Puppeteer PDF generation
|
||||
- [x] Phase 4 — Dashboard, CPAS scores, tier warnings, at-risk badges
|
||||
- [ ] Phase 5 — Recidivist point auto-suggest refinements / additional reporting
|
||||
|
||||
Reference in New Issue
Block a user