diff --git a/README.md b/README.md index 8a9d576..ee3a454 100755 --- a/README.md +++ b/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`) | --- @@ -134,16 +143,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) + auto-migrations +│ ├── 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 @@ -151,20 +160,23 @@ 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 + 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 + ├── 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 + ├── 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