docs: update README — add notes/expiration features, new endpoints, updated schema and roadmap
This commit is contained in:
57
README.md
57
README.md
@@ -53,7 +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
|
||||
- **🔍 Audit Log** button — filterable, paginated view of all system write actions
|
||||
|
||||
### Violation Form
|
||||
- Select existing employee or enter new employee by name
|
||||
@@ -68,12 +68,14 @@ docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker
|
||||
|
||||
### Employee Profile Modal
|
||||
- Full violation history with resolution status and **amendment count badge** per record
|
||||
- **✎ Edit Employee** button — update name, department, or supervisor inline
|
||||
- **✎ 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
|
||||
- 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
|
||||
|
||||
### Audit Log
|
||||
- Append-only log of every write action: employee created/edited/merged, violation logged/amended/negated/restored/deleted
|
||||
@@ -85,6 +87,11 @@ docker run -d --name cpas-tracker -p 3001:3001 -v cpas-data:/data cpas-tracker
|
||||
- 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
|
||||
|
||||
### In-App Documentation
|
||||
- **? Docs** button in the navbar opens a slide-in admin reference panel
|
||||
- Covers feature map, CPAS tier system, workflow guidance, and roadmap
|
||||
- No external link required; always reflects current deployed version
|
||||
|
||||
### CPAS Tier System
|
||||
|
||||
| Points | Tier | Label |
|
||||
@@ -112,21 +119,23 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/health` | Health check |
|
||||
| GET | `/api/employees` | List all employees |
|
||||
| GET | `/api/employees` | List all employees (includes `notes`) |
|
||||
| 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 |
|
||||
| PATCH | `/api/employees/:id` | Edit name, department, supervisor, or notes |
|
||||
| POST | `/api/employees/:id/merge` | Merge duplicate employee; reassigns all violations |
|
||||
| GET | `/api/employees/:id/score` | Get active CPAS score for employee |
|
||||
| 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 |
|
||||
| GET | `/api/violations/employee/:id` | Get violation history for employee (with resolutions + amendment counts) |
|
||||
| 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 |
|
||||
| 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) |
|
||||
| GET | `/api/audit` | Paginated audit log (filterable by `entity_type`, `entity_id`) |
|
||||
|
||||
---
|
||||
|
||||
@@ -164,7 +173,10 @@ cpas/
|
||||
├── 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
|
||||
├── ViolationHistory.jsx # Violation list component
|
||||
├── ExpirationTimeline.jsx # Per-violation 90-day roll-off countdown
|
||||
├── EmployeeNotes.jsx # Inline notes editor with quick-add HR tags
|
||||
└── ReadmeModal.jsx # In-app admin documentation panel
|
||||
```
|
||||
|
||||
---
|
||||
@@ -173,7 +185,7 @@ cpas/
|
||||
|
||||
Six tables + one view:
|
||||
|
||||
- **`employees`** — id, name, department, supervisor
|
||||
- **`employees`** — id, name, department, supervisor, **notes**
|
||||
- **`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
|
||||
@@ -182,6 +194,20 @@ Six tables + one view:
|
||||
|
||||
---
|
||||
|
||||
## Amendable Fields
|
||||
|
||||
Point values, violation type, and incident date are **immutable** after submission. The following fields can be amended:
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| `incident_time` | Time of day the incident occurred |
|
||||
| `location` | Where the incident took place |
|
||||
| `details` | Narrative description |
|
||||
| `submitted_by` | Supervisor who submitted |
|
||||
| `witness_name` | Witness on record |
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
### ✅ Completed
|
||||
@@ -204,18 +230,13 @@ Six tables + one view:
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
### 📋 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
|
||||
### 📋 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
|
||||
|
||||
Reference in New Issue
Block a user