Initial commit: PESCO NCR system

Complete Non-Conformance Report system replacing the PowerApps/SharePoint
prototype: FastAPI + SQLAlchemy 2 (async) + Alembic + MySQL 8 backend,
React 18 + Vite + TypeScript + MUI frontend, Entra ID auth (MSAL / JWKS,
group-gated), Microsoft Graph delegated Mail.Send notifications (OBO),
six-stage workflow state machine with server-side enforcement, atomic
NCR-YYYY-NNNN numbering, attachments with camera capture, immutable
field-level audit trail, admin reopen, reports + CSV export, WeasyPrint
PDF traveler, Power BI reporting views + read-only DB user, documented
VISUAL ERP job-lookup stub, pytest suite (26 tests), docker-compose
deployment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,78 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# PESCO NCR — environment configuration
+# Copy to `.env` and fill in the values marked __LIKE_THIS__.
+# Values with defaults can be left as-is for a local/dev deployment.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── General ─────────────────────────────────────────────────────────────────
+# Public URL users open in the browser. Used to build links inside
+# notification emails, so it must be reachable from user machines.
+APP_BASE_URL=http://localhost:8080
+# Host port the frontend (nginx) is published on.
+HTTP_PORT=8080
+LOG_LEVEL=INFO
+
+# ── Authentication (Microsoft Entra ID) ─────────────────────────────────────
+# AUTH_MODE=entra  → real Entra ID sign-in (production).
+# AUTH_MODE=dev    → NO real auth; the app trusts an X-Dev-User header and the
+#                    UI shows a user switcher. For local development/demo ONLY.
+AUTH_MODE=entra
+
+# From your Entra app registration (see README "Entra ID setup").
+ENTRA_TENANT_ID=__YOUR_ENTRA_TENANT_ID__
+ENTRA_CLIENT_ID=__YOUR_ENTRA_APP_CLIENT_ID__
+# Client secret is required for the On-Behalf-Of (OBO) exchange the API uses
+# to call Microsoft Graph (delegated Mail.Send) and for group-overage checks.
+ENTRA_CLIENT_SECRET=__YOUR_ENTRA_APP_CLIENT_SECRET__
+
+# Object ID of the security group that gates access to the app (e.g. NCR-Users).
+# Leave empty to disable the group check (not recommended in production).
+ENTRA_ALLOWED_GROUP_ID=__NCR_USERS_GROUP_OBJECT_ID__
+
+# Expected audience of API access tokens. Leave empty to accept the default
+# (api://<ENTRA_CLIENT_ID> and the bare client id).
+ENTRA_API_AUDIENCE=
+
+# Scope the frontend requests for the API. Leave empty for the default
+# api://<ENTRA_CLIENT_ID>/access_as_user
+ENTRA_API_SCOPE=
+
+# Comma-separated emails that are auto-granted the Admin role on first login.
+# Needed to bootstrap the first administrator.
+INITIAL_ADMIN_EMAILS=spencerm@pescoinc.biz
+
+# ── MySQL ───────────────────────────────────────────────────────────────────
+MYSQL_HOST=mysql
+MYSQL_PORT=3306
+MYSQL_DATABASE=pesco_ncr
+MYSQL_USER=ncr_app
+MYSQL_PASSWORD=__CHOOSE_A_STRONG_APP_PASSWORD__
+MYSQL_ROOT_PASSWORD=__CHOOSE_A_STRONG_ROOT_PASSWORD__
+# Host port MySQL is published on (for the Power BI gateway). Firewall this.
+MYSQL_PUBLISHED_PORT=3306
+# Password for the read-only reporting account (created on first startup).
+POWERBI_RO_PASSWORD=__CHOOSE_A_STRONG_POWERBI_PASSWORD__
+
+# ── Attachments ─────────────────────────────────────────────────────────────
+# Stored on the named docker volume `attachments_data`, mounted at this path.
+ATTACHMENTS_DIR=/data/attachments
+MAX_UPLOAD_MB=25
+
+# ── Email notifications (Microsoft Graph, delegated Mail.Send) ──────────────
+# Runtime on/off lives in the Admin screen; this is only the initial default.
+NOTIFICATIONS_ENABLED_DEFAULT=true
+
+# ── Job lookup provider (future Infor VISUAL ERP integration) ───────────────
+# null   → job numbers accepted as free text (current behavior)
+# visual → VisualJobLookupService (stub today; see backend/app/services/job_lookup.py)
+JOB_LOOKUP_PROVIDER=null
+VISUAL_DB_HOST=
+VISUAL_DB_PORT=1433
+VISUAL_DB_NAME=
+VISUAL_DB_USER=
+VISUAL_DB_PASSWORD=
+VISUAL_SITE_ID=
+
+# ── Seed data ───────────────────────────────────────────────────────────────
+# When `python -m app.seed` runs: also create demo users + sample NCRs.
+SEED_DEMO_DATA=true