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>

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))