From bad7aa29bb7eb07c502b0b00e92d02d9fae09841 Mon Sep 17 00:00:00 2001 From: cproudlock Date: Fri, 10 Jul 2026 08:39:53 -0400 Subject: [PATCH] Employee directory: note it varies per site + add self-hosted option - Flag the employee directory as the integration most likely to differ per site; USB (cmmc_usb) is standardized and rarely needs adaptation. - Add "Option B: stand up a self-hosted directory" with the canonical employees table DDL, for sites with no HR database. In-app management (CRUD/CSV import) noted as a possible future enhancement. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/employees/README.md | 37 +++++++++++++++++++++++++++++++++++++ plugins/usb/README.md | 6 ++++++ 2 files changed, 43 insertions(+) diff --git a/plugins/employees/README.md b/plugins/employees/README.md index 4d27ab7..844f8a6 100644 --- a/plugins/employees/README.md +++ b/plugins/employees/README.md @@ -8,6 +8,10 @@ Read-only lookups against a **separate** employee/HR directory database. Powers: The plugin never writes to this database. Use a read-only account. +> **This is the integration most likely to differ per site.** HR / directory +> systems vary widely, so expect to map a site's schema to the contract below - +> the `CREATE VIEW` recipe at the end is the normal way to do it. + ## Connection Credentials resolve **settings-first, then environment**, except the password @@ -63,6 +67,39 @@ The app renders it as `/static/employees/`, so the image files must live in the app's `static/employees/` directory. Leave `Picture` empty/NULL for people with no photo; the UI falls back to initials. +## Two ways to provide the directory + +**Option A - map an existing HR/directory database** (see the view recipe +below). Use this when the site already has a system of record for people. + +**Option B - stand up a self-hosted directory** for sites with no HR database. +Create the canonical table and point `employee_db_*` at it: + +```sql +CREATE DATABASE shopdb_directory CHARACTER SET utf8mb4; +USE shopdb_directory; + +CREATE TABLE employees ( + SSO INT NOT NULL PRIMARY KEY, + First_Name VARCHAR(100) NOT NULL, + Last_Name VARCHAR(100) NOT NULL, + Team VARCHAR(100) NULL, + Role VARCHAR(100) NULL, + Picture VARCHAR(255) NULL +); + +-- add people (or bulk-load from CSV with LOAD DATA INFILE) +INSERT INTO employees (SSO, First_Name, Last_Name, Team, Role, Picture) +VALUES (123456, 'Jane', 'Doe', 'Inspection', 'Quality Tech', '123456.jpg'); +``` + +Put photo files (named as in `Picture`) under the app's `static/employees/`. +This can be a dedicated MySQL database or another schema on the same server as +the main app DB - the plugin connects to it independently. + +> A future enhancement could manage this self-hosted directory in-app (add / +> edit people, CSV import) so a site needs no direct SQL. Not built yet. + ## Adapting a different site schema (recommended: a view) Sites whose HR/directory database uses different table or column names should diff --git a/plugins/usb/README.md b/plugins/usb/README.md index ae66985..b689a04 100644 --- a/plugins/usb/README.md +++ b/plugins/usb/README.md @@ -9,6 +9,12 @@ The plugin's own reference tables (`usbdevicetypes`, `usbdevices`, `usbcheckouts`) live in the main app database; only the live check-in/out data is in `cmmc_usb`. +> **This schema is typically standardized across sites** - the `cmmc_usb` +> check-in/out solution is the same deployment everywhere, so the tables below +> usually match as-is and no adaptation is needed. The view recipe at the end is +> a fallback for the rare site that differs. (Contrast the employee directory, +> which genuinely varies per site.) + ## Connection Credentials resolve **settings-first, then environment**, except the password