jason/cpas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentation
Build and Push Docker Image / build (push) Successful in 6s
Details

Browse Source
This commit is contained in:
jason
2026-05-11 13:28:02 -05:00
parent 3220ee70c4
commit ba2b631e23
1 changed files with 40 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+40 -23
View File
@@ -130,7 +130,6 @@ Useful for showing the app to stakeholders without exposing live employee data.
- Summary stat cards: total employees, elite standing (0 pts), with active points, at-risk count, highest active score - 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 - **At-risk badge**: flags employees within 2 points of the next tier escalation
- Search/filter by name, department, or supervisor - Search/filter by name, department, or supervisor
- **Department filter**: pre-loaded dropdown of all departments for quick scoped views
- Click any employee name to open their full profile modal - 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
@@ -138,9 +137,11 @@ Useful for showing the app to stakeholders without exposing live employee data.
- Select existing employee or enter new employee by name - Select existing employee or enter new employee by name
- **Employee intelligence**: shows current CPAS standing badge and 90-day violation count before submitting - **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 - Violation type dropdown grouped by category; shows prior 90-day counts inline
- **Custom violation types**: add or edit user-defined types directly from the form (`+ Add Type` / `Edit Type` buttons); persisted to the database and merged into the dropdown alongside hardcoded types
- **Recidivist auto-escalation**: if an employee has prior violations of the same type, points slider auto-sets to maximum per policy - **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 - Repeat offense badge with prior count displayed
- Context-sensitive fields (time, minutes late, amount, location, description) shown only when relevant to violation type - Context-sensitive fields (time, minutes late, amount, location, description) shown only when relevant to violation type
- **Financial amount tracking**: dollar amount in question recorded for chargeback / receipt / custom financial violations; surfaces on the PDF for repayment records and is audit-logged on edit
- **Tier crossing warning** (TierWarning component): previews what tier the new points would push the employee into before submission - **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 - Point slider for discretionary adjustments within the violation's min/max range
- **Employee Acknowledgment section**: optional "received by employee" name and date fields; when filled, the PDF signature block shows the recorded acknowledgment instead of a blank signature line - **Employee Acknowledgment section**: optional "received by employee" name and date fields; when filled, the PDF signature block shows the recorded acknowledgment instead of a blank signature line
@@ -214,23 +215,30 @@ Scores are computed over a **rolling 90-day window** (negated violations exclude
| Method | Endpoint | Description | | Method | Endpoint | Description |
|--------|----------|-------------| |--------|----------|-------------|
| GET | `/api/health` | Health check | | GET | `/api/health` | Health check (returns build SHA + timestamp) |
| GET | `/api/employees` | List all employees (includes `notes`) | | GET | `/api/employees` | List all employees (includes `notes`) |
| GET | `/api/employees/:id` | Single employee record |
| POST | `/api/employees` | Create or upsert employee | | POST | `/api/employees` | Create or upsert employee |
| PATCH | `/api/employees/:id` | Edit name, department, supervisor, or notes | | PATCH | `/api/employees/:id` | Edit name, department, supervisor, or notes |
| PATCH | `/api/employees/:id/notes` | Save employee notes only (shorthand) |
| POST | `/api/employees/:id/merge` | Merge duplicate employee; reassigns all violations | | 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/score` | Get active CPAS score for employee |
| GET | `/api/employees/:id/expiration` | Active violation roll-off timeline with days remaining | | 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/employees/:id/violation-counts` | 90-day non-negated counts grouped by violation type |
| GET | `/api/employees/:id/violation-counts/alltime` | All-time non-negated counts + max points used per type |
| GET | `/api/dashboard` | All employees with active points + violation counts | | GET | `/api/dashboard` | All employees with active points + violation counts |
| POST | `/api/violations` | Log a new violation (accepts `acknowledged_by`, `acknowledged_date`) | | POST | `/api/violations` | Log a new violation (accepts `acknowledged_by`, `acknowledged_date`, `amount`) |
| GET | `/api/violations/employee/:id` | Violation history with resolutions + amendment counts | | GET | `/api/violations/employee/:id` | Violation history with resolutions + amendment counts |
| PATCH | `/api/violations/:id/negated` | Negate a violation (soft delete + resolution record) | | 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/restore` | Restore a negated violation |
| PATCH | `/api/violations/:id/amend` | Amend non-scoring fields with field-level diff logging | | 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 | | GET | `/api/violations/:id/amendments` | Get amendment history for a violation |
| DELETE | `/api/violations/:id` | Hard delete a violation | | DELETE | `/api/violations/:id` | Hard delete a violation |
| GET | `/api/violations/:id/pdf` | Download violation PDF | | GET | `/api/violations/:id/pdf` | Download violation PDF |
| GET | `/api/violation-types` | List custom violation types |
| POST | `/api/violation-types` | Create a custom violation type |
| PUT | `/api/violation-types/:id` | Update a custom violation type |
| DELETE | `/api/violation-types/:id` | Delete a custom violation type (blocked if any violation references it) |
| GET | `/api/audit` | Paginated audit log (filterable by `entity_type`, `entity_id`) | | GET | `/api/audit` | Paginated audit log (filterable by `entity_type`, `entity_id`) |
--- ---
@@ -258,24 +266,29 @@ cpas/
├── main.jsx ├── main.jsx
├── App.jsx # Root app + AppFooter (copyright, dev ticker, Gitea link) ├── App.jsx # Root app + AppFooter (copyright, dev ticker, Gitea link)
├── data/ ├── data/
│ └── violations.js # All CPAS violation definitions + groups │ ├── violations.js # All hardcoded CPAS violation definitions + groups
│ └── departments.js # DEPARTMENTS constant; single source of truth
├── hooks/ ├── hooks/
│ └── useEmployeeIntelligence.js # Score + history hook │ └── useEmployeeIntelligence.js # Score + history hook
├── styles/
│ └── mobile.css # Mobile breakpoint overrides only
└── components/ └── components/
├── CpasBadge.jsx # Tier badge + color logic ├── CpasBadge.jsx # Tier badge + color logic (canonical TIERS, getTier)
├── TierWarning.jsx # Pre-submit tier crossing alert ├── TierWarning.jsx # Pre-submit tier crossing alert
├── Dashboard.jsx # Company-wide leaderboard + audit log trigger ├── Dashboard.jsx # Company-wide leaderboard + audit log trigger
├── ViolationForm.jsx # Violation entry form + ack signature fields ├── DashboardMobile.jsx # Mobile-optimized dashboard layout
├── EmployeeModal.jsx # Employee profile + history modal ├── ViolationForm.jsx # Violation entry form + ack signature + amount field
├── EditEmployeeModal.jsx # Employee edit + merge duplicate ├── ViolationTypeModal.jsx # Create / edit / delete custom violation types
├── AmendViolationModal.jsx # Non-scoring field amendment + diff history ├── EmployeeModal.jsx # Employee profile + history modal
├── AuditLog.jsx # Filterable audit log panel ├── EditEmployeeModal.jsx # Employee edit + merge duplicate
├── NegateModal.jsx # Negate/resolve violation dialog ├── AmendViolationModal.jsx # Non-scoring field amendment + diff history
├── ViolationHistory.jsx # Violation list component ├── AuditLog.jsx # Filterable audit log panel
├── ExpirationTimeline.jsx # Per-violation 90-day roll-off countdown ├── NegateModal.jsx # Negate/resolve violation dialog
├── EmployeeNotes.jsx # Inline notes editor with quick-add HR tags ├── ViolationHistory.jsx # Violation list component
├── ToastProvider.jsx # Global toast notification system + useToast hook ├── ExpirationTimeline.jsx # Per-violation 90-day roll-off countdown
└── ReadmeModal.jsx # In-app admin documentation panel ├── EmployeeNotes.jsx # Inline notes editor with quick-add HR tags
├── ToastProvider.jsx # Global toast notification system + useToast hook
└── ReadmeModal.jsx # In-app admin documentation panel
``` ```
--- ---
@@ -284,10 +297,11 @@ cpas/
Six tables + one view: Six tables + one view:
- **`employees`** — id, name, department, supervisor, **notes** - **`employees`** — id, name, department, supervisor, notes
- **`violations`** — full incident record including `prior_active_points` snapshot at time of logging, `acknowledged_by` and `acknowledged_date` for employee acknowledgment - **`violations`** — full incident record including `prior_active_points` snapshot, `acknowledged_by` / `acknowledged_date`, and `amount` (financial amount in question for chargeback/repayment)
- **`violation_resolutions`** — resolution type, details, resolved_by (linked to violations) - **`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 - **`violation_amendments`** — field-level diff log for violation edits; one row per changed field per amendment
- **`violation_types`** — persisted custom violation type definitions added via the UI; `type_key` is prefixed `custom_` to prevent collisions with hardcoded keys
- **`audit_log`** — append-only record of every write action (action, entity_type, entity_id, performed_by, details, timestamp) - **`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 - **`active_cpas_scores`** (view) — sum of points for non-negated violations in rolling 90 days, grouped by employee
@@ -306,6 +320,7 @@ Point values, violation type, and incident date are **immutable** after submissi
| `witness_name` | Witness on record | | `witness_name` | Witness on record |
| `acknowledged_by` | Employee who acknowledged receipt | | `acknowledged_by` | Employee who acknowledged receipt |
| `acknowledged_date` | Date of employee acknowledgment | | `acknowledged_date` | Date of employee acknowledgment |
| `amount` | Dollar amount in question (financial violations); typo-correctable for repayment records |
--- ---
@@ -339,6 +354,8 @@ Point values, violation type, and incident date are **immutable** after submissi
| 7 | Department dropdown | Pre-loaded select on the violation form replacing free-text department input; shared `DEPARTMENTS` constant | | 7 | Department dropdown | Pre-loaded select on the violation form replacing free-text department input; shared `DEPARTMENTS` constant |
| 8 | Stakeholder demo page | Standalone `/demo` route with synthetic data; static HTML served before SPA catch-all; useful for non-live presentations | | 8 | Stakeholder demo page | Standalone `/demo` route with synthetic data; static HTML served before SPA catch-all; useful for non-live presentations |
| 8 | App footer | Copyright (© Jason Stedwell), live dev ticker since first commit, Gitea repo icon+link | | 8 | App footer | Copyright (© Jason Stedwell), live dev ticker since first commit, Gitea repo icon+link |
| 9 | Custom violation types | Persisted user-defined violation types created from the form; `+ Add Type` / `Edit Type` UI; merged into the dropdown alongside hardcoded types; delete blocked when in use |
| 9 | Financial amount tracking | `amount` field on financial violations (chargeback, receipt negligence, custom types with the field enabled); stored on `violations`, rendered prominently on the PDF, amendable with audit-logged diffs |
--- ---