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>

.claude/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "frontend-dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "cwd": "frontend",
+      "port": 5173
+    }
+  ]
+}

.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

.gitignore

@@ -0,0 +1,29 @@
+# Environment / secrets
+.env
+*.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+htmlcov/
+.coverage
+
+# Node / frontend
+node_modules/
+frontend/dist/
+*.tsbuildinfo
+
+# Data
+attachments/
+*.db
+*.sqlite3
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

README.md

@@ -0,0 +1,308 @@
+# PESCO NCR — Non-Conformance Report System
+
+A web-based Non-Conformance Report (NCR / "QN") system for PESCO, replacing the
+PowerApps/SharePoint prototype. Shop-floor and office users log nonconformance
+issues on jobs, route them through disposition review, operations rework, QC
+inspection, and costing, then close them — with full audit history, email
+notifications, reporting, and Power BI access.
+
+## Contents
+
+- [Architecture](#architecture)
+- [Quick start (local demo, no Entra required)](#quick-start-local-demo-no-entra-required)
+- [Production setup](#production-setup)
+- [Entra ID app registration](#entra-id-app-registration)
+- [Email notifications (delegated Graph send)](#email-notifications-delegated-graph-send)
+- [Workflow & roles](#workflow--roles)
+- [Migrations & seed data](#migrations--seed-data)
+- [Power BI](#power-bi)
+- [Future VISUAL ERP integration](#future-visual-erp-integration)
+- [Backend tests](#backend-tests)
+- [Development outside Docker](#development-outside-docker)
+- [Troubleshooting](#troubleshooting)
+
+## Architecture
+
+```
+┌────────────┐   HTTPS    ┌─────────────────────┐        ┌──────────────┐
+│  Browser   │ ─────────▶ │ frontend (nginx)     │        │  Entra ID    │
+│ React SPA  │            │  - serves built SPA  │        │  (OIDC/JWKS) │
+│ MSAL       │            │  - proxies /api ────┼──┐     └──────▲───────┘
+└────────────┘            └─────────────────────┘  │            │ token
+                                                   ▼            │ validation,
+                          ┌─────────────────────────────┐       │ OBO exchange
+                          │ api (FastAPI, SQLAlchemy 2)  │ ──────┘
+                          │  - state machine, RBAC       │ ──▶ Microsoft Graph
+                          │  - audit trail, numbering    │     (delegated
+                          │  - WeasyPrint PDF, reports   │      Mail.Send)
+                          └───────┬──────────────┬───────┘
+                                  │              │
+                        ┌─────────▼───────┐  ┌───▼──────────────┐
+                        │ MySQL 8 (volume)│  │ attachments      │
+                        │ + reporting     │  │ (named volume)   │
+                        │   views for BI  │  └──────────────────┘
+                        └─────────────────┘
+```
+
+| Piece | Tech |
+|---|---|
+| Backend | Python 3.12, FastAPI, SQLAlchemy 2 (async, aiomysql), Alembic, Pydantic v2 |
+| Frontend | React 18 + Vite + TypeScript, MUI, React Router, TanStack Query, TipTap, Recharts |
+| Auth | Entra ID (OIDC) — `@azure/msal-react` in the SPA, `python-jose`/JWKS validation in the API |
+| Email | Microsoft Graph **delegated** `Mail.Send` via the On-Behalf-Of flow |
+| PDF | WeasyPrint (HTML → PDF) |
+| Database | MySQL 8 (utf8mb4), named volume; SQLite used only by the test suite |
+
+Key backend modules:
+
+- `backend/app/domain.py` — roles, stages, allowed transitions
+- `backend/app/services/workflow.py` — the state machine (all transitions validated server-side)
+- `backend/app/services/numbering.py` — atomic `NCR-YYYY-NNNN` allocation (per-year row lock)
+- `backend/app/services/notifications.py` — fault-tolerant Graph notifications
+- `backend/app/services/job_lookup.py` — `JobLookupService` seam for the future VISUAL integration
+- `backend/app/routers/ncrs.py` — NCR endpoints (create, queues, stage actions, attachments, audit, CSV, PDF)
+
+API docs (OpenAPI/Swagger) are served at **`/api/docs`**.
+
+## Quick start (local demo, no Entra required)
+
+Runs the full stack with **dev auth** (a user switcher instead of Entra —
+never use outside a lab):
+
+```bash
+cp .env.example .env
+# In .env set:
+#   AUTH_MODE=dev
+#   MYSQL_PASSWORD / MYSQL_ROOT_PASSWORD / POWERBI_RO_PASSWORD → anything
+docker compose up -d --build
+
+# seed departments/categories, demo users, and sample NCRs (SEED_DEMO_DATA=true)
+docker compose exec api python -m app.seed
+```
+
+Open **http://localhost:8080**. The switcher in the top bar signs you in as any
+demo user (`admin@`, `dispo@`, `second@`, `ops@`, `qc@`, `cost@`,
+`req@pescoinc.biz`) so you can walk an NCR through the whole workflow.
+
+## Production setup
+
+1. Complete the [Entra ID app registration](#entra-id-app-registration) below.
+2. `cp .env.example .env` and fill in everything marked `__LIKE_THIS__`:
+   - `AUTH_MODE=entra`
+   - `ENTRA_TENANT_ID`, `ENTRA_CLIENT_ID`, `ENTRA_CLIENT_SECRET`
+   - `ENTRA_ALLOWED_GROUP_ID` — object ID of the `NCR-Users` security group
+   - `INITIAL_ADMIN_EMAILS` — who gets the Admin role on first sign-in
+   - `APP_BASE_URL` — the URL users browse to (used in email links)
+   - strong MySQL + Power BI passwords
+3. `docker compose up -d --build` — migrations run automatically on API start.
+4. `docker compose exec api python -m app.seed` — seeds departments/categories
+   (set `SEED_DEMO_DATA=false` first to skip demo users/NCRs).
+5. Sign in with an `INITIAL_ADMIN_EMAILS` account, open **Admin → Users & Roles**,
+   and assign Disposition Authority / Operations / QC Inspector / Costing roles.
+
+Put TLS in front of the `frontend` service (reverse proxy or load balancer) and
+update the Entra redirect URI + `APP_BASE_URL` to the HTTPS URL.
+
+## Entra ID app registration
+
+One app registration serves both the SPA and the API.
+
+1. **Create the registration** — Azure portal → Entra ID → App registrations →
+   *New registration*. Name: `PESCO NCR`. Supported account types: *single
+   tenant*.
+2. **SPA redirect URIs** — Authentication → *Add a platform* →
+   **Single-page application** → add:
+   - `http://localhost:8080` (or your `APP_BASE_URL`)
+   - your production URL, e.g. `https://ncr.pescoinc.biz`
+3. **Expose the API** — Expose an API → *Set* the Application ID URI to the
+   default `api://<client-id>` → *Add a scope*:
+   - Scope name: `access_as_user`
+   - Who can consent: Admins and users
+   - Display name/description: "Access the PESCO NCR API as the signed-in user"
+4. **API permissions** — *Add a permission* → Microsoft Graph → **Delegated**:
+   - `User.Read` (usually present already)
+   - `Mail.Send` — required for stage-transition emails
+   - `GroupMember.Read.All` — optional; only needed for the group-overage
+     fallback (users in >200 groups)
+   Then click **Grant admin consent**.
+5. **Client secret** — Certificates & secrets → *New client secret* → put the
+   value in `ENTRA_CLIENT_SECRET`. (Used by the API for the OBO exchange and
+   overage checks; the SPA never sees it.)
+6. **Groups claim** — Token configuration → *Add groups claim* → select
+   **Security groups** (for both ID and access tokens). If your users belong to
+   many groups, prefer **Groups assigned to the application** and assign
+   `NCR-Users` to the app (Enterprise application → Users and groups) to avoid
+   claim overage.
+7. **Access-token version** — the API accepts both v1 and v2 issuers. For
+   clean v2 tokens set `"accessTokenAcceptedVersion": 2` in the app manifest.
+8. **Front-door group** — create (or reuse) a security group such as
+   `NCR-Users`, add everyone who may use the app, and put its **object ID** in
+   `ENTRA_ALLOWED_GROUP_ID`. Users outside the group get "Access denied" even
+   with a valid token.
+
+Users are auto-provisioned in the local DB on first sign-in (OID, name, email,
+employee ID when present in the token) with the default **Requester** role.
+
+## Email notifications (delegated Graph send)
+
+Notifications are sent **from the mailbox of the user who performed the
+action**, using the **On-Behalf-Of (OBO) flow** — chosen over passing
+frontend-acquired Graph tokens because it keeps Graph scopes and token plumbing
+entirely server-side: the SPA only ever requests the API scope, and the API
+exchanges the incoming access token for a delegated Graph token when it needs
+to send mail (`backend/app/services/graph.py`).
+
+| Event | Recipients | Sent from |
+|---|---|---|
+| New request submitted | selected Disposition Authority | requester |
+| Secondary review assigned | "Notify These People" | initial reviewer |
+| Released to Operations | all Operations users | releasing reviewer |
+| Operations complete | all QC Inspectors | operations user |
+| QC closed | all Costing users | QC inspector |
+| NCR closed | original requester | costing user |
+| Admin reopen | owners of the target stage + requester | admin |
+
+Fault tolerance: a Graph failure **never blocks a workflow transition** — the
+transition is already committed; the failure is logged and returned in the
+response `warnings` array, which the UI shows as a toast. The Admin → Settings
+screen has a global on/off toggle (handy during testing).
+
+## Workflow & roles
+
+Stages (enforced server-side; invalid transitions are rejected with HTTP 409):
+
+```
+New Request ──(initial disposition)──┬── needs secondary review ──▶ Secondary Disposition ─┐
+                                     └───────────── no ──────────────────▶ Operations ◀────┘
+Operations ─▶ QC Inspection ─▶ Costing ─▶ Closed (locked; Admin-only reopen with reason)
+```
+
+Notes:
+
+- "Initial Disposition" is the review a **Disposition Authority** performs on
+  an NCR sitting in the *New Request* queue (QC authority, work order,
+  rich-text disposition notes, secondary-review decision).
+- **Secondary Disposition** is visible only to the assigned "Notify These
+  People" users (their personal queue) and Admins; they may update disposition
+  fields and release to Operations.
+- **QC Inspection** can be saved repeatedly until *QC Closed* advances it.
+- Saving **Costing** (Labor/Material/Service/Other) closes the NCR. Closed
+  NCRs are fully read-only — including attachments — until an Admin reopens
+  them (required reason, recorded in the audit trail).
+- Every stage change writes a `stage_transitions` row (timestamp + acting
+  user) — the basis for the aging and cycle-time reports — and every field
+  change writes an immutable `audit_log` row (before/after values). The app
+  exposes no way to edit or delete audit rows.
+
+Roles (assigned in **Admin → Users & Roles**; a user may hold several):
+Requester (default), Disposition Authority, Secondary Disposition Authority,
+Operations, QC Inspector, Costing, Admin.
+
+## Migrations & seed data
+
+```bash
+# run migrations manually (they also run on every api container start)
+docker compose exec api alembic upgrade head
+
+# seed lookups (+ demo data when SEED_DEMO_DATA=true)
+docker compose exec api python -m app.seed
+
+# create a new migration after model changes
+docker compose exec api alembic revision --autogenerate -m "describe change"
+```
+
+## Power BI
+
+The schema ships three **read-only flattened views** for external reporting:
+
+| View | Grain |
+|---|---|
+| `vw_ncr_full` | one row per NCR — all stage data, costs, computed `total_cost`, `days_in_stage`, ERP enrichment |
+| `vw_ncr_stage_history` | one row per stage transition (for cycle-time analysis) |
+| `vw_ncr_costs` | one row per costed NCR (cost of nonconformance) |
+
+A dedicated MySQL account **`powerbi_ro`** is created on first startup
+(`db/init/01-powerbi-user.sh`) with `SELECT` on exactly those views and nothing
+else. If your MySQL volume was initialized before you set
+`POWERBI_RO_PASSWORD`, run `scripts/powerbi_grants.sql` (instructions inside).
+
+Pointing the gateway at it:
+
+1. MySQL is published on `MYSQL_PUBLISHED_PORT` (default 3306). Firewall it so
+   only the Power BI gateway host can reach it.
+2. On the gateway machine install the MySQL .NET connector
+   (Connector/NET 8.x — required for `caching_sha2_password`).
+3. In Power BI Desktop: *Get data → MySQL database* → server
+   `<docker-host>:3306`, database `pesco_ncr`, user `powerbi_ro`.
+4. Import (or DirectQuery) the three `vw_*` views; schedule refresh through the
+   gateway.
+
+## Future VISUAL ERP integration
+
+Job Number is free text today. The integration seam is already in place:
+
+- `backend/app/services/job_lookup.py` defines the `JobLookupService`
+  protocol. The default **`NullJobLookupService`** returns no enrichment.
+  **`VisualJobLookupService`** is a documented stub containing the verified
+  VISUAL 10 query plan (WORK_ORDER composite key `TYPE/BASE_ID/LOT_ID/
+  SPLIT_ID/SUB_ID`, PART join, and the DEMAND_SUPPLY_LINK →
+  CUST_ORDER_LINE → CUSTOMER_ORDER → CUSTOMER customer linkage).
+- The schema stores the job number as entered plus a nullable `job_info` row
+  (part, description, customer, WO status) any provider can populate.
+- The SPA's job-number field already calls `GET /api/jobs/{job}/lookup` while
+  typing and displays whatever enrichment returns — validation/autocomplete
+  light up without a redesign.
+
+To enable later: implement the stub (read-only SQL Server access — never write
+to VISUAL tables), set `JOB_LOOKUP_PROVIDER=visual` plus the `VISUAL_DB_*`
+variables, and restart the API.
+
+## Backend tests
+
+Covers the state machine (happy paths, invalid transitions, closure locking,
+reopen), per-stage permission enforcement, NCR numbering (format, year
+rollover, 12-way concurrent submission), attachments, and rich-text
+sanitization.
+
+```bash
+cd backend
+python -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
+.venv/bin/pytest
+```
+
+Tests run against SQLite by default (same models/state machine/numbering code
+paths); to exercise real MySQL locking:
+
+```bash
+DATABASE_URL="mysql+aiomysql://user:pass@host/pesco_ncr_test?charset=utf8mb4" .venv/bin/pytest
+```
+
+## Development outside Docker
+
+```bash
+# API (SQLite works fine for dev; export the vars or put them in backend/.env)
+cd backend
+export DATABASE_URL="sqlite+aiosqlite:///dev.db" AUTH_MODE=dev ATTACHMENTS_DIR=./attachments
+.venv/bin/python -m app.dev_init                      # create tables (models → SQLite)
+SEED_DEMO_DATA=true .venv/bin/python -m app.seed      # demo users + sample NCRs
+.venv/bin/uvicorn app.main:app --reload --port 8000
+
+# SPA (proxies /api to :8000; public/config.js defaults to dev auth)
+cd frontend
+npm install
+npm run dev            # http://localhost:5173
+```
+
+Note: generating PDFs locally requires WeasyPrint's system libraries (Pango/
+Cairo — `brew install pango` on macOS). The Docker image includes them.
+
+## Troubleshooting
+
+| Symptom | Likely cause / fix |
+|---|---|
+| "Access token has no groups claim" | Add the groups claim in Token configuration (step 6 above). |
+| "Could not verify group membership (group overage)" | Grant delegated `GroupMember.Read.All` + admin consent, or scope the group claim to "Groups assigned to the application". |
+| Notification warning "OBO token exchange failed" | Check `ENTRA_CLIENT_SECRET`, and that `Mail.Send` has admin consent. |
+| `api` container restarts at boot | MySQL still initializing; the entrypoint retries migrations 12×. Check `docker compose logs mysql`. |
+| Power BI can't authenticate | Update Connector/NET (needs `caching_sha2_password`), verify the `powerbi_ro` grants (`scripts/powerbi_grants.sql`). |
+| Uploads fail at ~25 MB | Raise `MAX_UPLOAD_MB` (API) — nginx `client_max_body_size` is 50 MB in `frontend/nginx.conf`. |

backend/.dockerignore

@@ -0,0 +1,9 @@
+__pycache__
+*.pyc
+.venv
+venv
+.pytest_cache
+tests
+dev.db
+attachments
+.env

backend/Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1
+
+# WeasyPrint runtime libraries (Pango/Cairo) + curl for the container healthcheck.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpango-1.0-0 \
+    libpangocairo-1.0-0 \
+    libcairo2 \
+    libgdk-pixbuf-2.0-0 \
+    libffi8 \
+    shared-mime-info \
+    fonts-dejavu-core \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /srv
+
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY alembic.ini .
+COPY alembic ./alembic
+COPY app ./app
+COPY entrypoint.sh .
+RUN chmod +x entrypoint.sh && mkdir -p /data/attachments
+
+EXPOSE 8000
+ENTRYPOINT ["./entrypoint.sh"]

backend/alembic.ini

@@ -0,0 +1,38 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+# URL is injected from app settings in alembic/env.py
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/alembic/env.py

@@ -0,0 +1,43 @@
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from app.config import get_settings
+from app.models import Base
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+config.set_main_option("sqlalchemy.url", get_settings().sync_database_url)
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/script.py.mako

@@ -0,0 +1,23 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

backend/alembic/versions/0001_initial_schema.py

@@ -0,0 +1,225 @@
+"""initial schema
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-07-13
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+MYSQL = {"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_unicode_ci"}
+
+
+def upgrade() -> None:
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("entra_oid", sa.String(64), nullable=True, unique=True),
+        sa.Column("email", sa.String(255), nullable=False, unique=True, index=True),
+        sa.Column("display_name", sa.String(255), nullable=False),
+        sa.Column("employee_id", sa.String(64), nullable=True),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("1")),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("last_login_at", sa.DateTime(), nullable=True),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "user_roles",
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column("role", sa.String(40), primary_key=True),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "departments",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("name", sa.String(100), nullable=False, unique=True),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("1")),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "deviation_categories",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("name", sa.String(100), nullable=False, unique=True),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("1")),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "ncr_sequences",
+        sa.Column("year", sa.Integer(), primary_key=True, autoincrement=False),
+        sa.Column("last_seq", sa.Integer(), nullable=False, server_default=sa.text("0")),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "ncrs",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("ncr_number", sa.String(20), nullable=False),
+        sa.Column("ncr_year", sa.Integer(), nullable=False),
+        sa.Column("ncr_seq", sa.Integer(), nullable=False),
+        sa.Column("job_number", sa.String(100), nullable=False),
+        sa.Column("department_id", sa.Integer(), sa.ForeignKey("departments.id"), nullable=False),
+        sa.Column(
+            "deviation_category_id",
+            sa.Integer(),
+            sa.ForeignKey("deviation_categories.id"),
+            nullable=False,
+        ),
+        sa.Column(
+            "disposition_authority_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=False
+        ),
+        sa.Column("deviation_detail", sa.Text(), nullable=False),
+        sa.Column("requester_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("stage", sa.String(30), nullable=False),
+        sa.Column("stage_entered_at", sa.DateTime(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.Column("qc_authority", sa.String(255), nullable=True),
+        sa.Column("work_order", sa.String(100), nullable=True),
+        sa.Column("disposition_notes", sa.Text(), nullable=True),
+        sa.Column("secondary_review_needed", sa.Boolean(), nullable=True),
+        sa.Column(
+            "operations_complete", sa.Boolean(), nullable=False, server_default=sa.text("0")
+        ),
+        sa.Column("operations_completed_at", sa.DateTime(), nullable=True),
+        sa.Column(
+            "operations_completed_by_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=True
+        ),
+        sa.Column("qc_approval", sa.String(10), nullable=True),
+        sa.Column("inspection_notes", sa.Text(), nullable=True),
+        sa.Column("qc_closed", sa.Boolean(), nullable=False, server_default=sa.text("0")),
+        sa.Column("qc_closed_at", sa.DateTime(), nullable=True),
+        sa.Column("qc_closed_by_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=True),
+        sa.Column("labor_cost", sa.Numeric(12, 2), nullable=True),
+        sa.Column("material_cost", sa.Numeric(12, 2), nullable=True),
+        sa.Column("service_cost", sa.Numeric(12, 2), nullable=True),
+        sa.Column("other_cost", sa.Numeric(12, 2), nullable=True),
+        sa.Column("costing_completed_at", sa.DateTime(), nullable=True),
+        sa.Column(
+            "costing_completed_by_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=True
+        ),
+        sa.Column("closed_at", sa.DateTime(), nullable=True),
+        sa.Column("closed_by_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=True),
+        sa.UniqueConstraint("ncr_number", name="uq_ncrs_ncr_number"),
+        **MYSQL,
+    )
+    op.create_index("ix_ncrs_stage", "ncrs", ["stage"])
+    op.create_index("ix_ncrs_job_number", "ncrs", ["job_number"])
+    op.create_index("ix_ncrs_created_at", "ncrs", ["created_at"])
+
+    op.create_table(
+        "ncr_secondary_assignees",
+        sa.Column(
+            "ncr_id", sa.Integer(), sa.ForeignKey("ncrs.id", ondelete="CASCADE"), primary_key=True
+        ),
+        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id"), primary_key=True),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "stage_transitions",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column(
+            "ncr_id", sa.Integer(), sa.ForeignKey("ncrs.id", ondelete="CASCADE"), nullable=False
+        ),
+        sa.Column("from_stage", sa.String(30), nullable=True),
+        sa.Column("to_stage", sa.String(30), nullable=False),
+        sa.Column("action", sa.String(40), nullable=False),
+        sa.Column("acted_by_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("acted_at", sa.DateTime(), nullable=False),
+        sa.Column("note", sa.Text(), nullable=True),
+        **MYSQL,
+    )
+    op.create_index("ix_stage_transitions_ncr", "stage_transitions", ["ncr_id", "acted_at"])
+
+    op.create_table(
+        "job_info",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column(
+            "ncr_id",
+            sa.Integer(),
+            sa.ForeignKey("ncrs.id", ondelete="CASCADE"),
+            nullable=False,
+            unique=True,
+        ),
+        sa.Column("part_id", sa.String(30), nullable=True),
+        sa.Column("part_description", sa.String(255), nullable=True),
+        sa.Column("customer_name", sa.String(100), nullable=True),
+        sa.Column("work_order_status", sa.String(20), nullable=True),
+        sa.Column("source", sa.String(20), nullable=False),
+        sa.Column("fetched_at", sa.DateTime(), nullable=False),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "attachments",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column(
+            "ncr_id", sa.Integer(), sa.ForeignKey("ncrs.id", ondelete="CASCADE"), nullable=False
+        ),
+        sa.Column("original_filename", sa.String(255), nullable=False),
+        sa.Column("stored_path", sa.String(300), nullable=False, unique=True),
+        sa.Column("content_type", sa.String(100), nullable=False),
+        sa.Column("size_bytes", sa.BigInteger(), nullable=False),
+        sa.Column("is_image", sa.Boolean(), nullable=False, server_default=sa.text("0")),
+        sa.Column("uploaded_by_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("uploaded_at", sa.DateTime(), nullable=False),
+        **MYSQL,
+    )
+
+    op.create_table(
+        "audit_log",
+        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column(
+            "ncr_id", sa.Integer(), sa.ForeignKey("ncrs.id", ondelete="SET NULL"), nullable=True
+        ),
+        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("action", sa.String(40), nullable=False),
+        sa.Column("field_name", sa.String(100), nullable=True),
+        sa.Column("old_value", sa.Text(), nullable=True),
+        sa.Column("new_value", sa.Text(), nullable=True),
+        sa.Column("detail", sa.String(500), nullable=True),
+        **MYSQL,
+    )
+    op.create_index("ix_audit_log_ncr", "audit_log", ["ncr_id", "created_at"])
+    op.create_index("ix_audit_log_created_at", "audit_log", ["created_at"])
+
+    op.create_table(
+        "app_settings",
+        sa.Column("key", sa.String(100), primary_key=True),
+        sa.Column("value", sa.String(500), nullable=False),
+        **MYSQL,
+    )
+
+
+def downgrade() -> None:
+    for table in (
+        "app_settings",
+        "audit_log",
+        "attachments",
+        "job_info",
+        "stage_transitions",
+        "ncr_secondary_assignees",
+        "ncrs",
+        "ncr_sequences",
+        "deviation_categories",
+        "departments",
+        "user_roles",
+        "users",
+    ):
+        op.drop_table(table)

backend/alembic/versions/0002_reporting_views.py

@@ -0,0 +1,129 @@
+"""read-only flattened reporting views for Power BI
+
+Revision ID: 0002
+Revises: 0001
+Create Date: 2026-07-13
+
+The powerbi_ro MySQL user (created by db/init/01-powerbi-user.sh) has SELECT
+on exactly these three views and nothing else.
+"""
+from alembic import op
+
+revision = "0002"
+down_revision = "0001"
+branch_labels = None
+depends_on = None
+
+VW_NCR_FULL = """
+CREATE OR REPLACE VIEW vw_ncr_full AS
+SELECT
+    n.id AS ncr_id,
+    n.ncr_number,
+    n.ncr_year,
+    n.ncr_seq,
+    n.created_at,
+    n.job_number,
+    d.name AS department,
+    dc.name AS deviation_category,
+    req.display_name AS requester,
+    req.email AS requester_email,
+    da.display_name AS disposition_authority,
+    n.stage,
+    n.stage_entered_at,
+    DATEDIFF(UTC_TIMESTAMP(), n.stage_entered_at) AS days_in_stage,
+    n.deviation_detail,
+    n.qc_authority,
+    n.work_order,
+    n.disposition_notes,
+    n.secondary_review_needed,
+    (SELECT GROUP_CONCAT(u2.display_name ORDER BY u2.display_name SEPARATOR '; ')
+       FROM ncr_secondary_assignees sa2
+       JOIN users u2 ON u2.id = sa2.user_id
+      WHERE sa2.ncr_id = n.id) AS secondary_authorities,
+    n.operations_complete,
+    n.operations_completed_at,
+    opu.display_name AS operations_completed_by,
+    n.qc_approval,
+    n.inspection_notes,
+    n.qc_closed,
+    n.qc_closed_at,
+    qcu.display_name AS qc_closed_by,
+    n.labor_cost,
+    n.material_cost,
+    n.service_cost,
+    n.other_cost,
+    COALESCE(n.labor_cost, 0) + COALESCE(n.material_cost, 0)
+      + COALESCE(n.service_cost, 0) + COALESCE(n.other_cost, 0) AS total_cost,
+    n.costing_completed_at,
+    n.closed_at,
+    clu.display_name AS closed_by,
+    ji.part_id,
+    ji.part_description,
+    ji.customer_name,
+    ji.work_order_status,
+    (SELECT COUNT(*) FROM attachments a WHERE a.ncr_id = n.id) AS attachment_count
+FROM ncrs n
+JOIN departments d            ON d.id  = n.department_id
+JOIN deviation_categories dc  ON dc.id = n.deviation_category_id
+JOIN users req                ON req.id = n.requester_id
+JOIN users da                 ON da.id  = n.disposition_authority_id
+LEFT JOIN users opu           ON opu.id = n.operations_completed_by_id
+LEFT JOIN users qcu           ON qcu.id = n.qc_closed_by_id
+LEFT JOIN users clu           ON clu.id = n.closed_by_id
+LEFT JOIN job_info ji         ON ji.ncr_id = n.id
+"""
+
+VW_NCR_STAGE_HISTORY = """
+CREATE OR REPLACE VIEW vw_ncr_stage_history AS
+SELECT
+    t.id AS transition_id,
+    t.ncr_id,
+    n.ncr_number,
+    n.job_number,
+    t.from_stage,
+    t.to_stage,
+    t.action,
+    t.acted_at,
+    u.display_name AS acted_by,
+    u.email AS acted_by_email,
+    t.note
+FROM stage_transitions t
+JOIN ncrs n  ON n.id = t.ncr_id
+JOIN users u ON u.id = t.acted_by_id
+"""
+
+VW_NCR_COSTS = """
+CREATE OR REPLACE VIEW vw_ncr_costs AS
+SELECT
+    n.id AS ncr_id,
+    n.ncr_number,
+    n.ncr_year,
+    n.job_number,
+    d.name AS department,
+    dc.name AS deviation_category,
+    n.created_at,
+    n.closed_at,
+    n.stage,
+    n.labor_cost,
+    n.material_cost,
+    n.service_cost,
+    n.other_cost,
+    COALESCE(n.labor_cost, 0) + COALESCE(n.material_cost, 0)
+      + COALESCE(n.service_cost, 0) + COALESCE(n.other_cost, 0) AS total_cost
+FROM ncrs n
+JOIN departments d           ON d.id  = n.department_id
+JOIN deviation_categories dc ON dc.id = n.deviation_category_id
+WHERE n.costing_completed_at IS NOT NULL
+"""
+
+
+def upgrade() -> None:
+    op.execute(VW_NCR_FULL)
+    op.execute(VW_NCR_STAGE_HISTORY)
+    op.execute(VW_NCR_COSTS)
+
+
+def downgrade() -> None:
+    op.execute("DROP VIEW IF EXISTS vw_ncr_costs")
+    op.execute("DROP VIEW IF EXISTS vw_ncr_stage_history")
+    op.execute("DROP VIEW IF EXISTS vw_ncr_full")

backend/app/auth/deps.py

@@ -0,0 +1,173 @@
+"""Request authentication + authorization dependencies.
+
+AUTH_MODE=entra: validates the bearer token, enforces the front-door group,
+and auto-provisions a local user (OID, name, email) on first login.
+
+AUTH_MODE=dev: trusts an X-Dev-User email header against seeded users.
+Local development only.
+"""
+import logging
+from dataclasses import dataclass, field
+from datetime import timedelta
+
+from fastapi import Depends, HTTPException, Request
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.entra import AuthError, ensure_group_membership, validate_access_token
+from app.config import get_settings
+from app.database import get_db
+from app.domain import Role
+from app.models import User, UserRole
+from app.models.base import utcnow
+
+logger = logging.getLogger(__name__)
+
+_bearer = HTTPBearer(auto_error=False)
+
+DEV_DEFAULT_USER = "admin@pescoinc.biz"
+
+
+@dataclass
+class CurrentUser:
+    user: User
+    roles: set[str] = field(default_factory=set)
+    token: str | None = None  # raw API access token (used for Graph OBO)
+    claims: dict = field(default_factory=dict)
+
+    @property
+    def id(self) -> int:
+        return self.user.id
+
+    @property
+    def is_admin(self) -> bool:
+        return Role.ADMIN.value in self.roles
+
+    def has_role(self, *roles: Role) -> bool:
+        return self.is_admin or any(r.value in self.roles for r in roles)
+
+
+async def _load_user_by_email(db: AsyncSession, email: str) -> User | None:
+    result = await db.execute(select(User).where(User.email == email.lower()))
+    return result.scalar_one_or_none()
+
+
+async def _provision_entra_user(db: AsyncSession, claims: dict) -> User:
+    settings = get_settings()
+    oid = claims.get("oid") or claims.get("sub")
+    email = (
+        claims.get("preferred_username")
+        or claims.get("email")
+        or claims.get("upn")
+        or ""
+    ).lower()
+    name = claims.get("name") or email or "Unknown User"
+    employee_id = claims.get("employeeid") or claims.get("employee_id")
+
+    user = (
+        await db.execute(select(User).where(User.entra_oid == oid))
+    ).scalar_one_or_none()
+    if user is None and email:
+        user = await _load_user_by_email(db, email)
+        if user is not None and user.entra_oid is None:
+            user.entra_oid = oid  # link pre-seeded user to their Entra identity
+
+    if user is None:
+        if not email:
+            raise AuthError("Token has no usable email/UPN claim.", 403)
+        user = User(
+            entra_oid=oid,
+            email=email,
+            display_name=name,
+            employee_id=employee_id,
+        )
+        db.add(user)
+        try:
+            await db.flush()
+            db.add(UserRole(user_id=user.id, role=Role.REQUESTER.value))
+            if email in settings.initial_admin_email_set:
+                db.add(UserRole(user_id=user.id, role=Role.ADMIN.value))
+            user.last_login_at = utcnow()
+            await db.commit()
+            logger.info("Auto-provisioned user %s", email)
+        except IntegrityError:
+            # Concurrent first login for the same user — use the winner's row.
+            await db.rollback()
+            user = (
+                await db.execute(select(User).where(User.entra_oid == oid))
+            ).scalar_one()
+        await db.refresh(user)
+        return user
+
+    # Keep profile fresh; throttle last_login writes to one per 15 minutes.
+    dirty = False
+    if name and user.display_name != name:
+        user.display_name = name
+        dirty = True
+    if email and user.email != email:
+        user.email = email
+        dirty = True
+    if employee_id and user.employee_id != employee_id:
+        user.employee_id = employee_id
+        dirty = True
+    if user.last_login_at is None or utcnow() - user.last_login_at > timedelta(minutes=15):
+        user.last_login_at = utcnow()
+        dirty = True
+    if dirty:
+        await db.commit()
+        await db.refresh(user)
+    return user
+
+
+async def get_current_user(
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None = Depends(_bearer),
+    db: AsyncSession = Depends(get_db),
+) -> CurrentUser:
+    settings = get_settings()
+
+    if settings.auth_mode == "dev":
+        email = request.headers.get("X-Dev-User", DEV_DEFAULT_USER)
+        user = await _load_user_by_email(db, email)
+        if user is None or not user.is_active:
+            raise HTTPException(
+                status_code=401,
+                detail=f"Unknown dev user '{email}'. Run `python -m app.seed` "
+                "or pass a seeded email in the X-Dev-User header.",
+            )
+        return CurrentUser(user=user, roles=set(user.roles), token=None, claims={})
+
+    if credentials is None:
+        raise HTTPException(status_code=401, detail="Missing bearer token.")
+    token = credentials.credentials
+    try:
+        claims = await validate_access_token(token)
+        await ensure_group_membership(claims, token)
+    except AuthError as exc:
+        raise HTTPException(status_code=exc.status_code, detail=exc.message) from exc
+
+    user = await _provision_entra_user(db, claims)
+    if not user.is_active:
+        raise HTTPException(status_code=403, detail="This account has been deactivated.")
+    return CurrentUser(user=user, roles=set(user.roles), token=token, claims=claims)
+
+
+def require_roles(*roles: Role):
+    """Dependency factory: caller must hold one of `roles` (Admin always passes)."""
+
+    async def dependency(
+        current: CurrentUser = Depends(get_current_user),
+    ) -> CurrentUser:
+        if current.has_role(*roles):
+            return current
+        needed = ", ".join(r.value for r in roles)
+        raise HTTPException(
+            status_code=403, detail=f"This action requires one of the roles: {needed}."
+        )
+
+    return dependency
+
+
+require_admin = require_roles(Role.ADMIN)

backend/app/auth/entra.py

@@ -0,0 +1,124 @@
+"""Entra ID access-token validation (python-jose + tenant JWKS)."""
+import logging
+import time
+
+import httpx
+from jose import JWTError, jwt
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class AuthError(Exception):
+    def __init__(self, message: str, status_code: int = 401):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+_jwks: dict[str, dict] = {}
+_jwks_fetched_at: float = 0.0
+_JWKS_TTL = 60 * 60 * 12
+
+
+async def _fetch_jwks() -> None:
+    global _jwks, _jwks_fetched_at
+    settings = get_settings()
+    url = (
+        f"https://login.microsoftonline.com/{settings.entra_tenant_id}"
+        "/discovery/v2.0/keys"
+    )
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.get(url)
+        resp.raise_for_status()
+        _jwks = {k["kid"]: k for k in resp.json().get("keys", [])}
+        _jwks_fetched_at = time.time()
+    logger.info("Fetched %d Entra signing keys", len(_jwks))
+
+
+async def _get_signing_key(kid: str) -> dict:
+    stale = time.time() - _jwks_fetched_at > _JWKS_TTL
+    if kid not in _jwks or stale:
+        await _fetch_jwks()
+    key = _jwks.get(kid)
+    if key is None:
+        raise AuthError("Token signed with an unknown key.")
+    return key
+
+
+async def validate_access_token(token: str) -> dict:
+    """Validate signature, expiry, audience, and issuer; return claims."""
+    settings = get_settings()
+    if not settings.entra_tenant_id or not settings.entra_client_id:
+        raise AuthError(
+            "Entra ID is not configured (ENTRA_TENANT_ID / ENTRA_CLIENT_ID).", 503
+        )
+    try:
+        header = jwt.get_unverified_header(token)
+        key = await _get_signing_key(header.get("kid", ""))
+        claims = jwt.decode(
+            token,
+            key,
+            algorithms=["RS256"],
+            options={"verify_aud": False},  # audience list checked below
+        )
+    except AuthError:
+        raise
+    except JWTError as exc:
+        raise AuthError(f"Invalid token: {exc}") from exc
+
+    aud = claims.get("aud")
+    if aud not in settings.api_audiences:
+        raise AuthError("Token audience does not match this API.")
+
+    tid = settings.entra_tenant_id
+    valid_issuers = {
+        f"https://login.microsoftonline.com/{tid}/v2.0",
+        f"https://sts.windows.net/{tid}/",
+    }
+    if claims.get("iss") not in valid_issuers:
+        raise AuthError("Token issuer does not match the configured tenant.")
+    return claims
+
+
+async def ensure_group_membership(claims: dict, token: str) -> None:
+    """Front-door gate: require membership in ENTRA_ALLOWED_GROUP_ID.
+
+    Uses the `groups` claim when present; on claim overage falls back to a
+    delegated Graph checkMemberGroups call.
+    """
+    settings = get_settings()
+    group_id = settings.entra_allowed_group_id
+    if not group_id:
+        return  # gate disabled by configuration
+
+    groups = claims.get("groups")
+    if groups is not None:
+        if group_id in groups:
+            return
+        raise AuthError(
+            "Your account is not a member of the NCR access group.", 403
+        )
+
+    claim_names = claims.get("_claim_names") or {}
+    if "groups" in claim_names:
+        # Group overage: too many groups to embed in the token.
+        from app.services.graph import check_member_group
+
+        try:
+            if await check_member_group(token, group_id):
+                return
+        except Exception as exc:
+            logger.warning("Group overage Graph check failed: %s", exc)
+            raise AuthError(
+                "Could not verify group membership (group overage). Ensure the "
+                "app has delegated GroupMember.Read.All consent, or scope the "
+                "group claim to 'Groups assigned to the application'.", 403
+            ) from exc
+        raise AuthError("Your account is not a member of the NCR access group.", 403)
+
+    raise AuthError(
+        "Access token has no groups claim. Add the groups claim in the app "
+        "registration (Token configuration → Add groups claim).", 403
+    )

backend/app/config.py

@@ -0,0 +1,88 @@
+"""Application configuration, sourced from environment variables (see .env.example)."""
+from functools import lru_cache
+from typing import Literal
+from urllib.parse import quote_plus
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    app_name: str = "PESCO NCR"
+    app_base_url: str = "http://localhost:8080"
+    log_level: str = "INFO"
+
+    # ── Auth ────────────────────────────────────────────────────────────────
+    # "entra" validates Entra ID JWTs; "dev" trusts an X-Dev-User header and
+    # must never be used outside local development.
+    auth_mode: Literal["entra", "dev"] = "entra"
+    entra_tenant_id: str = ""
+    entra_client_id: str = ""
+    entra_client_secret: str = ""
+    entra_allowed_group_id: str = ""
+    entra_api_audience: str = ""
+    initial_admin_emails: str = ""
+
+    # ── Database ────────────────────────────────────────────────────────────
+    # Full SQLAlchemy URL override (used by tests); otherwise assembled from
+    # the MYSQL_* parts below.
+    database_url: str = ""
+    mysql_host: str = "mysql"
+    mysql_port: int = 3306
+    mysql_database: str = "pesco_ncr"
+    mysql_user: str = "ncr_app"
+    mysql_password: str = ""
+
+    # ── Attachments ─────────────────────────────────────────────────────────
+    attachments_dir: str = "/data/attachments"
+    max_upload_mb: int = 25
+
+    # ── Notifications ───────────────────────────────────────────────────────
+    notifications_enabled_default: bool = True
+
+    # ── Job lookup (future VISUAL integration) ──────────────────────────────
+    job_lookup_provider: Literal["null", "visual"] = "null"
+    visual_db_host: str = ""
+    visual_db_port: int = 1433
+    visual_db_name: str = ""
+    visual_db_user: str = ""
+    visual_db_password: str = ""
+    visual_site_id: str = ""
+
+    seed_demo_data: bool = False
+
+    @property
+    def effective_database_url(self) -> str:
+        if self.database_url:
+            return self.database_url
+        return (
+            f"mysql+aiomysql://{quote_plus(self.mysql_user)}:{quote_plus(self.mysql_password)}"
+            f"@{self.mysql_host}:{self.mysql_port}/{self.mysql_database}?charset=utf8mb4"
+        )
+
+    @property
+    def sync_database_url(self) -> str:
+        """Synchronous-driver URL for Alembic."""
+        return self.effective_database_url.replace("+aiomysql", "+pymysql").replace(
+            "+aiosqlite", ""
+        )
+
+    @property
+    def api_audiences(self) -> list[str]:
+        if self.entra_api_audience:
+            return [self.entra_api_audience]
+        return [f"api://{self.entra_client_id}", self.entra_client_id]
+
+    @property
+    def initial_admin_email_set(self) -> set[str]:
+        return {e.strip().lower() for e in self.initial_admin_emails.split(",") if e.strip()}
+
+    @property
+    def max_upload_bytes(self) -> int:
+        return self.max_upload_mb * 1024 * 1024
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

backend/app/database.py

@@ -0,0 +1,68 @@
+"""Async SQLAlchemy engine/session setup.
+
+The engine is created lazily so importing the app (e.g. in tests that override
+`get_db`) never requires a reachable MySQL server or its driver.
+"""
+from collections.abc import AsyncIterator
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from app.config import get_settings
+
+_engine: AsyncEngine | None = None
+_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+
+def get_engine() -> AsyncEngine:
+    global _engine
+    if _engine is None:
+        settings = get_settings()
+        url = settings.effective_database_url
+        if url.startswith("sqlite"):
+            # Test runs: fresh connection per checkout (no cross-event-loop
+            # reuse) and a generous busy timeout for concurrent writers.
+            from sqlalchemy import event
+            from sqlalchemy.pool import NullPool
+
+            _engine = create_async_engine(
+                url, poolclass=NullPool, connect_args={"timeout": 30}
+            )
+
+            # SQLite (rollback-journal) deadlocks when a transaction upgrades
+            # from read to write while another writer waits. Taking the write
+            # lock up front (BEGIN IMMEDIATE) serializes transactions cleanly,
+            # mirroring the row-lock semantics InnoDB gives us in production.
+            @event.listens_for(_engine.sync_engine, "connect")
+            def _sqlite_autocommit(dbapi_conn, _record):
+                dbapi_conn.isolation_level = None
+
+            @event.listens_for(_engine.sync_engine, "begin")
+            def _sqlite_begin_immediate(conn):
+                conn.exec_driver_sql("BEGIN IMMEDIATE")
+        else:
+            _engine = create_async_engine(
+                url,
+                pool_pre_ping=True,
+                pool_recycle=1800,
+                echo=False,
+            )
+    return _engine
+
+
+def get_session_factory() -> async_sessionmaker[AsyncSession]:
+    global _session_factory
+    if _session_factory is None:
+        _session_factory = async_sessionmaker(
+            get_engine(), expire_on_commit=False, autoflush=False
+        )
+    return _session_factory
+
+
+async def get_db() -> AsyncIterator[AsyncSession]:
+    async with get_session_factory()() as session:
+        yield session

backend/app/dev_init.py

@@ -0,0 +1,21 @@
+"""Create the schema directly from the models — for LOCAL SQLite development
+only (`python -m app.dev_init`). Real MySQL deployments use Alembic
+(`alembic upgrade head`), which also creates the Power BI reporting views.
+"""
+import asyncio
+
+from app.config import get_settings
+from app.database import get_engine
+from app.models import Base
+
+
+async def main() -> None:
+    url = get_settings().effective_database_url
+    engine = get_engine()
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    print(f"Schema created for {url}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/app/domain.py

@@ -0,0 +1,84 @@
+"""Domain constants: roles, workflow stages, and the transition map.
+
+Workflow note: an NCR in the "New Request" stage is awaiting Initial
+Disposition — the initial-disposition review is the action a Disposition
+Authority performs on a New Request, and it moves the NCR either to
+Secondary Disposition (when secondary review is required) or straight to
+Operations. All transitions are validated server-side against
+ALLOWED_TRANSITIONS; anything else is rejected with HTTP 409.
+"""
+from enum import Enum
+
+
+class Role(str, Enum):
+    REQUESTER = "requester"
+    DISPOSITION_AUTHORITY = "disposition_authority"
+    SECONDARY_DISPOSITION_AUTHORITY = "secondary_disposition_authority"
+    OPERATIONS = "operations"
+    QC_INSPECTOR = "qc_inspector"
+    COSTING = "costing"
+    ADMIN = "admin"
+
+
+ALL_ROLES: set[str] = {r.value for r in Role}
+
+ROLE_LABELS: dict[str, str] = {
+    Role.REQUESTER: "Requester",
+    Role.DISPOSITION_AUTHORITY: "Disposition Authority",
+    Role.SECONDARY_DISPOSITION_AUTHORITY: "Secondary Disposition Authority",
+    Role.OPERATIONS: "Operations",
+    Role.QC_INSPECTOR: "QC Inspector",
+    Role.COSTING: "Costing",
+    Role.ADMIN: "Admin",
+}
+
+
+class Stage(str, Enum):
+    NEW_REQUEST = "new_request"
+    SECONDARY_DISPOSITION = "secondary_disposition"
+    OPERATIONS = "operations"
+    QC_INSPECTION = "qc_inspection"
+    COSTING = "costing"
+    CLOSED = "closed"
+
+
+STAGE_LABELS: dict[str, str] = {
+    Stage.NEW_REQUEST: "New Request",
+    Stage.SECONDARY_DISPOSITION: "Secondary Disposition",
+    Stage.OPERATIONS: "Operations",
+    Stage.QC_INSPECTION: "QC Inspection",
+    Stage.COSTING: "Costing",
+    Stage.CLOSED: "Closed",
+}
+
+# Stages an admin may reopen a closed NCR back into.
+REOPEN_TARGET_STAGES: list[Stage] = [
+    Stage.NEW_REQUEST,
+    Stage.SECONDARY_DISPOSITION,
+    Stage.OPERATIONS,
+    Stage.QC_INSPECTION,
+    Stage.COSTING,
+]
+
+ALLOWED_TRANSITIONS: dict[Stage, set[Stage]] = {
+    Stage.NEW_REQUEST: {Stage.SECONDARY_DISPOSITION, Stage.OPERATIONS},
+    Stage.SECONDARY_DISPOSITION: {Stage.OPERATIONS},
+    Stage.OPERATIONS: {Stage.QC_INSPECTION},
+    Stage.QC_INSPECTION: {Stage.COSTING},
+    Stage.COSTING: {Stage.CLOSED},
+    # Reopen (admin only, reason required) — enforced separately.
+    Stage.CLOSED: set(REOPEN_TARGET_STAGES),
+}
+
+# Role allowed to act on the NCR in each stage (Admin is always allowed;
+# Secondary Disposition additionally requires being an assigned authority).
+STAGE_ACTING_ROLE: dict[Stage, Role] = {
+    Stage.NEW_REQUEST: Role.DISPOSITION_AUTHORITY,
+    Stage.SECONDARY_DISPOSITION: Role.SECONDARY_DISPOSITION_AUTHORITY,
+    Stage.OPERATIONS: Role.OPERATIONS,
+    Stage.QC_INSPECTION: Role.QC_INSPECTOR,
+    Stage.COSTING: Role.COSTING,
+}
+
+# Owners to notify when an admin reopens an NCR into a given stage.
+STAGE_OWNER_ROLE: dict[Stage, Role] = STAGE_ACTING_ROLE

backend/app/main.py

@@ -0,0 +1,57 @@
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import get_settings
+from app.routers import admin, health, jobs, lookups, ncrs, reports, users
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    settings = get_settings()
+    logging.basicConfig(
+        level=getattr(logging, settings.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    Path(settings.attachments_dir).mkdir(parents=True, exist_ok=True)
+    if settings.auth_mode == "dev":
+        logging.getLogger(__name__).warning(
+            "AUTH_MODE=dev — authentication is BYPASSED. Never use in production."
+        )
+    # Fail fast on a misconfigured job-lookup provider.
+    from app.services.job_lookup import get_job_lookup_service
+
+    get_job_lookup_service()
+    yield
+
+
+app = FastAPI(
+    title="PESCO NCR API",
+    version="1.0.0",
+    docs_url="/api/docs",
+    openapi_url="/api/openapi.json",
+    redoc_url=None,
+    lifespan=lifespan,
+)
+
+# In production nginx serves the SPA and proxies /api same-origin, so CORS is
+# only exercised by the Vite dev server.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://127.0.0.1:5173"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+API = "/api"
+app.include_router(health.router, prefix=API)
+app.include_router(users.router, prefix=API)
+app.include_router(lookups.router, prefix=API)
+app.include_router(jobs.router, prefix=API)
+app.include_router(ncrs.router, prefix=API)
+app.include_router(reports.router, prefix=API)
+app.include_router(admin.router, prefix=API)

backend/app/models/__init__.py

@@ -0,0 +1,29 @@
+from app.models.base import Base
+from app.models.user import User, UserRole
+from app.models.lookups import Department, DeviationCategory
+from app.models.ncr import (
+    JobInfo,
+    Ncr,
+    NcrSecondaryAssignee,
+    NcrSequence,
+    StageTransition,
+)
+from app.models.attachment import Attachment
+from app.models.audit import AuditLog
+from app.models.app_setting import AppSetting
+
+__all__ = [
+    "Base",
+    "User",
+    "UserRole",
+    "Department",
+    "DeviationCategory",
+    "Ncr",
+    "NcrSequence",
+    "NcrSecondaryAssignee",
+    "StageTransition",
+    "JobInfo",
+    "Attachment",
+    "AuditLog",
+    "AppSetting",
+]

backend/app/models/app_setting.py

@@ -0,0 +1,14 @@
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base
+
+
+class AppSetting(Base):
+    __tablename__ = "app_settings"
+
+    key: Mapped[str] = mapped_column(String(100), primary_key=True)
+    value: Mapped[str] = mapped_column(String(500))
+
+
+NOTIFICATIONS_ENABLED_KEY = "notifications_enabled"

backend/app/models/attachment.py

@@ -0,0 +1,25 @@
+from datetime import datetime
+
+from sqlalchemy import BigInteger, Boolean, DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base, utcnow
+from app.models.user import User
+
+
+class Attachment(Base):
+    __tablename__ = "attachments"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ncr_id: Mapped[int] = mapped_column(ForeignKey("ncrs.id", ondelete="CASCADE"))
+    original_filename: Mapped[str] = mapped_column(String(255))
+    # Relative path under ATTACHMENTS_DIR: "<ncr_id>/<uuid><ext>"
+    stored_path: Mapped[str] = mapped_column(String(300), unique=True)
+    content_type: Mapped[str] = mapped_column(String(100))
+    size_bytes: Mapped[int] = mapped_column(BigInteger)
+    is_image: Mapped[bool] = mapped_column(Boolean, default=False)
+    uploaded_by_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+    uploaded_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow)
+
+    ncr = relationship("Ncr", back_populates="attachments")
+    uploaded_by: Mapped[User] = relationship(lazy="selectin")

backend/app/models/audit.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, ForeignKey, Index, Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base, utcnow
+from app.models.user import User
+
+
+class AuditLog(Base):
+    """Immutable audit record. The application exposes no update or delete
+    path for these rows; one row per changed field (field_name null for
+    record-level events such as create/transition/attachment/reopen)."""
+
+    __tablename__ = "audit_log"
+    __table_args__ = (
+        Index("ix_audit_log_ncr", "ncr_id", "created_at"),
+        Index("ix_audit_log_created_at", "created_at"),
+    )
+
+    # BigInteger on MySQL; plain INTEGER on SQLite (required for autoincrement).
+    id: Mapped[int] = mapped_column(
+        BigInteger().with_variant(Integer, "sqlite"), primary_key=True, autoincrement=True
+    )
+    # Nullable so admin actions without an NCR (settings, role changes) are auditable too.
+    ncr_id: Mapped[int | None] = mapped_column(
+        ForeignKey("ncrs.id", ondelete="SET NULL"), nullable=True
+    )
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow)
+    action: Mapped[str] = mapped_column(String(40))
+    field_name: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    old_value: Mapped[str | None] = mapped_column(Text, nullable=True)
+    new_value: Mapped[str | None] = mapped_column(Text, nullable=True)
+    detail: Mapped[str | None] = mapped_column(String(500), nullable=True)
+
+    user: Mapped[User] = relationship(lazy="selectin")

backend/app/models/base.py

@@ -0,0 +1,12 @@
+from datetime import datetime, timezone
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+def utcnow() -> datetime:
+    """Naive UTC timestamp — all datetimes are stored as UTC in MySQL DATETIME."""
+    return datetime.now(timezone.utc).replace(tzinfo=None)
+
+
+class Base(DeclarativeBase):
+    pass

backend/app/models/lookups.py

@@ -0,0 +1,22 @@
+from sqlalchemy import Boolean, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base
+
+
+class Department(Base):
+    __tablename__ = "departments"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(100), unique=True)
+    # Deactivated values are hidden from new-NCR forms but remain valid on
+    # existing records; values referenced by NCRs are never hard-deleted.
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+
+
+class DeviationCategory(Base):
+    __tablename__ = "deviation_categories"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(100), unique=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)

backend/app/models/ncr.py

@@ -0,0 +1,195 @@
+from datetime import datetime
+from decimal import Decimal
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    Numeric,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base, utcnow
+from app.models.user import User
+
+
+class NcrSequence(Base):
+    """Per-year NCR number allocator. Incremented atomically inside the
+    NCR-creation transaction (row lock held until commit) so concurrent
+    submissions can never produce the same number."""
+
+    __tablename__ = "ncr_sequences"
+
+    year: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=False)
+    last_seq: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+
+class Ncr(Base):
+    __tablename__ = "ncrs"
+    __table_args__ = (
+        UniqueConstraint("ncr_number", name="uq_ncrs_ncr_number"),
+        Index("ix_ncrs_stage", "stage"),
+        Index("ix_ncrs_job_number", "job_number"),
+        Index("ix_ncrs_created_at", "created_at"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ncr_number: Mapped[str] = mapped_column(String(20))
+    ncr_year: Mapped[int] = mapped_column(Integer)
+    ncr_seq: Mapped[int] = mapped_column(Integer)
+
+    # ── Request (stage 1) ────────────────────────────────────────────────────
+    job_number: Mapped[str] = mapped_column(String(100))
+    department_id: Mapped[int] = mapped_column(ForeignKey("departments.id"))
+    deviation_category_id: Mapped[int] = mapped_column(ForeignKey("deviation_categories.id"))
+    disposition_authority_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+    deviation_detail: Mapped[str] = mapped_column(Text)
+    requester_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+
+    # ── Workflow state ───────────────────────────────────────────────────────
+    stage: Mapped[str] = mapped_column(String(30))
+    stage_entered_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow, onupdate=utcnow)
+
+    # ── Disposition (initial + secondary) ────────────────────────────────────
+    qc_authority: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    work_order: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    disposition_notes: Mapped[str | None] = mapped_column(Text, nullable=True)  # sanitized HTML
+    secondary_review_needed: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+
+    # ── Operations ───────────────────────────────────────────────────────────
+    operations_complete: Mapped[bool] = mapped_column(Boolean, default=False)
+    operations_completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    operations_completed_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id"), nullable=True
+    )
+
+    # ── QC Inspection ────────────────────────────────────────────────────────
+    qc_approval: Mapped[str | None] = mapped_column(String(10), nullable=True)  # yes | no
+    inspection_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    qc_closed: Mapped[bool] = mapped_column(Boolean, default=False)
+    qc_closed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    qc_closed_by_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True)
+
+    # ── Costing ──────────────────────────────────────────────────────────────
+    labor_cost: Mapped[Decimal | None] = mapped_column(Numeric(12, 2), nullable=True)
+    material_cost: Mapped[Decimal | None] = mapped_column(Numeric(12, 2), nullable=True)
+    service_cost: Mapped[Decimal | None] = mapped_column(Numeric(12, 2), nullable=True)
+    other_cost: Mapped[Decimal | None] = mapped_column(Numeric(12, 2), nullable=True)
+    costing_completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    costing_completed_by_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id"), nullable=True
+    )
+
+    # ── Closure ──────────────────────────────────────────────────────────────
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    closed_by_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True)
+
+    # ── Relationships ────────────────────────────────────────────────────────
+    department = relationship("Department", lazy="selectin")
+    deviation_category = relationship("DeviationCategory", lazy="selectin")
+    requester: Mapped[User] = relationship(foreign_keys=[requester_id], lazy="selectin")
+    disposition_authority: Mapped[User] = relationship(
+        foreign_keys=[disposition_authority_id], lazy="selectin"
+    )
+    operations_completed_by: Mapped[User | None] = relationship(
+        foreign_keys=[operations_completed_by_id], lazy="selectin"
+    )
+    qc_closed_by: Mapped[User | None] = relationship(
+        foreign_keys=[qc_closed_by_id], lazy="selectin"
+    )
+    costing_completed_by: Mapped[User | None] = relationship(
+        foreign_keys=[costing_completed_by_id], lazy="selectin"
+    )
+    closed_by: Mapped[User | None] = relationship(foreign_keys=[closed_by_id], lazy="selectin")
+
+    secondary_assignee_rows: Mapped[list["NcrSecondaryAssignee"]] = relationship(
+        back_populates="ncr", cascade="all, delete-orphan", lazy="selectin"
+    )
+    transitions: Mapped[list["StageTransition"]] = relationship(
+        back_populates="ncr",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+        order_by="StageTransition.acted_at",
+    )
+    attachments: Mapped[list["Attachment"]] = relationship(  # noqa: F821
+        back_populates="ncr", cascade="all, delete-orphan", lazy="selectin"
+    )
+    job_info: Mapped["JobInfo | None"] = relationship(
+        back_populates="ncr", cascade="all, delete-orphan", lazy="selectin", uselist=False
+    )
+
+    @property
+    def secondary_authorities(self) -> list[User]:
+        return [row.user for row in self.secondary_assignee_rows]
+
+    @property
+    def total_cost(self) -> Decimal | None:
+        costs = [self.labor_cost, self.material_cost, self.service_cost, self.other_cost]
+        present = [c for c in costs if c is not None]
+        if not present:
+            return None
+        return sum(present, Decimal("0"))
+
+
+class NcrSecondaryAssignee(Base):
+    """Users selected as 'Notify These People' for secondary disposition."""
+
+    __tablename__ = "ncr_secondary_assignees"
+
+    ncr_id: Mapped[int] = mapped_column(
+        ForeignKey("ncrs.id", ondelete="CASCADE"), primary_key=True
+    )
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), primary_key=True)
+
+    ncr: Mapped[Ncr] = relationship(back_populates="secondary_assignee_rows")
+    user: Mapped[User] = relationship(lazy="selectin")
+
+
+class StageTransition(Base):
+    """One row per lifecycle event (create, stage change, reopen) — the basis
+    for aging and cycle-time reporting."""
+
+    __tablename__ = "stage_transitions"
+    __table_args__ = (Index("ix_stage_transitions_ncr", "ncr_id", "acted_at"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ncr_id: Mapped[int] = mapped_column(ForeignKey("ncrs.id", ondelete="CASCADE"))
+    from_stage: Mapped[str | None] = mapped_column(String(30), nullable=True)
+    to_stage: Mapped[str] = mapped_column(String(30))
+    action: Mapped[str] = mapped_column(String(40))
+    acted_by_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+    acted_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow)
+    note: Mapped[str | None] = mapped_column(Text, nullable=True)  # e.g. reopen reason
+
+    ncr: Mapped[Ncr] = relationship(back_populates="transitions")
+    acted_by: Mapped[User] = relationship(lazy="selectin")
+
+
+class JobInfo(Base):
+    """Read-only enrichment for a job number, populated by a JobLookupService.
+
+    Stays empty under NullJobLookupService; the future VisualJobLookupService
+    will fill it from Infor VISUAL (WORK_ORDER + customer order linkage).
+    """
+
+    __tablename__ = "job_info"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ncr_id: Mapped[int] = mapped_column(
+        ForeignKey("ncrs.id", ondelete="CASCADE"), unique=True
+    )
+    part_id: Mapped[str | None] = mapped_column(String(30), nullable=True)
+    part_description: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    customer_name: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    work_order_status: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    source: Mapped[str] = mapped_column(String(20), default="null")
+    fetched_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow)
+
+    ncr: Mapped[Ncr] = relationship(back_populates="job_info")

backend/app/models/user.py

@@ -0,0 +1,39 @@
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base, utcnow
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    # Entra object id; null for dev-mode/seeded users.
+    entra_oid: Mapped[str | None] = mapped_column(String(64), unique=True, nullable=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    display_name: Mapped[str] = mapped_column(String(255))
+    employee_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=utcnow)
+    last_login_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+
+    role_rows: Mapped[list["UserRole"]] = relationship(
+        back_populates="user", cascade="all, delete-orphan", lazy="selectin"
+    )
+
+    @property
+    def roles(self) -> list[str]:
+        return sorted(r.role for r in self.role_rows)
+
+
+class UserRole(Base):
+    __tablename__ = "user_roles"
+
+    user_id: Mapped[int] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), primary_key=True
+    )
+    role: Mapped[str] = mapped_column(String(40), primary_key=True)
+
+    user: Mapped[User] = relationship(back_populates="role_rows")

backend/app/routers/admin.py

@@ -0,0 +1,312 @@
+"""Admin area: role management, department/category lists, notification
+toggle, and the global audit log. All endpoints are Admin-only."""
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.deps import CurrentUser, require_admin
+from app.database import get_db
+from app.domain import Role
+from app.models import (
+    AppSetting,
+    AuditLog,
+    Department,
+    DeviationCategory,
+    Ncr,
+    User,
+    UserRole,
+)
+from app.models.app_setting import NOTIFICATIONS_ENABLED_KEY
+from app.schemas.lookup import LookupCreateIn, LookupPatchIn, NamedLookupOut
+from app.schemas.ncr import AuditEntryOut
+from app.schemas.user import RolesUpdateIn, UserOut
+from app.services.audit import audit_event
+from app.services.notifications import notifications_enabled
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+
+def _user_out(u: User) -> UserOut:
+    return UserOut(
+        id=u.id,
+        display_name=u.display_name,
+        email=u.email,
+        employee_id=u.employee_id,
+        is_active=u.is_active,
+        roles=u.roles,
+        last_login_at=u.last_login_at,
+    )
+
+
+# ── users & roles ────────────────────────────────────────────────────────────
+@router.get("/users", response_model=list[UserOut])
+async def list_all_users(
+    search: str | None = None,
+    _: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+) -> list[UserOut]:
+    stmt = select(User).order_by(User.display_name)
+    if search:
+        like = f"%{search.strip()}%"
+        stmt = stmt.where(User.display_name.like(like) | User.email.like(like))
+    users = (await db.execute(stmt)).scalars().unique().all()
+    return [_user_out(u) for u in users]
+
+
+@router.put("/users/{user_id}/roles", response_model=UserOut)
+async def set_user_roles(
+    user_id: int,
+    payload: RolesUpdateIn,
+    current: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+) -> UserOut:
+    user = await db.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found.")
+    if user.id == current.id and Role.ADMIN.value not in payload.roles:
+        raise HTTPException(
+            status_code=422,
+            detail="You cannot remove your own Admin role (lockout protection).",
+        )
+    old_roles = user.roles
+    user.role_rows = [UserRole(user_id=user.id, role=r) for r in payload.roles]
+    audit_event(
+        db,
+        user_id=current.id,
+        action="roles_update",
+        field_name=f"user:{user.email}",
+        old_value=", ".join(old_roles) or "(none)",
+        new_value=", ".join(payload.roles) or "(none)",
+    )
+    await db.commit()
+    await db.refresh(user)
+    return _user_out(user)
+
+
+class ActivePatchIn(BaseModel):
+    is_active: bool
+
+
+@router.put("/users/{user_id}/active", response_model=UserOut)
+async def set_user_active(
+    user_id: int,
+    payload: ActivePatchIn,
+    current: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+) -> UserOut:
+    user = await db.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found.")
+    if user.id == current.id and not payload.is_active:
+        raise HTTPException(status_code=422, detail="You cannot deactivate yourself.")
+    if user.is_active != payload.is_active:
+        audit_event(
+            db,
+            user_id=current.id,
+            action="user_active",
+            field_name=f"user:{user.email}",
+            old_value=user.is_active,
+            new_value=payload.is_active,
+        )
+        user.is_active = payload.is_active
+        await db.commit()
+        await db.refresh(user)
+    return _user_out(user)
+
+
+# ── departments & deviation categories ──────────────────────────────────────
+# No hard-delete endpoints exist by design: values referenced by existing
+# NCRs are only ever deactivated.
+@router.get("/departments", response_model=list[NamedLookupOut])
+async def list_departments(
+    _: CurrentUser = Depends(require_admin), db: AsyncSession = Depends(get_db)
+):
+    rows = (await db.execute(select(Department).order_by(Department.name))).scalars().all()
+    return [NamedLookupOut.model_validate(r) for r in rows]
+
+
+@router.post("/departments", response_model=NamedLookupOut, status_code=201)
+async def create_department(
+    payload: LookupCreateIn,
+    current: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    return await _create_lookup(Department, "Department", payload, current, db)
+
+
+@router.patch("/departments/{item_id}", response_model=NamedLookupOut)
+async def patch_department(
+    item_id: int,
+    payload: LookupPatchIn,
+    current: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    return await _patch_lookup(Department, "Department", item_id, payload, current, db)
+
+
+@router.get("/categories", response_model=list[NamedLookupOut])
+async def list_categories(
+    _: CurrentUser = Depends(require_admin), db: AsyncSession = Depends(get_db)
+):
+    rows = (
+        (await db.execute(select(DeviationCategory).order_by(DeviationCategory.name)))
+        .scalars()
+        .all()
+    )
+    return [NamedLookupOut.model_validate(r) for r in rows]
+
+
+@router.post("/categories", response_model=NamedLookupOut, status_code=201)
+async def create_category(
+    payload: LookupCreateIn,
+    current: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    return await _create_lookup(DeviationCategory, "Deviation category", payload, current, db)
+
+
+@router.patch("/categories/{item_id}", response_model=NamedLookupOut)
+async def patch_category(
+    item_id: int,
+    payload: LookupPatchIn,
+    current: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+):
+    return await _patch_lookup(
+        DeviationCategory, "Deviation category", item_id, payload, current, db
+    )
+
+
+async def _create_lookup(model, label, payload, current, db) -> NamedLookupOut:
+    exists = (
+        await db.execute(select(model).where(model.name == payload.name.strip()))
+    ).scalar_one_or_none()
+    if exists:
+        raise HTTPException(status_code=409, detail=f"{label} already exists.")
+    row = model(name=payload.name.strip(), is_active=True)
+    db.add(row)
+    audit_event(
+        db, user_id=current.id, action="lookup_create", field_name=label, new_value=payload.name
+    )
+    await db.commit()
+    await db.refresh(row)
+    return NamedLookupOut.model_validate(row)
+
+
+async def _patch_lookup(model, label, item_id, payload, current, db) -> NamedLookupOut:
+    row = await db.get(model, item_id)
+    if row is None:
+        raise HTTPException(status_code=404, detail=f"{label} not found.")
+    if payload.name is not None and payload.name.strip() != row.name:
+        audit_event(
+            db,
+            user_id=current.id,
+            action="lookup_rename",
+            field_name=label,
+            old_value=row.name,
+            new_value=payload.name.strip(),
+        )
+        row.name = payload.name.strip()
+    if payload.is_active is not None and payload.is_active != row.is_active:
+        audit_event(
+            db,
+            user_id=current.id,
+            action="lookup_active",
+            field_name=f"{label}: {row.name}",
+            old_value=row.is_active,
+            new_value=payload.is_active,
+        )
+        row.is_active = payload.is_active
+    await db.commit()
+    await db.refresh(row)
+    return NamedLookupOut.model_validate(row)
+
+
+# ── settings ─────────────────────────────────────────────────────────────────
+class SettingsOut(BaseModel):
+    notifications_enabled: bool
+
+
+@router.get("/settings", response_model=SettingsOut)
+async def get_admin_settings(
+    _: CurrentUser = Depends(require_admin), db: AsyncSession = Depends(get_db)
+) -> SettingsOut:
+    return SettingsOut(notifications_enabled=await notifications_enabled(db))
+
+
+@router.put("/settings", response_model=SettingsOut)
+async def put_admin_settings(
+    payload: SettingsOut,
+    current: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+) -> SettingsOut:
+    row = await db.get(AppSetting, NOTIFICATIONS_ENABLED_KEY)
+    old = await notifications_enabled(db)
+    if row is None:
+        row = AppSetting(
+            key=NOTIFICATIONS_ENABLED_KEY,
+            value="true" if payload.notifications_enabled else "false",
+        )
+        db.add(row)
+    else:
+        row.value = "true" if payload.notifications_enabled else "false"
+    if old != payload.notifications_enabled:
+        audit_event(
+            db,
+            user_id=current.id,
+            action="settings_update",
+            field_name=NOTIFICATIONS_ENABLED_KEY,
+            old_value=old,
+            new_value=payload.notifications_enabled,
+        )
+    await db.commit()
+    return SettingsOut(notifications_enabled=payload.notifications_enabled)
+
+
+# ── global audit log ─────────────────────────────────────────────────────────
+class GlobalAuditOut(BaseModel):
+    items: list[AuditEntryOut]
+    total: int
+    page: int
+    page_size: int
+
+
+@router.get("/audit", response_model=GlobalAuditOut)
+async def global_audit(
+    ncr_number: str | None = None,
+    action: str | None = None,
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=50, ge=1, le=200),
+    _: CurrentUser = Depends(require_admin),
+    db: AsyncSession = Depends(get_db),
+) -> GlobalAuditOut:
+    stmt = select(AuditLog)
+    if ncr_number:
+        stmt = stmt.where(
+            AuditLog.ncr_id.in_(
+                select(Ncr.id).where(Ncr.ncr_number.like(f"%{ncr_number.strip()}%"))
+            )
+        )
+    if action:
+        stmt = stmt.where(AuditLog.action == action)
+    total = (
+        await db.execute(select(func.count()).select_from(stmt.subquery()))
+    ).scalar_one()
+    rows = (
+        (
+            await db.execute(
+                stmt.order_by(AuditLog.created_at.desc(), AuditLog.id.desc())
+                .offset((page - 1) * page_size)
+                .limit(page_size)
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return GlobalAuditOut(
+        items=[AuditEntryOut.model_validate(r) for r in rows],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )

backend/app/routers/health.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+async def health() -> dict:
+    return {"status": "ok"}
+
+
+@router.get("/health/db")
+async def health_db(db: AsyncSession = Depends(get_db)) -> dict:
+    await db.execute(text("SELECT 1"))
+    return {"status": "ok", "database": "ok"}

backend/app/routers/jobs.py

@@ -0,0 +1,28 @@
+from fastapi import APIRouter, Depends
+
+from app.auth.deps import CurrentUser, get_current_user
+from app.services.job_lookup import get_job_lookup_service
+
+router = APIRouter(tags=["jobs"])
+
+
+@router.get("/jobs/{job_number}/lookup")
+async def lookup_job(
+    job_number: str,
+    _: CurrentUser = Depends(get_current_user),
+) -> dict:
+    """Job-number enrichment endpoint. Returns {found: false} under the
+    default NullJobLookupService; a future VisualJobLookupService will return
+    part/customer/work-order data from Infor VISUAL without frontend changes."""
+    info = await get_job_lookup_service().lookup(job_number)
+    if info is None:
+        return {"found": False, "job_number": job_number}
+    return {
+        "found": True,
+        "job_number": job_number,
+        "part_id": info.part_id,
+        "part_description": info.part_description,
+        "customer_name": info.customer_name,
+        "work_order_status": info.work_order_status,
+        "source": info.source,
+    }

backend/app/routers/lookups.py

@@ -0,0 +1,44 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.deps import CurrentUser, get_current_user
+from app.database import get_db
+from app.models import Department, DeviationCategory
+from app.schemas.lookup import LookupsOut, NamedLookupOut
+
+router = APIRouter(tags=["lookups"])
+
+
+@router.get("/lookups", response_model=LookupsOut)
+async def get_lookups(
+    _: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> LookupsOut:
+    """Active departments and deviation categories for form dropdowns."""
+    departments = (
+        (
+            await db.execute(
+                select(Department)
+                .where(Department.is_active.is_(True))
+                .order_by(Department.name)
+            )
+        )
+        .scalars()
+        .all()
+    )
+    categories = (
+        (
+            await db.execute(
+                select(DeviationCategory)
+                .where(DeviationCategory.is_active.is_(True))
+                .order_by(DeviationCategory.name)
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return LookupsOut(
+        departments=[NamedLookupOut.model_validate(d) for d in departments],
+        deviation_categories=[NamedLookupOut.model_validate(c) for c in categories],
+    )

backend/app/routers/ncrs.py

@@ -0,0 +1,866 @@
+"""NCR endpoints: creation, queues/search, stage actions (the workflow state
+machine), attachments, audit history, CSV export, and the printable PDF.
+
+Every stage action re-validates BOTH the caller's role and the NCR's current
+stage server-side; the frontend's `available_actions` hints are advisory only.
+"""
+import csv
+import io
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query, UploadFile
+from fastapi.responses import FileResponse, Response, StreamingResponse
+from sqlalchemy import delete, func, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.deps import CurrentUser, get_current_user, require_roles
+from app.database import get_db
+from app.domain import STAGE_LABELS, Role, Stage
+from app.models import (
+    Attachment,
+    Department,
+    DeviationCategory,
+    JobInfo,
+    Ncr,
+    NcrSecondaryAssignee,
+    User,
+    UserRole,
+)
+from app.models.base import utcnow
+from app.schemas.ncr import (
+    AttachmentOut,
+    AuditEntryOut,
+    AuditListOut,
+    CostingIn,
+    InitialDispositionIn,
+    InspectionIn,
+    JobInfoOut,
+    NcrCreateIn,
+    NcrDetailOut,
+    NcrListItem,
+    NcrListOut,
+    NcrMutationOut,
+    ReopenIn,
+    SecondaryDispositionIn,
+    TransitionOut,
+)
+from app.schemas.user import UserRef
+from app.services.audit import apply_field_updates, audit_event
+from app.services.job_lookup import get_job_lookup_service
+from app.services.notifications import NotifyEvent, send_stage_notification
+from app.services.numbering import allocate_ncr_number
+from app.services.sanitize import sanitize_html
+from app.services.storage import (
+    UploadValidationError,
+    attachment_abs_path,
+    save_attachment,
+)
+from app.services.workflow import InvalidTransitionError, record_creation, transition
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["ncrs"])
+
+_STAGE_ORDER = [
+    Stage.NEW_REQUEST,
+    Stage.SECONDARY_DISPOSITION,
+    Stage.OPERATIONS,
+    Stage.QC_INSPECTION,
+    Stage.COSTING,
+    Stage.CLOSED,
+]
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+async def _get_ncr(db: AsyncSession, ncr_id: int) -> Ncr:
+    ncr = await db.get(Ncr, ncr_id)
+    if ncr is None:
+        raise HTTPException(status_code=404, detail="NCR not found.")
+    return ncr
+
+
+def _days_in_stage(ncr: Ncr) -> int:
+    return max(0, (utcnow() - ncr.stage_entered_at).days)
+
+
+def _ensure_stage(ncr: Ncr, expected: Stage) -> None:
+    if ncr.stage == Stage.CLOSED.value and expected != Stage.CLOSED:
+        raise HTTPException(
+            status_code=409,
+            detail=f"{ncr.ncr_number} is closed and locked. Only an Admin can reopen it.",
+        )
+    if ncr.stage != expected.value:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                f"{ncr.ncr_number} is in stage '{STAGE_LABELS[Stage(ncr.stage)]}', "
+                f"but this action requires '{STAGE_LABELS[expected]}'."
+            ),
+        )
+
+
+def _is_secondary_assignee(ncr: Ncr, current: CurrentUser) -> bool:
+    return any(row.user_id == current.id for row in ncr.secondary_assignee_rows)
+
+
+def _available_actions(ncr: Ncr, current: CurrentUser) -> list[str]:
+    actions: list[str] = []
+    stage = Stage(ncr.stage)
+    if stage == Stage.NEW_REQUEST and current.has_role(Role.DISPOSITION_AUTHORITY):
+        actions.append("initial_disposition")
+    if stage == Stage.SECONDARY_DISPOSITION and (
+        current.is_admin or _is_secondary_assignee(ncr, current)
+    ):
+        actions.append("secondary_disposition")
+    if stage == Stage.OPERATIONS and current.has_role(Role.OPERATIONS):
+        actions.append("operations_complete")
+    if stage == Stage.QC_INSPECTION and current.has_role(Role.QC_INSPECTOR):
+        actions.append("inspection")
+    if stage == Stage.COSTING and current.has_role(Role.COSTING):
+        actions.append("costing")
+    if stage == Stage.CLOSED and current.is_admin:
+        actions.append("reopen")
+    if stage != Stage.CLOSED:
+        actions.append("add_attachment")
+    if current.has_role(Role.QC_INSPECTOR):  # admins pass automatically
+        actions.append("view_audit")
+    return actions
+
+
+def _detail(ncr: Ncr, current: CurrentUser) -> NcrDetailOut:
+    stage = Stage(ncr.stage)
+    return NcrDetailOut(
+        id=ncr.id,
+        ncr_number=ncr.ncr_number,
+        job_number=ncr.job_number,
+        created_at=ncr.created_at,
+        stage=stage.value,
+        stage_label=STAGE_LABELS[stage],
+        stage_entered_at=ncr.stage_entered_at,
+        days_in_stage=_days_in_stage(ncr),
+        department=ncr.department.name,
+        department_id=ncr.department_id,
+        deviation_category=ncr.deviation_category.name,
+        deviation_category_id=ncr.deviation_category_id,
+        deviation_detail=ncr.deviation_detail,
+        requester=UserRef.model_validate(ncr.requester),
+        disposition_authority=UserRef.model_validate(ncr.disposition_authority),
+        qc_authority=ncr.qc_authority,
+        work_order=ncr.work_order,
+        disposition_notes=ncr.disposition_notes,
+        secondary_review_needed=ncr.secondary_review_needed,
+        secondary_authorities=[
+            UserRef.model_validate(u) for u in ncr.secondary_authorities
+        ],
+        operations_complete=ncr.operations_complete,
+        operations_completed_at=ncr.operations_completed_at,
+        operations_completed_by=(
+            UserRef.model_validate(ncr.operations_completed_by)
+            if ncr.operations_completed_by
+            else None
+        ),
+        qc_approval=ncr.qc_approval,
+        inspection_notes=ncr.inspection_notes,
+        qc_closed=ncr.qc_closed,
+        qc_closed_at=ncr.qc_closed_at,
+        qc_closed_by=(
+            UserRef.model_validate(ncr.qc_closed_by) if ncr.qc_closed_by else None
+        ),
+        labor_cost=ncr.labor_cost,
+        material_cost=ncr.material_cost,
+        service_cost=ncr.service_cost,
+        other_cost=ncr.other_cost,
+        total_cost=ncr.total_cost,
+        costing_completed_at=ncr.costing_completed_at,
+        costing_completed_by=(
+            UserRef.model_validate(ncr.costing_completed_by)
+            if ncr.costing_completed_by
+            else None
+        ),
+        closed_at=ncr.closed_at,
+        closed_by=UserRef.model_validate(ncr.closed_by) if ncr.closed_by else None,
+        job_info=JobInfoOut.model_validate(ncr.job_info) if ncr.job_info else None,
+        attachments=[AttachmentOut.model_validate(a) for a in ncr.attachments],
+        transitions=[TransitionOut.model_validate(t) for t in ncr.transitions],
+        available_actions=_available_actions(ncr, current),
+    )
+
+
+async def _refetch(db: AsyncSession, ncr_id: int) -> Ncr:
+    """Reload the NCR with fresh relationship collections after a commit."""
+    db.expire_all()
+    return await _get_ncr(db, ncr_id)
+
+
+# ── create ───────────────────────────────────────────────────────────────────
+@router.post("/ncrs", response_model=NcrMutationOut, status_code=201)
+async def create_ncr(
+    payload: NcrCreateIn,
+    current: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> NcrMutationOut:
+    """Stage 1 — New Request. Open to every authenticated user."""
+    dept = await db.get(Department, payload.department_id)
+    if dept is None or not dept.is_active:
+        raise HTTPException(status_code=422, detail="Unknown or inactive department.")
+    cat = await db.get(DeviationCategory, payload.deviation_category_id)
+    if cat is None or not cat.is_active:
+        raise HTTPException(status_code=422, detail="Unknown or inactive deviation category.")
+    authority = await db.get(User, payload.disposition_authority_id)
+    if (
+        authority is None
+        or not authority.is_active
+        or Role.DISPOSITION_AUTHORITY.value not in authority.roles
+    ):
+        raise HTTPException(
+            status_code=422,
+            detail="Selected disposition authority does not hold the Disposition Authority role.",
+        )
+
+    # External enrichment BEFORE the numbering lock so a slow ERP lookup can
+    # never serialize submissions. NullJobLookupService returns instantly.
+    job_info_data = None
+    try:
+        job_info_data = await get_job_lookup_service().lookup(payload.job_number)
+    except Exception:
+        logger.exception("Job lookup failed for %s (non-blocking)", payload.job_number)
+
+    ncr_number, year, seq = await allocate_ncr_number(db)
+    ncr = Ncr(
+        ncr_number=ncr_number,
+        ncr_year=year,
+        ncr_seq=seq,
+        job_number=payload.job_number.strip(),
+        department_id=payload.department_id,
+        deviation_category_id=payload.deviation_category_id,
+        disposition_authority_id=payload.disposition_authority_id,
+        deviation_detail=payload.deviation_detail,
+        requester_id=current.id,
+        stage=Stage.NEW_REQUEST.value,
+    )
+    db.add(ncr)
+    await db.flush()
+    record_creation(db, ncr, current.id)
+    if job_info_data is not None:
+        db.add(
+            JobInfo(
+                ncr_id=ncr.id,
+                part_id=job_info_data.part_id,
+                part_description=job_info_data.part_description,
+                customer_name=job_info_data.customer_name,
+                work_order_status=job_info_data.work_order_status,
+                source=job_info_data.source,
+            )
+        )
+    await db.commit()
+
+    ncr = await _refetch(db, ncr.id)
+    warnings = await send_stage_notification(
+        db,
+        ncr,
+        NotifyEvent.CREATED,
+        current,
+        f"{current.user.display_name} submitted a new NCR and selected you as the "
+        "disposition authority.",
+    )
+    return NcrMutationOut(ncr=_detail(ncr, current), warnings=warnings)
+
+
+# ── queues / search / export ────────────────────────────────────────────────
+def _apply_filters(
+    stmt,
+    *,
+    q: str | None,
+    job_number: str | None,
+    department_id: int | None,
+    category_id: int | None,
+    stage: str | None,
+    date_from: str | None,
+    date_to: str | None,
+    disposition_authority_id: int | None,
+):
+    if q:
+        like = f"%{q.strip()}%"
+        stmt = stmt.where(or_(Ncr.ncr_number.like(like), Ncr.job_number.like(like)))
+    if job_number:
+        stmt = stmt.where(Ncr.job_number.like(f"%{job_number.strip()}%"))
+    if department_id:
+        stmt = stmt.where(Ncr.department_id == department_id)
+    if category_id:
+        stmt = stmt.where(Ncr.deviation_category_id == category_id)
+    if stage:
+        stmt = stmt.where(Ncr.stage == stage)
+    if date_from:
+        stmt = stmt.where(Ncr.created_at >= date_from)
+    if date_to:
+        stmt = stmt.where(Ncr.created_at <= f"{date_to} 23:59:59")
+    if disposition_authority_id:
+        stmt = stmt.where(Ncr.disposition_authority_id == disposition_authority_id)
+    return stmt
+
+
+def _queue_filter(stmt, queue: str, current: CurrentUser):
+    if queue == "my_requests":
+        return stmt.where(Ncr.requester_id == current.id)
+    if queue == "new_requests":
+        return stmt.where(Ncr.stage == Stage.NEW_REQUEST.value)
+    if queue == "secondary":
+        return stmt.where(
+            Ncr.stage == Stage.SECONDARY_DISPOSITION.value,
+            Ncr.id.in_(
+                select(NcrSecondaryAssignee.ncr_id).where(
+                    NcrSecondaryAssignee.user_id == current.id
+                )
+            ),
+        )
+    if queue == "operations":
+        return stmt.where(Ncr.stage == Stage.OPERATIONS.value)
+    if queue == "inspection":
+        return stmt.where(Ncr.stage == Stage.QC_INSPECTION.value)
+    if queue == "costing":
+        return stmt.where(Ncr.stage == Stage.COSTING.value)
+    if queue == "recently_closed":
+        return stmt.where(Ncr.stage == Stage.CLOSED.value)
+    if queue in ("all", ""):
+        return stmt
+    raise HTTPException(status_code=422, detail=f"Unknown queue '{queue}'.")
+
+
+def _list_item(ncr: Ncr) -> NcrListItem:
+    return NcrListItem(
+        id=ncr.id,
+        ncr_number=ncr.ncr_number,
+        job_number=ncr.job_number,
+        department=ncr.department.name,
+        deviation_category=ncr.deviation_category.name,
+        requester=ncr.requester.display_name,
+        disposition_authority=ncr.disposition_authority.display_name,
+        stage=ncr.stage,
+        stage_label=STAGE_LABELS[Stage(ncr.stage)],
+        days_in_stage=_days_in_stage(ncr),
+        created_at=ncr.created_at,
+    )
+
+
+@router.get("/ncrs", response_model=NcrListOut)
+async def list_ncrs(
+    queue: str = Query(default="all"),
+    q: str | None = None,
+    job_number: str | None = None,
+    department_id: int | None = None,
+    category_id: int | None = None,
+    stage: str | None = None,
+    date_from: str | None = Query(default=None, description="YYYY-MM-DD"),
+    date_to: str | None = Query(default=None, description="YYYY-MM-DD"),
+    disposition_authority_id: int | None = None,
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=25, ge=1, le=200),
+    current: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> NcrListOut:
+    stmt = select(Ncr)
+    stmt = _queue_filter(stmt, queue, current)
+    stmt = _apply_filters(
+        stmt,
+        q=q,
+        job_number=job_number,
+        department_id=department_id,
+        category_id=category_id,
+        stage=stage,
+        date_from=date_from,
+        date_to=date_to,
+        disposition_authority_id=disposition_authority_id,
+    )
+    total = (
+        await db.execute(select(func.count()).select_from(stmt.subquery()))
+    ).scalar_one()
+    order = Ncr.closed_at.desc() if queue == "recently_closed" else Ncr.created_at.desc()
+    rows = (
+        (await db.execute(stmt.order_by(order).offset((page - 1) * page_size).limit(page_size)))
+        .scalars()
+        .unique()
+        .all()
+    )
+    return NcrListOut(
+        items=[_list_item(n) for n in rows], total=total, page=page, page_size=page_size
+    )
+
+
+_CSV_COLUMNS = [
+    "ncr_number", "job_number", "department", "deviation_category", "requester",
+    "disposition_authority", "stage", "days_in_stage", "created_at", "work_order",
+    "qc_authority", "secondary_review_needed", "operations_complete", "qc_approval",
+    "qc_closed", "labor_cost", "material_cost", "service_cost", "other_cost",
+    "total_cost", "closed_at",
+]
+
+
+@router.get("/ncrs/export.csv")
+async def export_ncrs_csv(
+    queue: str = Query(default="all"),
+    q: str | None = None,
+    job_number: str | None = None,
+    department_id: int | None = None,
+    category_id: int | None = None,
+    stage: str | None = None,
+    date_from: str | None = None,
+    date_to: str | None = None,
+    disposition_authority_id: int | None = None,
+    current: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> StreamingResponse:
+    """CSV export of any queue/search view (same filters as GET /ncrs)."""
+    stmt = select(Ncr)
+    stmt = _queue_filter(stmt, queue, current)
+    stmt = _apply_filters(
+        stmt,
+        q=q,
+        job_number=job_number,
+        department_id=department_id,
+        category_id=category_id,
+        stage=stage,
+        date_from=date_from,
+        date_to=date_to,
+        disposition_authority_id=disposition_authority_id,
+    )
+    rows = (
+        (await db.execute(stmt.order_by(Ncr.created_at.desc()).limit(20000)))
+        .scalars()
+        .unique()
+        .all()
+    )
+
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow(_CSV_COLUMNS)
+    for n in rows:
+        writer.writerow(
+            [
+                n.ncr_number, n.job_number, n.department.name, n.deviation_category.name,
+                n.requester.display_name, n.disposition_authority.display_name,
+                STAGE_LABELS[Stage(n.stage)], _days_in_stage(n),
+                n.created_at.isoformat(sep=" "), n.work_order or "", n.qc_authority or "",
+                n.secondary_review_needed, n.operations_complete, n.qc_approval or "",
+                n.qc_closed, n.labor_cost or "", n.material_cost or "",
+                n.service_cost or "", n.other_cost or "", n.total_cost or "",
+                n.closed_at.isoformat(sep=" ") if n.closed_at else "",
+            ]
+        )
+    buf.seek(0)
+    return StreamingResponse(
+        iter([buf.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": 'attachment; filename="ncr-export.csv"'},
+    )
+
+
+@router.get("/ncrs/{ncr_id}", response_model=NcrDetailOut)
+async def get_ncr(
+    ncr_id: int,
+    current: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> NcrDetailOut:
+    ncr = await _get_ncr(db, ncr_id)
+    return _detail(ncr, current)
+
+
+# ── stage actions ────────────────────────────────────────────────────────────
+@router.post("/ncrs/{ncr_id}/initial-disposition", response_model=NcrMutationOut)
+async def initial_disposition(
+    ncr_id: int,
+    payload: InitialDispositionIn,
+    current: CurrentUser = Depends(require_roles(Role.DISPOSITION_AUTHORITY)),
+    db: AsyncSession = Depends(get_db),
+) -> NcrMutationOut:
+    """Stage 2 — Initial Disposition, performed on a New Request. Routes to
+    Secondary Disposition (when secondary review is needed) or Operations."""
+    ncr = await _get_ncr(db, ncr_id)
+    _ensure_stage(ncr, Stage.NEW_REQUEST)
+
+    assignees: list[User] = []
+    if payload.secondary_review_needed:
+        if not payload.secondary_authority_ids:
+            raise HTTPException(
+                status_code=422,
+                detail="Secondary review requires at least one person in 'Notify These People'.",
+            )
+        for uid in set(payload.secondary_authority_ids):
+            u = await db.get(User, uid)
+            if (
+                u is None
+                or not u.is_active
+                or Role.SECONDARY_DISPOSITION_AUTHORITY.value not in u.roles
+            ):
+                raise HTTPException(
+                    status_code=422,
+                    detail="All selected people must hold the Secondary Disposition Authority role.",
+                )
+            assignees.append(u)
+
+    updates = payload.model_dump(exclude_unset=True, exclude={"secondary_authority_ids"})
+    if "disposition_notes" in updates:
+        updates["disposition_notes"] = sanitize_html(updates["disposition_notes"])
+    updates["secondary_review_needed"] = payload.secondary_review_needed
+    apply_field_updates(db, ncr, current.id, updates, action="initial_disposition")
+
+    if payload.secondary_review_needed:
+        await db.execute(
+            delete(NcrSecondaryAssignee).where(NcrSecondaryAssignee.ncr_id == ncr.id)
+        )
+        for u in assignees:
+            db.add(NcrSecondaryAssignee(ncr_id=ncr.id, user_id=u.id))
+        audit_event(
+            db,
+            ncr_id=ncr.id,
+            user_id=current.id,
+            action="initial_disposition",
+            field_name="secondary_authorities",
+            new_value=", ".join(u.display_name for u in assignees),
+        )
+        _do_transition(db, ncr, Stage.SECONDARY_DISPOSITION, "initial_disposition", current)
+        event, summary = (
+            NotifyEvent.SECONDARY_ASSIGNED,
+            f"{current.user.display_name} completed initial disposition and assigned "
+            "you for secondary disposition review.",
+        )
+    else:
+        _do_transition(db, ncr, Stage.OPERATIONS, "initial_disposition", current)
+        event, summary = (
+            NotifyEvent.RELEASED_TO_OPERATIONS,
+            f"{current.user.display_name} completed initial disposition; the NCR is "
+            "ready for Operations.",
+        )
+
+    await db.commit()
+    ncr = await _refetch(db, ncr.id)
+    warnings = await send_stage_notification(db, ncr, event, current, summary)
+    return NcrMutationOut(ncr=_detail(ncr, current), warnings=warnings)
+
+
+@router.post("/ncrs/{ncr_id}/secondary-disposition", response_model=NcrMutationOut)
+async def secondary_disposition(
+    ncr_id: int,
+    payload: SecondaryDispositionIn,
+    current: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> NcrMutationOut:
+    """Stage 3 — Secondary Disposition. Only the assigned secondary
+    authorities (or an Admin) may update or release to Operations."""
+    ncr = await _get_ncr(db, ncr_id)
+    _ensure_stage(ncr, Stage.SECONDARY_DISPOSITION)
+    if not (current.is_admin or _is_secondary_assignee(ncr, current)):
+        raise HTTPException(
+            status_code=403,
+            detail="Only the assigned secondary disposition authority can act on this NCR.",
+        )
+
+    updates = payload.model_dump(exclude_unset=True, exclude={"release"})
+    if "disposition_notes" in updates:
+        updates["disposition_notes"] = sanitize_html(updates["disposition_notes"])
+    apply_field_updates(db, ncr, current.id, updates, action="secondary_disposition")
+
+    warnings: list[str] = []
+    if payload.release:
+        _do_transition(db, ncr, Stage.OPERATIONS, "secondary_release", current)
+        await db.commit()
+        ncr = await _refetch(db, ncr.id)
+        warnings = await send_stage_notification(
+            db,
+            ncr,
+            NotifyEvent.RELEASED_TO_OPERATIONS,
+            current,
+            f"{current.user.display_name} completed secondary disposition review and "
+            "released the NCR to Operations.",
+        )
+    else:
+        await db.commit()
+        ncr = await _refetch(db, ncr.id)
+    return NcrMutationOut(ncr=_detail(ncr, current), warnings=warnings)
+
+
+@router.post("/ncrs/{ncr_id}/operations-complete", response_model=NcrMutationOut)
+async def operations_complete(
+    ncr_id: int,
+    current: CurrentUser = Depends(require_roles(Role.OPERATIONS)),
+    db: AsyncSession = Depends(get_db),
+) -> NcrMutationOut:
+    """Stage 4 — Operations marks rework complete; NCR moves to QC Inspection."""
+    ncr = await _get_ncr(db, ncr_id)
+    _ensure_stage(ncr, Stage.OPERATIONS)
+
+    apply_field_updates(
+        db,
+        ncr,
+        current.id,
+        {
+            "operations_complete": True,
+            "operations_completed_at": utcnow(),
+            "operations_completed_by_id": current.id,
+        },
+        action="operations_complete",
+    )
+    _do_transition(db, ncr, Stage.QC_INSPECTION, "operations_complete", current)
+    await db.commit()
+    ncr = await _refetch(db, ncr.id)
+    warnings = await send_stage_notification(
+        db,
+        ncr,
+        NotifyEvent.OPERATIONS_COMPLETE,
+        current,
+        f"{current.user.display_name} marked operations complete; the NCR is ready "
+        "for QC inspection.",
+    )
+    return NcrMutationOut(ncr=_detail(ncr, current), warnings=warnings)
+
+
+@router.post("/ncrs/{ncr_id}/inspection", response_model=NcrMutationOut)
+async def inspection(
+    ncr_id: int,
+    payload: InspectionIn,
+    current: CurrentUser = Depends(require_roles(Role.QC_INSPECTOR)),
+    db: AsyncSession = Depends(get_db),
+) -> NcrMutationOut:
+    """Stage 5 — QC Inspection. QC can save repeatedly; checking QC Closed
+    advances the NCR to Costing."""
+    ncr = await _get_ncr(db, ncr_id)
+    _ensure_stage(ncr, Stage.QC_INSPECTION)
+
+    updates = payload.model_dump(exclude_unset=True, exclude={"qc_closed"})
+    if payload.qc_closed:
+        updates.update(
+            {"qc_closed": True, "qc_closed_at": utcnow(), "qc_closed_by_id": current.id}
+        )
+    apply_field_updates(db, ncr, current.id, updates, action="inspection")
+
+    warnings: list[str] = []
+    if payload.qc_closed:
+        _do_transition(db, ncr, Stage.COSTING, "qc_close", current)
+        await db.commit()
+        ncr = await _refetch(db, ncr.id)
+        warnings = await send_stage_notification(
+            db,
+            ncr,
+            NotifyEvent.QC_CLOSED,
+            current,
+            f"{current.user.display_name} closed QC inspection; the NCR is awaiting costing.",
+        )
+    else:
+        await db.commit()
+        ncr = await _refetch(db, ncr.id)
+    return NcrMutationOut(ncr=_detail(ncr, current), warnings=warnings)
+
+
+@router.post("/ncrs/{ncr_id}/costing", response_model=NcrMutationOut)
+async def costing(
+    ncr_id: int,
+    payload: CostingIn,
+    current: CurrentUser = Depends(require_roles(Role.COSTING)),
+    db: AsyncSession = Depends(get_db),
+) -> NcrMutationOut:
+    """Stage 6 — Costing. Saving costs completes the workflow and closes the NCR."""
+    ncr = await _get_ncr(db, ncr_id)
+    _ensure_stage(ncr, Stage.COSTING)
+
+    now = utcnow()
+    apply_field_updates(
+        db,
+        ncr,
+        current.id,
+        {
+            "labor_cost": payload.labor_cost,
+            "material_cost": payload.material_cost,
+            "service_cost": payload.service_cost,
+            "other_cost": payload.other_cost,
+            "costing_completed_at": now,
+            "costing_completed_by_id": current.id,
+            "closed_at": now,
+            "closed_by_id": current.id,
+        },
+        action="costing",
+    )
+    _do_transition(db, ncr, Stage.CLOSED, "complete_costing", current)
+    await db.commit()
+    ncr = await _refetch(db, ncr.id)
+    warnings = await send_stage_notification(
+        db,
+        ncr,
+        NotifyEvent.CLOSED,
+        current,
+        f"Costing is complete and your NCR has been closed. Total cost of "
+        f"nonconformance: ${ncr.total_cost:,.2f}.",
+    )
+    return NcrMutationOut(ncr=_detail(ncr, current), warnings=warnings)
+
+
+@router.post("/ncrs/{ncr_id}/reopen", response_model=NcrMutationOut)
+async def reopen(
+    ncr_id: int,
+    payload: ReopenIn,
+    current: CurrentUser = Depends(require_roles(Role.ADMIN)),
+    db: AsyncSession = Depends(get_db),
+) -> NcrMutationOut:
+    """Admin-only: reopen a closed NCR into a chosen prior stage. The reason
+    is required and recorded in the audit trail and transition history."""
+    ncr = await _get_ncr(db, ncr_id)
+    if ncr.stage != Stage.CLOSED.value:
+        raise HTTPException(status_code=409, detail="Only closed NCRs can be reopened.")
+    if payload.to_stage == Stage.SECONDARY_DISPOSITION and not ncr.secondary_assignee_rows:
+        raise HTTPException(
+            status_code=422,
+            detail="This NCR has no secondary authorities assigned; reopen it to "
+            "New Request so a disposition authority can assign them.",
+        )
+
+    target_idx = _STAGE_ORDER.index(payload.to_stage)
+    resets: dict = {"closed_at": None, "closed_by_id": None}
+    if target_idx <= _STAGE_ORDER.index(Stage.OPERATIONS):
+        resets.update(
+            {
+                "operations_complete": False,
+                "operations_completed_at": None,
+                "operations_completed_by_id": None,
+            }
+        )
+    if target_idx <= _STAGE_ORDER.index(Stage.QC_INSPECTION):
+        resets.update({"qc_closed": False, "qc_closed_at": None, "qc_closed_by_id": None})
+    if target_idx <= _STAGE_ORDER.index(Stage.COSTING):
+        resets.update({"costing_completed_at": None, "costing_completed_by_id": None})
+    apply_field_updates(db, ncr, current.id, resets, action="reopen")
+    _do_transition(
+        db, ncr, payload.to_stage, "reopen", current, note=f"Reopen reason: {payload.reason}"
+    )
+    await db.commit()
+    ncr = await _refetch(db, ncr.id)
+    warnings = await send_stage_notification(
+        db,
+        ncr,
+        NotifyEvent.REOPENED,
+        current,
+        f"{current.user.display_name} reopened this NCR to "
+        f"'{STAGE_LABELS[payload.to_stage]}'. Reason: {payload.reason}",
+    )
+    return NcrMutationOut(ncr=_detail(ncr, current), warnings=warnings)
+
+
+def _do_transition(
+    db: AsyncSession,
+    ncr: Ncr,
+    to_stage: Stage,
+    action: str,
+    current: CurrentUser,
+    note: str | None = None,
+) -> None:
+    try:
+        transition(db, ncr, to_stage, action=action, actor_id=current.id, note=note)
+    except InvalidTransitionError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+
+
+# ── attachments ──────────────────────────────────────────────────────────────
+@router.post("/ncrs/{ncr_id}/attachments", response_model=list[AttachmentOut], status_code=201)
+async def upload_attachments(
+    ncr_id: int,
+    files: list[UploadFile],
+    current: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> list[AttachmentOut]:
+    """Photo/file attachments (multiple per request; camera capture on
+    tablets posts here too). Blocked once the NCR is closed."""
+    ncr = await _get_ncr(db, ncr_id)
+    if ncr.stage == Stage.CLOSED.value:
+        raise HTTPException(
+            status_code=409, detail="This NCR is closed; attachments are locked."
+        )
+    if not files:
+        raise HTTPException(status_code=422, detail="No files provided.")
+
+    saved: list[Attachment] = []
+    for f in files:
+        try:
+            meta = await save_attachment(f, ncr.id)
+        except UploadValidationError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        att = Attachment(ncr_id=ncr.id, uploaded_by_id=current.id, **meta)
+        db.add(att)
+        audit_event(
+            db,
+            ncr_id=ncr.id,
+            user_id=current.id,
+            action="attachment_add",
+            field_name="attachments",
+            new_value=meta["original_filename"],
+            detail=f"{meta['size_bytes']} bytes, {meta['content_type']}",
+        )
+        saved.append(att)
+    await db.commit()
+    for att in saved:
+        await db.refresh(att)
+    return [AttachmentOut.model_validate(a) for a in saved]
+
+
+@router.get("/attachments/{attachment_id}/download")
+async def download_attachment(
+    attachment_id: int,
+    _: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> FileResponse:
+    att = await db.get(Attachment, attachment_id)
+    if att is None:
+        raise HTTPException(status_code=404, detail="Attachment not found.")
+    path = attachment_abs_path(att.stored_path)
+    if not path.is_file():
+        raise HTTPException(status_code=404, detail="Attachment file missing from storage.")
+    return FileResponse(
+        path,
+        media_type=att.content_type,
+        filename=att.original_filename,
+        content_disposition_type="inline" if att.is_image else "attachment",
+    )
+
+
+# ── audit history ────────────────────────────────────────────────────────────
+@router.get("/ncrs/{ncr_id}/audit", response_model=AuditListOut)
+async def ncr_audit(
+    ncr_id: int,
+    current: CurrentUser = Depends(require_roles(Role.QC_INSPECTOR)),
+    db: AsyncSession = Depends(get_db),
+) -> AuditListOut:
+    """Audit History tab — Admin and QC roles."""
+    from app.models import AuditLog
+
+    await _get_ncr(db, ncr_id)
+    rows = (
+        (
+            await db.execute(
+                select(AuditLog)
+                .where(AuditLog.ncr_id == ncr_id)
+                .order_by(AuditLog.created_at.desc(), AuditLog.id.desc())
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return AuditListOut(
+        items=[AuditEntryOut.model_validate(r) for r in rows], total=len(rows)
+    )
+
+
+# ── printable PDF ────────────────────────────────────────────────────────────
+@router.get("/ncrs/{ncr_id}/pdf")
+async def ncr_pdf(
+    ncr_id: int,
+    current: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Response:
+    """Clean single-document rendering of the complete NCR for hard-copy
+    travelers and audits."""
+    from app.services.pdf import render_ncr_pdf
+
+    ncr = await _get_ncr(db, ncr_id)
+    pdf_bytes = await render_ncr_pdf(ncr)
+    return Response(
+        content=pdf_bytes,
+        media_type="application/pdf",
+        headers={
+            "Content-Disposition": f'inline; filename="{ncr.ncr_number}.pdf"'
+        },
+    )

backend/app/routers/reports.py

@@ -0,0 +1,185 @@
+"""Built-in reports: counts, cost of nonconformance, aging, cycle times,
+top jobs. All queries respect the shared date-range/department/category
+filters."""
+from collections import defaultdict
+from decimal import Decimal
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.deps import CurrentUser, get_current_user
+from app.database import get_db
+from app.domain import STAGE_LABELS, Stage
+from app.models import Department, DeviationCategory, Ncr, StageTransition
+from app.models.base import utcnow
+from app.schemas.report import (
+    AgingBucket,
+    CostByMonth,
+    CountByMonth,
+    CountByName,
+    ReportsSummaryOut,
+    StageCycleTime,
+    TopJob,
+)
+
+router = APIRouter(tags=["reports"])
+
+_AGING_BUCKETS = [(0, 7, "0–7 days"), (8, 14, "8–14 days"), (15, 30, "15–30 days"),
+                  (31, 60, "31–60 days"), (61, None, "60+ days")]
+
+
+def _base_filters(stmt, date_from, date_to, department_id, category_id):
+    if date_from:
+        stmt = stmt.where(Ncr.created_at >= date_from)
+    if date_to:
+        stmt = stmt.where(Ncr.created_at <= f"{date_to} 23:59:59")
+    if department_id:
+        stmt = stmt.where(Ncr.department_id == department_id)
+    if category_id:
+        stmt = stmt.where(Ncr.deviation_category_id == category_id)
+    return stmt
+
+
+@router.get("/reports/summary", response_model=ReportsSummaryOut)
+async def reports_summary(
+    date_from: str | None = Query(default=None, description="YYYY-MM-DD"),
+    date_to: str | None = Query(default=None, description="YYYY-MM-DD"),
+    department_id: int | None = None,
+    category_id: int | None = None,
+    _: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> ReportsSummaryOut:
+    filters = dict(
+        date_from=date_from,
+        date_to=date_to,
+        department_id=department_id,
+        category_id=category_id,
+    )
+
+    # Load the filtered NCR set once; aggregate in Python. NCR volume is a few
+    # thousand rows a year, so this stays cheap and keeps the SQL portable.
+    ncrs = (
+        (await db.execute(_base_filters(select(Ncr), **filters))).scalars().unique().all()
+    )
+
+    dept_names = {
+        d.id: d.name for d in (await db.execute(select(Department))).scalars().all()
+    }
+    cat_names = {
+        c.id: c.name
+        for c in (await db.execute(select(DeviationCategory))).scalars().all()
+    }
+
+    by_dept: dict[str, int] = defaultdict(int)
+    by_cat: dict[str, int] = defaultdict(int)
+    by_month: dict[str, int] = defaultdict(int)
+    cost_by_month: dict[str, dict[str, Decimal]] = defaultdict(
+        lambda: {"labor": Decimal(0), "material": Decimal(0), "service": Decimal(0), "other": Decimal(0)}
+    )
+    aging_counts: dict[str, int] = {label: 0 for _, _, label in _AGING_BUCKETS}
+    job_counts: dict[str, int] = defaultdict(int)
+    total_cost = Decimal(0)
+    open_count = 0
+    closed_count = 0
+    now = utcnow()
+
+    for n in ncrs:
+        by_dept[dept_names.get(n.department_id, "?")] += 1
+        by_cat[cat_names.get(n.deviation_category_id, "?")] += 1
+        by_month[n.created_at.strftime("%Y-%m")] += 1
+        job_counts[n.job_number] += 1
+        if n.stage == Stage.CLOSED.value:
+            closed_count += 1
+            month = (n.closed_at or n.created_at).strftime("%Y-%m")
+            bucket = cost_by_month[month]
+            bucket["labor"] += n.labor_cost or 0
+            bucket["material"] += n.material_cost or 0
+            bucket["service"] += n.service_cost or 0
+            bucket["other"] += n.other_cost or 0
+            total_cost += n.total_cost or 0
+        else:
+            open_count += 1
+            days = max(0, (now - n.stage_entered_at).days)
+            for lo, hi, label in _AGING_BUCKETS:
+                if days >= lo and (hi is None or days <= hi):
+                    aging_counts[label] += 1
+                    break
+
+    # ── cycle times from the transition history ─────────────────────────────
+    ncr_ids = [n.id for n in ncrs]
+    stage_durations: dict[str, list[float]] = defaultdict(list)
+    end_to_end: list[float] = []
+    if ncr_ids:
+        transitions = (
+            (
+                await db.execute(
+                    select(StageTransition)
+                    .where(StageTransition.ncr_id.in_(ncr_ids))
+                    .order_by(StageTransition.ncr_id, StageTransition.acted_at)
+                )
+            )
+            .scalars()
+            .all()
+        )
+        per_ncr: dict[int, list[StageTransition]] = defaultdict(list)
+        for t in transitions:
+            per_ncr[t.ncr_id].append(t)
+        for items in per_ncr.values():
+            for prev, nxt in zip(items, items[1:]):
+                delta_days = (nxt.acted_at - prev.acted_at).total_seconds() / 86400
+                stage_durations[prev.to_stage].append(delta_days)
+            first, last = items[0], items[-1]
+            if last.to_stage == Stage.CLOSED.value:
+                end_to_end.append(
+                    (last.acted_at - first.acted_at).total_seconds() / 86400
+                )
+
+    cycle_times = [
+        StageCycleTime(
+            stage=s.value,
+            stage_label=STAGE_LABELS[s],
+            avg_days=round(sum(v) / len(v), 2),
+            samples=len(v),
+        )
+        for s in Stage
+        if s != Stage.CLOSED and (v := stage_durations.get(s.value))
+    ]
+
+    months = sorted(set(by_month) | set(cost_by_month))
+    return ReportsSummaryOut(
+        total_ncrs=len(ncrs),
+        open_ncrs=open_count,
+        closed_ncrs=closed_count,
+        total_cost=total_cost,
+        by_department=sorted(
+            (CountByName(name=k, count=v) for k, v in by_dept.items()),
+            key=lambda x: -x.count,
+        ),
+        by_category=sorted(
+            (CountByName(name=k, count=v) for k, v in by_cat.items()),
+            key=lambda x: -x.count,
+        ),
+        by_month=[CountByMonth(month=m, count=by_month.get(m, 0)) for m in months],
+        cost_over_time=[
+            CostByMonth(
+                month=m,
+                labor=c["labor"],
+                material=c["material"],
+                service=c["service"],
+                other=c["other"],
+                total=c["labor"] + c["material"] + c["service"] + c["other"],
+            )
+            for m in months
+            if (c := cost_by_month.get(m))
+        ],
+        aging=[AgingBucket(bucket=label, count=aging_counts[label]) for _, _, label in _AGING_BUCKETS],
+        cycle_times=cycle_times,
+        end_to_end_avg_days=(
+            round(sum(end_to_end) / len(end_to_end), 2) if end_to_end else None
+        ),
+        top_jobs=sorted(
+            (TopJob(job_number=j, count=c) for j, c in job_counts.items()),
+            key=lambda x: -x.count,
+        )[:10],
+    )

backend/app/routers/users.py

@@ -0,0 +1,55 @@
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.deps import CurrentUser, get_current_user
+from app.config import get_settings
+from app.database import get_db
+from app.domain import ALL_ROLES
+from app.models import User, UserRole
+from app.schemas.user import MeOut, UserOut
+
+router = APIRouter(tags=["users"])
+
+
+@router.get("/me", response_model=MeOut)
+async def get_me(current: CurrentUser = Depends(get_current_user)) -> MeOut:
+    u = current.user
+    return MeOut(
+        id=u.id,
+        display_name=u.display_name,
+        email=u.email,
+        employee_id=u.employee_id,
+        is_active=u.is_active,
+        roles=sorted(current.roles),
+        last_login_at=u.last_login_at,
+        auth_mode=get_settings().auth_mode,
+    )
+
+
+@router.get("/users", response_model=list[UserOut])
+async def list_users(
+    role: str | None = Query(default=None, description="Filter to users holding this role"),
+    _: CurrentUser = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> list[UserOut]:
+    """User directory for pickers (e.g. Disposition Authority dropdown,
+    'Notify These People'). Only active users are returned."""
+    stmt = select(User).where(User.is_active.is_(True)).order_by(User.display_name)
+    if role:
+        if role not in ALL_ROLES:
+            return []
+        stmt = stmt.join(UserRole, UserRole.user_id == User.id).where(UserRole.role == role)
+    users = (await db.execute(stmt)).scalars().unique().all()
+    return [
+        UserOut(
+            id=u.id,
+            display_name=u.display_name,
+            email=u.email,
+            employee_id=u.employee_id,
+            is_active=u.is_active,
+            roles=u.roles,
+            last_login_at=u.last_login_at,
+        )
+        for u in users
+    ]

backend/app/schemas/common.py

@@ -0,0 +1,19 @@
+from datetime import datetime, timezone
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, PlainSerializer
+
+
+def _serialize_utc(dt: datetime) -> str:
+    """All DB datetimes are naive UTC; emit RFC3339 with Z so browsers parse
+    them into the user's local timezone."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+UTCDateTime = Annotated[datetime, PlainSerializer(_serialize_utc, return_type=str)]
+
+
+class AppModel(BaseModel):
+    model_config = ConfigDict(from_attributes=True)

backend/app/schemas/lookup.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel, Field
+
+from app.schemas.common import AppModel
+
+
+class NamedLookupOut(AppModel):
+    id: int
+    name: str
+    is_active: bool
+
+
+class LookupCreateIn(BaseModel):
+    name: str = Field(min_length=1, max_length=100)
+
+
+class LookupPatchIn(BaseModel):
+    name: str | None = Field(default=None, min_length=1, max_length=100)
+    is_active: bool | None = None
+
+
+class LookupsOut(BaseModel):
+    departments: list[NamedLookupOut]
+    deviation_categories: list[NamedLookupOut]

backend/app/schemas/ncr.py

@@ -0,0 +1,187 @@
+from decimal import Decimal
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from app.domain import REOPEN_TARGET_STAGES, Stage
+from app.schemas.common import AppModel, UTCDateTime
+from app.schemas.user import UserRef
+
+Money = Annotated[Decimal, Field(ge=0, max_digits=12, decimal_places=2)]
+
+
+# ── Inputs ───────────────────────────────────────────────────────────────────
+class NcrCreateIn(BaseModel):
+    job_number: str = Field(min_length=1, max_length=100)
+    department_id: int
+    deviation_category_id: int
+    disposition_authority_id: int
+    deviation_detail: str = Field(min_length=5, max_length=20000)
+
+
+class InitialDispositionIn(BaseModel):
+    qc_authority: str | None = Field(default=None, max_length=255)
+    work_order: str | None = Field(default=None, max_length=100)
+    disposition_notes: str | None = Field(default=None, max_length=100000)
+    secondary_review_needed: bool
+    # "Notify These People" — required when secondary_review_needed is true.
+    secondary_authority_ids: list[int] = []
+
+
+class SecondaryDispositionIn(BaseModel):
+    qc_authority: str | None = Field(default=None, max_length=255)
+    work_order: str | None = Field(default=None, max_length=100)
+    disposition_notes: str | None = Field(default=None, max_length=100000)
+    # False = save updates and keep in my queue; True = release to Operations.
+    release: bool = False
+
+
+class InspectionIn(BaseModel):
+    qc_approval: Literal["yes", "no"] | None = None
+    inspection_notes: str | None = Field(default=None, max_length=20000)
+    # False = save and revisit later; True = advance to Costing.
+    qc_closed: bool = False
+
+
+class CostingIn(BaseModel):
+    labor_cost: Money
+    material_cost: Money
+    service_cost: Money
+    other_cost: Money
+
+
+class ReopenIn(BaseModel):
+    to_stage: Stage
+    reason: str = Field(min_length=5, max_length=2000)
+
+    @field_validator("to_stage")
+    @classmethod
+    def _valid_target(cls, v: Stage) -> Stage:
+        if v not in REOPEN_TARGET_STAGES:
+            raise ValueError("Reopen target must be a prior (non-closed) stage.")
+        return v
+
+
+# ── Outputs ──────────────────────────────────────────────────────────────────
+class AttachmentOut(AppModel):
+    id: int
+    original_filename: str
+    content_type: str
+    size_bytes: int
+    is_image: bool
+    uploaded_at: UTCDateTime
+    uploaded_by: UserRef
+
+
+class TransitionOut(AppModel):
+    id: int
+    from_stage: str | None
+    to_stage: str
+    action: str
+    acted_at: UTCDateTime
+    acted_by: UserRef
+    note: str | None
+
+
+class JobInfoOut(AppModel):
+    part_id: str | None
+    part_description: str | None
+    customer_name: str | None
+    work_order_status: str | None
+    source: str
+
+
+class NcrListItem(BaseModel):
+    id: int
+    ncr_number: str
+    job_number: str
+    department: str
+    deviation_category: str
+    requester: str
+    disposition_authority: str
+    stage: str
+    stage_label: str
+    days_in_stage: int
+    created_at: UTCDateTime
+
+
+class NcrListOut(BaseModel):
+    items: list[NcrListItem]
+    total: int
+    page: int
+    page_size: int
+
+
+class NcrDetailOut(BaseModel):
+    id: int
+    ncr_number: str
+    job_number: str
+    created_at: UTCDateTime
+    stage: str
+    stage_label: str
+    stage_entered_at: UTCDateTime
+    days_in_stage: int
+
+    department: str
+    department_id: int
+    deviation_category: str
+    deviation_category_id: int
+    deviation_detail: str
+    requester: UserRef
+    disposition_authority: UserRef
+
+    qc_authority: str | None
+    work_order: str | None
+    disposition_notes: str | None
+    secondary_review_needed: bool | None
+    secondary_authorities: list[UserRef]
+
+    operations_complete: bool
+    operations_completed_at: UTCDateTime | None
+    operations_completed_by: UserRef | None
+
+    qc_approval: str | None
+    inspection_notes: str | None
+    qc_closed: bool
+    qc_closed_at: UTCDateTime | None
+    qc_closed_by: UserRef | None
+
+    labor_cost: Decimal | None
+    material_cost: Decimal | None
+    service_cost: Decimal | None
+    other_cost: Decimal | None
+    total_cost: Decimal | None
+    costing_completed_at: UTCDateTime | None
+    costing_completed_by: UserRef | None
+
+    closed_at: UTCDateTime | None
+    closed_by: UserRef | None
+
+    job_info: JobInfoOut | None
+    attachments: list[AttachmentOut]
+    transitions: list[TransitionOut]
+
+    # Actions the *current* user may take right now (informs the UI; the API
+    # re-enforces every one of these server-side).
+    available_actions: list[str]
+
+
+class NcrMutationOut(BaseModel):
+    ncr: NcrDetailOut
+    warnings: list[str] = []
+
+
+class AuditEntryOut(AppModel):
+    id: int
+    created_at: UTCDateTime
+    user: UserRef
+    action: str
+    field_name: str | None
+    old_value: str | None
+    new_value: str | None
+    detail: str | None
+
+
+class AuditListOut(BaseModel):
+    items: list[AuditEntryOut]
+    total: int

backend/app/schemas/report.py

@@ -0,0 +1,54 @@
+from decimal import Decimal
+
+from pydantic import BaseModel
+
+
+class CountByName(BaseModel):
+    name: str
+    count: int
+
+
+class CountByMonth(BaseModel):
+    month: str  # YYYY-MM
+    count: int
+
+
+class CostByMonth(BaseModel):
+    month: str
+    labor: Decimal
+    material: Decimal
+    service: Decimal
+    other: Decimal
+    total: Decimal
+
+
+class AgingBucket(BaseModel):
+    bucket: str
+    count: int
+
+
+class StageCycleTime(BaseModel):
+    stage: str
+    stage_label: str
+    avg_days: float
+    samples: int
+
+
+class TopJob(BaseModel):
+    job_number: str
+    count: int
+
+
+class ReportsSummaryOut(BaseModel):
+    total_ncrs: int
+    open_ncrs: int
+    closed_ncrs: int
+    total_cost: Decimal
+    by_department: list[CountByName]
+    by_category: list[CountByName]
+    by_month: list[CountByMonth]
+    cost_over_time: list[CostByMonth]
+    aging: list[AgingBucket]
+    cycle_times: list[StageCycleTime]
+    end_to_end_avg_days: float | None
+    top_jobs: list[TopJob]

backend/app/schemas/user.py

@@ -0,0 +1,33 @@
+from pydantic import BaseModel, field_validator
+
+from app.domain import ALL_ROLES
+from app.schemas.common import AppModel, UTCDateTime
+
+
+class UserRef(AppModel):
+    id: int
+    display_name: str
+    email: str
+
+
+class UserOut(UserRef):
+    employee_id: str | None = None
+    is_active: bool
+    roles: list[str]
+    last_login_at: UTCDateTime | None = None
+
+
+class MeOut(UserOut):
+    auth_mode: str = "entra"
+
+
+class RolesUpdateIn(BaseModel):
+    roles: list[str]
+
+    @field_validator("roles")
+    @classmethod
+    def _valid_roles(cls, v: list[str]) -> list[str]:
+        unknown = set(v) - ALL_ROLES
+        if unknown:
+            raise ValueError(f"Unknown roles: {', '.join(sorted(unknown))}")
+        return sorted(set(v))

backend/app/seed.py

@@ -0,0 +1,243 @@
+"""Idempotent seed script.
+
+    docker compose exec api python -m app.seed
+
+Always ensures the default departments/deviation categories and the
+notifications setting. When SEED_DEMO_DATA=true it also creates dev users
+(one per role — usable directly with AUTH_MODE=dev) and a spread of sample
+NCRs across every workflow stage for development and demos.
+"""
+import asyncio
+import logging
+import random
+from datetime import timedelta
+from decimal import Decimal
+
+from sqlalchemy import select
+
+from app.config import get_settings
+from app.database import get_session_factory
+from app.domain import Role, Stage
+from app.models import (
+    AppSetting,
+    Department,
+    DeviationCategory,
+    Ncr,
+    NcrSecondaryAssignee,
+    StageTransition,
+    User,
+    UserRole,
+)
+from app.models.app_setting import NOTIFICATIONS_ENABLED_KEY
+from app.models.base import utcnow
+from app.services.numbering import allocate_ncr_number
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+log = logging.getLogger("seed")
+
+DEPARTMENTS = [
+    "Machining", "Welding", "Fabrication", "Assembly", "Paint & Coating",
+    "Shipping / Receiving", "Engineering", "Quality",
+]
+
+CATEGORIES = [
+    "Dimensional", "Material Defect", "Weld Defect", "Documentation",
+    "Process Deviation", "Supplier Nonconformance", "Damage / Handling", "Other",
+]
+
+DEV_USERS = [
+    ("admin@pescoinc.biz", "Dev Admin", list(r.value for r in Role)),
+    ("dispo@pescoinc.biz", "Dana Disposition", [Role.REQUESTER.value, Role.DISPOSITION_AUTHORITY.value]),
+    ("second@pescoinc.biz", "Sam Secondary", [Role.REQUESTER.value, Role.SECONDARY_DISPOSITION_AUTHORITY.value]),
+    ("ops@pescoinc.biz", "Owen Operations", [Role.REQUESTER.value, Role.OPERATIONS.value]),
+    ("qc@pescoinc.biz", "Quinn Inspector", [Role.REQUESTER.value, Role.QC_INSPECTOR.value]),
+    ("cost@pescoinc.biz", "Casey Costing", [Role.REQUESTER.value, Role.COSTING.value]),
+    ("req@pescoinc.biz", "Riley Requester", [Role.REQUESTER.value]),
+]
+
+DETAILS = [
+    "Bore diameter measured 0.008\" over drawing tolerance on 3 of 12 pieces.",
+    "Weld porosity found on the underside seam during visual inspection.",
+    "Wrong material grade pulled from stock; heat number does not match the traveler.",
+    "Paint runs and inadequate coverage on exterior panels after first coat.",
+    "Fixture shifted during machining; datum surfaces out of parallel by 0.015\".",
+    "Supplier-provided casting shows shrinkage cavity at the flange face.",
+    "Part dropped during transfer between stations; visible dent on sealing surface.",
+    "Traveler missing signed inspection step for operation 40.",
+]
+
+
+async def seed() -> None:
+    settings = get_settings()
+    session_factory = get_session_factory()
+    async with session_factory() as db:
+        # ── lookups ──────────────────────────────────────────────────────────
+        existing = {
+            d.name for d in (await db.execute(select(Department))).scalars().all()
+        }
+        for name in DEPARTMENTS:
+            if name not in existing:
+                db.add(Department(name=name, is_active=True))
+        existing = {
+            c.name
+            for c in (await db.execute(select(DeviationCategory))).scalars().all()
+        }
+        for name in CATEGORIES:
+            if name not in existing:
+                db.add(DeviationCategory(name=name, is_active=True))
+
+        if await db.get(AppSetting, NOTIFICATIONS_ENABLED_KEY) is None:
+            db.add(
+                AppSetting(
+                    key=NOTIFICATIONS_ENABLED_KEY,
+                    value="true" if settings.notifications_enabled_default else "false",
+                )
+            )
+        await db.commit()
+        log.info("Lookups + settings seeded.")
+
+        if not settings.seed_demo_data:
+            log.info("SEED_DEMO_DATA is false — skipping demo users/NCRs. Done.")
+            return
+
+        # ── dev users ────────────────────────────────────────────────────────
+        users: dict[str, User] = {}
+        for email, name, roles in DEV_USERS:
+            user = (
+                await db.execute(select(User).where(User.email == email))
+            ).scalar_one_or_none()
+            if user is None:
+                user = User(email=email, display_name=name, is_active=True)
+                db.add(user)
+                await db.flush()
+                for role in roles:
+                    db.add(UserRole(user_id=user.id, role=role))
+            users[email] = user
+        await db.commit()
+        log.info("Dev users seeded: %s", ", ".join(u for u, _, _ in DEV_USERS))
+
+        # ── demo NCRs ────────────────────────────────────────────────────────
+        ncr_count = (await db.execute(select(Ncr.id).limit(1))).first()
+        if ncr_count is not None:
+            log.info("NCRs already exist — skipping demo NCR creation. Done.")
+            return
+
+        departments = (await db.execute(select(Department))).scalars().all()
+        categories = (await db.execute(select(DeviationCategory))).scalars().all()
+        rng = random.Random(42)
+
+        dispo = users["dispo@pescoinc.biz"]
+        second = users["second@pescoinc.biz"]
+        ops = users["ops@pescoinc.biz"]
+        qc = users["qc@pescoinc.biz"]
+        cost = users["cost@pescoinc.biz"]
+        req = users["req@pescoinc.biz"]
+
+        # (target_stage, count)
+        plan = [
+            (Stage.NEW_REQUEST, 3),
+            (Stage.SECONDARY_DISPOSITION, 2),
+            (Stage.OPERATIONS, 3),
+            (Stage.QC_INSPECTION, 2),
+            (Stage.COSTING, 2),
+            (Stage.CLOSED, 4),
+        ]
+
+        for target, count in plan:
+            for _ in range(count):
+                days_ago = rng.randint(5, 120)
+                created = utcnow() - timedelta(days=days_ago)
+                number, year, seq = await allocate_ncr_number(db, now=created)
+                use_secondary = rng.random() < 0.4 or target == Stage.SECONDARY_DISPOSITION
+                ncr = Ncr(
+                    ncr_number=number,
+                    ncr_year=year,
+                    ncr_seq=seq,
+                    job_number=f"J{rng.randint(10000, 49999)}",
+                    department_id=rng.choice(departments).id,
+                    deviation_category_id=rng.choice(categories).id,
+                    disposition_authority_id=dispo.id,
+                    deviation_detail=rng.choice(DETAILS),
+                    requester_id=req.id,
+                    stage=Stage.NEW_REQUEST.value,
+                    created_at=created,
+                    stage_entered_at=created,
+                    updated_at=created,
+                )
+                db.add(ncr)
+                await db.flush()
+
+                t = created
+                db.add(StageTransition(
+                    ncr_id=ncr.id, from_stage=None, to_stage=Stage.NEW_REQUEST.value,
+                    action="create", acted_by_id=req.id, acted_at=t,
+                ))
+
+                def hop(days_lo=1, days_hi=4):
+                    nonlocal t
+                    t = min(utcnow(), t + timedelta(days=rng.randint(days_lo, days_hi),
+                                                    hours=rng.randint(0, 8)))
+                    return t
+
+                def advance(to_stage: Stage, action: str, actor: User, note=None):
+                    db.add(StageTransition(
+                        ncr_id=ncr.id, from_stage=ncr.stage, to_stage=to_stage.value,
+                        action=action, acted_by_id=actor.id, acted_at=hop(), note=note,
+                    ))
+                    ncr.stage = to_stage.value
+                    ncr.stage_entered_at = t
+
+                if target == Stage.NEW_REQUEST:
+                    continue
+
+                # initial disposition
+                ncr.qc_authority = "AS9100 8.7"
+                ncr.work_order = f"WO-{rng.randint(1000, 9999)}"
+                ncr.disposition_notes = (
+                    "<p><strong>Disposition:</strong> Rework per attached instructions. "
+                    "Re-inspect all affected features.</p>"
+                )
+                ncr.secondary_review_needed = use_secondary
+                if use_secondary:
+                    db.add(NcrSecondaryAssignee(ncr_id=ncr.id, user_id=second.id))
+                    advance(Stage.SECONDARY_DISPOSITION, "initial_disposition", dispo)
+                    if target == Stage.SECONDARY_DISPOSITION:
+                        continue
+                    advance(Stage.OPERATIONS, "secondary_release", second)
+                else:
+                    advance(Stage.OPERATIONS, "initial_disposition", dispo)
+                if target == Stage.OPERATIONS:
+                    continue
+
+                ncr.operations_complete = True
+                ncr.operations_completed_by_id = ops.id
+                advance(Stage.QC_INSPECTION, "operations_complete", ops)
+                ncr.operations_completed_at = t
+                if target == Stage.QC_INSPECTION:
+                    continue
+
+                ncr.qc_approval = "yes"
+                ncr.inspection_notes = "Reworked features re-inspected; all within tolerance."
+                ncr.qc_closed = True
+                ncr.qc_closed_by_id = qc.id
+                advance(Stage.COSTING, "qc_close", qc)
+                ncr.qc_closed_at = t
+                if target == Stage.COSTING:
+                    continue
+
+                ncr.labor_cost = Decimal(rng.randint(80, 2400))
+                ncr.material_cost = Decimal(rng.randint(0, 1800))
+                ncr.service_cost = Decimal(rng.choice([0, 0, 150, 450, 900]))
+                ncr.other_cost = Decimal(rng.choice([0, 0, 0, 75, 200]))
+                ncr.costing_completed_by_id = cost.id
+                ncr.closed_by_id = cost.id
+                advance(Stage.CLOSED, "complete_costing", cost)
+                ncr.costing_completed_at = t
+                ncr.closed_at = t
+
+        await db.commit()
+        log.info("Demo NCRs seeded. Done.")
+
+
+if __name__ == "__main__":
+    asyncio.run(seed())

backend/app/services/audit.py

@@ -0,0 +1,67 @@
+"""Audit trail helpers. Audit rows are append-only: the application exposes
+no endpoint that updates or deletes them."""
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import AuditLog, Ncr
+
+
+def _fmt(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def audit_event(
+    db: AsyncSession,
+    *,
+    user_id: int,
+    action: str,
+    ncr_id: int | None = None,
+    field_name: str | None = None,
+    old_value: Any = None,
+    new_value: Any = None,
+    detail: str | None = None,
+) -> None:
+    db.add(
+        AuditLog(
+            ncr_id=ncr_id,
+            user_id=user_id,
+            action=action,
+            field_name=field_name,
+            old_value=_fmt(old_value),
+            new_value=_fmt(new_value),
+            detail=detail,
+        )
+    )
+
+
+def apply_field_updates(
+    db: AsyncSession,
+    ncr: Ncr,
+    user_id: int,
+    updates: dict[str, Any],
+    action: str = "update",
+) -> dict[str, tuple[Any, Any]]:
+    """Set attributes on the NCR, writing one audit row per actually-changed
+    field. Returns {field: (old, new)} for the fields that changed."""
+    changes: dict[str, tuple[Any, Any]] = {}
+    for field, new_value in updates.items():
+        old_value = getattr(ncr, field)
+        if old_value == new_value:
+            continue
+        setattr(ncr, field, new_value)
+        changes[field] = (old_value, new_value)
+        audit_event(
+            db,
+            ncr_id=ncr.id,
+            user_id=user_id,
+            action=action,
+            field_name=field,
+            old_value=old_value,
+            new_value=new_value,
+        )
+    return changes

backend/app/services/graph.py

@@ -0,0 +1,91 @@
+"""Microsoft Graph helpers.
+
+Delegated access uses the OAuth2 On-Behalf-Of (OBO) flow: the SPA sends the
+API its access token (audience = this API); the API exchanges it with Entra ID
+for a Graph token carrying the *signed-in user's* identity, so mail goes out
+from that user's own mailbox. This keeps Graph scopes off the frontend and
+needs no extra token plumbing on state-changing requests.
+"""
+import logging
+from functools import partial
+
+import anyio
+import httpx
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+GRAPH_BASE = "https://graph.microsoft.com/v1.0"
+MAIL_SEND_SCOPE = "https://graph.microsoft.com/Mail.Send"
+GROUP_READ_SCOPE = "https://graph.microsoft.com/GroupMember.Read.All"
+
+_cca = None
+
+
+def _get_cca():
+    global _cca
+    if _cca is None:
+        import msal  # imported lazily so tests never need Entra config
+
+        settings = get_settings()
+        _cca = msal.ConfidentialClientApplication(
+            settings.entra_client_id,
+            authority=f"https://login.microsoftonline.com/{settings.entra_tenant_id}",
+            client_credential=settings.entra_client_secret,
+        )
+    return _cca
+
+
+def _acquire_obo_sync(user_token: str, scopes: list[str]) -> str:
+    result = _get_cca().acquire_token_on_behalf_of(
+        user_assertion=user_token, scopes=scopes
+    )
+    if "access_token" in result:
+        return result["access_token"]
+    raise RuntimeError(
+        f"OBO token exchange failed: {result.get('error')}: "
+        f"{result.get('error_description')}"
+    )
+
+
+async def acquire_obo_token(user_token: str, scopes: list[str]) -> str:
+    """Exchange the caller's API access token for a delegated Graph token."""
+    return await anyio.to_thread.run_sync(partial(_acquire_obo_sync, user_token, scopes))
+
+
+async def send_mail_as_user(
+    user_token: str, subject: str, html_body: str, to_emails: list[str]
+) -> None:
+    """Send an email from the signed-in user's mailbox (delegated Mail.Send)."""
+    graph_token = await acquire_obo_token(user_token, [MAIL_SEND_SCOPE])
+    payload = {
+        "message": {
+            "subject": subject,
+            "body": {"contentType": "HTML", "content": html_body},
+            "toRecipients": [{"emailAddress": {"address": e}} for e in to_emails],
+        },
+        "saveToSentItems": True,
+    }
+    async with httpx.AsyncClient(timeout=20) as client:
+        resp = await client.post(
+            f"{GRAPH_BASE}/me/sendMail",
+            json=payload,
+            headers={"Authorization": f"Bearer {graph_token}"},
+        )
+        if resp.status_code != 202:
+            raise RuntimeError(f"Graph sendMail returned {resp.status_code}: {resp.text[:300]}")
+
+
+async def check_member_group(user_token: str, group_id: str) -> bool:
+    """Group-overage fallback: ask Graph whether the signed-in user is in the
+    gate group. Requires delegated GroupMember.Read.All (see README)."""
+    graph_token = await acquire_obo_token(user_token, [GROUP_READ_SCOPE])
+    async with httpx.AsyncClient(timeout=20) as client:
+        resp = await client.post(
+            f"{GRAPH_BASE}/me/checkMemberGroups",
+            json={"groupIds": [group_id]},
+            headers={"Authorization": f"Bearer {graph_token}"},
+        )
+        resp.raise_for_status()
+        return group_id in resp.json().get("value", [])

backend/app/services/job_lookup.py

@@ -0,0 +1,116 @@
+"""Job number lookup abstraction — the seam for the future Infor VISUAL ERP
+integration.
+
+Today, Job Number is free text: the default NullJobLookupService accepts any
+value and returns no enrichment. When PESCO is ready to integrate VISUAL,
+implement VisualJobLookupService below, set JOB_LOOKUP_PROVIDER=visual (plus
+the VISUAL_DB_* variables) in .env, and restart — no schema or frontend
+changes required:
+
+* the NCR schema already stores the job number exactly as entered, plus a
+  related `job_info` row (part_id, part_description, customer_name,
+  work_order_status) that any provider can populate at NCR creation;
+* the frontend job-number field already calls GET /api/jobs/{job_number}/lookup
+  as the user types and displays whatever enrichment comes back, so
+  validation/autocomplete light up automatically with a real provider.
+"""
+import logging
+from dataclasses import dataclass
+from typing import Protocol
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class JobInfoData:
+    part_id: str | None = None
+    part_description: str | None = None
+    customer_name: str | None = None
+    work_order_status: str | None = None
+    source: str = "null"
+
+
+class JobLookupService(Protocol):
+    async def lookup(self, job_number: str) -> JobInfoData | None:
+        """Return read-only enrichment for a job number, or None when the job
+        is unknown / the provider has nothing to add. Implementations must
+        never raise for a merely-unknown job number."""
+        ...
+
+
+class NullJobLookupService:
+    """Default provider: job numbers are accepted as-is, no enrichment."""
+
+    async def lookup(self, job_number: str) -> JobInfoData | None:  # noqa: ARG002
+        return None
+
+
+class VisualJobLookupService:
+    """PLACEHOLDER for the future Infor VISUAL Manufacturing (SQL Server)
+    integration. Not implemented yet — selecting JOB_LOOKUP_PROVIDER=visual
+    today raises at startup with a pointer here.
+
+    Implementation notes (verified against PESCO's VISUAL 10 schema):
+
+    * Connect read-only to the VISUAL SQL Server database (VISUAL_DB_* env
+      vars) with a dedicated SELECT-only SQL login. Use `aioodbc` or `pymssql`.
+      NEVER write to VISUAL tables — hundreds of triggers maintain derived
+      values and direct writes bypass application validation.
+
+    * A PESCO "job number" corresponds to a work order base id (typically
+      with lot/split/sub qualifiers). WORK_ORDER's primary key is composite:
+      (TYPE, BASE_ID, LOT_ID, SPLIT_ID, SUB_ID); manufacturing work orders
+      have TYPE = 'W'. Parse the entered job number into BASE_ID (and LOT_ID
+      when the shop uses BASE/LOT notation, e.g. "12345/1") and query:
+
+        SELECT TOP 1 wo.BASE_ID, wo.LOT_ID, wo.SUB_ID, wo.PART_ID,
+                     wo.STATUS, wo.DESIRED_QTY, wo.CREATE_DATE,
+                     p.DESCRIPTION AS PART_DESCRIPTION
+        FROM WORK_ORDER wo
+        LEFT JOIN PART p ON p.ID = wo.PART_ID
+        WHERE wo.TYPE = 'W' AND wo.BASE_ID = :base_id
+        ORDER BY wo.LOT_ID, wo.SPLIT_ID, wo.SUB_ID
+
+      STATUS is a one-char code (R=released, C=closed, etc.) — map it to a
+      readable label for work_order_status.
+
+    * Customer enrichment goes through the demand/supply linkage:
+      DEMAND_SUPPLY_LINK rows with SUPPLY_TYPE='WO' and SUPPLY_BASE_ID =
+      wo.BASE_ID (match SUPPLY_LOT_ID/SUPPLY_SPLIT_ID/SUPPLY_SUB_ID when
+      present) point at customer-order demand (DEMAND_TYPE='CO',
+      DEMAND_BASE_ID = CUST_ORDER_LINE.CUST_ORDER_ID, DEMAND_SEQ_NO = line
+      no). Join CUSTOMER_ORDER -> CUSTOMER for the customer name.
+
+    * Return JobInfoData(part_id=..., part_description=...,
+      customer_name=..., work_order_status=..., source="visual").
+      Return None when no WORK_ORDER row matches. Wrap connection errors in
+      logging + return None so an ERP outage never blocks NCR entry.
+    """
+
+    def __init__(self) -> None:
+        settings = get_settings()
+        raise NotImplementedError(
+            "VisualJobLookupService is a documented stub. Implement it per the "
+            "notes in app/services/job_lookup.py, or set JOB_LOOKUP_PROVIDER=null. "
+            f"(Configured VISUAL host: {settings.visual_db_host or 'unset'})"
+        )
+
+    async def lookup(self, job_number: str) -> JobInfoData | None:
+        raise NotImplementedError
+
+
+_service: JobLookupService | None = None
+
+
+def get_job_lookup_service() -> JobLookupService:
+    global _service
+    if _service is None:
+        provider = get_settings().job_lookup_provider
+        if provider == "visual":
+            _service = VisualJobLookupService()  # raises: intentionally loud
+        else:
+            _service = NullJobLookupService()
+        logger.info("Job lookup provider: %s", provider)
+    return _service

backend/app/services/notifications.py

@@ -0,0 +1,156 @@
+"""Stage-transition email notifications via Microsoft Graph delegated
+Mail.Send. Mail is sent FROM the mailbox of the user whose action triggered
+the transition (OBO flow — see services/graph.py).
+
+Fault tolerance contract: a Graph/network failure must never block a workflow
+transition. Every failure path logs and returns a human-readable warning that
+the API surfaces in the response `warnings` array; the transition itself has
+already been committed by the caller.
+"""
+import html
+import logging
+from enum import Enum
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.deps import CurrentUser
+from app.config import get_settings
+from app.domain import STAGE_LABELS, STAGE_OWNER_ROLE, Role, Stage
+from app.models import AppSetting, Ncr, User, UserRole
+from app.models.app_setting import NOTIFICATIONS_ENABLED_KEY
+from app.services.graph import send_mail_as_user
+
+logger = logging.getLogger(__name__)
+
+
+class NotifyEvent(str, Enum):
+    CREATED = "created"
+    SECONDARY_ASSIGNED = "secondary_assigned"
+    RELEASED_TO_OPERATIONS = "released_to_operations"
+    OPERATIONS_COMPLETE = "operations_complete"
+    QC_CLOSED = "qc_closed"
+    CLOSED = "closed"
+    REOPENED = "reopened"
+
+
+_EVENT_SUBJECT = {
+    NotifyEvent.CREATED: "New NCR submitted — disposition needed",
+    NotifyEvent.SECONDARY_ASSIGNED: "Secondary disposition review assigned to you",
+    NotifyEvent.RELEASED_TO_OPERATIONS: "NCR released to Operations",
+    NotifyEvent.OPERATIONS_COMPLETE: "Operations complete — QC inspection needed",
+    NotifyEvent.QC_CLOSED: "QC closed — costing needed",
+    NotifyEvent.CLOSED: "Your NCR has been closed",
+    NotifyEvent.REOPENED: "NCR reopened by an administrator",
+}
+
+
+async def notifications_enabled(db: AsyncSession) -> bool:
+    row = await db.get(AppSetting, NOTIFICATIONS_ENABLED_KEY)
+    if row is None:
+        return get_settings().notifications_enabled_default
+    return row.value == "true"
+
+
+async def _role_emails(db: AsyncSession, role: Role) -> list[str]:
+    result = await db.execute(
+        select(User.email)
+        .join(UserRole, UserRole.user_id == User.id)
+        .where(UserRole.role == role.value, User.is_active.is_(True))
+    )
+    return [r[0] for r in result.all()]
+
+
+async def _recipients(db: AsyncSession, ncr: Ncr, event: NotifyEvent) -> list[str]:
+    if event == NotifyEvent.CREATED:
+        return [ncr.disposition_authority.email]
+    if event == NotifyEvent.SECONDARY_ASSIGNED:
+        return [u.email for u in ncr.secondary_authorities]
+    if event == NotifyEvent.RELEASED_TO_OPERATIONS:
+        return await _role_emails(db, Role.OPERATIONS)
+    if event == NotifyEvent.OPERATIONS_COMPLETE:
+        return await _role_emails(db, Role.QC_INSPECTOR)
+    if event == NotifyEvent.QC_CLOSED:
+        return await _role_emails(db, Role.COSTING)
+    if event == NotifyEvent.CLOSED:
+        return [ncr.requester.email]
+    if event == NotifyEvent.REOPENED:
+        owner_role = STAGE_OWNER_ROLE.get(Stage(ncr.stage))
+        emails = await _role_emails(db, owner_role) if owner_role else []
+        if ncr.requester.email not in emails:
+            emails.append(ncr.requester.email)
+        return emails
+    return []
+
+
+def _build_body(ncr: Ncr, event: NotifyEvent, summary: str) -> str:
+    e = html.escape
+    link = f"{get_settings().app_base_url}/ncrs/{ncr.id}"
+    rows = [
+        ("NCR Number", ncr.ncr_number),
+        ("Job Number", ncr.job_number),
+        ("Department", ncr.department.name if ncr.department else ""),
+        ("Deviation Category", ncr.deviation_category.name if ncr.deviation_category else ""),
+        ("Current Stage", STAGE_LABELS.get(Stage(ncr.stage), ncr.stage)),
+        ("Requester", ncr.requester.display_name if ncr.requester else ""),
+    ]
+    table = "".join(
+        f"<tr><td style='padding:4px 12px 4px 0;color:#555'>{e(k)}</td>"
+        f"<td style='padding:4px 0'><strong>{e(v or '')}</strong></td></tr>"
+        for k, v in rows
+    )
+    return f"""
+    <div style="font-family:Segoe UI,Arial,sans-serif;font-size:14px;color:#222">
+      <h2 style="margin:0 0 4px">{e(_EVENT_SUBJECT[event])}</h2>
+      <p style="margin:4px 0 12px">{e(summary)}</p>
+      <table style="border-collapse:collapse">{table}</table>
+      <p style="margin:16px 0">
+        <a href="{e(link)}" style="background:#1a5fb4;color:#fff;padding:10px 18px;
+           border-radius:4px;text-decoration:none">Open {e(ncr.ncr_number)}</a>
+      </p>
+      <p style="color:#888;font-size:12px">Sent automatically by the PESCO NCR system.</p>
+    </div>
+    """
+
+
+async def send_stage_notification(
+    db: AsyncSession,
+    ncr: Ncr,
+    event: NotifyEvent,
+    actor: CurrentUser,
+    summary: str,
+) -> list[str]:
+    """Best-effort notification. Returns a list of non-blocking warnings
+    (empty on success or when notifications are disabled)."""
+    try:
+        if not await notifications_enabled(db):
+            logger.info("Notifications disabled; skipping %s for %s", event, ncr.ncr_number)
+            return []
+        recipients = sorted(set(await _recipients(db, ncr, event)))
+        if not recipients:
+            logger.info("No recipients for %s on %s", event, ncr.ncr_number)
+            return []
+        if actor.token is None:
+            # dev auth mode: no real user token to send on behalf of
+            logger.info(
+                "[dev] Would send '%s' for %s from %s to %s",
+                event.value, ncr.ncr_number, actor.user.email, recipients,
+            )
+            return [
+                f"Email not sent (dev auth mode): '{_EVENT_SUBJECT[event]}' "
+                f"to {', '.join(recipients)}."
+            ]
+        subject = f"[{ncr.ncr_number}] {_EVENT_SUBJECT[event]}"
+        body = _build_body(ncr, event, summary)
+        await send_mail_as_user(actor.token, subject, body, recipients)
+        logger.info(
+            "Sent %s notification for %s from %s to %s",
+            event.value, ncr.ncr_number, actor.user.email, recipients,
+        )
+        return []
+    except Exception as exc:  # noqa: BLE001 — must never block the workflow
+        logger.exception("Notification failed for %s (%s)", ncr.ncr_number, event.value)
+        return [
+            f"The workflow change was saved, but the notification email could not "
+            f"be sent: {exc}"
+        ]

backend/app/services/numbering.py

@@ -0,0 +1,56 @@
+"""Atomic NCR number allocation.
+
+Format: NCR-YYYY-NNNN (zero-padded, per-calendar-year sequence).
+
+Strategy: UPDATE-first on the per-year row in ncr_sequences. The UPDATE takes
+a row lock (InnoDB) / reserved write lock (SQLite) that is held until the
+enclosing transaction commits, so two concurrent submissions serialize and can
+never read the same sequence value. If the year row doesn't exist yet
+(first NCR of a new year), it is inserted inside a SAVEPOINT; a losing racer
+gets an IntegrityError, rolls back only the savepoint, and proceeds to the
+UPDATE which now finds the winner's row.
+"""
+from datetime import datetime
+
+from sqlalchemy import select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import NcrSequence
+from app.models.base import utcnow
+
+
+async def allocate_ncr_number(
+    db: AsyncSession, now: datetime | None = None
+) -> tuple[str, int, int]:
+    """Allocate the next NCR number inside the caller's transaction.
+
+    Returns (ncr_number, year, seq). Must be called within the same
+    transaction that inserts the NCR so the sequence row lock is held
+    until commit.
+    """
+    year = (now or utcnow()).year
+
+    result = await db.execute(
+        update(NcrSequence)
+        .where(NcrSequence.year == year)
+        .values(last_seq=NcrSequence.last_seq + 1)
+    )
+    if result.rowcount == 0:
+        # First NCR of this calendar year — create the sequence row.
+        try:
+            async with db.begin_nested():
+                db.add(NcrSequence(year=year, last_seq=0))
+                await db.flush()
+        except IntegrityError:
+            pass  # another request created it first; fall through to UPDATE
+        await db.execute(
+            update(NcrSequence)
+            .where(NcrSequence.year == year)
+            .values(last_seq=NcrSequence.last_seq + 1)
+        )
+
+    seq = (
+        await db.execute(select(NcrSequence.last_seq).where(NcrSequence.year == year))
+    ).scalar_one()
+    return f"NCR-{year}-{seq:04d}", year, seq

backend/app/services/pdf.py

@@ -0,0 +1,64 @@
+"""Printable NCR PDF (WeasyPrint) — a clean single-document rendering of the
+complete NCR for hard-copy travelers and audits.
+
+WeasyPrint is imported lazily so environments without the Pango/Cairo system
+libraries (e.g. unit tests) can still import the app.
+"""
+from functools import partial
+from pathlib import Path
+
+import anyio
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from app.domain import STAGE_LABELS, Stage
+from app.models import Ncr
+from app.models.base import utcnow
+from app.services.storage import attachment_abs_path
+
+_TEMPLATES_DIR = Path(__file__).resolve().parent.parent / "templates"
+
+_env = Environment(
+    loader=FileSystemLoader(_TEMPLATES_DIR),
+    autoescape=select_autoescape(["html"]),
+)
+
+
+def _render_html(ncr: Ncr) -> str:
+    images = []
+    other_files = []
+    for att in ncr.attachments:
+        entry = {
+            "filename": att.original_filename,
+            "uploaded_by": att.uploaded_by.display_name,
+            "uploaded_at": att.uploaded_at,
+            "size_kb": max(1, att.size_bytes // 1024),
+        }
+        path = attachment_abs_path(att.stored_path)
+        if att.is_image and path.is_file():
+            entry["src"] = path.as_uri()
+            images.append(entry)
+        else:
+            other_files.append(entry)
+
+    template = _env.get_template("ncr_pdf.html")
+    return template.render(
+        ncr=ncr,
+        stage_label=STAGE_LABELS[Stage(ncr.stage)],
+        stage_labels=STAGE_LABELS,
+        Stage=Stage,
+        images=images,
+        other_files=other_files,
+        generated_at=utcnow(),
+    )
+
+
+def _html_to_pdf(html: str) -> bytes:
+    from weasyprint import HTML  # lazy: needs Pango/Cairo system libs
+
+    return HTML(string=html).write_pdf()
+
+
+async def render_ncr_pdf(ncr: Ncr) -> bytes:
+    html = _render_html(ncr)
+    # WeasyPrint rendering is CPU-bound; keep it off the event loop.
+    return await anyio.to_thread.run_sync(partial(_html_to_pdf, html))

backend/app/services/sanitize.py

@@ -0,0 +1,31 @@
+"""Rich-text HTML sanitization (XSS defense) using nh3 (ammonia bindings).
+Applied server-side to every rich-text field before it is stored."""
+import nh3
+
+_ALLOWED_TAGS = {
+    "p", "br", "div", "span",
+    "strong", "b", "em", "i", "u", "s", "sub", "sup",
+    "ul", "ol", "li",
+    "h1", "h2", "h3", "h4",
+    "blockquote", "pre", "code",
+    "a", "hr", "table", "thead", "tbody", "tr", "th", "td",
+}
+
+_ALLOWED_ATTRIBUTES = {
+    "a": {"href", "title"},
+    "th": {"colspan", "rowspan"},
+    "td": {"colspan", "rowspan"},
+}
+
+
+def sanitize_html(value: str | None) -> str | None:
+    if value is None:
+        return None
+    cleaned = nh3.clean(
+        value,
+        tags=_ALLOWED_TAGS,
+        attributes=_ALLOWED_ATTRIBUTES,
+        link_rel="noopener noreferrer",
+        url_schemes={"http", "https", "mailto"},
+    )
+    return cleaned

backend/app/services/storage.py

@@ -0,0 +1,87 @@
+"""Attachment storage on the local filesystem (a named Docker volume in
+production). Files live at ATTACHMENTS_DIR/<ncr_id>/<uuid><ext>; metadata is
+kept in the attachments table."""
+import re
+import uuid
+from pathlib import Path
+
+from fastapi import UploadFile
+
+from app.config import get_settings
+
+ALLOWED_EXTENSIONS = {
+    # images (camera capture on tablets produces jpg/png/heic)
+    ".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic", ".heif", ".bmp", ".tiff", ".tif",
+    # documents
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".csv", ".txt", ".msg", ".eml",
+}
+
+IMAGE_EXTENSIONS = {
+    ".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic", ".heif", ".bmp", ".tiff", ".tif",
+}
+
+CHUNK_SIZE = 1024 * 1024
+
+
+class UploadValidationError(Exception):
+    pass
+
+
+def _safe_filename(name: str) -> str:
+    name = Path(name or "upload").name
+    return re.sub(r"[^\w.\- ()]", "_", name)[:255] or "upload"
+
+
+async def save_attachment(upload: UploadFile, ncr_id: int) -> dict:
+    """Validate and persist an uploaded file. Returns metadata for the
+    Attachment row. Raises UploadValidationError on type/size violations."""
+    settings = get_settings()
+    original = _safe_filename(upload.filename or "upload")
+    ext = Path(original).suffix.lower()
+    if ext not in ALLOWED_EXTENSIONS:
+        raise UploadValidationError(
+            f"File type '{ext or 'unknown'}' is not allowed. "
+            f"Allowed: {', '.join(sorted(ALLOWED_EXTENSIONS))}"
+        )
+
+    stored_rel = f"{ncr_id}/{uuid.uuid4().hex}{ext}"
+    dest = Path(settings.attachments_dir) / stored_rel
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    size = 0
+    max_bytes = settings.max_upload_bytes
+    try:
+        with dest.open("wb") as out:
+            while chunk := await upload.read(CHUNK_SIZE):
+                size += len(chunk)
+                if size > max_bytes:
+                    raise UploadValidationError(
+                        f"File exceeds the {settings.max_upload_mb} MB limit."
+                    )
+                out.write(chunk)
+    except UploadValidationError:
+        dest.unlink(missing_ok=True)
+        raise
+    except Exception:
+        dest.unlink(missing_ok=True)
+        raise
+    if size == 0:
+        dest.unlink(missing_ok=True)
+        raise UploadValidationError("Uploaded file is empty.")
+
+    return {
+        "original_filename": original,
+        "stored_path": stored_rel,
+        "content_type": upload.content_type or "application/octet-stream",
+        "size_bytes": size,
+        "is_image": ext in IMAGE_EXTENSIONS,
+    }
+
+
+def attachment_abs_path(stored_path: str) -> Path:
+    settings = get_settings()
+    base = Path(settings.attachments_dir).resolve()
+    p = (base / stored_path).resolve()
+    if not str(p).startswith(str(base)):
+        raise UploadValidationError("Invalid attachment path.")
+    return p

backend/app/services/workflow.py

@@ -0,0 +1,76 @@
+"""Server-side workflow state machine. Every stage change flows through
+`transition()`, which validates against ALLOWED_TRANSITIONS and records both
+a StageTransition row (timestamps + acting user, for aging/cycle-time
+reporting) and an audit entry."""
+from app.domain import ALLOWED_TRANSITIONS, Stage
+from app.models import Ncr, StageTransition
+from app.models.base import utcnow
+from app.services.audit import audit_event
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class InvalidTransitionError(Exception):
+    def __init__(self, from_stage: str, to_stage: str):
+        self.from_stage = from_stage
+        self.to_stage = to_stage
+        super().__init__(f"Invalid stage transition: {from_stage} -> {to_stage}")
+
+
+def transition(
+    db: AsyncSession,
+    ncr: Ncr,
+    to_stage: Stage,
+    *,
+    action: str,
+    actor_id: int,
+    note: str | None = None,
+) -> None:
+    from_stage = Stage(ncr.stage)
+    if to_stage not in ALLOWED_TRANSITIONS.get(from_stage, set()):
+        raise InvalidTransitionError(from_stage.value, to_stage.value)
+
+    now = utcnow()
+    ncr.stage = to_stage.value
+    ncr.stage_entered_at = now
+    db.add(
+        StageTransition(
+            ncr_id=ncr.id,
+            from_stage=from_stage.value,
+            to_stage=to_stage.value,
+            action=action,
+            acted_by_id=actor_id,
+            acted_at=now,
+            note=note,
+        )
+    )
+    audit_event(
+        db,
+        ncr_id=ncr.id,
+        user_id=actor_id,
+        action=action,
+        field_name="stage",
+        old_value=from_stage.value,
+        new_value=to_stage.value,
+        detail=note,
+    )
+
+
+def record_creation(db: AsyncSession, ncr: Ncr, actor_id: int) -> None:
+    db.add(
+        StageTransition(
+            ncr_id=ncr.id,
+            from_stage=None,
+            to_stage=Stage.NEW_REQUEST.value,
+            action="create",
+            acted_by_id=actor_id,
+            acted_at=ncr.created_at,
+        )
+    )
+    audit_event(
+        db,
+        ncr_id=ncr.id,
+        user_id=actor_id,
+        action="create",
+        detail=f"NCR {ncr.ncr_number} created",
+    )

backend/app/templates/ncr_pdf.html

@@ -0,0 +1,204 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  @page {
+    size: letter;
+    margin: 18mm 14mm 20mm 14mm;
+    @bottom-left { content: "{{ ncr.ncr_number }} — Non-Conformance Report"; font-size: 8pt; color: #777; }
+    @bottom-right { content: "Page " counter(page) " of " counter(pages); font-size: 8pt; color: #777; }
+  }
+  body { font-family: "DejaVu Sans", sans-serif; font-size: 9.5pt; color: #1a1a1a; }
+  h1 { font-size: 17pt; margin: 0; }
+  h2 {
+    font-size: 10.5pt; text-transform: uppercase; letter-spacing: 0.06em;
+    background: #eef2f7; border-left: 4px solid #1a5fb4; padding: 4px 8px;
+    margin: 16px 0 6px;
+  }
+  .header { display: flex; justify-content: space-between; align-items: flex-start;
+            border-bottom: 3px solid #1a5fb4; padding-bottom: 8px; }
+  .brand { font-size: 13pt; font-weight: bold; color: #1a5fb4; }
+  .doc-meta { text-align: right; font-size: 9pt; color: #444; }
+  .ncr-number { font-size: 15pt; font-weight: bold; }
+  .stage-chip { display: inline-block; background: #1a5fb4; color: #fff;
+                padding: 2px 10px; border-radius: 10px; font-size: 9pt; }
+  table.fields { width: 100%; border-collapse: collapse; margin: 4px 0; }
+  table.fields td { border: 1px solid #ccd4de; padding: 5px 7px; vertical-align: top; }
+  table.fields td.lbl { width: 24%; background: #f6f8fa; color: #555; font-size: 8.5pt;
+                        text-transform: uppercase; letter-spacing: 0.04em; }
+  .notes { border: 1px solid #ccd4de; padding: 7px; min-height: 30px; }
+  .pending { color: #999; font-style: italic; }
+  table.history { width: 100%; border-collapse: collapse; font-size: 8.5pt; }
+  table.history th { background: #f6f8fa; border: 1px solid #ccd4de; padding: 4px 6px;
+                     text-align: left; }
+  table.history td { border: 1px solid #ccd4de; padding: 4px 6px; }
+  .thumb-grid { display: flex; flex-wrap: wrap; gap: 8px; }
+  .thumb { width: 30%; border: 1px solid #ccd4de; padding: 4px; }
+  .thumb img { width: 100%; max-height: 150px; object-fit: contain; }
+  .thumb .cap { font-size: 7.5pt; color: #666; margin-top: 2px; }
+  .costs td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  .costs tr.total td { font-weight: bold; background: #eef2f7; }
+</style>
+</head>
+<body>
+
+<div class="header">
+  <div>
+    <div class="brand">PESCO</div>
+    <h1>Non-Conformance Report</h1>
+  </div>
+  <div class="doc-meta">
+    <div class="ncr-number">{{ ncr.ncr_number }}</div>
+    <div>Stage: <span class="stage-chip">{{ stage_label }}</span></div>
+    <div>Generated {{ generated_at.strftime("%Y-%m-%d %H:%M") }} UTC</div>
+  </div>
+</div>
+
+<h2>Request</h2>
+<table class="fields">
+  <tr>
+    <td class="lbl">NCR Number</td><td>{{ ncr.ncr_number }}</td>
+    <td class="lbl">Date</td><td>{{ ncr.created_at.strftime("%Y-%m-%d") }}</td>
+  </tr>
+  <tr>
+    <td class="lbl">Job Number</td><td>{{ ncr.job_number }}</td>
+    <td class="lbl">Department</td><td>{{ ncr.department.name }}</td>
+  </tr>
+  <tr>
+    <td class="lbl">Deviation Category</td><td>{{ ncr.deviation_category.name }}</td>
+    <td class="lbl">Requester</td><td>{{ ncr.requester.display_name }}</td>
+  </tr>
+  <tr>
+    <td class="lbl">Disposition Authority</td><td>{{ ncr.disposition_authority.display_name }}</td>
+    <td class="lbl">Work Order</td><td>{{ ncr.work_order or "—" }}</td>
+  </tr>
+  {% if ncr.job_info %}
+  <tr>
+    <td class="lbl">Part (ERP)</td>
+    <td>{{ ncr.job_info.part_id or "—" }} {{ ncr.job_info.part_description or "" }}</td>
+    <td class="lbl">Customer (ERP)</td><td>{{ ncr.job_info.customer_name or "—" }}</td>
+  </tr>
+  {% endif %}
+</table>
+<div class="notes">{{ ncr.deviation_detail }}</div>
+
+<h2>Disposition</h2>
+<table class="fields">
+  <tr>
+    <td class="lbl">QC Authority</td><td>{{ ncr.qc_authority or "—" }}</td>
+    <td class="lbl">Secondary Review</td>
+    <td>
+      {% if ncr.secondary_review_needed is none %}—
+      {% elif ncr.secondary_review_needed %}Yes —
+        {{ ncr.secondary_authorities | map(attribute="display_name") | join(", ") or "unassigned" }}
+      {% else %}No{% endif %}
+    </td>
+  </tr>
+</table>
+{% if ncr.disposition_notes %}
+  <div class="notes">{{ ncr.disposition_notes | safe }}</div>
+{% else %}
+  <div class="notes pending">No disposition notes recorded.</div>
+{% endif %}
+
+<h2>Operations</h2>
+<table class="fields">
+  <tr>
+    <td class="lbl">Operations Complete</td>
+    <td>{% if ncr.operations_complete %}Yes{% else %}<span class="pending">Pending</span>{% endif %}</td>
+    <td class="lbl">Completed By / At</td>
+    <td>
+      {% if ncr.operations_completed_by %}
+        {{ ncr.operations_completed_by.display_name }} —
+        {{ ncr.operations_completed_at.strftime("%Y-%m-%d %H:%M") }} UTC
+      {% else %}—{% endif %}
+    </td>
+  </tr>
+</table>
+
+<h2>QC Inspection</h2>
+<table class="fields">
+  <tr>
+    <td class="lbl">QC Approval</td>
+    <td>{{ ncr.qc_approval | capitalize if ncr.qc_approval else "—" }}</td>
+    <td class="lbl">QC Closed</td>
+    <td>
+      {% if ncr.qc_closed %}Yes — {{ ncr.qc_closed_by.display_name }},
+        {{ ncr.qc_closed_at.strftime("%Y-%m-%d %H:%M") }} UTC
+      {% else %}<span class="pending">Pending</span>{% endif %}
+    </td>
+  </tr>
+</table>
+{% if ncr.inspection_notes %}
+  <div class="notes">{{ ncr.inspection_notes }}</div>
+{% endif %}
+
+<h2>Costing</h2>
+<table class="fields costs">
+  <tr>
+    <td class="lbl">Labor</td>
+    <td class="num">{% if ncr.labor_cost is not none %}${{ "%.2f" | format(ncr.labor_cost) }}{% else %}—{% endif %}</td>
+    <td class="lbl">Material</td>
+    <td class="num">{% if ncr.material_cost is not none %}${{ "%.2f" | format(ncr.material_cost) }}{% else %}—{% endif %}</td>
+  </tr>
+  <tr>
+    <td class="lbl">Service</td>
+    <td class="num">{% if ncr.service_cost is not none %}${{ "%.2f" | format(ncr.service_cost) }}{% else %}—{% endif %}</td>
+    <td class="lbl">Other</td>
+    <td class="num">{% if ncr.other_cost is not none %}${{ "%.2f" | format(ncr.other_cost) }}{% else %}—{% endif %}</td>
+  </tr>
+  <tr class="total">
+    <td class="lbl">Total Cost of Nonconformance</td>
+    <td class="num" colspan="3">
+      {% if ncr.total_cost is not none %}${{ "%.2f" | format(ncr.total_cost) }}{% else %}—{% endif %}
+    </td>
+  </tr>
+</table>
+{% if ncr.closed_at %}
+<p>Closed by {{ ncr.closed_by.display_name }} on {{ ncr.closed_at.strftime("%Y-%m-%d %H:%M") }} UTC.</p>
+{% endif %}
+
+{% if images or other_files %}
+<h2>Attachments ({{ images | length + other_files | length }})</h2>
+{% if images %}
+<div class="thumb-grid">
+  {% for img in images %}
+  <div class="thumb">
+    <img src="{{ img.src }}" alt="{{ img.filename }}">
+    <div class="cap">{{ img.filename }} — {{ img.uploaded_by }},
+      {{ img.uploaded_at.strftime("%Y-%m-%d") }}</div>
+  </div>
+  {% endfor %}
+</div>
+{% endif %}
+{% if other_files %}
+<table class="history" style="margin-top:6px">
+  <tr><th>File</th><th>Uploaded By</th><th>Date</th><th>Size</th></tr>
+  {% for f in other_files %}
+  <tr>
+    <td>{{ f.filename }}</td><td>{{ f.uploaded_by }}</td>
+    <td>{{ f.uploaded_at.strftime("%Y-%m-%d %H:%M") }}</td><td>{{ f.size_kb }} KB</td>
+  </tr>
+  {% endfor %}
+</table>
+{% endif %}
+{% endif %}
+
+<h2>Workflow History</h2>
+<table class="history">
+  <tr><th>Date (UTC)</th><th>Action</th><th>From</th><th>To</th><th>By</th><th>Note</th></tr>
+  {% for t in ncr.transitions %}
+  <tr>
+    <td>{{ t.acted_at.strftime("%Y-%m-%d %H:%M") }}</td>
+    <td>{{ t.action.replace("_", " ") | title }}</td>
+    <td>{{ stage_labels[Stage(t.from_stage)] if t.from_stage else "—" }}</td>
+    <td>{{ stage_labels[Stage(t.to_stage)] }}</td>
+    <td>{{ t.acted_by.display_name }}</td>
+    <td>{{ t.note or "" }}</td>
+  </tr>
+  {% endfor %}
+</table>
+
+</body>
+</html>

backend/entrypoint.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+
+echo "[api] running database migrations..."
+attempt=0
+until alembic upgrade head; do
+  attempt=$((attempt + 1))
+  if [ "$attempt" -ge 12 ]; then
+    echo "[api] migrations failed after $attempt attempts, giving up." >&2
+    exit 1
+  fi
+  echo "[api] database not ready (attempt $attempt), retrying in 5s..."
+  sleep 5
+done
+echo "[api] migrations complete."
+
+exec uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 2

backend/pyproject.toml

@@ -0,0 +1,6 @@
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning:jose.*",
+]

backend/requirements-dev.txt

@@ -0,0 +1,4 @@
+-r requirements.txt
+pytest>=8.2
+pytest-asyncio>=0.24
+aiosqlite>=0.20

backend/requirements.txt

@@ -0,0 +1,16 @@
+fastapi>=0.115,<1
+uvicorn[standard]>=0.30
+sqlalchemy[asyncio]>=2.0.43
+alembic>=1.13
+aiomysql>=0.2.3
+PyMySQL>=1.1
+greenlet>=3.0
+pydantic>=2.9
+pydantic-settings>=2.4
+python-jose[cryptography]>=3.3
+msal>=1.31
+httpx>=0.27
+nh3>=0.2.18
+weasyprint>=62
+jinja2>=3.1
+python-multipart>=0.0.9

backend/tests/conftest.py

@@ -0,0 +1,89 @@
+"""Test configuration.
+
+The environment MUST be set before any `app.*` import (settings are cached):
+tests run against a file-backed SQLite database with AUTH_MODE=dev, which
+exercises the same SQLAlchemy models, state machine, numbering, and
+permission code paths as MySQL. To run the suite against a real MySQL
+instance instead:
+
+    DATABASE_URL="mysql+aiomysql://user:pass@host/db_test?charset=utf8mb4" pytest
+"""
+import asyncio
+import os
+import tempfile
+import uuid
+
+_TMPDIR = tempfile.mkdtemp(prefix="pesco-ncr-tests-")
+os.environ.setdefault("DATABASE_URL", f"sqlite+aiosqlite:///{_TMPDIR}/test.db")
+os.environ["AUTH_MODE"] = "dev"
+os.environ["ATTACHMENTS_DIR"] = os.path.join(_TMPDIR, "attachments")
+os.environ["INITIAL_ADMIN_EMAILS"] = ""
+os.environ["JOB_LOOKUP_PROVIDER"] = "null"
+# Disabled by default so mutation responses have empty `warnings`;
+# notification-specific tests flip the AppSetting row explicitly.
+os.environ["NOTIFICATIONS_ENABLED_DEFAULT"] = "false"
+
+import pytest  # noqa: E402
+from httpx import ASGITransport, AsyncClient  # noqa: E402
+
+from app.database import get_engine, get_session_factory  # noqa: E402
+from app.main import app  # noqa: E402
+from app.models import Base, Department, DeviationCategory, User, UserRole  # noqa: E402
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _create_schema():
+    async def _run():
+        engine = get_engine()
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+        async with get_session_factory()() as db:
+            db.add(Department(name="Machining", is_active=True))
+            db.add(Department(name="Inactive Dept", is_active=False))
+            db.add(DeviationCategory(name="Dimensional", is_active=True))
+            await db.commit()
+
+    asyncio.run(_run())
+    yield
+
+
+@pytest.fixture
+async def client():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as c:
+        yield c
+
+
+@pytest.fixture
+def make_user():
+    async def _make(roles: list[str], name: str | None = None) -> str:
+        email = f"user-{uuid.uuid4().hex[:10]}@pescoinc.biz"
+        async with get_session_factory()() as db:
+            user = User(
+                email=email,
+                display_name=name or f"Test {email.split('@')[0]}",
+                is_active=True,
+            )
+            db.add(user)
+            await db.flush()
+            for role in roles:
+                db.add(UserRole(user_id=user.id, role=role))
+            await db.commit()
+        return email
+
+    return _make
+
+
+@pytest.fixture
+async def team(make_user) -> dict[str, str]:
+    """One user per workflow role, fresh for each test."""
+    return {
+        "requester": await make_user(["requester"]),
+        "dispo": await make_user(["requester", "disposition_authority"]),
+        "second": await make_user(["requester", "secondary_disposition_authority"]),
+        "second2": await make_user(["requester", "secondary_disposition_authority"]),
+        "ops": await make_user(["requester", "operations"]),
+        "qc": await make_user(["requester", "qc_inspector"]),
+        "cost": await make_user(["requester", "costing"]),
+        "admin": await make_user(["admin"]),
+    }

backend/tests/test_attachments.py

@@ -0,0 +1,62 @@
+"""Attachment upload validation, metadata, download, and closure locking."""
+from .util import create_ncr, hdr, to_closed
+
+TINY_PNG = (
+    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
+    b"\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\nIDATx\x9cc\x00\x01"
+    b"\x00\x00\x05\x00\x01\r\n-\xb4\x00\x00\x00\x00IEND\xaeB`\x82"
+)
+
+
+async def test_upload_download_and_metadata(client, team):
+    ncr = await create_ncr(client, team)
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/attachments",
+        files=[
+            ("files", ("photo one.png", TINY_PNG, "image/png")),
+            ("files", ("notes.txt", b"observed at station 4", "text/plain")),
+        ],
+        headers=hdr(team["requester"]),
+    )
+    assert r.status_code == 201, r.text
+    items = r.json()
+    assert len(items) == 2
+    png = next(i for i in items if i["is_image"])
+    assert png["original_filename"] == "photo one.png"
+    assert png["uploaded_by"]["email"] == team["requester"]
+    assert png["size_bytes"] == len(TINY_PNG)
+
+    r = await client.get(
+        f"/api/attachments/{png['id']}/download", headers=hdr(team["ops"])
+    )
+    assert r.status_code == 200
+    assert r.content == TINY_PNG
+
+    # attachment add shows in detail + audit
+    detail = (await client.get(f"/api/ncrs/{ncr['id']}", headers=hdr(team["qc"]))).json()
+    assert len(detail["attachments"]) == 2
+    audit = (
+        await client.get(f"/api/ncrs/{ncr['id']}/audit", headers=hdr(team["qc"]))
+    ).json()
+    assert sum(1 for a in audit["items"] if a["action"] == "attachment_add") == 2
+
+
+async def test_disallowed_type_rejected(client, team):
+    ncr = await create_ncr(client, team)
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/attachments",
+        files=[("files", ("malware.exe", b"MZ...", "application/octet-stream"))],
+        headers=hdr(team["requester"]),
+    )
+    assert r.status_code == 422
+    assert "not allowed" in r.json()["detail"]
+
+
+async def test_attachments_locked_when_closed(client, team):
+    ncr = await to_closed(client, team, (await create_ncr(client, team))["id"])
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/attachments",
+        files=[("files", ("late.png", TINY_PNG, "image/png"))],
+        headers=hdr(team["requester"]),
+    )
+    assert r.status_code == 409

backend/tests/test_numbering.py

@@ -0,0 +1,51 @@
+"""NCR numbering: format, per-year sequence + rollover, and concurrency."""
+import asyncio
+import re
+from datetime import datetime
+
+from app.database import get_session_factory
+from app.services.numbering import allocate_ncr_number
+
+from .util import create_ncr
+
+NCR_RE = re.compile(r"^NCR-(\d{4})-(\d{4})$")
+
+
+async def test_number_format_and_sequence(client, team):
+    first = await create_ncr(client, team)
+    second = await create_ncr(client, team)
+
+    m1, m2 = NCR_RE.match(first["ncr_number"]), NCR_RE.match(second["ncr_number"])
+    assert m1 and m2, (first["ncr_number"], second["ncr_number"])
+    assert int(m1.group(1)) == datetime.now().year
+    assert int(m2.group(2)) == int(m1.group(2)) + 1
+
+
+async def test_year_rollover_resets_sequence():
+    async with get_session_factory()() as db:
+        n1, year1, seq1 = await allocate_ncr_number(db, now=datetime(2098, 12, 31))
+        n2, year2, seq2 = await allocate_ncr_number(db, now=datetime(2099, 1, 1))
+        n3, _, seq3 = await allocate_ncr_number(db, now=datetime(2099, 6, 15))
+        await db.rollback()
+
+    assert (year1, seq1) == (2098, 1) and n1 == "NCR-2098-0001"
+    assert (year2, seq2) == (2099, 1) and n2 == "NCR-2099-0001"
+    assert seq3 == 2 and n3 == "NCR-2099-0002"
+
+
+async def test_zero_padding():
+    async with get_session_factory()() as db:
+        number, _, _ = await allocate_ncr_number(db, now=datetime(2097, 3, 1))
+        await db.rollback()
+    assert number == "NCR-2097-0001"
+
+
+async def test_concurrent_submissions_never_collide(client, team):
+    """Twelve simultaneous submissions must all succeed with distinct numbers."""
+    results = await asyncio.gather(
+        *[create_ncr(client, team, job_number=f"J-CONC-{i}") for i in range(12)]
+    )
+    numbers = [r["ncr_number"] for r in results]
+    assert len(set(numbers)) == 12, numbers
+    seqs = sorted(int(NCR_RE.match(n).group(2)) for n in numbers)
+    assert seqs == list(range(seqs[0], seqs[0] + 12))

backend/tests/test_permissions.py

@@ -0,0 +1,223 @@
+"""Server-side role enforcement per stage and admin-area authorization."""
+from .util import (
+    create_ncr,
+    do_initial_disposition,
+    hdr,
+    to_costing,
+    to_operations,
+    to_qc_inspection,
+    user_id_by_email,
+)
+
+
+async def test_stage_actions_require_stage_role(client, team):
+    ncr = await create_ncr(client, team)
+
+    # a plain requester can't perform initial disposition
+    r = await do_initial_disposition(client, team, ncr["id"], as_user=team["requester"])
+    assert r.status_code == 403
+    # nor can operations/qc/costing roles
+    r = await do_initial_disposition(client, team, ncr["id"], as_user=team["ops"])
+    assert r.status_code == 403
+
+    await to_operations(client, team, ncr["id"])
+    # only operations can mark complete
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/operations-complete", headers=hdr(team["requester"])
+    )
+    assert r.status_code == 403
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/operations-complete", headers=hdr(team["qc"])
+    )
+    assert r.status_code == 403
+
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/operations-complete", headers=hdr(team["ops"])
+    )
+    assert r.status_code == 200
+
+    # only QC can edit inspection fields
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/inspection",
+        json={"qc_approval": "yes"},
+        headers=hdr(team["ops"]),
+    )
+    assert r.status_code == 403
+
+    # only costing can cost
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/inspection",
+        json={"qc_approval": "yes", "qc_closed": True},
+        headers=hdr(team["qc"]),
+    )
+    assert r.status_code == 200
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/costing",
+        json={"labor_cost": "1", "material_cost": "1", "service_cost": "1", "other_cost": "1"},
+        headers=hdr(team["qc"]),
+    )
+    assert r.status_code == 403
+
+
+async def test_admin_can_act_at_every_stage(client, team):
+    ncr = await create_ncr(client, team)
+    r = await do_initial_disposition(client, team, ncr["id"], as_user=team["admin"])
+    assert r.status_code == 200
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/operations-complete", headers=hdr(team["admin"])
+    )
+    assert r.status_code == 200
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/inspection",
+        json={"qc_approval": "yes", "qc_closed": True},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 200
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/costing",
+        json={"labor_cost": "1", "material_cost": "1", "service_cost": "1", "other_cost": "1"},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 200
+    assert r.json()["ncr"]["stage"] == "closed"
+
+
+async def test_secondary_restricted_to_assignees(client, team):
+    ncr = await create_ncr(client, team)
+    second_id = await user_id_by_email(
+        client, team["dispo"], team["second"], "secondary_disposition_authority"
+    )
+    await do_initial_disposition(
+        client, team, ncr["id"], secondary=True, secondary_ids=[second_id]
+    )
+
+    # another user holding the secondary role but NOT assigned is rejected
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/secondary-disposition",
+        json={"release": True},
+        headers=hdr(team["second2"]),
+    )
+    assert r.status_code == 403
+
+    # the assignee is allowed
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/secondary-disposition",
+        json={"release": True},
+        headers=hdr(team["second"]),
+    )
+    assert r.status_code == 200
+    assert r.json()["ncr"]["stage"] == "operations"
+
+
+async def test_secondary_queue_filtered_by_identity(client, team):
+    ncr = await create_ncr(client, team)
+    second_id = await user_id_by_email(
+        client, team["dispo"], team["second"], "secondary_disposition_authority"
+    )
+    await do_initial_disposition(
+        client, team, ncr["id"], secondary=True, secondary_ids=[second_id]
+    )
+
+    r = await client.get("/api/ncrs?queue=secondary", headers=hdr(team["second"]))
+    assert any(item["id"] == ncr["id"] for item in r.json()["items"])
+
+    r = await client.get("/api/ncrs?queue=secondary", headers=hdr(team["second2"]))
+    assert not any(item["id"] == ncr["id"] for item in r.json()["items"])
+
+
+async def test_create_requires_valid_disposition_authority(client, team):
+    from .util import lookup_ids
+
+    dept_id, cat_id = await lookup_ids(client, team["requester"])
+    ops_id = await user_id_by_email(client, team["requester"], team["ops"], "operations")
+    r = await client.post(
+        "/api/ncrs",
+        json={
+            "job_number": "J1",
+            "department_id": dept_id,
+            "deviation_category_id": cat_id,
+            "disposition_authority_id": ops_id,  # lacks the role
+            "deviation_detail": "Detail long enough.",
+        },
+        headers=hdr(team["requester"]),
+    )
+    assert r.status_code == 422
+
+
+async def test_secondary_assignees_must_hold_role(client, team):
+    ncr = await create_ncr(client, team)
+    ops_id = await user_id_by_email(client, team["dispo"], team["ops"], "operations")
+    r = await do_initial_disposition(
+        client, team, ncr["id"], secondary=True, secondary_ids=[ops_id]
+    )
+    assert r.status_code == 422
+
+
+async def test_audit_endpoint_restricted(client, team):
+    ncr = await create_ncr(client, team)
+    r = await client.get(f"/api/ncrs/{ncr['id']}/audit", headers=hdr(team["requester"]))
+    assert r.status_code == 403
+    r = await client.get(f"/api/ncrs/{ncr['id']}/audit", headers=hdr(team["qc"]))
+    assert r.status_code == 200
+    r = await client.get(f"/api/ncrs/{ncr['id']}/audit", headers=hdr(team["admin"]))
+    assert r.status_code == 200
+
+
+async def test_admin_area_requires_admin(client, team):
+    for path in ("/api/admin/users", "/api/admin/departments", "/api/admin/settings",
+                 "/api/admin/audit"):
+        r = await client.get(path, headers=hdr(team["requester"]))
+        assert r.status_code == 403, path
+        r = await client.get(path, headers=hdr(team["admin"]))
+        assert r.status_code == 200, path
+
+
+async def test_role_assignment_and_lockout_protection(client, team, make_user):
+    target = await make_user(["requester"])
+    r = await client.get("/api/admin/users", headers=hdr(team["admin"]))
+    target_id = next(u["id"] for u in r.json() if u["email"] == target)
+    admin_id = next(u["id"] for u in r.json() if u["email"] == team["admin"])
+
+    r = await client.put(
+        f"/api/admin/users/{target_id}/roles",
+        json={"roles": ["requester", "qc_inspector"]},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 200
+    assert set(r.json()["roles"]) == {"requester", "qc_inspector"}
+
+    # unknown role rejected
+    r = await client.put(
+        f"/api/admin/users/{target_id}/roles",
+        json={"roles": ["superuser"]},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 422
+
+    # admin cannot remove their own admin role
+    r = await client.put(
+        f"/api/admin/users/{admin_id}/roles",
+        json={"roles": ["requester"]},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 422
+
+
+async def test_everyone_can_view_and_search(client, team):
+    ncr = await create_ncr(client, team)
+    r = await client.get(f"/api/ncrs/{ncr['id']}", headers=hdr(team["ops"]))
+    assert r.status_code == 200
+    # available_actions reflect the viewer's role
+    assert "initial_disposition" not in r.json()["available_actions"]
+    r = await client.get(f"/api/ncrs/{ncr['id']}", headers=hdr(team["dispo"]))
+    assert "initial_disposition" in r.json()["available_actions"]
+
+    r = await client.get(
+        f"/api/ncrs?q={ncr['ncr_number']}", headers=hdr(team["requester"])
+    )
+    assert r.json()["total"] >= 1
+
+
+async def test_unknown_dev_user_rejected(client):
+    r = await client.get("/api/me", headers=hdr("ghost@pescoinc.biz"))
+    assert r.status_code == 401

backend/tests/test_state_machine.py

@@ -0,0 +1,244 @@
+"""Workflow state machine: happy paths, invalid transitions, closure locking,
+admin reopen, and rich-text sanitization."""
+from .util import (
+    create_ncr,
+    do_initial_disposition,
+    hdr,
+    to_closed,
+    to_costing,
+    to_operations,
+    to_qc_inspection,
+    user_id_by_email,
+)
+
+
+async def test_full_lifecycle_direct_to_operations(client, team):
+    ncr = await create_ncr(client, team)
+    assert ncr["stage"] == "new_request"
+    assert ncr["ncr_number"].startswith("NCR-")
+
+    ncr = await to_operations(client, team, ncr["id"])
+    assert ncr["stage"] == "operations"
+    assert ncr["secondary_review_needed"] is False
+    assert ncr["qc_authority"] == "AS9100 8.7"
+
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/operations-complete", headers=hdr(team["ops"])
+    )
+    body = r.json()["ncr"]
+    assert body["stage"] == "qc_inspection"
+    assert body["operations_complete"] is True
+    assert body["operations_completed_by"]["email"] == team["ops"]
+
+    # QC can save repeatedly without closing
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/inspection",
+        json={"qc_approval": "no", "inspection_notes": "First pass failed."},
+        headers=hdr(team["qc"]),
+    )
+    assert r.json()["ncr"]["stage"] == "qc_inspection"
+
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/inspection",
+        json={"qc_approval": "yes", "inspection_notes": "Rework verified.", "qc_closed": True},
+        headers=hdr(team["qc"]),
+    )
+    body = r.json()["ncr"]
+    assert body["stage"] == "costing"
+    assert body["qc_closed"] is True
+
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/costing",
+        json={
+            "labor_cost": "100.00",
+            "material_cost": "50.25",
+            "service_cost": "0",
+            "other_cost": "10",
+        },
+        headers=hdr(team["cost"]),
+    )
+    body = r.json()["ncr"]
+    assert body["stage"] == "closed"
+    assert body["total_cost"] == "160.25"
+    assert body["closed_at"] is not None
+
+    # Transition history is complete and ordered
+    stages = [t["to_stage"] for t in body["transitions"]]
+    assert stages == ["new_request", "operations", "qc_inspection", "costing", "closed"]
+
+
+async def test_secondary_disposition_flow(client, team):
+    ncr = await create_ncr(client, team)
+    second_id = await user_id_by_email(
+        client, team["dispo"], team["second"], "secondary_disposition_authority"
+    )
+
+    # secondary review without assignees is rejected
+    r = await do_initial_disposition(client, team, ncr["id"], secondary=True, secondary_ids=[])
+    assert r.status_code == 422
+
+    r = await do_initial_disposition(
+        client, team, ncr["id"], secondary=True, secondary_ids=[second_id]
+    )
+    body = r.json()["ncr"]
+    assert body["stage"] == "secondary_disposition"
+    assert [u["email"] for u in body["secondary_authorities"]] == [team["second"]]
+
+    # assignee saves without releasing
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/secondary-disposition",
+        json={"disposition_notes": "<p>Updated by secondary.</p>", "release": False},
+        headers=hdr(team["second"]),
+    )
+    assert r.json()["ncr"]["stage"] == "secondary_disposition"
+
+    # then releases to operations
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/secondary-disposition",
+        json={"work_order": "WO-2002", "release": True},
+        headers=hdr(team["second"]),
+    )
+    body = r.json()["ncr"]
+    assert body["stage"] == "operations"
+    assert body["work_order"] == "WO-2002"
+    # earlier saved notes were not wiped by the release payload
+    assert "Updated by secondary" in body["disposition_notes"]
+
+
+async def test_invalid_transitions_rejected(client, team):
+    ncr = await create_ncr(client, team)
+
+    # can't skip ahead from new_request
+    r = await client.post(f"/api/ncrs/{ncr['id']}/operations-complete", headers=hdr(team["ops"]))
+    assert r.status_code == 409
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/inspection",
+        json={"qc_closed": True},
+        headers=hdr(team["qc"]),
+    )
+    assert r.status_code == 409
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/costing",
+        json={"labor_cost": "1", "material_cost": "1", "service_cost": "1", "other_cost": "1"},
+        headers=hdr(team["cost"]),
+    )
+    assert r.status_code == 409
+
+    # once in operations, initial disposition can't run again
+    await to_operations(client, team, ncr["id"])
+    r = await do_initial_disposition(client, team, ncr["id"])
+    assert r.status_code == 409
+
+
+async def test_closed_ncr_is_fully_locked(client, team):
+    ncr = await to_closed(client, team, (await create_ncr(client, team))["id"])
+    assert ncr["stage"] == "closed"
+
+    for path, payload, user in [
+        ("initial-disposition", {"secondary_review_needed": False}, team["dispo"]),
+        ("secondary-disposition", {"release": True}, team["second"]),
+        ("operations-complete", None, team["ops"]),
+        ("inspection", {"qc_closed": True}, team["qc"]),
+        ("costing", {"labor_cost": "9", "material_cost": "9", "service_cost": "9", "other_cost": "9"}, team["cost"]),
+    ]:
+        r = await client.post(
+            f"/api/ncrs/{ncr['id']}/{path}",
+            json=payload,
+            headers=hdr(user),
+        )
+        assert r.status_code == 409, f"{path}: {r.status_code} {r.text}"
+        assert "closed" in r.json()["detail"].lower()
+
+
+async def test_admin_reopen_with_reason(client, team):
+    ncr = await to_closed(client, team, (await create_ncr(client, team))["id"])
+
+    # non-admin cannot reopen
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/reopen",
+        json={"to_stage": "costing", "reason": "Costs were entered incorrectly."},
+        headers=hdr(team["cost"]),
+    )
+    assert r.status_code == 403
+
+    # reason is required (min length)
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/reopen",
+        json={"to_stage": "costing", "reason": ""},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 422
+
+    # reopening to 'closed' is not a valid target
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/reopen",
+        json={"to_stage": "closed", "reason": "does not make sense"},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 422
+
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/reopen",
+        json={"to_stage": "costing", "reason": "Costs were entered incorrectly."},
+        headers=hdr(team["admin"]),
+    )
+    body = r.json()["ncr"]
+    assert body["stage"] == "costing"
+    assert body["closed_at"] is None
+    # costs preserved for correction
+    assert body["labor_cost"] == "125.50"
+
+    # reopen is recorded with its reason in the transition history + audit trail
+    reopen_t = [t for t in body["transitions"] if t["action"] == "reopen"]
+    assert len(reopen_t) == 1
+    assert "Costs were entered incorrectly." in reopen_t[0]["note"]
+
+    audit = await client.get(f"/api/ncrs/{ncr['id']}/audit", headers=hdr(team["admin"]))
+    actions = [a["action"] for a in audit.json()["items"]]
+    assert "reopen" in actions
+
+    # workflow resumes: costing can close it again
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/costing",
+        json={"labor_cost": "200", "material_cost": "0", "service_cost": "0", "other_cost": "0"},
+        headers=hdr(team["cost"]),
+    )
+    assert r.json()["ncr"]["stage"] == "closed"
+
+
+async def test_reopen_only_from_closed(client, team):
+    ncr = await create_ncr(client, team)
+    r = await client.post(
+        f"/api/ncrs/{ncr['id']}/reopen",
+        json={"to_stage": "new_request", "reason": "not closed yet"},
+        headers=hdr(team["admin"]),
+    )
+    assert r.status_code == 409
+
+
+async def test_rich_text_is_sanitized(client, team):
+    ncr = await create_ncr(client, team)
+    r = await do_initial_disposition(
+        client,
+        team,
+        ncr["id"],
+        notes='<p onclick="evil()">Keep</p><script>alert("xss")</script><a href="javascript:x()">link</a>',
+    )
+    notes = r.json()["ncr"]["disposition_notes"]
+    assert "<script" not in notes
+    assert "onclick" not in notes
+    assert "javascript:" not in notes
+    assert "Keep" in notes
+
+
+async def test_audit_trail_field_level(client, team):
+    ncr = await create_ncr(client, team)
+    await to_operations(client, team, ncr["id"])
+
+    r = await client.get(f"/api/ncrs/{ncr['id']}/audit", headers=hdr(team["qc"]))
+    items = r.json()["items"]
+    by_field = {i["field_name"]: i for i in items if i["field_name"]}
+    assert by_field["stage"]["old_value"] == "new_request"
+    assert by_field["stage"]["new_value"] == "operations"
+    assert by_field["work_order"]["new_value"] == "WO-1001"
+    assert any(i["action"] == "create" for i in items)

backend/tests/util.py

@@ -0,0 +1,108 @@
+"""Shared helpers: drive the API exactly the way the frontend does."""
+from httpx import AsyncClient
+
+
+def hdr(email: str) -> dict[str, str]:
+    return {"X-Dev-User": email}
+
+
+async def lookup_ids(client: AsyncClient, email: str) -> tuple[int, int]:
+    r = await client.get("/api/lookups", headers=hdr(email))
+    assert r.status_code == 200, r.text
+    body = r.json()
+    return body["departments"][0]["id"], body["deviation_categories"][0]["id"]
+
+
+async def user_id_by_email(client: AsyncClient, as_email: str, email: str, role: str) -> int:
+    r = await client.get(f"/api/users?role={role}", headers=hdr(as_email))
+    assert r.status_code == 200, r.text
+    for u in r.json():
+        if u["email"] == email:
+            return u["id"]
+    raise AssertionError(f"user {email} with role {role} not found")
+
+
+async def create_ncr(client: AsyncClient, team: dict, **overrides) -> dict:
+    dept_id, cat_id = await lookup_ids(client, team["requester"])
+    dispo_id = await user_id_by_email(
+        client, team["requester"], team["dispo"], "disposition_authority"
+    )
+    payload = {
+        "job_number": "J12345",
+        "department_id": dept_id,
+        "deviation_category_id": cat_id,
+        "disposition_authority_id": dispo_id,
+        "deviation_detail": "Bore diameter out of tolerance on 3 pieces.",
+    }
+    payload.update(overrides)
+    r = await client.post("/api/ncrs", json=payload, headers=hdr(team["requester"]))
+    assert r.status_code == 201, r.text
+    return r.json()["ncr"]
+
+
+async def do_initial_disposition(
+    client: AsyncClient,
+    team: dict,
+    ncr_id: int,
+    *,
+    secondary: bool = False,
+    secondary_ids: list[int] | None = None,
+    as_user: str | None = None,
+    notes: str = "<p>Rework per instructions.</p>",
+):
+    body = {
+        "qc_authority": "AS9100 8.7",
+        "work_order": "WO-1001",
+        "disposition_notes": notes,
+        "secondary_review_needed": secondary,
+    }
+    if secondary_ids is not None:
+        body["secondary_authority_ids"] = secondary_ids
+    return await client.post(
+        f"/api/ncrs/{ncr_id}/initial-disposition",
+        json=body,
+        headers=hdr(as_user or team["dispo"]),
+    )
+
+
+async def to_operations(client: AsyncClient, team: dict, ncr_id: int) -> dict:
+    """Walk a fresh NCR straight to the Operations stage."""
+    r = await do_initial_disposition(client, team, ncr_id, secondary=False)
+    assert r.status_code == 200, r.text
+    return r.json()["ncr"]
+
+
+async def to_qc_inspection(client: AsyncClient, team: dict, ncr_id: int) -> dict:
+    await to_operations(client, team, ncr_id)
+    r = await client.post(
+        f"/api/ncrs/{ncr_id}/operations-complete", headers=hdr(team["ops"])
+    )
+    assert r.status_code == 200, r.text
+    return r.json()["ncr"]
+
+
+async def to_costing(client: AsyncClient, team: dict, ncr_id: int) -> dict:
+    await to_qc_inspection(client, team, ncr_id)
+    r = await client.post(
+        f"/api/ncrs/{ncr_id}/inspection",
+        json={"qc_approval": "yes", "inspection_notes": "All good.", "qc_closed": True},
+        headers=hdr(team["qc"]),
+    )
+    assert r.status_code == 200, r.text
+    return r.json()["ncr"]
+
+
+async def to_closed(client: AsyncClient, team: dict, ncr_id: int) -> dict:
+    await to_costing(client, team, ncr_id)
+    r = await client.post(
+        f"/api/ncrs/{ncr_id}/costing",
+        json={
+            "labor_cost": "125.50",
+            "material_cost": "60.00",
+            "service_cost": "0",
+            "other_cost": "14.50",
+        },
+        headers=hdr(team["cost"]),
+    )
+    assert r.status_code == 200, r.text
+    return r.json()["ncr"]

db/init/01-powerbi-user.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Runs once, on first initialization of the MySQL data volume.
+# Creates the read-only reporting account used by the Power BI gateway.
+#
+# MySQL allows table-level grants on objects that do not exist yet, so the
+# grants below take effect as soon as Alembic creates the reporting views.
+# For an already-initialized database, run scripts/powerbi_grants.sql instead
+# (see README → "Power BI").
+set -euo pipefail
+
+if [ -z "${POWERBI_RO_PASSWORD:-}" ]; then
+  echo "[init] POWERBI_RO_PASSWORD not set - skipping powerbi_ro user creation."
+  exit 0
+fi
+
+mysql -u root -p"${MYSQL_ROOT_PASSWORD}" <<SQL
+CREATE USER IF NOT EXISTS 'powerbi_ro'@'%' IDENTIFIED BY '${POWERBI_RO_PASSWORD}';
+GRANT SELECT ON \`${MYSQL_DATABASE}\`.\`vw_ncr_full\`          TO 'powerbi_ro'@'%';
+GRANT SELECT ON \`${MYSQL_DATABASE}\`.\`vw_ncr_stage_history\` TO 'powerbi_ro'@'%';
+GRANT SELECT ON \`${MYSQL_DATABASE}\`.\`vw_ncr_costs\`         TO 'powerbi_ro'@'%';
+FLUSH PRIVILEGES;
+SQL
+
+echo "[init] powerbi_ro user created with SELECT on reporting views."

docker-compose.yml

@@ -0,0 +1,87 @@
+name: pesco-ncr
+
+services:
+  mysql:
+    image: mysql:8.4
+    command:
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
+      MYSQL_DATABASE: ${MYSQL_DATABASE:-pesco_ncr}
+      MYSQL_USER: ${MYSQL_USER:-ncr_app}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
+      POWERBI_RO_PASSWORD: ${POWERBI_RO_PASSWORD}
+    ports:
+      # Published so the on-prem Power BI gateway can reach the reporting views.
+      # Remove or firewall this mapping if external reporting access is not needed.
+      - "${MYSQL_PUBLISHED_PORT:-3306}:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+      - ./db/init:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -u root -p$$MYSQL_ROOT_PASSWORD --silent"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 40s
+    restart: unless-stopped
+
+  api:
+    build: ./backend
+    environment:
+      APP_BASE_URL: ${APP_BASE_URL:-http://localhost:8080}
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+      AUTH_MODE: ${AUTH_MODE:-entra}
+      ENTRA_TENANT_ID: ${ENTRA_TENANT_ID:-}
+      ENTRA_CLIENT_ID: ${ENTRA_CLIENT_ID:-}
+      ENTRA_CLIENT_SECRET: ${ENTRA_CLIENT_SECRET:-}
+      ENTRA_ALLOWED_GROUP_ID: ${ENTRA_ALLOWED_GROUP_ID:-}
+      ENTRA_API_AUDIENCE: ${ENTRA_API_AUDIENCE:-}
+      INITIAL_ADMIN_EMAILS: ${INITIAL_ADMIN_EMAILS:-}
+      MYSQL_HOST: mysql
+      MYSQL_PORT: 3306
+      MYSQL_DATABASE: ${MYSQL_DATABASE:-pesco_ncr}
+      MYSQL_USER: ${MYSQL_USER:-ncr_app}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
+      ATTACHMENTS_DIR: ${ATTACHMENTS_DIR:-/data/attachments}
+      MAX_UPLOAD_MB: ${MAX_UPLOAD_MB:-25}
+      NOTIFICATIONS_ENABLED_DEFAULT: ${NOTIFICATIONS_ENABLED_DEFAULT:-true}
+      JOB_LOOKUP_PROVIDER: ${JOB_LOOKUP_PROVIDER:-null}
+      VISUAL_DB_HOST: ${VISUAL_DB_HOST:-}
+      VISUAL_DB_PORT: ${VISUAL_DB_PORT:-1433}
+      VISUAL_DB_NAME: ${VISUAL_DB_NAME:-}
+      VISUAL_DB_USER: ${VISUAL_DB_USER:-}
+      VISUAL_DB_PASSWORD: ${VISUAL_DB_PASSWORD:-}
+      VISUAL_SITE_ID: ${VISUAL_SITE_ID:-}
+      SEED_DEMO_DATA: ${SEED_DEMO_DATA:-false}
+    volumes:
+      - attachments_data:/data/attachments
+    depends_on:
+      mysql:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8000/api/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 30s
+    restart: unless-stopped
+
+  frontend:
+    build: ./frontend
+    ports:
+      - "${HTTP_PORT:-8080}:80"
+    environment:
+      AUTH_MODE: ${AUTH_MODE:-entra}
+      ENTRA_TENANT_ID: ${ENTRA_TENANT_ID:-}
+      ENTRA_CLIENT_ID: ${ENTRA_CLIENT_ID:-}
+      ENTRA_API_SCOPE: ${ENTRA_API_SCOPE:-}
+    depends_on:
+      api:
+        condition: service_healthy
+    restart: unless-stopped
+
+volumes:
+  mysql_data:
+  attachments_data:

frontend/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.env
+*.tsbuildinfo

frontend/Dockerfile

@@ -0,0 +1,13 @@
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci 2>/dev/null || npm install
+COPY . .
+RUN npm run build
+
+FROM nginx:1.27-alpine
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+COPY docker-entrypoint.d/50-config.sh /docker-entrypoint.d/50-config.sh
+RUN chmod +x /docker-entrypoint.d/50-config.sh
+EXPOSE 80

frontend/docker-entrypoint.d/50-config.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# Generates the SPA's runtime configuration from container environment
+# variables (nginx image runs every /docker-entrypoint.d/*.sh on start).
+set -e
+
+API_SCOPE="${ENTRA_API_SCOPE}"
+if [ -z "$API_SCOPE" ] && [ -n "$ENTRA_CLIENT_ID" ]; then
+  API_SCOPE="api://${ENTRA_CLIENT_ID}/access_as_user"
+fi
+
+cat > /usr/share/nginx/html/config.js <<EOF
+window.__APP_CONFIG__ = {
+  authMode: "${AUTH_MODE:-entra}",
+  tenantId: "${ENTRA_TENANT_ID}",
+  clientId: "${ENTRA_CLIENT_ID}",
+  apiScope: "${API_SCOPE}"
+};
+EOF
+
+echo "[frontend] config.js generated (authMode=${AUTH_MODE:-entra})"

frontend/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta name="theme-color" content="#1a5fb4" />
+    <title>PESCO NCR</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='18' fill='%231a5fb4'/><text x='50' y='68' font-size='52' text-anchor='middle' fill='white' font-family='Arial' font-weight='bold'>N</text></svg>" />
+    <!-- Runtime configuration, generated from env by the nginx entrypoint -->
+    <script src="/config.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/nginx.conf

@@ -0,0 +1,33 @@
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Attachment uploads flow through this proxy; keep in sync with MAX_UPLOAD_MB.
+    client_max_body_size 50m;
+
+    gzip on;
+    gzip_types text/css application/javascript application/json image/svg+xml;
+
+    location /api/ {
+        proxy_pass http://api:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 120s;
+    }
+
+    location = /config.js {
+        add_header Cache-Control "no-store";
+    }
+
+    location /assets/ {
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

frontend/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pesco-ncr-frontend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@azure/msal-browser": "^3.26.1",
+    "@azure/msal-react": "^2.1.1",
+    "@emotion/react": "^11.13.3",
+    "@emotion/styled": "^11.13.0",
+    "@mui/icons-material": "^5.16.7",
+    "@mui/material": "^5.16.7",
+    "@tanstack/react-query": "^5.59.0",
+    "@tiptap/extension-link": "^2.9.1",
+    "@tiptap/react": "^2.9.1",
+    "@tiptap/starter-kit": "^2.9.1",
+    "dayjs": "^1.11.13",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.26.2",
+    "recharts": "^2.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "@types/react": "^18.3.10",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.2",
+    "typescript": "~5.5.4",
+    "vite": "^5.4.8"
+  }
+}

frontend/public/config.js

@@ -0,0 +1,8 @@
+// Local development defaults. In Docker this file is REPLACED at container
+// start by docker-entrypoint.d/50-config.sh using the real environment.
+window.__APP_CONFIG__ = {
+  authMode: "dev",
+  tenantId: "",
+  clientId: "",
+  apiScope: "",
+};

frontend/src/App.tsx

@@ -0,0 +1,24 @@
+import { Navigate, Route, Routes } from "react-router-dom";
+import { Layout } from "./components/Layout";
+import { AdminPage } from "./pages/admin/AdminPage";
+import { DashboardPage } from "./pages/DashboardPage";
+import { NcrDetailPage } from "./pages/NcrDetailPage";
+import { NewNcrPage } from "./pages/NewNcrPage";
+import { ReportsPage } from "./pages/ReportsPage";
+import { SearchPage } from "./pages/SearchPage";
+
+export default function App() {
+  return (
+    <Layout>
+      <Routes>
+        <Route path="/" element={<DashboardPage />} />
+        <Route path="/ncrs/new" element={<NewNcrPage />} />
+        <Route path="/ncrs/:id" element={<NcrDetailPage />} />
+        <Route path="/search" element={<SearchPage />} />
+        <Route path="/reports" element={<ReportsPage />} />
+        <Route path="/admin/*" element={<AdminPage />} />
+        <Route path="*" element={<Navigate to="/" replace />} />
+      </Routes>
+    </Layout>
+  );
+}

frontend/src/api/client.ts

@@ -0,0 +1,135 @@
+import {
+  InteractionRequiredAuthError,
+  PublicClientApplication,
+} from "@azure/msal-browser";
+import { config } from "../config";
+
+export const msalInstance =
+  config.authMode === "entra"
+    ? new PublicClientApplication({
+        auth: {
+          clientId: config.clientId,
+          authority: `https://login.microsoftonline.com/${config.tenantId}`,
+          redirectUri: window.location.origin,
+          postLogoutRedirectUri: window.location.origin,
+        },
+        cache: { cacheLocation: "sessionStorage" },
+      })
+    : null;
+
+const DEV_USER_KEY = "pesco-ncr-dev-user";
+
+export function getDevUser(): string {
+  return localStorage.getItem(DEV_USER_KEY) || "admin@pescoinc.biz";
+}
+
+export function setDevUser(email: string): void {
+  localStorage.setItem(DEV_USER_KEY, email);
+}
+
+async function authHeaders(): Promise<Record<string, string>> {
+  if (config.authMode === "dev") {
+    return { "X-Dev-User": getDevUser() };
+  }
+  const instance = msalInstance!;
+  const account = instance.getActiveAccount() ?? instance.getAllAccounts()[0];
+  if (!account) {
+    await instance.loginRedirect({ scopes: [config.apiScope] });
+    throw new Error("Redirecting to sign in…");
+  }
+  try {
+    const result = await instance.acquireTokenSilent({
+      scopes: [config.apiScope],
+      account,
+    });
+    return { Authorization: `Bearer ${result.accessToken}` };
+  } catch (err) {
+    if (err instanceof InteractionRequiredAuthError) {
+      await instance.acquireTokenRedirect({ scopes: [config.apiScope], account });
+    }
+    throw err;
+  }
+}
+
+export class ApiError extends Error {
+  status: number;
+  constructor(status: number, detail: string) {
+    super(detail);
+    this.status = status;
+  }
+}
+
+async function parseError(resp: Response): Promise<ApiError> {
+  let detail = `Request failed (${resp.status})`;
+  try {
+    const body = await resp.json();
+    if (typeof body.detail === "string") detail = body.detail;
+    else if (Array.isArray(body.detail) && body.detail[0]?.msg)
+      detail = body.detail
+        .map((d: { loc?: unknown[]; msg: string }) => d.msg)
+        .join("; ");
+  } catch {
+    /* non-JSON body */
+  }
+  return new ApiError(resp.status, detail);
+}
+
+export async function api<T>(
+  path: string,
+  options: { method?: string; body?: unknown } = {},
+): Promise<T> {
+  const headers: Record<string, string> = await authHeaders();
+  const init: RequestInit = { method: options.method ?? "GET", headers };
+  if (options.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    init.body = JSON.stringify(options.body);
+  }
+  const resp = await fetch(path, init);
+  if (!resp.ok) throw await parseError(resp);
+  if (resp.status === 204) return undefined as T;
+  return (await resp.json()) as T;
+}
+
+export async function apiUpload<T>(path: string, form: FormData): Promise<T> {
+  const headers = await authHeaders();
+  const resp = await fetch(path, { method: "POST", headers, body: form });
+  if (!resp.ok) throw await parseError(resp);
+  return (await resp.json()) as T;
+}
+
+export async function apiBlob(path: string): Promise<Blob> {
+  const headers = await authHeaders();
+  const resp = await fetch(path, { headers });
+  if (!resp.ok) throw await parseError(resp);
+  return resp.blob();
+}
+
+/** Fetch a protected file and hand it to the browser (download or new tab). */
+export async function openBlob(
+  path: string,
+  filename: string,
+  mode: "download" | "open",
+): Promise<void> {
+  const blob = await apiBlob(path);
+  const url = URL.createObjectURL(blob);
+  if (mode === "open") {
+    window.open(url, "_blank");
+  } else {
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    a.click();
+  }
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+export function buildQuery(params: Record<string, unknown>): string {
+  const q = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") {
+      q.set(key, String(value));
+    }
+  }
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}

frontend/src/api/hooks.ts

@@ -0,0 +1,121 @@
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
+import { api, apiUpload, buildQuery } from "./client";
+import type {
+  AttachmentOut,
+  AuditListOut,
+  JobLookupOut,
+  LookupsOut,
+  MeOut,
+  NcrDetail,
+  NcrListOut,
+  NcrMutationOut,
+  QueueFilters,
+  ReportsSummary,
+  UserOut,
+} from "./types";
+
+export function useMe() {
+  return useQuery({
+    queryKey: ["me"],
+    queryFn: () => api<MeOut>("/api/me"),
+    staleTime: 5 * 60_000,
+    retry: 1,
+  });
+}
+
+export function useLookups() {
+  return useQuery({
+    queryKey: ["lookups"],
+    queryFn: () => api<LookupsOut>("/api/lookups"),
+    staleTime: 5 * 60_000,
+  });
+}
+
+export function useUsersByRole(role: string) {
+  return useQuery({
+    queryKey: ["users", role],
+    queryFn: () => api<UserOut[]>(`/api/users?role=${role}`),
+    staleTime: 60_000,
+  });
+}
+
+export function useQueue(queue: string, filters: QueueFilters, page: number, pageSize = 25) {
+  return useQuery({
+    queryKey: ["ncrs", queue, filters, page, pageSize],
+    queryFn: () =>
+      api<NcrListOut>(
+        `/api/ncrs${buildQuery({ queue, page, page_size: pageSize, ...filters })}`,
+      ),
+    placeholderData: (prev) => prev,
+  });
+}
+
+export function useNcr(id: number | undefined) {
+  return useQuery({
+    queryKey: ["ncr", id],
+    queryFn: () => api<NcrDetail>(`/api/ncrs/${id}`),
+    enabled: id !== undefined,
+  });
+}
+
+export function useNcrAudit(id: number, enabled: boolean) {
+  return useQuery({
+    queryKey: ["ncr-audit", id],
+    queryFn: () => api<AuditListOut>(`/api/ncrs/${id}/audit`),
+    enabled,
+  });
+}
+
+export function useJobLookup(jobNumber: string) {
+  return useQuery({
+    queryKey: ["job-lookup", jobNumber],
+    queryFn: () =>
+      api<JobLookupOut>(`/api/jobs/${encodeURIComponent(jobNumber)}/lookup`),
+    enabled: jobNumber.trim().length > 2,
+    staleTime: 60_000,
+  });
+}
+
+export function useReportsSummary(filters: Record<string, unknown>) {
+  return useQuery({
+    queryKey: ["reports", filters],
+    queryFn: () =>
+      api<ReportsSummary>(`/api/reports/summary${buildQuery(filters)}`),
+  });
+}
+
+/** Shared invalidation + warning plumbing for every NCR mutation. */
+export function useNcrMutation<TVars>(
+  mutationFn: (vars: TVars) => Promise<NcrMutationOut>,
+  onWarnings?: (warnings: string[]) => void,
+) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn,
+    onSuccess: (data) => {
+      qc.setQueryData(["ncr", data.ncr.id], data.ncr);
+      qc.invalidateQueries({ queryKey: ["ncrs"] });
+      qc.invalidateQueries({ queryKey: ["ncr-audit", data.ncr.id] });
+      if (data.warnings.length && onWarnings) onWarnings(data.warnings);
+    },
+  });
+}
+
+export function useUploadAttachments(ncrId: number) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (files: File[]) => {
+      const form = new FormData();
+      for (const f of files) form.append("files", f, f.name);
+      return apiUpload<AttachmentOut[]>(`/api/ncrs/${ncrId}/attachments`, form);
+    },
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ["ncr", ncrId] });
+      qc.invalidateQueries({ queryKey: ["ncr-audit", ncrId] });
+    },
+  });
+}

frontend/src/api/types.ts

@@ -0,0 +1,246 @@
+export type StageValue =
+  | "new_request"
+  | "secondary_disposition"
+  | "operations"
+  | "qc_inspection"
+  | "costing"
+  | "closed";
+
+export const STAGE_LABELS: Record<StageValue, string> = {
+  new_request: "New Request",
+  secondary_disposition: "Secondary Disposition",
+  operations: "Operations",
+  qc_inspection: "QC Inspection",
+  costing: "Costing",
+  closed: "Closed",
+};
+
+export const STAGE_ORDER: StageValue[] = [
+  "new_request",
+  "secondary_disposition",
+  "operations",
+  "qc_inspection",
+  "costing",
+  "closed",
+];
+
+export const ROLES = [
+  "requester",
+  "disposition_authority",
+  "secondary_disposition_authority",
+  "operations",
+  "qc_inspector",
+  "costing",
+  "admin",
+] as const;
+export type Role = (typeof ROLES)[number];
+
+export const ROLE_LABELS: Record<Role, string> = {
+  requester: "Requester",
+  disposition_authority: "Disposition Authority",
+  secondary_disposition_authority: "Secondary Disposition Authority",
+  operations: "Operations",
+  qc_inspector: "QC Inspector",
+  costing: "Costing",
+  admin: "Admin",
+};
+
+export interface UserRef {
+  id: number;
+  display_name: string;
+  email: string;
+}
+
+export interface UserOut extends UserRef {
+  employee_id: string | null;
+  is_active: boolean;
+  roles: Role[];
+  last_login_at: string | null;
+}
+
+export interface MeOut extends UserOut {
+  auth_mode: "entra" | "dev";
+}
+
+export interface NamedLookup {
+  id: number;
+  name: string;
+  is_active: boolean;
+}
+
+export interface LookupsOut {
+  departments: NamedLookup[];
+  deviation_categories: NamedLookup[];
+}
+
+export interface AttachmentOut {
+  id: number;
+  original_filename: string;
+  content_type: string;
+  size_bytes: number;
+  is_image: boolean;
+  uploaded_at: string;
+  uploaded_by: UserRef;
+}
+
+export interface TransitionOut {
+  id: number;
+  from_stage: StageValue | null;
+  to_stage: StageValue;
+  action: string;
+  acted_at: string;
+  acted_by: UserRef;
+  note: string | null;
+}
+
+export interface JobInfoOut {
+  part_id: string | null;
+  part_description: string | null;
+  customer_name: string | null;
+  work_order_status: string | null;
+  source: string;
+}
+
+export interface NcrListItem {
+  id: number;
+  ncr_number: string;
+  job_number: string;
+  department: string;
+  deviation_category: string;
+  requester: string;
+  disposition_authority: string;
+  stage: StageValue;
+  stage_label: string;
+  days_in_stage: number;
+  created_at: string;
+}
+
+export interface NcrListOut {
+  items: NcrListItem[];
+  total: number;
+  page: number;
+  page_size: number;
+}
+
+export type NcrAction =
+  | "initial_disposition"
+  | "secondary_disposition"
+  | "operations_complete"
+  | "inspection"
+  | "costing"
+  | "reopen"
+  | "add_attachment"
+  | "view_audit";
+
+export interface NcrDetail {
+  id: number;
+  ncr_number: string;
+  job_number: string;
+  created_at: string;
+  stage: StageValue;
+  stage_label: string;
+  stage_entered_at: string;
+  days_in_stage: number;
+  department: string;
+  department_id: number;
+  deviation_category: string;
+  deviation_category_id: number;
+  deviation_detail: string;
+  requester: UserRef;
+  disposition_authority: UserRef;
+  qc_authority: string | null;
+  work_order: string | null;
+  disposition_notes: string | null;
+  secondary_review_needed: boolean | null;
+  secondary_authorities: UserRef[];
+  operations_complete: boolean;
+  operations_completed_at: string | null;
+  operations_completed_by: UserRef | null;
+  qc_approval: "yes" | "no" | null;
+  inspection_notes: string | null;
+  qc_closed: boolean;
+  qc_closed_at: string | null;
+  qc_closed_by: UserRef | null;
+  labor_cost: string | null;
+  material_cost: string | null;
+  service_cost: string | null;
+  other_cost: string | null;
+  total_cost: string | null;
+  costing_completed_at: string | null;
+  costing_completed_by: UserRef | null;
+  closed_at: string | null;
+  closed_by: UserRef | null;
+  job_info: JobInfoOut | null;
+  attachments: AttachmentOut[];
+  transitions: TransitionOut[];
+  available_actions: NcrAction[];
+}
+
+export interface NcrMutationOut {
+  ncr: NcrDetail;
+  warnings: string[];
+}
+
+export interface AuditEntry {
+  id: number;
+  created_at: string;
+  user: UserRef;
+  action: string;
+  field_name: string | null;
+  old_value: string | null;
+  new_value: string | null;
+  detail: string | null;
+}
+
+export interface AuditListOut {
+  items: AuditEntry[];
+  total: number;
+}
+
+export interface QueueFilters {
+  q?: string;
+  job_number?: string;
+  department_id?: number;
+  category_id?: number;
+  stage?: string;
+  date_from?: string;
+  date_to?: string;
+  disposition_authority_id?: number;
+}
+
+export interface ReportsSummary {
+  total_ncrs: number;
+  open_ncrs: number;
+  closed_ncrs: number;
+  total_cost: string;
+  by_department: { name: string; count: number }[];
+  by_category: { name: string; count: number }[];
+  by_month: { month: string; count: number }[];
+  cost_over_time: {
+    month: string;
+    labor: string;
+    material: string;
+    service: string;
+    other: string;
+    total: string;
+  }[];
+  aging: { bucket: string; count: number }[];
+  cycle_times: {
+    stage: StageValue;
+    stage_label: string;
+    avg_days: number;
+    samples: number;
+  }[];
+  end_to_end_avg_days: number | null;
+  top_jobs: { job_number: string; count: number }[];
+}
+
+export interface JobLookupOut {
+  found: boolean;
+  job_number: string;
+  part_id?: string | null;
+  part_description?: string | null;
+  customer_name?: string | null;
+  work_order_status?: string | null;
+  source?: string;
+}

frontend/src/auth/AuthGate.tsx

@@ -0,0 +1,117 @@
+import {
+  Alert,
+  Box,
+  Button,
+  CircularProgress,
+  Stack,
+  Typography,
+} from "@mui/material";
+import { MsalProvider, useIsAuthenticated, useMsal } from "@azure/msal-react";
+import type { ReactNode } from "react";
+import { useEffect } from "react";
+import { msalInstance } from "../api/client";
+import { ApiError } from "../api/client";
+import { useMe } from "../api/hooks";
+import { config } from "../config";
+
+function Centered({ children }: { children: ReactNode }) {
+  return (
+    <Box
+      sx={{
+        minHeight: "100vh",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        p: 2,
+      }}
+    >
+      <Stack spacing={2} alignItems="center" sx={{ maxWidth: 480 }}>
+        {children}
+      </Stack>
+    </Box>
+  );
+}
+
+/** After sign-in (or in dev mode), /api/me must succeed before the app loads:
+ * it auto-provisions the user and enforces the front-door group. */
+function MeGate({ children }: { children: ReactNode }) {
+  const me = useMe();
+
+  if (me.isLoading) {
+    return (
+      <Centered>
+        <CircularProgress />
+        <Typography color="text.secondary">Signing you in…</Typography>
+      </Centered>
+    );
+  }
+  if (me.isError) {
+    const err = me.error;
+    const detail =
+      err instanceof ApiError ? err.message : "Could not reach the NCR API.";
+    const denied = err instanceof ApiError && err.status === 403;
+    return (
+      <Centered>
+        <Typography variant="h5">PESCO NCR</Typography>
+        <Alert severity={denied ? "warning" : "error"} sx={{ width: "100%" }}>
+          {denied ? "Access denied. " : ""}
+          {detail}
+        </Alert>
+        {denied && (
+          <Typography color="text.secondary" variant="body2">
+            Ask IT to add you to the NCR access group, then sign in again.
+          </Typography>
+        )}
+        <Button variant="contained" onClick={() => me.refetch()}>
+          Try again
+        </Button>
+      </Centered>
+    );
+  }
+  return <>{children}</>;
+}
+
+function EntraGate({ children }: { children: ReactNode }) {
+  const isAuthenticated = useIsAuthenticated();
+  const { instance, inProgress } = useMsal();
+
+  useEffect(() => {
+    if (!isAuthenticated && inProgress === "none") {
+      void instance.loginRedirect({ scopes: [config.apiScope] });
+    }
+  }, [isAuthenticated, inProgress, instance]);
+
+  if (!isAuthenticated) {
+    return (
+      <Centered>
+        <CircularProgress />
+        <Typography color="text.secondary">
+          Redirecting to Microsoft sign-in…
+        </Typography>
+      </Centered>
+    );
+  }
+  return <MeGate>{children}</MeGate>;
+}
+
+export function AuthGate({ children }: { children: ReactNode }) {
+  if (config.authMode === "dev") {
+    return <MeGate>{children}</MeGate>;
+  }
+  if (!config.clientId || !config.tenantId) {
+    return (
+      <Centered>
+        <Typography variant="h5">PESCO NCR</Typography>
+        <Alert severity="error">
+          Entra ID is not configured. Set ENTRA_TENANT_ID and ENTRA_CLIENT_ID in
+          .env (see README), or set AUTH_MODE=dev for local development.
+        </Alert>
+      </Centered>
+    );
+  }
+  return (
+    <MsalProvider instance={msalInstance!}>
+      <EntraGate>{children}</EntraGate>
+    </MsalProvider>
+  );
+}

frontend/src/components/AttachmentSection.tsx

@@ -0,0 +1,189 @@
+import AttachFileIcon from "@mui/icons-material/AttachFile";
+import DescriptionIcon from "@mui/icons-material/Description";
+import PhotoCameraIcon from "@mui/icons-material/PhotoCamera";
+import {
+  Box,
+  Button,
+  CircularProgress,
+  Dialog,
+  DialogContent,
+  Stack,
+  Tooltip,
+  Typography,
+} from "@mui/material";
+import { useQuery } from "@tanstack/react-query";
+import { useRef, useState } from "react";
+import { apiBlob, openBlob } from "../api/client";
+import { useUploadAttachments } from "../api/hooks";
+import type { AttachmentOut } from "../api/types";
+import { useToast } from "./Toast";
+
+/** Images are behind the authenticated API, so <img src> can't load them
+ * directly — fetch as a blob and use an object URL. */
+function useAttachmentUrl(att: AttachmentOut, enabled: boolean) {
+  return useQuery({
+    queryKey: ["attachment-blob", att.id],
+    queryFn: async () => {
+      const blob = await apiBlob(`/api/attachments/${att.id}/download`);
+      return URL.createObjectURL(blob);
+    },
+    enabled,
+    staleTime: Infinity,
+    gcTime: 10 * 60_000,
+  });
+}
+
+function Thumbnail({ att, onOpen }: { att: AttachmentOut; onOpen: (url: string) => void }) {
+  const url = useAttachmentUrl(att, att.is_image);
+
+  if (!att.is_image) {
+    return (
+      <Tooltip title={`${att.original_filename} — click to download`}>
+        <Box
+          onClick={() => void openBlob(`/api/attachments/${att.id}/download`, att.original_filename, "download")}
+          sx={{
+            width: 96,
+            height: 96,
+            border: "1px solid",
+            borderColor: "divider",
+            borderRadius: 1,
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            justifyContent: "center",
+            cursor: "pointer",
+            p: 0.5,
+          }}
+        >
+          <DescriptionIcon color="action" />
+          <Typography variant="caption" noWrap sx={{ maxWidth: 88 }}>
+            {att.original_filename}
+          </Typography>
+        </Box>
+      </Tooltip>
+    );
+  }
+
+  return (
+    <Tooltip
+      title={`${att.original_filename} — ${att.uploaded_by.display_name}, ${new Date(att.uploaded_at).toLocaleString()}`}
+    >
+      <Box
+        onClick={() => url.data && onOpen(url.data)}
+        sx={{
+          width: 96,
+          height: 96,
+          borderRadius: 1,
+          overflow: "hidden",
+          border: "1px solid",
+          borderColor: "divider",
+          cursor: "pointer",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          bgcolor: "#fafafa",
+        }}
+      >
+        {url.data ? (
+          <img
+            src={url.data}
+            alt={att.original_filename}
+            style={{ width: "100%", height: "100%", objectFit: "cover" }}
+          />
+        ) : (
+          <CircularProgress size={20} />
+        )}
+      </Box>
+    </Tooltip>
+  );
+}
+
+interface Props {
+  ncrId: number;
+  attachments: AttachmentOut[];
+  canAdd: boolean;
+}
+
+export function AttachmentSection({ ncrId, attachments, canAdd }: Props) {
+  const upload = useUploadAttachments(ncrId);
+  const { toast } = useToast();
+  const fileInput = useRef<HTMLInputElement>(null);
+  const cameraInput = useRef<HTMLInputElement>(null);
+  const [lightbox, setLightbox] = useState<string | null>(null);
+
+  const handleFiles = (list: FileList | null) => {
+    if (!list || list.length === 0) return;
+    upload.mutate(Array.from(list), {
+      onSuccess: (items) =>
+        toast(`${items.length} attachment${items.length > 1 ? "s" : ""} added.`),
+      onError: (err) => toast(err.message, "error"),
+    });
+    if (fileInput.current) fileInput.current.value = "";
+    if (cameraInput.current) cameraInput.current.value = "";
+  };
+
+  return (
+    <Box>
+      <Stack direction="row" spacing={1} flexWrap="wrap" useFlexGap sx={{ mb: 1 }}>
+        {attachments.map((att) => (
+          <Thumbnail key={att.id} att={att} onOpen={setLightbox} />
+        ))}
+        {attachments.length === 0 && (
+          <Typography color="text.secondary" variant="body2">
+            No attachments yet.
+          </Typography>
+        )}
+      </Stack>
+
+      {canAdd && (
+        <Stack direction="row" spacing={1}>
+          <Button
+            startIcon={<PhotoCameraIcon />}
+            variant="outlined"
+            onClick={() => cameraInput.current?.click()}
+            disabled={upload.isPending}
+          >
+            Take Photo
+          </Button>
+          <Button
+            startIcon={upload.isPending ? <CircularProgress size={16} /> : <AttachFileIcon />}
+            variant="outlined"
+            onClick={() => fileInput.current?.click()}
+            disabled={upload.isPending}
+          >
+            Add Files
+          </Button>
+          {/* capture="environment" opens the rear camera on tablets/phones */}
+          <input
+            ref={cameraInput}
+            type="file"
+            accept="image/*"
+            capture="environment"
+            hidden
+            onChange={(e) => handleFiles(e.target.files)}
+          />
+          <input
+            ref={fileInput}
+            type="file"
+            multiple
+            accept="image/*,.pdf,.doc,.docx,.xls,.xlsx,.csv,.txt,.msg,.eml"
+            hidden
+            onChange={(e) => handleFiles(e.target.files)}
+          />
+        </Stack>
+      )}
+
+      <Dialog open={lightbox !== null} onClose={() => setLightbox(null)} maxWidth="lg">
+        <DialogContent sx={{ p: 0.5 }}>
+          {lightbox && (
+            <img
+              src={lightbox}
+              alt="attachment"
+              style={{ maxWidth: "90vw", maxHeight: "85vh", display: "block" }}
+            />
+          )}
+        </DialogContent>
+      </Dialog>
+    </Box>
+  );
+}

frontend/src/components/FieldRow.tsx

@@ -0,0 +1,14 @@
+import { Grid, Typography } from "@mui/material";
+import type { ReactNode } from "react";
+
+/** Label/value pair used across the NCR detail read-only sections. */
+export function FieldRow({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <Grid item xs={12} sm={6} md={4}>
+      <Typography variant="caption" color="text.secondary" display="block">
+        {label}
+      </Typography>
+      <Typography component="div">{children || "—"}</Typography>
+    </Grid>
+  );
+}

frontend/src/components/JobNumberField.tsx

@@ -0,0 +1,46 @@
+import { Chip, Stack, TextField } from "@mui/material";
+import { useEffect, useState } from "react";
+import { useJobLookup } from "../api/hooks";
+
+interface Props {
+  value: string;
+  onChange: (v: string) => void;
+  required?: boolean;
+}
+
+/** Job number entry. Free text today (NullJobLookupService); when the VISUAL
+ * provider is enabled the enrichment chips below light up automatically —
+ * no redesign needed. */
+export function JobNumberField({ value, onChange, required }: Props) {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setDebounced(value), 400);
+    return () => clearTimeout(t);
+  }, [value]);
+
+  const lookup = useJobLookup(debounced);
+  const info = lookup.data;
+
+  return (
+    <Stack spacing={0.5}>
+      <TextField
+        label="Job Number"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        required={required}
+        inputProps={{ maxLength: 100 }}
+      />
+      {info?.found && (
+        <Stack direction="row" spacing={0.5} flexWrap="wrap" useFlexGap>
+          {info.part_id && <Chip size="small" label={`Part: ${info.part_id}`} />}
+          {info.customer_name && (
+            <Chip size="small" label={`Customer: ${info.customer_name}`} />
+          )}
+          {info.work_order_status && (
+            <Chip size="small" label={`WO Status: ${info.work_order_status}`} />
+          )}
+        </Stack>
+      )}
+    </Stack>
+  );
+}

frontend/src/components/Layout.tsx

@@ -0,0 +1,197 @@
+import AddCircleIcon from "@mui/icons-material/AddCircle";
+import AdminPanelSettingsIcon from "@mui/icons-material/AdminPanelSettings";
+import AssessmentIcon from "@mui/icons-material/Assessment";
+import DashboardIcon from "@mui/icons-material/Dashboard";
+import MenuIcon from "@mui/icons-material/Menu";
+import SearchIcon from "@mui/icons-material/Search";
+import {
+  AppBar,
+  Avatar,
+  Box,
+  Divider,
+  Drawer,
+  IconButton,
+  List,
+  ListItemButton,
+  ListItemIcon,
+  ListItemText,
+  MenuItem,
+  Select,
+  Toolbar,
+  Tooltip,
+  Typography,
+  useMediaQuery,
+  useTheme,
+} from "@mui/material";
+import type { ReactNode } from "react";
+import { useState } from "react";
+import { useLocation, useNavigate } from "react-router-dom";
+import { getDevUser, setDevUser } from "../api/client";
+import { useMe } from "../api/hooks";
+import { config } from "../config";
+
+const DRAWER_WIDTH = 232;
+
+const DEV_USERS = [
+  "admin@pescoinc.biz",
+  "dispo@pescoinc.biz",
+  "second@pescoinc.biz",
+  "ops@pescoinc.biz",
+  "qc@pescoinc.biz",
+  "cost@pescoinc.biz",
+  "req@pescoinc.biz",
+];
+
+function DevUserSwitcher() {
+  return (
+    <Tooltip title="AUTH_MODE=dev — switch the simulated user">
+      <Select
+        size="small"
+        value={getDevUser()}
+        onChange={(e) => {
+          setDevUser(e.target.value);
+          window.location.reload();
+        }}
+        sx={{
+          mr: 1,
+          bgcolor: "rgba(255,255,255,0.15)",
+          color: "#fff",
+          ".MuiSvgIcon-root": { color: "#fff" },
+          fontSize: 13,
+        }}
+      >
+        {DEV_USERS.map((u) => (
+          <MenuItem key={u} value={u}>
+            {u.split("@")[0]}
+          </MenuItem>
+        ))}
+      </Select>
+    </Tooltip>
+  );
+}
+
+export function Layout({ children }: { children: ReactNode }) {
+  const theme = useTheme();
+  const isDesktop = useMediaQuery(theme.breakpoints.up("md"));
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const navigate = useNavigate();
+  const location = useLocation();
+  const me = useMe();
+  const isAdmin = me.data?.roles.includes("admin") ?? false;
+
+  const nav = [
+    { label: "Dashboard", icon: <DashboardIcon />, path: "/" },
+    { label: "New NCR", icon: <AddCircleIcon />, path: "/ncrs/new" },
+    { label: "Search", icon: <SearchIcon />, path: "/search" },
+    { label: "Reports", icon: <AssessmentIcon />, path: "/reports" },
+    ...(isAdmin
+      ? [{ label: "Admin", icon: <AdminPanelSettingsIcon />, path: "/admin" }]
+      : []),
+  ];
+
+  const drawer = (
+    <Box sx={{ pt: 1 }}>
+      <Toolbar sx={{ minHeight: { xs: 56, md: 64 } }}>
+        <Typography variant="h6" color="primary">
+          PESCO NCR
+        </Typography>
+      </Toolbar>
+      <Divider />
+      <List>
+        {nav.map((item) => {
+          const selected =
+            item.path === "/"
+              ? location.pathname === "/"
+              : location.pathname.startsWith(item.path);
+          return (
+            <ListItemButton
+              key={item.path}
+              selected={selected}
+              onClick={() => {
+                navigate(item.path);
+                setMobileOpen(false);
+              }}
+              sx={{ minHeight: 48 }}
+            >
+              <ListItemIcon>{item.icon}</ListItemIcon>
+              <ListItemText primary={item.label} />
+            </ListItemButton>
+          );
+        })}
+      </List>
+    </Box>
+  );
+
+  return (
+    <Box sx={{ display: "flex", minHeight: "100vh" }}>
+      <AppBar
+        position="fixed"
+        sx={{ zIndex: theme.zIndex.drawer + 1 }}
+        elevation={1}
+      >
+        <Toolbar sx={{ minHeight: { xs: 56, md: 64 } }}>
+          {!isDesktop && (
+            <IconButton
+              color="inherit"
+              edge="start"
+              onClick={() => setMobileOpen(true)}
+              sx={{ mr: 1 }}
+            >
+              <MenuIcon />
+            </IconButton>
+          )}
+          <Typography variant="h6" sx={{ flexGrow: 1 }} noWrap>
+            Non-Conformance Reports
+          </Typography>
+          {config.authMode === "dev" && <DevUserSwitcher />}
+          {me.data && (
+            <Tooltip title={`${me.data.display_name} (${me.data.email})`}>
+              <Avatar sx={{ bgcolor: "secondary.main", width: 36, height: 36 }}>
+                {me.data.display_name
+                  .split(" ")
+                  .map((p) => p[0])
+                  .slice(0, 2)
+                  .join("")}
+              </Avatar>
+            </Tooltip>
+          )}
+        </Toolbar>
+      </AppBar>
+
+      {isDesktop ? (
+        <Drawer
+          variant="permanent"
+          sx={{
+            width: DRAWER_WIDTH,
+            flexShrink: 0,
+            "& .MuiDrawer-paper": { width: DRAWER_WIDTH, boxSizing: "border-box" },
+          }}
+        >
+          {drawer}
+        </Drawer>
+      ) : (
+        <Drawer
+          variant="temporary"
+          open={mobileOpen}
+          onClose={() => setMobileOpen(false)}
+          ModalProps={{ keepMounted: true }}
+          sx={{ "& .MuiDrawer-paper": { width: DRAWER_WIDTH } }}
+        >
+          {drawer}
+        </Drawer>
+      )}
+
+      <Box
+        component="main"
+        sx={{
+          flexGrow: 1,
+          p: { xs: 1.5, sm: 2, md: 3 },
+          width: { md: `calc(100% - ${DRAWER_WIDTH}px)` },
+          mt: { xs: "56px", md: "64px" },
+        }}
+      >
+        {children}
+      </Box>
+    </Box>
+  );
+}

frontend/src/components/QueueTable.tsx

@@ -0,0 +1,144 @@
+import {
+  Box,
+  Card,
+  CardActionArea,
+  CardContent,
+  CircularProgress,
+  Stack,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TablePagination,
+  TableRow,
+  Typography,
+  useMediaQuery,
+  useTheme,
+} from "@mui/material";
+import { useNavigate } from "react-router-dom";
+import type { NcrListItem } from "../api/types";
+import { StageChip } from "./StageChip";
+
+function fmtDate(iso: string): string {
+  return new Date(iso).toLocaleDateString();
+}
+
+interface Props {
+  items: NcrListItem[];
+  total: number;
+  page: number; // 1-based
+  pageSize: number;
+  onPageChange: (page: number) => void;
+  loading?: boolean;
+}
+
+/** Responsive queue view: a dense table on desktop, tap-friendly cards on
+ * phones/tablets in portrait. */
+export function QueueTable({ items, total, page, pageSize, onPageChange, loading }: Props) {
+  const theme = useTheme();
+  const isSmall = useMediaQuery(theme.breakpoints.down("md"));
+  const navigate = useNavigate();
+
+  if (loading && items.length === 0) {
+    return (
+      <Box sx={{ py: 6, textAlign: "center" }}>
+        <CircularProgress />
+      </Box>
+    );
+  }
+  if (items.length === 0) {
+    return (
+      <Typography color="text.secondary" sx={{ py: 4, textAlign: "center" }}>
+        No NCRs in this queue.
+      </Typography>
+    );
+  }
+
+  const pagination = (
+    <TablePagination
+      component="div"
+      count={total}
+      page={page - 1}
+      onPageChange={(_, p) => onPageChange(p + 1)}
+      rowsPerPage={pageSize}
+      rowsPerPageOptions={[pageSize]}
+    />
+  );
+
+  if (isSmall) {
+    return (
+      <Box>
+        <Stack spacing={1}>
+          {items.map((n) => (
+            <Card key={n.id} variant="outlined">
+              <CardActionArea onClick={() => navigate(`/ncrs/${n.id}`)}>
+                <CardContent sx={{ py: 1.5 }}>
+                  <Stack
+                    direction="row"
+                    justifyContent="space-between"
+                    alignItems="center"
+                  >
+                    <Typography fontWeight={700}>{n.ncr_number}</Typography>
+                    <StageChip stage={n.stage} />
+                  </Stack>
+                  <Typography variant="body2" color="text.secondary">
+                    Job {n.job_number} · {n.department} · {n.deviation_category}
+                  </Typography>
+                  <Typography variant="body2" color="text.secondary">
+                    {n.requester} · {fmtDate(n.created_at)} · {n.days_in_stage}d in
+                    stage
+                  </Typography>
+                </CardContent>
+              </CardActionArea>
+            </Card>
+          ))}
+        </Stack>
+        {pagination}
+      </Box>
+    );
+  }
+
+  return (
+    <Box>
+      <TableContainer>
+        <Table size="small">
+          <TableHead>
+            <TableRow>
+              <TableCell>NCR #</TableCell>
+              <TableCell>Job #</TableCell>
+              <TableCell>Department</TableCell>
+              <TableCell>Requester</TableCell>
+              <TableCell>Category</TableCell>
+              <TableCell>Stage</TableCell>
+              <TableCell align="right">Days in Stage</TableCell>
+              <TableCell align="right">Created</TableCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {items.map((n) => (
+              <TableRow
+                key={n.id}
+                hover
+                sx={{ cursor: "pointer" }}
+                onClick={() => navigate(`/ncrs/${n.id}`)}
+              >
+                <TableCell sx={{ fontWeight: 700 }}>{n.ncr_number}</TableCell>
+                <TableCell>{n.job_number}</TableCell>
+                <TableCell>{n.department}</TableCell>
+                <TableCell>{n.requester}</TableCell>
+                <TableCell>{n.deviation_category}</TableCell>
+                <TableCell>
+                  <StageChip stage={n.stage} />
+                </TableCell>
+                <TableCell align="right">{n.days_in_stage}</TableCell>
+                <TableCell align="right">{fmtDate(n.created_at)}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </TableContainer>
+      {pagination}
+    </Box>
+  );
+}

frontend/src/components/RichTextEditor.tsx

@@ -0,0 +1,141 @@
+import FormatBoldIcon from "@mui/icons-material/FormatBold";
+import FormatItalicIcon from "@mui/icons-material/FormatItalic";
+import FormatListBulletedIcon from "@mui/icons-material/FormatListBulleted";
+import FormatListNumberedIcon from "@mui/icons-material/FormatListNumbered";
+import LinkIcon from "@mui/icons-material/Link";
+import RedoIcon from "@mui/icons-material/Redo";
+import StrikethroughSIcon from "@mui/icons-material/StrikethroughS";
+import UndoIcon from "@mui/icons-material/Undo";
+import { Box, Divider, ToggleButton, Typography } from "@mui/material";
+import Link from "@tiptap/extension-link";
+import { EditorContent, useEditor } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { useEffect } from "react";
+
+interface Props {
+  label?: string;
+  value: string;
+  onChange: (html: string) => void;
+  minHeight?: number;
+}
+
+/** Rich-text editor for disposition notes. Output HTML is sanitized again
+ * server-side (nh3) before storage. */
+export function RichTextEditor({ label, value, onChange, minHeight = 140 }: Props) {
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      Link.configure({ openOnClick: false, autolink: true }),
+    ],
+    content: value,
+    onUpdate: ({ editor }) => onChange(editor.getHTML()),
+  });
+
+  useEffect(() => {
+    if (editor && value !== editor.getHTML() && !editor.isFocused) {
+      editor.commands.setContent(value || "", false);
+    }
+  }, [value, editor]);
+
+  if (!editor) return null;
+
+  const btn = (
+    active: boolean,
+    onClick: () => void,
+    icon: React.ReactNode,
+    title: string,
+  ) => (
+    <ToggleButton
+      value={title}
+      selected={active}
+      onMouseDown={(e) => {
+        e.preventDefault();
+        onClick();
+      }}
+      size="small"
+      sx={{ border: 0, px: 1 }}
+      title={title}
+    >
+      {icon}
+    </ToggleButton>
+  );
+
+  return (
+    <Box>
+      {label && (
+        <Typography variant="caption" color="text.secondary">
+          {label}
+        </Typography>
+      )}
+      <Box
+        sx={{
+          border: "1px solid",
+          borderColor: "divider",
+          borderRadius: 1,
+          "&:focus-within": { borderColor: "primary.main" },
+        }}
+      >
+        <Box sx={{ display: "flex", flexWrap: "wrap", p: 0.5, gap: 0.25 }}>
+          {btn(
+            editor.isActive("bold"),
+            () => editor.chain().focus().toggleBold().run(),
+            <FormatBoldIcon fontSize="small" />,
+            "Bold",
+          )}
+          {btn(
+            editor.isActive("italic"),
+            () => editor.chain().focus().toggleItalic().run(),
+            <FormatItalicIcon fontSize="small" />,
+            "Italic",
+          )}
+          {btn(
+            editor.isActive("strike"),
+            () => editor.chain().focus().toggleStrike().run(),
+            <StrikethroughSIcon fontSize="small" />,
+            "Strikethrough",
+          )}
+          {btn(
+            editor.isActive("bulletList"),
+            () => editor.chain().focus().toggleBulletList().run(),
+            <FormatListBulletedIcon fontSize="small" />,
+            "Bullet list",
+          )}
+          {btn(
+            editor.isActive("orderedList"),
+            () => editor.chain().focus().toggleOrderedList().run(),
+            <FormatListNumberedIcon fontSize="small" />,
+            "Numbered list",
+          )}
+          {btn(
+            editor.isActive("link"),
+            () => {
+              if (editor.isActive("link")) {
+                editor.chain().focus().unsetLink().run();
+                return;
+              }
+              const url = window.prompt("Link URL (https://…)");
+              if (url) editor.chain().focus().setLink({ href: url }).run();
+            },
+            <LinkIcon fontSize="small" />,
+            "Link",
+          )}
+          <Divider flexItem orientation="vertical" sx={{ mx: 0.5 }} />
+          {btn(false, () => editor.chain().focus().undo().run(), <UndoIcon fontSize="small" />, "Undo")}
+          {btn(false, () => editor.chain().focus().redo().run(), <RedoIcon fontSize="small" />, "Redo")}
+        </Box>
+        <Divider />
+        <Box
+          sx={{
+            px: 1.5,
+            py: 1,
+            minHeight,
+            "& .ProseMirror": { outline: "none", minHeight: minHeight - 20 },
+            "& .ProseMirror p": { m: 0, mb: 0.5 },
+          }}
+        >
+          <EditorContent editor={editor} />
+        </Box>
+      </Box>
+    </Box>
+  );
+}

frontend/src/components/RichTextView.tsx

@@ -0,0 +1,16 @@
+import { Box } from "@mui/material";
+
+/** Renders server-sanitized rich text (the API cleans all HTML with nh3
+ * before storing it, so this content is trusted). */
+export function RichTextView({ html }: { html: string }) {
+  return (
+    <Box
+      sx={{
+        "& p": { mt: 0, mb: 0.75 },
+        "& ul, & ol": { mt: 0, pl: 3 },
+        wordBreak: "break-word",
+      }}
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+}

frontend/src/components/StageChip.tsx

@@ -0,0 +1,21 @@
+import { Chip } from "@mui/material";
+import type { StageValue } from "../api/types";
+import { STAGE_LABELS } from "../api/types";
+import { STAGE_COLORS } from "../theme";
+
+export function StageChip({
+  stage,
+  size = "small",
+}: {
+  stage: StageValue;
+  size?: "small" | "medium";
+}) {
+  const colors = STAGE_COLORS[stage] ?? { bg: "#eee", fg: "#333" };
+  return (
+    <Chip
+      label={STAGE_LABELS[stage] ?? stage}
+      size={size}
+      sx={{ bgcolor: colors.bg, color: colors.fg, fontWeight: 600 }}
+    />
+  );
+}

frontend/src/components/StageStepper.tsx

@@ -0,0 +1,30 @@
+import { Step, StepLabel, Stepper, useMediaQuery, useTheme } from "@mui/material";
+import type { NcrDetail } from "../api/types";
+import { STAGE_LABELS, STAGE_ORDER } from "../api/types";
+
+/** Visual progress through the workflow. Secondary Disposition is only shown
+ * when that route was taken. */
+export function StageStepper({ ncr }: { ncr: NcrDetail }) {
+  const theme = useTheme();
+  const isSmall = useMediaQuery(theme.breakpoints.down("md"));
+
+  const stages = STAGE_ORDER.filter(
+    (s) => s !== "secondary_disposition" || ncr.secondary_review_needed,
+  );
+  const activeIndex = stages.indexOf(ncr.stage);
+
+  return (
+    <Stepper
+      activeStep={ncr.stage === "closed" ? stages.length : activeIndex}
+      alternativeLabel={!isSmall}
+      orientation={isSmall ? "vertical" : "horizontal"}
+      sx={{ my: 1 }}
+    >
+      {stages.map((s) => (
+        <Step key={s} completed={stages.indexOf(s) < activeIndex || ncr.stage === "closed"}>
+          <StepLabel>{STAGE_LABELS[s]}</StepLabel>
+        </Step>
+      ))}
+    </Stepper>
+  );
+}

frontend/src/components/Toast.tsx

@@ -0,0 +1,74 @@
+import { Alert, Snackbar, Stack } from "@mui/material";
+import type { ReactNode } from "react";
+import { createContext, useCallback, useContext, useState } from "react";
+
+type Severity = "success" | "info" | "warning" | "error";
+
+interface Toast {
+  id: number;
+  message: string;
+  severity: Severity;
+}
+
+interface ToastContextValue {
+  toast: (message: string, severity?: Severity) => void;
+  warnings: (messages: string[]) => void;
+}
+
+const ToastContext = createContext<ToastContextValue>({
+  toast: () => {},
+  warnings: () => {},
+});
+
+export function useToast(): ToastContextValue {
+  return useContext(ToastContext);
+}
+
+let nextId = 1;
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<Toast[]>([]);
+
+  const toast = useCallback((message: string, severity: Severity = "success") => {
+    setToasts((prev) => [...prev, { id: nextId++, message, severity }]);
+  }, []);
+
+  const warnings = useCallback(
+    (messages: string[]) => {
+      for (const m of messages) toast(m, "warning");
+    },
+    [toast],
+  );
+
+  const dismiss = (id: number) =>
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+
+  return (
+    <ToastContext.Provider value={{ toast, warnings }}>
+      {children}
+      <Stack
+        spacing={1}
+        sx={{ position: "fixed", bottom: 16, left: 16, zIndex: 2000, maxWidth: 420 }}
+      >
+        {toasts.map((t) => (
+          <Snackbar
+            key={t.id}
+            open
+            autoHideDuration={t.severity === "warning" ? 10000 : 4000}
+            onClose={() => dismiss(t.id)}
+            sx={{ position: "static", transform: "none" }}
+          >
+            <Alert
+              severity={t.severity}
+              onClose={() => dismiss(t.id)}
+              variant="filled"
+              sx={{ width: "100%" }}
+            >
+              {t.message}
+            </Alert>
+          </Snackbar>
+        ))}
+      </Stack>
+    </ToastContext.Provider>
+  );
+}

frontend/src/components/UserPicker.tsx

@@ -0,0 +1,46 @@
+import { Autocomplete, TextField } from "@mui/material";
+import { useUsersByRole } from "../api/hooks";
+import type { UserOut } from "../api/types";
+
+interface Props {
+  role: string;
+  label: string;
+  multiple?: boolean;
+  value: UserOut[] | UserOut | null;
+  onChange: (value: UserOut[] | UserOut | null) => void;
+  helperText?: string;
+  required?: boolean;
+}
+
+/** Picker over users holding a given in-app role (drives the Disposition
+ * Authority dropdown and "Notify These People"). */
+export function UserPicker({
+  role,
+  label,
+  multiple = false,
+  value,
+  onChange,
+  helperText,
+  required,
+}: Props) {
+  const users = useUsersByRole(role);
+  return (
+    <Autocomplete
+      multiple={multiple}
+      options={users.data ?? []}
+      loading={users.isLoading}
+      value={value as never}
+      onChange={(_, v) => onChange(v as never)}
+      getOptionLabel={(u: UserOut) => u.display_name}
+      isOptionEqualToValue={(a: UserOut, b: UserOut) => a.id === b.id}
+      renderInput={(params) => (
+        <TextField
+          {...params}
+          label={label}
+          helperText={helperText}
+          required={required}
+        />
+      )}
+    />
+  );
+}

frontend/src/config.ts

@@ -0,0 +1,22 @@
+export interface AppConfig {
+  authMode: "entra" | "dev";
+  tenantId: string;
+  clientId: string;
+  apiScope: string;
+}
+
+declare global {
+  interface Window {
+    __APP_CONFIG__?: Partial<AppConfig>;
+  }
+}
+
+const w = window.__APP_CONFIG__ ?? {};
+
+export const config: AppConfig = {
+  authMode: w.authMode === "entra" ? "entra" : "dev",
+  tenantId: w.tenantId ?? "",
+  clientId: w.clientId ?? "",
+  apiScope:
+    w.apiScope || (w.clientId ? `api://${w.clientId}/access_as_user` : ""),
+};

frontend/src/main.tsx

@@ -0,0 +1,48 @@
+import { CssBaseline, ThemeProvider } from "@mui/material";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import App from "./App";
+import { msalInstance } from "./api/client";
+import { AuthGate } from "./auth/AuthGate";
+import { ToastProvider } from "./components/Toast";
+import { theme } from "./theme";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { retry: 1, refetchOnWindowFocus: false },
+  },
+});
+
+async function bootstrap() {
+  if (msalInstance) {
+    await msalInstance.initialize();
+    const result = await msalInstance.handleRedirectPromise();
+    if (result?.account) {
+      msalInstance.setActiveAccount(result.account);
+    } else {
+      const accounts = msalInstance.getAllAccounts();
+      if (accounts.length > 0) msalInstance.setActiveAccount(accounts[0]);
+    }
+  }
+
+  ReactDOM.createRoot(document.getElementById("root")!).render(
+    <React.StrictMode>
+      <ThemeProvider theme={theme}>
+        <CssBaseline />
+        <QueryClientProvider client={queryClient}>
+          <BrowserRouter>
+            <ToastProvider>
+              <AuthGate>
+                <App />
+              </AuthGate>
+            </ToastProvider>
+          </BrowserRouter>
+        </QueryClientProvider>
+      </ThemeProvider>
+    </React.StrictMode>,
+  );
+}
+
+void bootstrap();

frontend/src/pages/DashboardPage.tsx

@@ -0,0 +1,186 @@
+import AddIcon from "@mui/icons-material/Add";
+import DownloadIcon from "@mui/icons-material/Download";
+import {
+  Box,
+  Button,
+  Card,
+  CardContent,
+  MenuItem,
+  Stack,
+  Tab,
+  Tabs,
+  TextField,
+  Typography,
+} from "@mui/material";
+import { useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { buildQuery, openBlob } from "../api/client";
+import { useMe, useQueue, useUsersByRole } from "../api/hooks";
+import type { QueueFilters } from "../api/types";
+import { QueueTable } from "../components/QueueTable";
+import { useToast } from "../components/Toast";
+
+interface QueueDef {
+  key: string;
+  label: string;
+  visible: (roles: string[]) => boolean;
+}
+
+const QUEUES: QueueDef[] = [
+  { key: "my_requests", label: "My Requests", visible: () => true },
+  {
+    key: "new_requests",
+    label: "New Requests",
+    visible: (r) => r.includes("disposition_authority") || r.includes("admin"),
+  },
+  {
+    key: "secondary",
+    label: "My Secondary Queue",
+    visible: (r) =>
+      r.includes("secondary_disposition_authority") || r.includes("admin"),
+  },
+  {
+    key: "operations",
+    label: "Operations",
+    visible: (r) => r.includes("operations") || r.includes("admin"),
+  },
+  {
+    key: "inspection",
+    label: "QC Inspection",
+    visible: (r) => r.includes("qc_inspector") || r.includes("admin"),
+  },
+  {
+    key: "costing",
+    label: "Awaiting Costing",
+    visible: (r) => r.includes("costing") || r.includes("admin"),
+  },
+  { key: "recently_closed", label: "Recently Closed", visible: () => true },
+];
+
+export function DashboardPage() {
+  const me = useMe();
+  const navigate = useNavigate();
+  const { toast } = useToast();
+  const roles = useMemo(() => me.data?.roles ?? [], [me.data]);
+  const queues = useMemo(() => QUEUES.filter((q) => q.visible(roles)), [roles]);
+
+  const [tab, setTab] = useState(0);
+  const [page, setPage] = useState(1);
+  const [jobFilter, setJobFilter] = useState("");
+  const [authorityFilter, setAuthorityFilter] = useState<number | "">("");
+
+  const active = queues[Math.min(tab, queues.length - 1)];
+  const isNewRequests = active?.key === "new_requests";
+  const authorities = useUsersByRole("disposition_authority");
+
+  const filters: QueueFilters = isNewRequests
+    ? {
+        job_number: jobFilter || undefined,
+        disposition_authority_id: authorityFilter || undefined,
+      }
+    : {};
+
+  const queue = useQueue(active?.key ?? "my_requests", filters, page);
+
+  const exportCsv = () => {
+    void openBlob(
+      `/api/ncrs/export.csv${buildQuery({ queue: active.key, ...filters })}`,
+      `ncr-${active.key}.csv`,
+      "download",
+    ).catch((e) => toast(e.message, "error"));
+  };
+
+  return (
+    <Box>
+      <Stack
+        direction={{ xs: "column", sm: "row" }}
+        justifyContent="space-between"
+        alignItems={{ sm: "center" }}
+        spacing={1}
+        sx={{ mb: 2 }}
+      >
+        <Typography variant="h5">Dashboard</Typography>
+        <Button
+          variant="contained"
+          size="large"
+          startIcon={<AddIcon />}
+          onClick={() => navigate("/ncrs/new")}
+        >
+          New NCR
+        </Button>
+      </Stack>
+
+      <Card>
+        <Tabs
+          value={Math.min(tab, queues.length - 1)}
+          onChange={(_, v) => {
+            setTab(v);
+            setPage(1);
+          }}
+          variant="scrollable"
+          scrollButtons="auto"
+          sx={{ borderBottom: 1, borderColor: "divider" }}
+        >
+          {queues.map((q) => (
+            <Tab key={q.key} label={q.label} />
+          ))}
+        </Tabs>
+        <CardContent>
+          <Stack
+            direction={{ xs: "column", sm: "row" }}
+            spacing={1}
+            sx={{ mb: 1 }}
+            alignItems={{ sm: "center" }}
+          >
+            {isNewRequests && (
+              <>
+                <TextField
+                  size="small"
+                  label="Filter by job number"
+                  value={jobFilter}
+                  onChange={(e) => {
+                    setJobFilter(e.target.value);
+                    setPage(1);
+                  }}
+                />
+                <TextField
+                  size="small"
+                  select
+                  label="Disposition authority"
+                  value={authorityFilter}
+                  onChange={(e) => {
+                    setAuthorityFilter(
+                      e.target.value === "" ? "" : Number(e.target.value),
+                    );
+                    setPage(1);
+                  }}
+                  sx={{ minWidth: 220 }}
+                >
+                  <MenuItem value="">All</MenuItem>
+                  {(authorities.data ?? []).map((u) => (
+                    <MenuItem key={u.id} value={u.id}>
+                      {u.display_name}
+                    </MenuItem>
+                  ))}
+                </TextField>
+              </>
+            )}
+            <Box sx={{ flexGrow: 1 }} />
+            <Button startIcon={<DownloadIcon />} onClick={exportCsv}>
+              Export CSV
+            </Button>
+          </Stack>
+
+          <QueueTable
+            items={queue.data?.items ?? []}
+            total={queue.data?.total ?? 0}
+            page={page}
+            pageSize={25}
+            onPageChange={setPage}
+            loading={queue.isLoading}
+          />
+        </CardContent>
+      </Card>
+    </Box>
+  );
+}

frontend/src/pages/NcrDetailPage.tsx

@@ -0,0 +1,421 @@
+import HistoryIcon from "@mui/icons-material/History";
+import LockIcon from "@mui/icons-material/Lock";
+import LockOpenIcon from "@mui/icons-material/LockOpen";
+import PictureAsPdfIcon from "@mui/icons-material/PictureAsPdf";
+import {
+  Alert,
+  Box,
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  Chip,
+  CircularProgress,
+  Divider,
+  Grid,
+  Stack,
+  Tab,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+  Tabs,
+  Typography,
+} from "@mui/material";
+import { useState } from "react";
+import { useParams } from "react-router-dom";
+import { openBlob } from "../api/client";
+import { useMe, useNcr, useNcrAudit } from "../api/hooks";
+import type { NcrDetail } from "../api/types";
+import { STAGE_LABELS } from "../api/types";
+import { AttachmentSection } from "../components/AttachmentSection";
+import { FieldRow } from "../components/FieldRow";
+import { RichTextView } from "../components/RichTextView";
+import { StageChip } from "../components/StageChip";
+import { StageStepper } from "../components/StageStepper";
+import { useToast } from "../components/Toast";
+import {
+  CostingForm,
+  InitialDispositionForm,
+  InspectionForm,
+  OperationsForm,
+  ReopenDialog,
+  SecondaryDispositionForm,
+} from "./StageForms";
+
+function fmt(iso: string | null): string {
+  return iso ? new Date(iso).toLocaleString() : "—";
+}
+
+function money(v: string | null): string {
+  return v === null
+    ? "—"
+    : Number(v).toLocaleString(undefined, { style: "currency", currency: "USD" });
+}
+
+function SectionCard({
+  title,
+  action,
+  children,
+}: {
+  title: string;
+  action?: React.ReactNode;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card sx={{ mb: 2 }}>
+      <CardHeader title={title} action={action} titleTypographyProps={{ variant: "h6" }} />
+      <Divider />
+      <CardContent>{children}</CardContent>
+    </Card>
+  );
+}
+
+function AuditTab({ ncrId }: { ncrId: number }) {
+  const audit = useNcrAudit(ncrId, true);
+  if (audit.isLoading) return <CircularProgress sx={{ m: 2 }} />;
+  if (audit.isError)
+    return <Alert severity="error">{(audit.error as Error).message}</Alert>;
+  const items = audit.data?.items ?? [];
+  return (
+    <Table size="small">
+      <TableHead>
+        <TableRow>
+          <TableCell>When</TableCell>
+          <TableCell>Who</TableCell>
+          <TableCell>Action</TableCell>
+          <TableCell>Field</TableCell>
+          <TableCell>Before</TableCell>
+          <TableCell>After</TableCell>
+        </TableRow>
+      </TableHead>
+      <TableBody>
+        {items.map((a) => (
+          <TableRow key={a.id}>
+            <TableCell sx={{ whiteSpace: "nowrap" }}>{fmt(a.created_at)}</TableCell>
+            <TableCell>{a.user.display_name}</TableCell>
+            <TableCell>
+              <Chip size="small" label={a.action.replace(/_/g, " ")} />
+              {a.detail && (
+                <Typography variant="caption" display="block" color="text.secondary">
+                  {a.detail}
+                </Typography>
+              )}
+            </TableCell>
+            <TableCell>{a.field_name ?? ""}</TableCell>
+            <TableCell sx={{ maxWidth: 220, overflowWrap: "anywhere" }}>
+              {a.old_value ?? ""}
+            </TableCell>
+            <TableCell sx={{ maxWidth: 220, overflowWrap: "anywhere" }}>
+              {a.new_value ?? ""}
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+
+function DetailBody({ ncr }: { ncr: NcrDetail }) {
+  const actions = ncr.available_actions;
+  const closed = ncr.stage === "closed";
+
+  return (
+    <>
+      {closed && (
+        <Alert icon={<LockIcon />} severity="info" sx={{ mb: 2 }}>
+          This NCR is closed and locked. Closed on {fmt(ncr.closed_at)} by{" "}
+          {ncr.closed_by?.display_name}. Only an Admin can reopen it.
+        </Alert>
+      )}
+
+      <SectionCard title="Request">
+        <Grid container spacing={2}>
+          <FieldRow label="Job Number">{ncr.job_number}</FieldRow>
+          <FieldRow label="Date">{new Date(ncr.created_at).toLocaleDateString()}</FieldRow>
+          <FieldRow label="Department">{ncr.department}</FieldRow>
+          <FieldRow label="Deviation Category">{ncr.deviation_category}</FieldRow>
+          <FieldRow label="Requester">{ncr.requester.display_name}</FieldRow>
+          <FieldRow label="Disposition Authority">
+            {ncr.disposition_authority.display_name}
+          </FieldRow>
+          {ncr.job_info && (
+            <>
+              <FieldRow label="Part (ERP)">
+                {[ncr.job_info.part_id, ncr.job_info.part_description]
+                  .filter(Boolean)
+                  .join(" — ")}
+              </FieldRow>
+              <FieldRow label="Customer (ERP)">{ncr.job_info.customer_name}</FieldRow>
+              <FieldRow label="WO Status (ERP)">{ncr.job_info.work_order_status}</FieldRow>
+            </>
+          )}
+          <Grid item xs={12}>
+            <Typography variant="caption" color="text.secondary" display="block">
+              Deviation Detail
+            </Typography>
+            <Typography sx={{ whiteSpace: "pre-wrap" }}>{ncr.deviation_detail}</Typography>
+          </Grid>
+        </Grid>
+        <Divider sx={{ my: 2 }} />
+        <Typography variant="subtitle2" gutterBottom>
+          Attachments
+        </Typography>
+        <AttachmentSection
+          ncrId={ncr.id}
+          attachments={ncr.attachments}
+          canAdd={actions.includes("add_attachment")}
+        />
+      </SectionCard>
+
+      <SectionCard title="Disposition">
+        {ncr.stage === "new_request" && !actions.includes("initial_disposition") ? (
+          <Typography color="text.secondary">
+            Awaiting initial disposition by {ncr.disposition_authority.display_name}.
+          </Typography>
+        ) : (
+          <Grid container spacing={2} sx={{ mb: 1 }}>
+            <FieldRow label="QC Authority">{ncr.qc_authority}</FieldRow>
+            <FieldRow label="Work Order">{ncr.work_order}</FieldRow>
+            <FieldRow label="Secondary Review">
+              {ncr.secondary_review_needed === null
+                ? "—"
+                : ncr.secondary_review_needed
+                  ? `Yes — ${ncr.secondary_authorities.map((u) => u.display_name).join(", ") || "unassigned"}`
+                  : "No"}
+            </FieldRow>
+            {ncr.disposition_notes && (
+              <Grid item xs={12}>
+                <Typography variant="caption" color="text.secondary" display="block">
+                  Disposition Notes
+                </Typography>
+                <RichTextView html={ncr.disposition_notes} />
+              </Grid>
+            )}
+          </Grid>
+        )}
+        {actions.includes("initial_disposition") && (
+          <>
+            <Divider sx={{ my: 2 }}>
+              <Chip label="Initial Disposition — your action" color="primary" size="small" />
+            </Divider>
+            <InitialDispositionForm ncr={ncr} />
+          </>
+        )}
+        {actions.includes("secondary_disposition") && (
+          <>
+            <Divider sx={{ my: 2 }}>
+              <Chip label="Secondary Disposition — your action" color="primary" size="small" />
+            </Divider>
+            <SecondaryDispositionForm ncr={ncr} />
+          </>
+        )}
+      </SectionCard>
+
+      <SectionCard title="Operations">
+        <Grid container spacing={2}>
+          <FieldRow label="Operations Complete">
+            {ncr.operations_complete ? "Yes" : "Pending"}
+          </FieldRow>
+          <FieldRow label="Completed By">
+            {ncr.operations_completed_by?.display_name}
+          </FieldRow>
+          <FieldRow label="Completed At">{fmt(ncr.operations_completed_at)}</FieldRow>
+        </Grid>
+        {actions.includes("operations_complete") && (
+          <>
+            <Divider sx={{ my: 2 }}>
+              <Chip label="Operations — your action" color="primary" size="small" />
+            </Divider>
+            <OperationsForm ncr={ncr} />
+          </>
+        )}
+      </SectionCard>
+
+      <SectionCard title="QC Inspection">
+        <Grid container spacing={2}>
+          <FieldRow label="QC Approval">
+            {ncr.qc_approval === null ? "—" : ncr.qc_approval === "yes" ? "Yes" : "No"}
+          </FieldRow>
+          <FieldRow label="QC Closed">
+            {ncr.qc_closed
+              ? `Yes — ${ncr.qc_closed_by?.display_name}, ${fmt(ncr.qc_closed_at)}`
+              : "Pending"}
+          </FieldRow>
+          {ncr.inspection_notes && (
+            <Grid item xs={12}>
+              <Typography variant="caption" color="text.secondary" display="block">
+                Inspection Notes
+              </Typography>
+              <Typography sx={{ whiteSpace: "pre-wrap" }}>{ncr.inspection_notes}</Typography>
+            </Grid>
+          )}
+        </Grid>
+        {actions.includes("inspection") && (
+          <>
+            <Divider sx={{ my: 2 }}>
+              <Chip label="QC Inspection — your action" color="primary" size="small" />
+            </Divider>
+            <InspectionForm ncr={ncr} />
+          </>
+        )}
+      </SectionCard>
+
+      <SectionCard title="Costing">
+        <Grid container spacing={2}>
+          <FieldRow label="Labor">{money(ncr.labor_cost)}</FieldRow>
+          <FieldRow label="Material">{money(ncr.material_cost)}</FieldRow>
+          <FieldRow label="Service">{money(ncr.service_cost)}</FieldRow>
+          <FieldRow label="Other">{money(ncr.other_cost)}</FieldRow>
+          <FieldRow label="Total">
+            <Typography component="span" fontWeight={700}>
+              {money(ncr.total_cost)}
+            </Typography>
+          </FieldRow>
+          <FieldRow label="Costed By">
+            {ncr.costing_completed_by
+              ? `${ncr.costing_completed_by.display_name}, ${fmt(ncr.costing_completed_at)}`
+              : null}
+          </FieldRow>
+        </Grid>
+        {actions.includes("costing") && (
+          <>
+            <Divider sx={{ my: 2 }}>
+              <Chip label="Costing — your action" color="primary" size="small" />
+            </Divider>
+            <CostingForm ncr={ncr} />
+          </>
+        )}
+      </SectionCard>
+
+      <SectionCard title="Workflow History">
+        <Table size="small">
+          <TableHead>
+            <TableRow>
+              <TableCell>When</TableCell>
+              <TableCell>Action</TableCell>
+              <TableCell>From</TableCell>
+              <TableCell>To</TableCell>
+              <TableCell>By</TableCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {ncr.transitions.map((t) => (
+              <TableRow key={t.id}>
+                <TableCell sx={{ whiteSpace: "nowrap" }}>{fmt(t.acted_at)}</TableCell>
+                <TableCell>
+                  {t.action.replace(/_/g, " ")}
+                  {t.note && (
+                    <Typography variant="caption" display="block" color="text.secondary">
+                      {t.note}
+                    </Typography>
+                  )}
+                </TableCell>
+                <TableCell>{t.from_stage ? STAGE_LABELS[t.from_stage] : "—"}</TableCell>
+                <TableCell>{STAGE_LABELS[t.to_stage]}</TableCell>
+                <TableCell>{t.acted_by.display_name}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </SectionCard>
+    </>
+  );
+}
+
+export function NcrDetailPage() {
+  const { id } = useParams();
+  const ncrId = Number(id);
+  const ncrQuery = useNcr(Number.isFinite(ncrId) ? ncrId : undefined);
+  const me = useMe();
+  const { toast } = useToast();
+  const [tab, setTab] = useState(0);
+  const [reopenOpen, setReopenOpen] = useState(false);
+
+  if (ncrQuery.isLoading) {
+    return (
+      <Box sx={{ textAlign: "center", py: 8 }}>
+        <CircularProgress />
+      </Box>
+    );
+  }
+  if (ncrQuery.isError || !ncrQuery.data) {
+    return (
+      <Alert severity="error">
+        {(ncrQuery.error as Error | undefined)?.message ?? "NCR not found."}
+      </Alert>
+    );
+  }
+  const ncr = ncrQuery.data;
+  const canAudit =
+    ncr.available_actions.includes("view_audit") ||
+    (me.data?.roles.includes("admin") ?? false);
+
+  return (
+    <Box sx={{ maxWidth: 1100, mx: "auto" }}>
+      <Stack
+        direction={{ xs: "column", md: "row" }}
+        justifyContent="space-between"
+        alignItems={{ md: "center" }}
+        spacing={1}
+        sx={{ mb: 1 }}
+      >
+        <Stack direction="row" spacing={1.5} alignItems="center">
+          <Typography variant="h5">{ncr.ncr_number}</Typography>
+          <StageChip stage={ncr.stage} size="medium" />
+          <Typography color="text.secondary" variant="body2">
+            {ncr.days_in_stage}d in stage
+          </Typography>
+        </Stack>
+        <Stack direction="row" spacing={1}>
+          <Button
+            startIcon={<PictureAsPdfIcon />}
+            variant="outlined"
+            onClick={() =>
+              void openBlob(`/api/ncrs/${ncr.id}/pdf`, `${ncr.ncr_number}.pdf`, "open").catch(
+                (e) => toast(e.message, "error"),
+              )
+            }
+          >
+            Print / Download PDF
+          </Button>
+          {ncr.available_actions.includes("reopen") && (
+            <Button
+              startIcon={<LockOpenIcon />}
+              variant="outlined"
+              color="warning"
+              onClick={() => setReopenOpen(true)}
+            >
+              Reopen
+            </Button>
+          )}
+        </Stack>
+      </Stack>
+
+      <StageStepper ncr={ncr} />
+
+      {canAudit ? (
+        <>
+          <Tabs value={tab} onChange={(_, v) => setTab(v)} sx={{ mb: 2 }}>
+            <Tab label="Details" />
+            <Tab icon={<HistoryIcon />} iconPosition="start" label="Audit History" />
+          </Tabs>
+          {tab === 0 ? (
+            <DetailBody ncr={ncr} />
+          ) : (
+            <Card>
+              <CardContent>
+                <AuditTab ncrId={ncr.id} />
+              </CardContent>
+            </Card>
+          )}
+        </>
+      ) : (
+        <DetailBody ncr={ncr} />
+      )}
+
+      <ReopenDialog ncr={ncr} open={reopenOpen} onClose={() => setReopenOpen(false)} />
+    </Box>
+  );
+}

frontend/src/pages/NewNcrPage.tsx

@@ -0,0 +1,193 @@
+import CheckCircleIcon from "@mui/icons-material/CheckCircle";
+import {
+  Alert,
+  Box,
+  Button,
+  Card,
+  CardContent,
+  CircularProgress,
+  MenuItem,
+  Stack,
+  TextField,
+  Typography,
+} from "@mui/material";
+import { useMutation } from "@tanstack/react-query";
+import { useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { api } from "../api/client";
+import { useLookups } from "../api/hooks";
+import type { NcrDetail, NcrMutationOut, UserOut } from "../api/types";
+import { AttachmentSection } from "../components/AttachmentSection";
+import { JobNumberField } from "../components/JobNumberField";
+import { useToast } from "../components/Toast";
+import { UserPicker } from "../components/UserPicker";
+
+export function NewNcrPage() {
+  const lookups = useLookups();
+  const navigate = useNavigate();
+  const { warnings } = useToast();
+
+  const [jobNumber, setJobNumber] = useState("");
+  const [departmentId, setDepartmentId] = useState<number | "">("");
+  const [categoryId, setCategoryId] = useState<number | "">("");
+  const [authority, setAuthority] = useState<UserOut | null>(null);
+  const [detail, setDetail] = useState("");
+  const [created, setCreated] = useState<NcrDetail | null>(null);
+
+  const create = useMutation({
+    mutationFn: () =>
+      api<NcrMutationOut>("/api/ncrs", {
+        method: "POST",
+        body: {
+          job_number: jobNumber.trim(),
+          department_id: departmentId,
+          deviation_category_id: categoryId,
+          disposition_authority_id: authority?.id,
+          deviation_detail: detail.trim(),
+        },
+      }),
+    onSuccess: (data) => {
+      setCreated(data.ncr);
+      if (data.warnings.length) warnings(data.warnings);
+      window.scrollTo({ top: 0 });
+    },
+  });
+
+  const valid =
+    jobNumber.trim().length > 0 &&
+    departmentId !== "" &&
+    categoryId !== "" &&
+    authority !== null &&
+    detail.trim().length >= 5;
+
+  // ── Confirmation screen: prominent NCR number + immediate photo upload ────
+  if (created) {
+    return (
+      <Box sx={{ maxWidth: 720, mx: "auto" }}>
+        <Card>
+          <CardContent sx={{ textAlign: "center", py: 4 }}>
+            <CheckCircleIcon color="success" sx={{ fontSize: 56 }} />
+            <Typography variant="h6" sx={{ mt: 1 }}>
+              NCR submitted
+            </Typography>
+            <Typography
+              variant="h3"
+              color="primary"
+              sx={{ fontWeight: 800, my: 1, letterSpacing: 1 }}
+            >
+              {created.ncr_number}
+            </Typography>
+            <Typography color="text.secondary">
+              Job {created.job_number} · {created.department} ·{" "}
+              {created.deviation_category}
+            </Typography>
+            <Typography color="text.secondary" variant="body2" sx={{ mt: 0.5 }}>
+              {created.disposition_authority.display_name} has been notified for
+              initial disposition.
+            </Typography>
+
+            <Box sx={{ textAlign: "left", mt: 3 }}>
+              <Typography variant="subtitle2" gutterBottom>
+                Add photos / files now (optional)
+              </Typography>
+              <AttachmentSection
+                ncrId={created.id}
+                attachments={created.attachments}
+                canAdd
+              />
+            </Box>
+
+            <Stack direction="row" spacing={1} justifyContent="center" sx={{ mt: 3 }}>
+              <Button variant="contained" onClick={() => navigate(`/ncrs/${created.id}`)}>
+                View NCR
+              </Button>
+              <Button
+                onClick={() => {
+                  setCreated(null);
+                  setJobNumber("");
+                  setDetail("");
+                }}
+              >
+                Submit another
+              </Button>
+            </Stack>
+          </CardContent>
+        </Card>
+      </Box>
+    );
+  }
+
+  return (
+    <Box sx={{ maxWidth: 720, mx: "auto" }}>
+      <Typography variant="h5" gutterBottom>
+        New NCR Request
+      </Typography>
+      <Card>
+        <CardContent>
+          <Stack spacing={2}>
+            {create.isError && (
+              <Alert severity="error">{(create.error as Error).message}</Alert>
+            )}
+            <JobNumberField value={jobNumber} onChange={setJobNumber} required />
+            <TextField
+              select
+              required
+              label="Department"
+              value={departmentId}
+              onChange={(e) => setDepartmentId(Number(e.target.value))}
+            >
+              {(lookups.data?.departments ?? []).map((d) => (
+                <MenuItem key={d.id} value={d.id}>
+                  {d.name}
+                </MenuItem>
+              ))}
+            </TextField>
+            <TextField
+              select
+              required
+              label="Deviation Category"
+              value={categoryId}
+              onChange={(e) => setCategoryId(Number(e.target.value))}
+            >
+              {(lookups.data?.deviation_categories ?? []).map((c) => (
+                <MenuItem key={c.id} value={c.id}>
+                  {c.name}
+                </MenuItem>
+              ))}
+            </TextField>
+            <UserPicker
+              role="disposition_authority"
+              label="Disposition Authority"
+              value={authority}
+              onChange={(v) => setAuthority(v as UserOut | null)}
+              required
+              helperText="Who should review this nonconformance?"
+            />
+            <TextField
+              label="Deviation Detail"
+              value={detail}
+              onChange={(e) => setDetail(e.target.value)}
+              required
+              multiline
+              minRows={4}
+              helperText="Describe what was found, where, and how many pieces are affected."
+            />
+            <Typography variant="body2" color="text.secondary">
+              Photos and file attachments can be added on the next screen, right
+              after the NCR number is assigned.
+            </Typography>
+            <Button
+              variant="contained"
+              size="large"
+              disabled={!valid || create.isPending}
+              onClick={() => create.mutate()}
+              startIcon={create.isPending ? <CircularProgress size={18} /> : undefined}
+            >
+              Submit NCR
+            </Button>
+          </Stack>
+        </CardContent>
+      </Card>
+    </Box>
+  );
+}

frontend/src/pages/ReportsPage.tsx

@@ -0,0 +1,414 @@
+import DownloadIcon from "@mui/icons-material/Download";
+import TableChartIcon from "@mui/icons-material/TableChart";
+import {
+  Box,
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CircularProgress,
+  Divider,
+  Grid,
+  MenuItem,
+  Stack,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+  TextField,
+  ToggleButton,
+  Typography,
+} from "@mui/material";
+import { useState } from "react";
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Legend,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+import { useLookups, useReportsSummary } from "../api/hooks";
+
+/* Validated categorical palette (dataviz reference instance, light mode).
+ * Fixed slot order — color follows the entity: labor=1 material=2 service=3
+ * other=4. Aqua/yellow sit below 3:1 on white, so the cost chart ships a
+ * table view (relief rule). */
+const SERIES = {
+  labor: "#2a78d6",
+  material: "#1baf7a",
+  service: "#eda100",
+  other: "#008300",
+};
+const SINGLE_HUE = "#2a78d6";
+const GRID = "#eceff1";
+const TICK = { fill: "#52514e", fontSize: 12 };
+
+function money(n: number): string {
+  return n.toLocaleString(undefined, {
+    style: "currency",
+    currency: "USD",
+    maximumFractionDigits: 0,
+  });
+}
+
+function csvDownload(filename: string, rows: Record<string, unknown>[]): void {
+  if (rows.length === 0) return;
+  const headers = Object.keys(rows[0]);
+  const esc = (v: unknown) => `"${String(v ?? "").replace(/"/g, '""')}"`;
+  const csv = [
+    headers.join(","),
+    ...rows.map((r) => headers.map((h) => esc(r[h])).join(",")),
+  ].join("\n");
+  const url = URL.createObjectURL(new Blob([csv], { type: "text/csv" }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  setTimeout(() => URL.revokeObjectURL(url), 30_000);
+}
+
+function StatTile({ label, value }: { label: string; value: string }) {
+  return (
+    <Card sx={{ flexGrow: 1, minWidth: 150 }}>
+      <CardContent sx={{ py: 1.5, "&:last-child": { pb: 1.5 } }}>
+        <Typography variant="caption" color="text.secondary">
+          {label}
+        </Typography>
+        <Typography variant="h5">{value}</Typography>
+      </CardContent>
+    </Card>
+  );
+}
+
+function ChartCard({
+  title,
+  subheader,
+  action,
+  children,
+}: {
+  title: string;
+  subheader?: string;
+  action?: React.ReactNode;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card sx={{ height: "100%" }}>
+      <CardHeader
+        title={title}
+        subheader={subheader}
+        action={action}
+        titleTypographyProps={{ variant: "subtitle1", fontWeight: 700 }}
+        subheaderTypographyProps={{ variant: "caption" }}
+      />
+      <Divider />
+      <CardContent>{children}</CardContent>
+    </Card>
+  );
+}
+
+export function ReportsPage() {
+  const lookups = useLookups();
+  const [dateFrom, setDateFrom] = useState("");
+  const [dateTo, setDateTo] = useState("");
+  const [departmentId, setDepartmentId] = useState<number | "">("");
+  const [categoryId, setCategoryId] = useState<number | "">("");
+  const [costAsTable, setCostAsTable] = useState(false);
+
+  const summary = useReportsSummary({
+    date_from: dateFrom || undefined,
+    date_to: dateTo || undefined,
+    department_id: departmentId || undefined,
+    category_id: categoryId || undefined,
+  });
+
+  const data = summary.data;
+  const costRows = (data?.cost_over_time ?? []).map((c) => ({
+    month: c.month,
+    Labor: Number(c.labor),
+    Material: Number(c.material),
+    Service: Number(c.service),
+    Other: Number(c.other),
+    Total: Number(c.total),
+  }));
+
+  return (
+    <Box>
+      <Typography variant="h5" gutterBottom>
+        Reports
+      </Typography>
+
+      {/* Filters — one row above the charts */}
+      <Card sx={{ mb: 2 }}>
+        <CardContent sx={{ py: 1.5, "&:last-child": { pb: 1.5 } }}>
+          <Stack direction={{ xs: "column", sm: "row" }} spacing={1.5}>
+            <TextField
+              size="small"
+              type="date"
+              label="From"
+              InputLabelProps={{ shrink: true }}
+              value={dateFrom}
+              onChange={(e) => setDateFrom(e.target.value)}
+            />
+            <TextField
+              size="small"
+              type="date"
+              label="To"
+              InputLabelProps={{ shrink: true }}
+              value={dateTo}
+              onChange={(e) => setDateTo(e.target.value)}
+            />
+            <TextField
+              size="small"
+              select
+              label="Department"
+              value={departmentId}
+              onChange={(e) =>
+                setDepartmentId(e.target.value === "" ? "" : Number(e.target.value))
+              }
+              sx={{ minWidth: 180 }}
+            >
+              <MenuItem value="">All departments</MenuItem>
+              {(lookups.data?.departments ?? []).map((d) => (
+                <MenuItem key={d.id} value={d.id}>
+                  {d.name}
+                </MenuItem>
+              ))}
+            </TextField>
+            <TextField
+              size="small"
+              select
+              label="Category"
+              value={categoryId}
+              onChange={(e) =>
+                setCategoryId(e.target.value === "" ? "" : Number(e.target.value))
+              }
+              sx={{ minWidth: 180 }}
+            >
+              <MenuItem value="">All categories</MenuItem>
+              {(lookups.data?.deviation_categories ?? []).map((c) => (
+                <MenuItem key={c.id} value={c.id}>
+                  {c.name}
+                </MenuItem>
+              ))}
+            </TextField>
+          </Stack>
+        </CardContent>
+      </Card>
+
+      {summary.isLoading || !data ? (
+        <Box sx={{ textAlign: "center", py: 8 }}>
+          <CircularProgress />
+        </Box>
+      ) : (
+        <>
+          <Stack direction="row" spacing={1.5} sx={{ mb: 2 }} flexWrap="wrap" useFlexGap>
+            <StatTile label="Total NCRs" value={String(data.total_ncrs)} />
+            <StatTile label="Open" value={String(data.open_ncrs)} />
+            <StatTile label="Closed" value={String(data.closed_ncrs)} />
+            <StatTile label="Cost of Nonconformance" value={money(Number(data.total_cost))} />
+            <StatTile
+              label="Avg End-to-End"
+              value={
+                data.end_to_end_avg_days !== null
+                  ? `${data.end_to_end_avg_days} days`
+                  : "—"
+              }
+            />
+          </Stack>
+
+          <Grid container spacing={2}>
+            <Grid item xs={12} md={6}>
+              <ChartCard title="NCRs by Month">
+                <ResponsiveContainer width="100%" height={260}>
+                  <BarChart data={data.by_month}>
+                    <CartesianGrid stroke={GRID} vertical={false} />
+                    <XAxis dataKey="month" tick={TICK} tickLine={false} />
+                    <YAxis allowDecimals={false} tick={TICK} tickLine={false} axisLine={false} />
+                    <Tooltip />
+                    <Bar dataKey="count" name="NCRs" fill={SINGLE_HUE} radius={[4, 4, 0, 0]} />
+                  </BarChart>
+                </ResponsiveContainer>
+              </ChartCard>
+            </Grid>
+
+            <Grid item xs={12} md={6}>
+              <ChartCard
+                title="Cost of Nonconformance Over Time"
+                subheader="Closed NCRs, by month closed"
+                action={
+                  <Stack direction="row" spacing={0.5}>
+                    <ToggleButton
+                      value="table"
+                      size="small"
+                      selected={costAsTable}
+                      onChange={() => setCostAsTable(!costAsTable)}
+                      title="Toggle table view"
+                    >
+                      <TableChartIcon fontSize="small" />
+                    </ToggleButton>
+                    <Button
+                      size="small"
+                      startIcon={<DownloadIcon />}
+                      onClick={() => csvDownload("cost-of-nonconformance.csv", costRows)}
+                    >
+                      CSV
+                    </Button>
+                  </Stack>
+                }
+              >
+                {costAsTable ? (
+                  <Table size="small">
+                    <TableHead>
+                      <TableRow>
+                        <TableCell>Month</TableCell>
+                        <TableCell align="right">Labor</TableCell>
+                        <TableCell align="right">Material</TableCell>
+                        <TableCell align="right">Service</TableCell>
+                        <TableCell align="right">Other</TableCell>
+                        <TableCell align="right">Total</TableCell>
+                      </TableRow>
+                    </TableHead>
+                    <TableBody>
+                      {costRows.map((r) => (
+                        <TableRow key={r.month}>
+                          <TableCell>{r.month}</TableCell>
+                          <TableCell align="right">{money(r.Labor)}</TableCell>
+                          <TableCell align="right">{money(r.Material)}</TableCell>
+                          <TableCell align="right">{money(r.Service)}</TableCell>
+                          <TableCell align="right">{money(r.Other)}</TableCell>
+                          <TableCell align="right" sx={{ fontWeight: 700 }}>
+                            {money(r.Total)}
+                          </TableCell>
+                        </TableRow>
+                      ))}
+                    </TableBody>
+                  </Table>
+                ) : (
+                  <ResponsiveContainer width="100%" height={260}>
+                    <BarChart data={costRows}>
+                      <CartesianGrid stroke={GRID} vertical={false} />
+                      <XAxis dataKey="month" tick={TICK} tickLine={false} />
+                      <YAxis
+                        tick={TICK}
+                        tickLine={false}
+                        axisLine={false}
+                        tickFormatter={(v: number) => money(v)}
+                        width={72}
+                      />
+                      <Tooltip formatter={(v: number) => money(v)} />
+                      <Legend />
+                      {/* 2px surface gap between stacked segments via stroke */}
+                      <Bar dataKey="Labor" stackId="cost" fill={SERIES.labor} stroke="#fff" strokeWidth={1} />
+                      <Bar dataKey="Material" stackId="cost" fill={SERIES.material} stroke="#fff" strokeWidth={1} />
+                      <Bar dataKey="Service" stackId="cost" fill={SERIES.service} stroke="#fff" strokeWidth={1} />
+                      <Bar dataKey="Other" stackId="cost" fill={SERIES.other} stroke="#fff" strokeWidth={1} radius={[4, 4, 0, 0]} />
+                    </BarChart>
+                  </ResponsiveContainer>
+                )}
+              </ChartCard>
+            </Grid>
+
+            <Grid item xs={12} md={6}>
+              <ChartCard title="NCRs by Department">
+                <ResponsiveContainer width="100%" height={Math.max(200, data.by_department.length * 34)}>
+                  <BarChart data={data.by_department} layout="vertical">
+                    <CartesianGrid stroke={GRID} horizontal={false} />
+                    <XAxis type="number" allowDecimals={false} tick={TICK} tickLine={false} />
+                    <YAxis type="category" dataKey="name" width={130} tick={TICK} tickLine={false} axisLine={false} />
+                    <Tooltip />
+                    <Bar dataKey="count" name="NCRs" fill={SINGLE_HUE} radius={[0, 4, 4, 0]} />
+                  </BarChart>
+                </ResponsiveContainer>
+              </ChartCard>
+            </Grid>
+
+            <Grid item xs={12} md={6}>
+              <ChartCard title="NCRs by Deviation Category">
+                <ResponsiveContainer width="100%" height={Math.max(200, data.by_category.length * 34)}>
+                  <BarChart data={data.by_category} layout="vertical">
+                    <CartesianGrid stroke={GRID} horizontal={false} />
+                    <XAxis type="number" allowDecimals={false} tick={TICK} tickLine={false} />
+                    <YAxis type="category" dataKey="name" width={160} tick={TICK} tickLine={false} axisLine={false} />
+                    <Tooltip />
+                    <Bar dataKey="count" name="NCRs" fill={SINGLE_HUE} radius={[0, 4, 4, 0]} />
+                  </BarChart>
+                </ResponsiveContainer>
+              </ChartCard>
+            </Grid>
+
+            <Grid item xs={12} md={6}>
+              <ChartCard title="Open NCR Aging" subheader="Days in current stage">
+                <ResponsiveContainer width="100%" height={240}>
+                  <BarChart data={data.aging}>
+                    <CartesianGrid stroke={GRID} vertical={false} />
+                    <XAxis dataKey="bucket" tick={TICK} tickLine={false} />
+                    <YAxis allowDecimals={false} tick={TICK} tickLine={false} axisLine={false} />
+                    <Tooltip />
+                    <Bar dataKey="count" name="Open NCRs" fill={SINGLE_HUE} radius={[4, 4, 0, 0]} />
+                  </BarChart>
+                </ResponsiveContainer>
+              </ChartCard>
+            </Grid>
+
+            <Grid item xs={12} md={6}>
+              <ChartCard title="Average Cycle Time per Stage" subheader="Days spent in each stage">
+                <ResponsiveContainer width="100%" height={240}>
+                  <BarChart data={data.cycle_times} layout="vertical">
+                    <CartesianGrid stroke={GRID} horizontal={false} />
+                    <XAxis type="number" tick={TICK} tickLine={false} />
+                    <YAxis type="category" dataKey="stage_label" width={150} tick={TICK} tickLine={false} axisLine={false} />
+                    <Tooltip formatter={(v: number) => `${v} days`} />
+                    <Bar dataKey="avg_days" name="Avg days" fill={SINGLE_HUE} radius={[0, 4, 4, 0]} />
+                  </BarChart>
+                </ResponsiveContainer>
+              </ChartCard>
+            </Grid>
+
+            <Grid item xs={12} md={6}>
+              <ChartCard
+                title="Top Job Numbers by NCR Count"
+                action={
+                  <Button
+                    size="small"
+                    startIcon={<DownloadIcon />}
+                    onClick={() => csvDownload("top-jobs.csv", data.top_jobs)}
+                  >
+                    CSV
+                  </Button>
+                }
+              >
+                <Table size="small">
+                  <TableHead>
+                    <TableRow>
+                      <TableCell>Job Number</TableCell>
+                      <TableCell align="right">NCRs</TableCell>
+                    </TableRow>
+                  </TableHead>
+                  <TableBody>
+                    {data.top_jobs.map((j) => (
+                      <TableRow key={j.job_number}>
+                        <TableCell>{j.job_number}</TableCell>
+                        <TableCell align="right">{j.count}</TableCell>
+                      </TableRow>
+                    ))}
+                    {data.top_jobs.length === 0 && (
+                      <TableRow>
+                        <TableCell colSpan={2}>
+                          <Typography color="text.secondary">No data.</Typography>
+                        </TableCell>
+                      </TableRow>
+                    )}
+                  </TableBody>
+                </Table>
+              </ChartCard>
+            </Grid>
+          </Grid>
+        </>
+      )}
+    </Box>
+  );
+}

frontend/src/pages/SearchPage.tsx

@@ -0,0 +1,172 @@
+import DownloadIcon from "@mui/icons-material/Download";
+import {
+  Box,
+  Button,
+  Card,
+  CardContent,
+  Grid,
+  MenuItem,
+  TextField,
+  Typography,
+} from "@mui/material";
+import { useState } from "react";
+import { buildQuery, openBlob } from "../api/client";
+import { useLookups, useQueue } from "../api/hooks";
+import type { QueueFilters } from "../api/types";
+import { STAGE_LABELS, STAGE_ORDER } from "../api/types";
+import { QueueTable } from "../components/QueueTable";
+import { useToast } from "../components/Toast";
+
+export function SearchPage() {
+  const lookups = useLookups();
+  const { toast } = useToast();
+  const [page, setPage] = useState(1);
+  const [q, setQ] = useState("");
+  const [departmentId, setDepartmentId] = useState<number | "">("");
+  const [categoryId, setCategoryId] = useState<number | "">("");
+  const [stage, setStage] = useState("");
+  const [dateFrom, setDateFrom] = useState("");
+  const [dateTo, setDateTo] = useState("");
+
+  const filters: QueueFilters = {
+    q: q || undefined,
+    department_id: departmentId || undefined,
+    category_id: categoryId || undefined,
+    stage: stage || undefined,
+    date_from: dateFrom || undefined,
+    date_to: dateTo || undefined,
+  };
+  const results = useQueue("all", filters, page);
+
+  const set = <T,>(setter: (v: T) => void) => (v: T) => {
+    setter(v);
+    setPage(1);
+  };
+
+  return (
+    <Box>
+      <Typography variant="h5" gutterBottom>
+        Search NCRs
+      </Typography>
+      <Card sx={{ mb: 2 }}>
+        <CardContent>
+          <Grid container spacing={1.5}>
+            <Grid item xs={12} sm={4} md={3}>
+              <TextField
+                fullWidth
+                size="small"
+                label="NCR # or Job #"
+                value={q}
+                onChange={(e) => set(setQ)(e.target.value)}
+              />
+            </Grid>
+            <Grid item xs={6} sm={4} md={2}>
+              <TextField
+                fullWidth
+                size="small"
+                select
+                label="Department"
+                value={departmentId}
+                onChange={(e) =>
+                  set(setDepartmentId)(e.target.value === "" ? "" : Number(e.target.value))
+                }
+              >
+                <MenuItem value="">All</MenuItem>
+                {(lookups.data?.departments ?? []).map((d) => (
+                  <MenuItem key={d.id} value={d.id}>
+                    {d.name}
+                  </MenuItem>
+                ))}
+              </TextField>
+            </Grid>
+            <Grid item xs={6} sm={4} md={2}>
+              <TextField
+                fullWidth
+                size="small"
+                select
+                label="Category"
+                value={categoryId}
+                onChange={(e) =>
+                  set(setCategoryId)(e.target.value === "" ? "" : Number(e.target.value))
+                }
+              >
+                <MenuItem value="">All</MenuItem>
+                {(lookups.data?.deviation_categories ?? []).map((c) => (
+                  <MenuItem key={c.id} value={c.id}>
+                    {c.name}
+                  </MenuItem>
+                ))}
+              </TextField>
+            </Grid>
+            <Grid item xs={6} sm={4} md={2}>
+              <TextField
+                fullWidth
+                size="small"
+                select
+                label="Stage"
+                value={stage}
+                onChange={(e) => set(setStage)(e.target.value)}
+              >
+                <MenuItem value="">All</MenuItem>
+                {STAGE_ORDER.map((s) => (
+                  <MenuItem key={s} value={s}>
+                    {STAGE_LABELS[s]}
+                  </MenuItem>
+                ))}
+              </TextField>
+            </Grid>
+            <Grid item xs={6} sm={4} md={1.5}>
+              <TextField
+                fullWidth
+                size="small"
+                type="date"
+                label="From"
+                InputLabelProps={{ shrink: true }}
+                value={dateFrom}
+                onChange={(e) => set(setDateFrom)(e.target.value)}
+              />
+            </Grid>
+            <Grid item xs={6} sm={4} md={1.5}>
+              <TextField
+                fullWidth
+                size="small"
+                type="date"
+                label="To"
+                InputLabelProps={{ shrink: true }}
+                value={dateTo}
+                onChange={(e) => set(setDateTo)(e.target.value)}
+              />
+            </Grid>
+          </Grid>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardContent>
+          <Box sx={{ display: "flex", justifyContent: "flex-end", mb: 1 }}>
+            <Button
+              startIcon={<DownloadIcon />}
+              onClick={() =>
+                void openBlob(
+                  `/api/ncrs/export.csv${buildQuery({ queue: "all", ...filters })}`,
+                  "ncr-search.csv",
+                  "download",
+                ).catch((e) => toast(e.message, "error"))
+              }
+            >
+              Export CSV
+            </Button>
+          </Box>
+          <QueueTable
+            items={results.data?.items ?? []}
+            total={results.data?.total ?? 0}
+            page={page}
+            pageSize={25}
+            onPageChange={setPage}
+            loading={results.isLoading}
+          />
+        </CardContent>
+      </Card>
+    </Box>
+  );
+}

frontend/src/pages/StageForms.tsx

@@ -0,0 +1,455 @@
+/** Editable forms for the current workflow stage. Visibility is driven by the
+ * server's `available_actions`; the API re-enforces role + stage on submit. */
+import SendIcon from "@mui/icons-material/Send";
+import {
+  Alert,
+  Button,
+  Checkbox,
+  CircularProgress,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  FormControlLabel,
+  InputAdornment,
+  MenuItem,
+  Stack,
+  TextField,
+  ToggleButton,
+  ToggleButtonGroup,
+  Typography,
+} from "@mui/material";
+import { useMemo, useState } from "react";
+import { api } from "../api/client";
+import { useNcrMutation } from "../api/hooks";
+import type { NcrDetail, NcrMutationOut, UserOut } from "../api/types";
+import { STAGE_LABELS } from "../api/types";
+import { RichTextEditor } from "../components/RichTextEditor";
+import { useToast } from "../components/Toast";
+import { UserPicker } from "../components/UserPicker";
+
+function useWarnToast() {
+  const { warnings, toast } = useToast();
+  return { warnings, toast };
+}
+
+// ── Initial Disposition ──────────────────────────────────────────────────────
+export function InitialDispositionForm({ ncr }: { ncr: NcrDetail }) {
+  const { warnings, toast } = useWarnToast();
+  const [qcAuthority, setQcAuthority] = useState(ncr.qc_authority ?? "");
+  const [workOrder, setWorkOrder] = useState(ncr.work_order ?? "");
+  const [notes, setNotes] = useState(ncr.disposition_notes ?? "");
+  const [secondary, setSecondary] = useState(false);
+  const [assignees, setAssignees] = useState<UserOut[]>([]);
+
+  const mutation = useNcrMutation(
+    () =>
+      api<NcrMutationOut>(`/api/ncrs/${ncr.id}/initial-disposition`, {
+        method: "POST",
+        body: {
+          qc_authority: qcAuthority || null,
+          work_order: workOrder || null,
+          disposition_notes: notes || null,
+          secondary_review_needed: secondary,
+          secondary_authority_ids: assignees.map((u) => u.id),
+        },
+      }),
+    warnings,
+  );
+
+  return (
+    <Stack spacing={2}>
+      {mutation.isError && (
+        <Alert severity="error">{(mutation.error as Error).message}</Alert>
+      )}
+      <TextField
+        label="QC Authority"
+        value={qcAuthority}
+        onChange={(e) => setQcAuthority(e.target.value)}
+      />
+      <TextField
+        label="Work Order"
+        value={workOrder}
+        onChange={(e) => setWorkOrder(e.target.value)}
+      />
+      <RichTextEditor label="Disposition Notes" value={notes} onChange={setNotes} />
+      <FormControlLabel
+        control={
+          <Checkbox checked={secondary} onChange={(e) => setSecondary(e.target.checked)} />
+        }
+        label="Secondary review needed"
+      />
+      {secondary && (
+        <UserPicker
+          role="secondary_disposition_authority"
+          label="Notify These People"
+          multiple
+          value={assignees}
+          onChange={(v) => setAssignees((v as UserOut[]) ?? [])}
+          helperText="The selected secondary disposition authorities will see this NCR in their personal queue."
+          required
+        />
+      )}
+      <Button
+        variant="contained"
+        endIcon={mutation.isPending ? <CircularProgress size={16} /> : <SendIcon />}
+        disabled={mutation.isPending || (secondary && assignees.length === 0)}
+        onClick={() =>
+          mutation.mutate(undefined as never, {
+            onSuccess: () =>
+              toast(
+                secondary
+                  ? "Sent for secondary disposition review."
+                  : "Released to Operations.",
+              ),
+          })
+        }
+      >
+        {secondary ? "Send for Secondary Review" : "Release to Operations"}
+      </Button>
+    </Stack>
+  );
+}
+
+// ── Secondary Disposition ────────────────────────────────────────────────────
+export function SecondaryDispositionForm({ ncr }: { ncr: NcrDetail }) {
+  const { warnings, toast } = useWarnToast();
+  const [qcAuthority, setQcAuthority] = useState(ncr.qc_authority ?? "");
+  const [workOrder, setWorkOrder] = useState(ncr.work_order ?? "");
+  const [notes, setNotes] = useState(ncr.disposition_notes ?? "");
+
+  const mutation = useNcrMutation(
+    (release: boolean) =>
+      api<NcrMutationOut>(`/api/ncrs/${ncr.id}/secondary-disposition`, {
+        method: "POST",
+        body: {
+          qc_authority: qcAuthority || null,
+          work_order: workOrder || null,
+          disposition_notes: notes || null,
+          release,
+        },
+      }),
+    warnings,
+  );
+
+  return (
+    <Stack spacing={2}>
+      {mutation.isError && (
+        <Alert severity="error">{(mutation.error as Error).message}</Alert>
+      )}
+      <TextField
+        label="QC Authority"
+        value={qcAuthority}
+        onChange={(e) => setQcAuthority(e.target.value)}
+      />
+      <TextField
+        label="Work Order"
+        value={workOrder}
+        onChange={(e) => setWorkOrder(e.target.value)}
+      />
+      <RichTextEditor label="Disposition Notes" value={notes} onChange={setNotes} />
+      <Stack direction="row" spacing={1}>
+        <Button
+          variant="outlined"
+          disabled={mutation.isPending}
+          onClick={() =>
+            mutation.mutate(false, { onSuccess: () => toast("Saved.") })
+          }
+        >
+          Save
+        </Button>
+        <Button
+          variant="contained"
+          endIcon={mutation.isPending ? <CircularProgress size={16} /> : <SendIcon />}
+          disabled={mutation.isPending}
+          onClick={() =>
+            mutation.mutate(true, {
+              onSuccess: () => toast("Released to Operations."),
+            })
+          }
+        >
+          Release to Operations
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}
+
+// ── Operations ───────────────────────────────────────────────────────────────
+export function OperationsForm({ ncr }: { ncr: NcrDetail }) {
+  const { warnings, toast } = useWarnToast();
+  const mutation = useNcrMutation(
+    () =>
+      api<NcrMutationOut>(`/api/ncrs/${ncr.id}/operations-complete`, {
+        method: "POST",
+      }),
+    warnings,
+  );
+  return (
+    <Stack spacing={1}>
+      {mutation.isError && (
+        <Alert severity="error">{(mutation.error as Error).message}</Alert>
+      )}
+      <Typography color="text.secondary" variant="body2">
+        Review the disposition above, complete the rework/repair, then mark
+        operations complete to send this NCR to QC Inspection.
+      </Typography>
+      <Button
+        variant="contained"
+        disabled={mutation.isPending}
+        endIcon={mutation.isPending ? <CircularProgress size={16} /> : <SendIcon />}
+        onClick={() =>
+          mutation.mutate(undefined as never, {
+            onSuccess: () => toast("Operations complete — sent to QC Inspection."),
+          })
+        }
+      >
+        Mark Operations Complete
+      </Button>
+    </Stack>
+  );
+}
+
+// ── QC Inspection ────────────────────────────────────────────────────────────
+export function InspectionForm({ ncr }: { ncr: NcrDetail }) {
+  const { warnings, toast } = useWarnToast();
+  const [approval, setApproval] = useState<"yes" | "no" | null>(ncr.qc_approval);
+  const [notes, setNotes] = useState(ncr.inspection_notes ?? "");
+  const [close, setClose] = useState(false);
+
+  const mutation = useNcrMutation(
+    () =>
+      api<NcrMutationOut>(`/api/ncrs/${ncr.id}/inspection`, {
+        method: "POST",
+        body: {
+          qc_approval: approval,
+          inspection_notes: notes || null,
+          qc_closed: close,
+        },
+      }),
+    warnings,
+  );
+
+  return (
+    <Stack spacing={2}>
+      {mutation.isError && (
+        <Alert severity="error">{(mutation.error as Error).message}</Alert>
+      )}
+      <Stack direction="row" spacing={2} alignItems="center">
+        <Typography>QC Approval:</Typography>
+        <ToggleButtonGroup
+          exclusive
+          value={approval}
+          onChange={(_, v) => setApproval(v)}
+          size="small"
+        >
+          <ToggleButton value="yes" color="success">
+            Yes
+          </ToggleButton>
+          <ToggleButton value="no" color="error">
+            No
+          </ToggleButton>
+        </ToggleButtonGroup>
+      </Stack>
+      <TextField
+        label="Inspection Notes"
+        value={notes}
+        onChange={(e) => setNotes(e.target.value)}
+        multiline
+        minRows={3}
+      />
+      <FormControlLabel
+        control={<Checkbox checked={close} onChange={(e) => setClose(e.target.checked)} />}
+        label="QC Closed — send to Costing (inspection can no longer be edited)"
+      />
+      <Button
+        variant="contained"
+        disabled={mutation.isPending}
+        endIcon={mutation.isPending ? <CircularProgress size={16} /> : <SendIcon />}
+        onClick={() =>
+          mutation.mutate(undefined as never, {
+            onSuccess: () =>
+              toast(close ? "QC closed — sent to Costing." : "Inspection saved."),
+          })
+        }
+      >
+        {close ? "Save & Close QC" : "Save Inspection"}
+      </Button>
+    </Stack>
+  );
+}
+
+// ── Costing ──────────────────────────────────────────────────────────────────
+function CostField({
+  label,
+  value,
+  onChange,
+}: {
+  label: string;
+  value: string;
+  onChange: (v: string) => void;
+}) {
+  return (
+    <TextField
+      label={label}
+      value={value}
+      onChange={(e) => {
+        const v = e.target.value;
+        if (/^\d*\.?\d{0,2}$/.test(v)) onChange(v);
+      }}
+      inputProps={{ inputMode: "decimal" }}
+      InputProps={{ startAdornment: <InputAdornment position="start">$</InputAdornment> }}
+      sx={{ maxWidth: 220 }}
+    />
+  );
+}
+
+export function CostingForm({ ncr }: { ncr: NcrDetail }) {
+  const { warnings, toast } = useWarnToast();
+  const [labor, setLabor] = useState(ncr.labor_cost ?? "");
+  const [material, setMaterial] = useState(ncr.material_cost ?? "");
+  const [service, setService] = useState(ncr.service_cost ?? "");
+  const [other, setOther] = useState(ncr.other_cost ?? "");
+
+  const total = useMemo(() => {
+    const sum =
+      (parseFloat(labor) || 0) +
+      (parseFloat(material) || 0) +
+      (parseFloat(service) || 0) +
+      (parseFloat(other) || 0);
+    return sum.toLocaleString(undefined, {
+      style: "currency",
+      currency: "USD",
+    });
+  }, [labor, material, service, other]);
+
+  const allSet = [labor, material, service, other].every((v) => v !== "");
+
+  const mutation = useNcrMutation(
+    () =>
+      api<NcrMutationOut>(`/api/ncrs/${ncr.id}/costing`, {
+        method: "POST",
+        body: {
+          labor_cost: labor || "0",
+          material_cost: material || "0",
+          service_cost: service || "0",
+          other_cost: other || "0",
+        },
+      }),
+    warnings,
+  );
+
+  return (
+    <Stack spacing={2}>
+      {mutation.isError && (
+        <Alert severity="error">{(mutation.error as Error).message}</Alert>
+      )}
+      <Stack direction="row" spacing={2} flexWrap="wrap" useFlexGap>
+        <CostField label="Labor Cost" value={labor} onChange={setLabor} />
+        <CostField label="Material Cost" value={material} onChange={setMaterial} />
+        <CostField label="Service Cost" value={service} onChange={setService} />
+        <CostField label="Other Cost" value={other} onChange={setOther} />
+      </Stack>
+      <Typography variant="h6">Total: {total}</Typography>
+      <Alert severity="info">
+        Saving costs completes the workflow and closes this NCR. A closed NCR is
+        locked; only an Admin can reopen it.
+      </Alert>
+      <Button
+        variant="contained"
+        disabled={!allSet || mutation.isPending}
+        endIcon={mutation.isPending ? <CircularProgress size={16} /> : <SendIcon />}
+        onClick={() =>
+          mutation.mutate(undefined as never, {
+            onSuccess: () => toast("Costing complete — NCR closed."),
+          })
+        }
+      >
+        Save Costs & Close NCR
+      </Button>
+    </Stack>
+  );
+}
+
+// ── Admin Reopen ─────────────────────────────────────────────────────────────
+const REOPEN_TARGETS = [
+  "new_request",
+  "secondary_disposition",
+  "operations",
+  "qc_inspection",
+  "costing",
+] as const;
+
+export function ReopenDialog({
+  ncr,
+  open,
+  onClose,
+}: {
+  ncr: NcrDetail;
+  open: boolean;
+  onClose: () => void;
+}) {
+  const { warnings, toast } = useWarnToast();
+  const [target, setTarget] = useState<string>("costing");
+  const [reason, setReason] = useState("");
+
+  const mutation = useNcrMutation(
+    () =>
+      api<NcrMutationOut>(`/api/ncrs/${ncr.id}/reopen`, {
+        method: "POST",
+        body: { to_stage: target, reason: reason.trim() },
+      }),
+    warnings,
+  );
+
+  return (
+    <Dialog open={open} onClose={onClose} fullWidth maxWidth="sm">
+      <DialogTitle>Reopen {ncr.ncr_number}</DialogTitle>
+      <DialogContent>
+        <Stack spacing={2} sx={{ mt: 1 }}>
+          {mutation.isError && (
+            <Alert severity="error">{(mutation.error as Error).message}</Alert>
+          )}
+          <TextField
+            select
+            label="Reopen to stage"
+            value={target}
+            onChange={(e) => setTarget(e.target.value)}
+          >
+            {REOPEN_TARGETS.map((s) => (
+              <MenuItem key={s} value={s}>
+                {STAGE_LABELS[s]}
+              </MenuItem>
+            ))}
+          </TextField>
+          <TextField
+            label="Reason (required, recorded in the audit trail)"
+            value={reason}
+            onChange={(e) => setReason(e.target.value)}
+            multiline
+            minRows={2}
+            required
+          />
+        </Stack>
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={onClose}>Cancel</Button>
+        <Button
+          variant="contained"
+          color="warning"
+          disabled={reason.trim().length < 5 || mutation.isPending}
+          onClick={() =>
+            mutation.mutate(undefined as never, {
+              onSuccess: () => {
+                toast("NCR reopened.");
+                onClose();
+              },
+            })
+          }
+        >
+          Reopen NCR
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}

frontend/src/pages/admin/AdminAuditPage.tsx

@@ -0,0 +1,105 @@
+import {
+  Card,
+  CardContent,
+  Chip,
+  Stack,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TablePagination,
+  TableRow,
+  TextField,
+  Typography,
+} from "@mui/material";
+import { useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import { api, buildQuery } from "../../api/client";
+import type { AuditEntry } from "../../api/types";
+
+interface GlobalAudit {
+  items: AuditEntry[];
+  total: number;
+  page: number;
+  page_size: number;
+}
+
+export function AdminAuditPage() {
+  const [page, setPage] = useState(1);
+  const [ncrNumber, setNcrNumber] = useState("");
+
+  const audit = useQuery({
+    queryKey: ["admin-audit", page, ncrNumber],
+    queryFn: () =>
+      api<GlobalAudit>(
+        `/api/admin/audit${buildQuery({ page, page_size: 50, ncr_number: ncrNumber })}`,
+      ),
+    placeholderData: (prev) => prev,
+  });
+
+  return (
+    <Card>
+      <CardContent>
+        <Stack direction="row" spacing={1} alignItems="center" sx={{ mb: 2 }}>
+          <TextField
+            size="small"
+            label="Filter by NCR number"
+            value={ncrNumber}
+            onChange={(e) => {
+              setNcrNumber(e.target.value);
+              setPage(1);
+            }}
+          />
+          <Typography variant="body2" color="text.secondary">
+            Immutable system-wide audit trail (field-level before/after values).
+          </Typography>
+        </Stack>
+        <Table size="small">
+          <TableHead>
+            <TableRow>
+              <TableCell>When</TableCell>
+              <TableCell>Who</TableCell>
+              <TableCell>Action</TableCell>
+              <TableCell>Field</TableCell>
+              <TableCell>Before</TableCell>
+              <TableCell>After</TableCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {(audit.data?.items ?? []).map((a) => (
+              <TableRow key={a.id}>
+                <TableCell sx={{ whiteSpace: "nowrap" }}>
+                  {new Date(a.created_at).toLocaleString()}
+                </TableCell>
+                <TableCell>{a.user.display_name}</TableCell>
+                <TableCell>
+                  <Chip size="small" label={a.action.replace(/_/g, " ")} />
+                  {a.detail && (
+                    <Typography variant="caption" display="block" color="text.secondary">
+                      {a.detail}
+                    </Typography>
+                  )}
+                </TableCell>
+                <TableCell>{a.field_name ?? ""}</TableCell>
+                <TableCell sx={{ maxWidth: 200, overflowWrap: "anywhere" }}>
+                  {a.old_value ?? ""}
+                </TableCell>
+                <TableCell sx={{ maxWidth: 200, overflowWrap: "anywhere" }}>
+                  {a.new_value ?? ""}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+        <TablePagination
+          component="div"
+          count={audit.data?.total ?? 0}
+          page={page - 1}
+          onPageChange={(_, p) => setPage(p + 1)}
+          rowsPerPage={50}
+          rowsPerPageOptions={[50]}
+        />
+      </CardContent>
+    </Card>
+  );
+}