# Claude.md — JQC Developer Reference > **Audience:** AI assistants and developers working on this codebase. > **Purpose:** Authoritative reference for architecture, conventions, gotchas, and decisions. > **Last reviewed:** July 2026 (Phase 19 complete + mobile API gap-fill Phases A–E + customer UI refinements + Phase 22 comment visibility + Phase 23 support chat/tickets + inspector performance Excel export + inspection list filters + customer issue logging + AI chatbot + dashboard grouped sections + issues/inspections PDF export + date/ID filters + Reports expansion Phases R1–R4 + Phase 24 issue_created notify defaults + Phase 25 inspection GPS + Phase 26 issue vendor fields + Phase 27 facility score alerts + Phase 28 inspection-notify fix + Phase 29 admin broadcasts + Phases 30–32 device registry consolidation + ProxyFix reverse-proxy fix + Phase 33 per-contract notification recipients + grouped Admin nav dropdown + forgot-password case-insensitive lookup & email normalization + transactional email sender/branding fix + Phase 34 facility QR public pages & report-a-problem + Phase 35 issue handler_type (our staff / facility / vendor) + Phase 36 scheduled inspections) --- ## Table of Contents 1. [Project Overview](#1-project-overview) 2. [Tech Stack](#2-tech-stack) 3. [Repository Layout](#3-repository-layout) 4. [Environment & Configuration](#4-environment--configuration) 5. [Database Models](#5-database-models) 6. [Role & Permission Matrix](#6-role--permission-matrix) 7. [Blueprint Prefixes & Route Inventory](#7-blueprint-prefixes--route-inventory) 8. [Utility Modules](#8-utility-modules) 9. [Mobile API (Phase 7 / Phase A–E)](#9-mobile-api-phase-7--phase-ae) 10. [iPad Native App](#10-ipad-native-app) 11. [Notification System](#11-notification-system) 12. [SLA Engine](#12-sla-engine) 13. [Audit Trail](#13-audit-trail) 14. [PDF Export](#14-pdf-export) 15. [Scheduled Reports](#15-scheduled-reports) 16. [Rate Limiting](#16-rate-limiting) 17. [Alembic Migration Chain](#17-alembic-migration-chain) 18. [Frontend Conventions](#18-frontend-conventions) 19. [Infrastructure](#19-infrastructure) 20. [Known Constraints & Hard Rules](#20-known-constraints--hard-rules) 21. [Change Philosophy](#21-change-philosophy) --- ## 1. Project Overview **JQC (Janitorial Quality Control)** is a production-grade, full-stack web application that manages: - Janitorial service contracts organised as **Contracts (Projects) → Facilities → Areas** - **Inspection** execution against configurable templates with dynamic form builder - **Issue** tracking with SLA enforcement, follower subscriptions, and verification workflow - **Customer portal** with scoped facility visibility and invitation-based onboarding - **Notification** system (in-app + email) driven by an admin-controlled matrix - **Reports** — on-demand PDF/CSV/Excel scorecards, scheduled email digests, Issues Aging, SLA Compliance, Follow-up Closure Rate, and per-facility Customer PDF Summary - **Audit trail** — immutable log of every create/update/delete action - **Support chat** — Groq AI chatbot for customers with preset FAQ chips; escalation to admin via ticketing system; customers can view and reply to their own tickets; admins manage tickets at `/support/admin/tickets` - **Mobile API** — JWT-authenticated REST layer for the iPad native app - **iPad native app** — SwiftUI + SwiftData offline-first inspection tool (Phase A + B + C complete) The application is actively deployed in production and maintained by a single developer/administrator. --- ## 2. Tech Stack | Layer | Technology | |---|---| | Language | Python 3.11+ | | Web framework | Flask (application factory pattern) | | ORM | Flask-SQLAlchemy (SQLAlchemy 2.x) | | Database | MySQL (via PyMySQL driver) | | Auth (web) | Flask-Login + Flask-WTF CSRF | | Auth (API) | JWT access tokens + opaque refresh tokens (PyJWT) | | Rate limiting | Flask-Limiter (Redis-backed in production via `REDIS_URL`; falls back to in-process memory for dev) | | Migrations | Flask-Migrate / Alembic | | Email | Flask-Mail (SMTP, background threading) | | PDF generation | ReportLab | | Forms | WTForms + Flask-WTF | | Templating | Jinja2 | | Frontend | Bootstrap 5, Chart.js, vanilla JS | | Server | Gunicorn (sync workers) behind Nginx | | OS | Ubuntu Linux | | **iPad app** | **SwiftUI + SwiftData, iOS 17+, Xcode 26** | | **iPad networking** | **URLSession async/await + NWPathMonitor** | | **iPad auth storage** | **iOS Keychain (Security.framework)** | | Timezone | All datetimes stored as US/Eastern (naive, via `now_eastern()`) | --- ## 3. Repository Layout ``` lt_janitorial_quality_control/ ├── app/ │ ├── __init__.py # Application factory — limiter, csrf, db, mail, login_manager │ ├── api/ # Mobile REST API │ │ ├── __init__.py # api_bp parent blueprint + register_api() │ │ ├── auth.py # /api/v1/auth/* and /api/v1/devices/* │ │ ├── facilities.py # /api/v1/facilities/* (Phase A) │ │ ├── templates.py # /api/v1/templates/* (Phase A) │ │ ├── inspections.py # /api/v1/inspections/* (Phase B) │ │ ├── issues.py # /api/v1/issues/* (Phase B + Phase 19 + Phase E) │ │ ├── photos.py # /api/v1/photos/upload (Phase B) │ │ ├── stats.py # /api/v1/stats/dashboard (Phase B stats) │ │ ├── comments.py # /api/v1/issues//comments (Phase D) │ │ ├── decorators.py # @jwt_required │ │ ├── errors.py # JSON error helpers + error handler registration │ │ └── jwt_utils.py # generate_access_token() │ ├── models/ │ │ ├── inspection.py # Inspection — mobile_local_id column (Phase B) │ │ ├── issue.py # Issue — mobile_local_id (Phase B), reported_by (Phase 18), mobile_photo_paths (Phase 19) │ │ ├── support.py # SupportTicket, SupportTicketReply (Phase 23) │ │ └── ... │ ├── routes/ │ │ ├── support.py # /support/* — AI chat, ticket submit/list/detail (Phase 23) │ │ └── ... │ ├── static/ │ │ └── uploads/ # UPLOAD_FOLDER root │ │ ├── inspection_photos/ │ │ ├── issue_photos/ # photo_path and mobile_photo_paths files │ │ └── issue_result_photos/ # result_photos files (web-added resolution photos) │ ├── templates/ │ │ ├── issues/ │ │ │ ├── view.html # Shows photo_path + mobile_photo_paths under "Photo Evidence" │ │ │ └── issues_view.html # Same photo evidence logic │ │ ├── reports/ │ │ │ ├── _subnav.html # Shared sub-nav include for all report pages │ │ │ ├── index.html # Overview & Trends (score trend, facility scores + per-Contract filter, charts) │ │ │ ├── facility.html # Per-facility detail report │ │ │ ├── scorecard.html # Per-facility scorecard (trend, area scores, SLA, open issues) + PDF Summary button │ │ │ ├── inspector_performance.html # Inspector KPI table + drill-down chart │ │ │ ├── issues_aging.html # Open issues grouped by age bucket (R1) │ │ │ ├── sla_compliance.html # SLA compliance by severity and facility (R2) │ │ │ └── followup_closure.html # Follow-up re-inspection closure rate (R3) │ │ ├── scheduled_reports/ │ │ │ └── index.html # Includes _subnav.html for Reports sub-nav │ │ └── support/ │ │ ├── chat.html # Customer AI chatbot + FAQ chips + submit-ticket modal │ │ ├── my_tickets.html # Customer: list of own tickets │ │ ├── my_ticket_detail.html # Customer: ticket detail + staff replies + follow-up form │ │ ├── admin_tickets.html # Admin: paginated ticket list with status filter tabs │ │ └── admin_ticket_detail.html # Admin: ticket detail + reply form + status controls │ └── utils/ ├── migrations/ │ └── versions/ │ └── phase36_scheduled_inspections.py ← HEAD └── ... Note: `app/routes/broadcast.py` + `app/models/broadcast.py` (admin broadcasts) and `app/routes/devices.py` (admin device registry, reads `api_device_tokens`) are also part of the tree — see §7. Device registration on the API side lives in `app/api/auth.py` only (there is no `app/api/devices.py`). ``` --- ## 4. Environment & Configuration ### Required Environment Variables | Variable | Notes | |---|---| | `SECRET_KEY` | Flask secret — no fallback; startup fails if absent | | `DATABASE_URL` | e.g. `mysql+pymysql://user:pass@localhost/jqc` | | `MAIL_SERVER` | SMTP hostname | | `MAIL_USERNAME` | SMTP login | | `MAIL_PASSWORD` | SMTP password | | `MAIL_PORT` | 465 (SSL) or 587 (STARTTLS) — auto-selects flags | | `APP_BASE_URL` | Full URL for email links | | `MAIL_DEFAULT_SENDER` | From address | | `DIGEST_SECRET` | Authenticates all cron endpoints | | `REDIS_URL` | Optional. When set, Flask-Limiter uses Redis for shared rate-limit counters across Gunicorn workers. | | `GROQ_API_KEY` | Optional. When set, enables the AI chatbot at `/support/chat`. Absent → chat input disabled; customers see a "Submit to Support" fallback only. | | `GROQ_MODEL` | Optional. Groq model ID. Defaults to `llama-3.3-70b-versatile`. | ### Email SSL Auto-Detection ```python MAIL_USE_SSL = _mail_port == 465 MAIL_USE_TLS = not MAIL_USE_SSL ``` **Critical:** Never set both to `True` — Flask-Mail breaks silently. ### File Uploads - `UPLOAD_FOLDER` = `app/static/uploads/` - `MAX_CONTENT_LENGTH` = 50 MB - Allowed: `png`, `jpg`, `jpeg`, `gif` --- ## 5. Database Models ### User ``` users: id, username (unique, indexed), full_name, email (unique, indexed), password_hash, role (ENUM), created_at, active, password_set, set_password_token (indexed), set_password_token_expires ``` **Role ENUM:** `admin`, `director`, `inspector`, `project_manager`, `customer` **Key property:** `display_name` → `full_name.strip()` or falls back to `username`. ### Facility / Area ``` facilities: id, name, address, contact_person, contact_phone, active, project_id (FK), public_token VARCHAR(48) unique ← Phase 34 (QR landing page) areas: id, facility_id (FK), name, area_type ``` **`public_token`** (Phase 34): unguessable per-facility token encoded in the facility's QR code. The QR points at `/f/` — a **login-free** occupant summary page. `Facility.generate_public_token()` / `ensure_public_token()` mint one on demand; new facilities get one at creation, existing rows were backfilled by phase34. Rotating the token (regenerating it) invalidates any printed QR — intentional, for when a code is compromised. **`area_type` choices:** `restroom`, `lobby`, `hallway`, `office`, `kitchen`, `storage`, `floor`, `outdoor`, `other` ### Project / CustomerAssignment ``` projects: id, name, description, project_manager_id, active, created_at customer_assignments: id, user_id, project_id, facility_id (nullable) UniqueConstraint(user_id, project_id, facility_id) inspector_assignments: id, user_id, project_id, created_at UniqueConstraint(user_id, project_id, name='uq_inspector_project') ForeignKey user_id → users(id) ON DELETE CASCADE ForeignKey project_id → projects(id) ON DELETE CASCADE ``` ### Inspection ``` inspections: id, template_id, facility_id, area_id, inspector_id, inspection_date, overall_score, status (in_progress/completed/flagged), notes, form_data (JSON), completed_at, parent_inspection_id (self-FK), follow_up_required, follow_up_note, mobile_local_id VARCHAR(64) nullable indexed ← Phase B submit_latitude DECIMAL(10,7) nullable ← Phase 25 submit_longitude DECIMAL(10,7) nullable ← Phase 25 ``` **`mobile_local_id`:** UUID string generated on the iPad. Used for idempotency — if a submission arrives twice (network retry), the server returns the existing record without creating a duplicate. Set `NULL` for all web-created inspections. **Score rule:** Items with `score = 0` mean "unanswered" — excluded from calculation entirely. ### Issue ``` issues: id, inspection_id (nullable), area_id, facility_id (nullable), severity (low/medium/high/critical), description, photo_path VARCHAR(255), status (open/in_progress/resolved/pending_verification), assigned_to, reported_by (nullable FK → users, SET NULL on delete), reported_at, resolved_at, result_notes, result_photos (JSON), mobile_photo_paths (JSON), ← Phase 19 verified_by, verified_at, verification_note, sla_notified, mobile_local_id VARCHAR(64) nullable indexed, ← Phase B vendor_name VARCHAR(100) nullable, ← Phase 26 vendor_contact VARCHAR(200) nullable, ← Phase 26 vendor_notes TEXT nullable, ← Phase 26 handler_type ENUM('internal','facility','vendor') NOT NULL DEFAULT 'internal', ← Phase 35 facility_handler_name VARCHAR(100) nullable, ← Phase 35 facility_handler_contact VARCHAR(200) nullable, ← Phase 35 facility_handler_notes TEXT nullable ← Phase 35 ``` **Handler (`handler_type`, Phase 35) — who is doing the work:** | Value | Meaning | Detail fields | `assigned_to` role | |---|---|---|---| | `internal` (default) | Janitorial Staff (our crew) | — (the assignee IS the handler) | the handler | | `facility` | The facility's own staff | `facility_handler_name/contact/notes` (free text) | internal **follow-up owner** | | `vendor` | External contractor | `vendor_name/contact/notes` (Phase 26) | internal **follow-up owner** | **Display labels are perspective-neutral** (they read the same for staff and customers) with a descriptor line under the selector and a tooltip on badges: `internal` → **"Janitorial Staff"** ("Our janitorial crew handles it."), `facility` → **"Facility Staff"** ("The facility's own on-site staff handle it."), `vendor` → **"External Vendor"** ("An outside contractor handles it."). Labels/descriptions live in `Issue.HANDLER_LABELS` / `HANDLER_DESCRIPTIONS`, the WTForms `handler_type` choices, and the `HANDLER_DESC` JS map in both issue templates — keep these in sync. Do **not** use viewer-relative words like "Our"/"Your" for the stored categories. `assigned_to` (a JQC User) is **always** available: it is the handler for `internal`, and the internal follow-up owner (e.g. the inspector who verifies/updates) for `facility`/`vendor`. Settable in **two places**, both with a "Handled By" selector that reveals the facility or vendor sub-fields via JS: - **Log New Issue** form (`issues/form.html`) — at creation, for non-customer staff. Customer-created issues stay `internal` (the handler UI is hidden for them, same as `assigned_to`). - **Update Issue** panel on the issue detail page (`issues/view.html`) — triage after creation. Triage of `handler_type` + facility/vendor detail fields on the **update** panel is **admin/director/project_manager only** (same gate as vendor fields); on the **create** form it follows the form's own access (admin/director create for staff). `assigned_to` editing on update remains admin/director. Issue list is filterable by `?handler_type=` and shows a Facility/Vendor badge. `Issue.handler_label` gives the display string. Not yet exposed in the mobile API. **Photo columns — three distinct fields with different semantics:** | Column | Type | Populated by | Displayed as | |---|---|---|---| | `photo_path` | `VARCHAR(255)` | Web form upload OR first iPad photo | "Photo Evidence" (primary) | | `mobile_photo_paths` | `JSON` (`list[str]`) | iPad PATCH `/issues//photos` — extra evidence photos | "Photo Evidence" (additional) | | `result_photos` | `JSON` (`list[str]`) | Web update form file upload — resolution photos | "Resolution Details" | **Rule:** Never write iPad evidence photos into `result_photos`. They belong in `mobile_photo_paths` so they appear under "Photo Evidence" on the web, not "Resolution Details". **`reported_by`:** Added in phase18. Set at creation time to the user who filed the issue. Nullable for backward compatibility. Used by `GET /api/v1/issues` to return issues the inspector created but hasn't been assigned yet. ### Notification / NotificationPreference ``` notifications: id, user_id, title, body, link, is_read, created_at, issue_id, inspection_id, event_type VARCHAR(50) NULL, digest_pending notification_preferences: id, user_id, event_type, email_enabled, digest_mode, digest_frequency ``` ### IssueComment ``` issue_comments: id, issue_id (FK), user_id (FK), body, created_at, status_at_time, is_customer_visible (BOOLEAN, default False) ← Phase 22 ``` **`is_customer_visible`:** Staff comments are hidden from customers by default (`False`). Staff can tick "Share with customer" at post time to set `True`. Customer-authored comments are always stored as `True`. Customers see only `is_customer_visible=True` comments; staff see all. ### FacilityScoreAlert ``` facility_score_alerts: id, facility_id (FK→facilities CASCADE), sent_at DATETIME, current_avg DECIMAL(5,2), prior_avg DECIMAL(5,2), delta DECIMAL(5,2) INDEX ix_fsa_facility_sent (facility_id, sent_at) ``` Records each score-trend alert dispatched for a facility. `send_score_alerts()` queries this table to skip re-alerting a facility within the last 24 hours, preventing notification storms on persistent score drops. ### SupportTicket / SupportTicketReply ``` support_tickets: id, customer_id (FK→users SET NULL), facility_id (FK→facilities SET NULL), subject VARCHAR(200), body TEXT, status VARCHAR(20) DEFAULT 'open', created_at DATETIME status values: open / answered / closed support_ticket_replies: id, ticket_id (FK→support_tickets CASCADE), user_id (FK→users SET NULL), body TEXT, created_at DATETIME ``` **Flow:** - Customer submits ticket via chat page modal → status `open` → admins notified (in-app + email) - Admin replies → status auto-advances to `answered` → customer notified (in-app + email, link to `/support/my-tickets/`) - Customer adds follow-up → status reverts to `open` → admins notified again - Admin can manually set: `open` / `answered` / `closed` - Closed tickets cannot receive new replies from customers ### NotificationMatrix ``` notification_matrix: id, event_type, role_key, enabled, custom_emails (JSON) UniqueConstraint(event_type, role_key) ``` ### AuditLog ``` audit_logs: id, user_id (nullable), username (snapshot), user_role (snapshot), action, entity_type, entity_id, entity_label, details, created_at (indexed), ip_address ``` ### RefreshToken / DeviceToken ``` api_refresh_tokens: id, user_id, token_hash (SHA-256, unique), device_id, device_name, created_at, expires_at, revoked api_device_tokens: id, user_id, device_id, apns_token, device_name, app_version, ios_version, registered_at, last_seen_at ← ios_version + last_seen_at added phase32 UniqueConstraint(user_id, device_id) ``` `api_device_tokens` is the **single** source of truth for device tracking. It is upserted by `POST /api/v1/devices/register` (in `app/api/auth.py`) on every app foreground and read by the admin Devices page (`/admin/devices`). The earlier `device_registrations` table / `DeviceRegistration` model was removed — see §17 phase30–32. ### Broadcast ``` broadcasts: id, title VARCHAR(255), body TEXT, target_roles (JSON list of role strings), sent_by_id (FK→users SET NULL), sent_at DATETIME, recipient_count INT ``` Admin-authored broadcast messages. Sending a broadcast fans out one `Notification` row per targeted user; the iPad picks them up through its existing `GET /api/v1/notifications?since=...` poll — **no dedicated broadcast API endpoint exists**. `recipient_count` snapshots how many notifications were created. Managed at `/admin/broadcast` (see §7 `broadcast` blueprint). ### ContractNotificationRecipient ``` contract_notification_recipients: id, project_id (FK→projects CASCADE, indexed), user_id (FK→users CASCADE, nullable, indexed), -- staff-user recipient email VARCHAR(200) nullable, -- external email recipient event_types TEXT (JSON list of event_type keys), created_at ``` **Per-contract additional notification recipients.** Each row is ONE extra recipient attached to a Contract who is notified — for the `event_types` they subscribe to — whenever those events fire within that contract's facilities, **in addition to** the global `NotificationMatrix` routing. Exactly one of `user_id` / `email` is set (enforced in the route, not the DB): - `user_id` set → existing staff user → **in-app notification + email** - `email` set → free-form external address → **email only** `event_types` is a JSON list of `MATRIX_EVENTS` keys. A recipient fires only when the event is in its list. Managed admin-only on the **Contract detail page** (`/projects/`) via `add_notify_recipient` / `remove_notify_recipient`. Dispatch is resolved centrally in `notify_by_matrix()` — see §11. ### ScheduledInspection ``` scheduled_inspections: id, facility_id (FK→facilities CASCADE), template_id (FK→inspection_templates CASCADE), inspector_id (FK→users SET NULL), frequency ENUM('once','daily','weekly','monthly'), next_due_date DATE, active BOOL, notes TEXT, created_by, created_at, last_completed_at DATETIME, advance_notified BOOL, due_notified BOOL, overdue_notified BOOL inspections.scheduled_inspection_id FK→scheduled_inspections SET NULL ← Phase 36 ``` **A plan, not an inspection.** Names a facility + template + assigned inspector + `next_due_date`. Lifecycle: - The assigned inspector (or a manager) clicks **Start** → `scheduled_inspections.start` creates a normal `in_progress` Inspection with `scheduled_inspection_id` set, then redirects to the execute flow. - On **completion** (execute route, status → `completed`), `ScheduledInspection.fulfill()` runs in the same atomic commit: `once` → `active=False`; recurring → `next_due_date` rolls forward past today via `_add_interval()` and the three `*_notified` flags reset. - **Assignment notification** (immediate): on **create**, the assigned inspector gets an in-app + email "assigned to you" notification; on **edit**, only when the inspector actually changes (a "reassigned to you" notification to the new assignee). Via `_notify_assignee()` in the blueprint using `event_type=EVENT_SCHEDULED_INSPECTION`. - **Reminders** are dispatched by the cron endpoint (see §11): advance (1 day before) + due-date to the inspector, overdue to admin/director — each fires at most once per occurrence via the `*_notified` flags. Uses `notify()` with `event_type=EVENT_SCHEDULED_INSPECTION`. - Dashboard shows an **upcoming (next 7 days) / overdue** panel for non-customers (inspectors see only their own). Management (`/scheduled-inspections/new|edit|delete`) is `@project_manager_required`; **Start** is the assigned inspector or a manager; inspectors' list/dashboard views are scoped to their own `inspector_id`. --- ## 6. Role & Permission Matrix | Area | admin | director | project_manager | inspector | customer | |---|---|---|---|---|---| | Dashboard | ✅ full | ✅ full | ✅ full | ✅ limited | ✅ scoped | | Users | ✅ | ✅ | ❌ | ❌ | ❌ | | Notification Matrix | ✅ only | ❌ | ❌ | ❌ | ❌ | | Customers | ✅ | ✅ | ❌ | ❌ | ❌ | | Facilities | ✅ | ✅ | ✅ | read | scoped | | Facility QR (view/print) | ✅ | ✅ | ✅ | ✅ | scoped | | Facility QR (regenerate) | ✅ | ✅ | ❌ | ❌ | scoped | | Contracts | ✅ | ✅ | ✅ | read | scoped | | Templates | ✅ | ✅ | ❌ | ❌ | ❌ | | Inspections (execute) | ✅ | ✅ | ✅ | ✅ | read | | Issues (create/assign) | ✅ | ✅ | ✅ | ✅ | ✅ create own | | Issues (quick-assign) | ✅ | ✅ | ❌ | ❌ | ❌ | | Issue verification | ✅ | ✅ | ❌ | ❌ | ❌ | | Issue comments | ✅ | ✅ | ✅ | ✅ | followed/reported issues only | | Support Chat (AI) | ❌ | ❌ | ❌ | ❌ | ✅ | | Support Tickets (manage) | ✅ | ✅ | ❌ | ❌ | own only | | Reports | ✅ | ✅ | ✅ | ✅ | scoped | | Scheduled Reports | ✅ | ✅ | ✅ | ❌ | ❌ | | Audit Trail | ✅ only | ❌ | ❌ | ❌ | ❌ | | Mobile API | ✅ | ✅ | ✅ | ✅ | ❌ | ### Decorator Map ```python @admin_required # role == 'admin' only @supervisor_required # role in ('admin', 'director') — name kept to avoid touching 30+ routes @project_manager_required # role in ('admin', 'director', 'project_manager') @customer_required # role == 'customer' only ``` --- ## 7. Blueprint Prefixes & Route Inventory | Blueprint | Prefix | Notable routes | |---|---|---| | `auth` | `/auth` | `/login`, `/logout`, `/profile`, `/users/*`, `/notification-matrix` | | `dashboard` | `/` | `GET /`, `/facility-trend` (AJAX) | | `facilities` | `/facilities` | CRUD + area management + QR code: `//qr` printable page, `//qr.png` image, `POST //qr/regenerate` (invalidates old printed code), `/qr/print-all[?contract_id=]` bulk sheet. **Customers may use all QR actions (including regenerate) for their own assigned facilities**; inspectors/PM/admin/director for any. Scope enforced by `_facility_for_qr_or_403()` (customers) / `get_customer_scope` (print-all). Regenerate is limited to admin/director + scoped customer (PM/inspector excluded). | | `public` | `/f` | **No login.** `GET /` occupant facility summary; `POST //report` occupant issue report (rate-limited `5/hour`, honeypot). Resolves ACTIVE facility by `public_token` or 404. | | `projects` | `/projects` | CRUD + customer assignment management + notification-recipient add/remove (`//notify-recipients/add`, `/notify-recipients//remove` — admin only) | | `customers` | `/customers` | list, invite, set-password, manage, import CSV | | `inspections` | `/inspections` | list, start, execute, view, PDF export, flag-issue, save-draft (AJAX), flag-followup, reinspect, upload-photo (AJAX) | | `templates` | `/templates` | list, create, edit, delete, form editor, preview | | `issues` | `/issues` | list, view, create, update, verify, comment, follow/unfollow, verification queue, bulk-verify, delete, quick-assign | | `notifications` | `/notifications` | list, mark-read, preferences, send-digest (cron), check-sla (cron), cleanup-tokens (cron) | | `audit` | `/audit` | list (admin only), view, purge | | `reports` | `/reports` | index, facility report, scorecard, CSV/PDF/Excel export, issues-aging, sla-compliance, followup-closure, facility summary PDF | | `scheduled_reports` | `/scheduled-reports` | CRUD + manual trigger (accessible via Reports sub-nav) | | `scheduled_inspections` | `/scheduled-inspections` | list, new/edit/delete (PM+), `GET //start` (assigned inspector or manager → creates linked inspection), `POST /run` (cron reminders, `token=DIGEST_SECRET`) | | `support` | `/support` | `GET /chat`, `POST /chat/message` (AJAX→Groq), `POST /tickets`, `GET /my-tickets`, `GET/POST /my-tickets/`, `GET /admin/tickets`, `GET/POST /admin/tickets/` | | `broadcast` | `/admin/broadcast` | `GET /` (compose + history), `POST /send` (admin-only; fans out one Notification per targeted user) | | `devices` | `/admin/devices` | `GET /` (device list from `api_device_tokens`), `POST /notify` (admin-only) | | `api` | `/api/v1` | parent blueprint | | `api_auth` | `/api/v1` | `/auth/login`, `/auth/refresh`, `/auth/logout`, `/auth/me`, `/devices/register` | | `api_facilities` | `/api/v1` | `/facilities`, `/facilities//areas` | | `api_templates` | `/api/v1` | `/templates`, `/templates/` | | `api_inspections` | `/api/v1` | `GET /inspections`, `POST /inspections`, `PATCH /inspections/` | | `api_issues` | `/api/v1` | `GET /issues`, `POST /issues`, `GET /issues/`, `PATCH /issues//status`, `PATCH /issues//photos` ← Phase 19 | | `api_photos` | `/api/v1` | `POST /photos/upload` | | `api_notifications` | `/api/v1` | `GET /notifications`, `PATCH /notifications/mark-read` | | `api_stats` | `/api/v1` | `GET /stats/dashboard` — inspector-scoped KPIs with severity breakdown (Phase B) | | `api_comments` | `/api/v1` | `GET /issues//comments`, `POST /issues//comments` (Phase D) | --- ## 8. Utility Modules ### `time_utils.py` `now_eastern()` — always use this, never `datetime.utcnow()`. ### `audit.py` `log_action(action, entity_type, entity_id, entity_label, details)` — call **after** `db.session.commit()`. **This function calls `db.session.commit()` internally.** Calling it before the primary commit will prematurely persist any dirty ORM state in the session. ### `mail_utils.py` `branded_sender(base_url=None)` — returns a Flask-Mail `(display_name, address)` sender tuple whose identity tracks the current host, used by the customer invite email. Two things vary independently: - **Display name** (always applied, zero DNS): per-domain brand from `BRAND_NAMES` (fallback `DEFAULT_BRAND_NAME`), e.g. `"Gov Services QC"`. - **From address** (gated): the authenticated local part (`jqc.noreply`) with the host's registrable domain — but **only** for the authenticated sender's own domain or a domain listed in `SENDER_AUTHORIZED_DOMAINS`. Every other domain keeps the authenticated `MAIL_DEFAULT_SENDER` address so it still passes SPF/DMARC and delivers. So with no DNS work an invite from `jqc.govservicesinc.com` sends `From: "Gov Services QC" ` (branded name, deliverable address). After that domain's SPF `include:` + DKIM are live, add it to `SENDER_AUTHORIZED_DOMAINS` and it upgrades to `` — no code change. Falls back to the bare authenticated sender string for unparseable hosts (localhost, empty). Edit `BRAND_NAMES` / `SENDER_AUTHORIZED_DOMAINS` as brands and DNS come online. See rule 64. ### `scope.py` `get_customer_scope(user)` — returns `list[int]` facility IDs for customers, `None` for non-customers. `get_inspector_scope(user)` — returns `list[int]` facility IDs for inspectors (empty list = no assignments = no access), `None` for non-inspectors. Derived from `InspectorAssignment` rows → project → active facilities. ### `forms.py` All WTForms classes. `AreaForm.area_type` includes `floor`. `UserForm` excludes `customer` role. ### `notifications.py` `notify()`, `notify_by_matrix()`, `notify_customers_for_facility()` — all email sent in background thread. `notify()` stores `event_type` on the `Notification` record (phase17+). `flag_followup` route calls `notify()` for the original inspector. ### `sla.py` `sla_status(issue)` → `'ok'` | `'at_risk'` | `'breached'` | `None` (resolved). ### `pdf_export.py` ReportLab-based. 12-column grid must be preserved — never collapse in PDF views. **Public functions:** - `generate_inspection_pdf(inspection, form_fields, form_data, issues, static_folder)` — per-inspection PDF - `generate_issues_list_pdf(issues, filter_summary)` — landscape issues list PDF (from issues list export) - `generate_inspections_list_pdf(inspections, filter_summary)` — landscape inspections list PDF - `generate_facility_summary_pdf(facility, days, start, now, total_inspections, avg_score, area_scores, open_issues, resolved_count)` — customer-facing one-page facility summary PDF (Phase R4) **`_build_styles()` registered style names:** `ReportTitle`, `ReportSub`, `SectionHead`, `FieldLabel`, `FieldValue`, `MetaLabel`, `MetaValue`, `IssueDesc`, `FooterStyle`, `SummaryTitle`, `ReportSubtitle`, `Meta`, `ScoreValue`, `ScoreLabel`, `SectionHeader`, `TableHeader`, `TableCell` The last eight styles (`SummaryTitle` through `TableCell`) were added for the facility summary PDF and are available for any future customer-facing PDF functions. --- ## 9. Mobile API (Phase 7 / Phase A–E) ### CSRF Exemption Pattern — Critical **`csrf.exempt(api_bp)` does NOT cascade to sub-blueprints.** Each child blueprint must be exempted individually in `app/__init__.py`. The new `api_issues` blueprint (including its `PATCH /issues//photos` route) inherits the exemption already applied to `_api_issues_bp`. **Every new blueprint must add its own `csrf.exempt()` line before `register_api(app)`.** ### Auth Flow 1. `POST /api/v1/auth/login` → access token (60 min JWT) + refresh token (30 day opaque hex) 2. Bearer token on every request 3. `POST /api/v1/auth/refresh` → token rotation (old revoked, new issued) 4. `POST /api/v1/auth/logout` → revokes refresh token ### Phase A Endpoints | Endpoint | Auth | Description | |---|---|---| | `GET /api/v1/facilities` | jwt_required | All active facilities scoped to user | | `GET /api/v1/facilities//areas` | jwt_required | Areas for a facility | | `GET /api/v1/templates` | jwt_required | Template list (summary, no form_schema) | | `GET /api/v1/templates/` | jwt_required | Full template with form_schema | ### Phase B Endpoints | Endpoint | Auth | Description | |---|---|---| | `POST /api/v1/inspections` | jwt_required | Create inspection; idempotent via `mobile_local_id` | | `PATCH /api/v1/inspections/` | jwt_required | Update inspection (draft → completed) | | `POST /api/v1/issues` | jwt_required | Create issue; idempotent via `mobile_local_id`; accepts `result_photos` list stored in `mobile_photo_paths` | | `POST /api/v1/photos/upload` | jwt_required | Multipart photo upload; returns `server_path` | ### Phase C Endpoints | Endpoint | Auth | Description | |---|---|---| | `GET /api/v1/inspections` | jwt_required | Inspector's own inspection history (paginated) | | `GET /api/v1/issues` | jwt_required | Issues assigned to OR reported by current user (inspectors); all non-resolved (admin/director/PM) | | `GET /api/v1/issues/` | jwt_required | Single issue detail | | `PATCH /api/v1/issues//status` | jwt_required | Update issue status | | `GET /api/v1/notifications` | jwt_required | Unread notifications; accepts `?since=` | | `PATCH /api/v1/notifications/mark-read` | jwt_required | Mark list of notification IDs as read | ### Phase 19 Endpoint | Endpoint | Auth | Description | |---|---|---| | `PATCH /api/v1/issues//photos` | jwt_required | Attach extra evidence photos to an issue. Accepts `{ "result_photos": ["uploads/..."] }`. Stores in `mobile_photo_paths` (NOT `result_photos`). Idempotent — merges with existing paths, never overwrites. | ### Phase B (Stats) Endpoint | Endpoint | Auth | Description | |---|---|---| | `GET /api/v1/stats/dashboard` | jwt_required | Inspector-scoped KPIs: `today_inspections`, `completed_today`, `open_issues`, `avg_score_30d`, `pending_followups`, `sla_breached`, `sla_at_risk`, `severity_breakdown` (dict: critical/high/medium/low). Inspectors scoped to contracted facilities. Admins/directors/PMs get org-wide numbers. Customers get 403. | ### Phase D (Comments) Endpoints | Endpoint | Auth | Description | |---|---|---| | `GET /api/v1/issues//comments` | jwt_required | All comments oldest-first. Returns: `id`, `issue_id`, `author_name`, `author_role`, `status_at_time`, `body`, `created_at`. Inspectors limited to contracted facilities. | | `POST /api/v1/issues//comments` | jwt_required | Add a comment. Body: `{ "body": "..." }`. Fires `notify_by_matrix('issue_comment')`. Calls `log_action()` after commit. | ### Phase E Additions to Existing Endpoints `_issue_payload()` in `issues.py` now returns `area_name` and `assigned_to_name` (both nullable). These populate `LocalIssue.areaNameCache` and `LocalIssue.assignedToName` on the iPad after every `pullAssignedIssues()`. `refreshStatusFromServer()` also refreshes them on demand. `stats.py` now returns `severity_breakdown` dict alongside the existing KPIs. Derived from the already-loaded `open_issues_all` list — zero extra DB queries. ### Issue API — `_issue_payload()` fields ```python { 'id', 'status', 'severity', 'description', 'assigned_to', 'facility_id', 'facility_name', 'reported_at', 'resolved_at', 'mobile_local_id', 'photo_path', # primary evidence photo (first iPad photo or web upload) 'mobile_photo_paths', # extra evidence photos from iPad (list) 'result_photos', # resolution photos added via web form (list) # Phase A additions: 'result_notes', # resolution notes entered by web staff 'verified_at', # ISO 8601 datetime when fix was verified (nullable) 'verification_note', # note from the verifier (nullable) 'reported_by_name', # display_name of User who filed the issue (nullable) # Phase E additions: 'area_name', # name of the Area the issue was flagged in (nullable) 'assigned_to_name', # display_name of currently assigned User (nullable) } ``` **iOS reads `photo_path` + `mobile_photo_paths` into `photoServerPaths`. It does NOT read `result_photos` — those are web-only resolution photos.** ### Issue API Scope Rules - **Inspector:** `GET /issues` returns issues where `assigned_to == current_user.id` **OR** `reported_by == current_user.id`. - **Admin / Director / Project Manager:** `GET /issues` returns all non-resolved issues (default) or filtered by `?status=`. - `GET /issues/` and `PATCH /issues//status` and `PATCH /issues//photos` all enforce the same combined inspector check. ### Photo Upload Flow (multi-photo issues) ``` 1. iPad calls POST /api/v1/photos/upload × N → gets N server_path strings 2. iPad calls POST /api/v1/issues → sends photo_path = paths[0] result_photos = paths[1:] (stored in mobile_photo_paths) 3. iPad calls PATCH /api/v1/issues//photos → sends result_photos = paths[1:] (PATCH is belt-and-suspenders for race safety) ``` Web template shows `photo_path` + `mobile_photo_paths` together under **"Photo Evidence"**. `result_photos` (resolution photos from web form) appears under **"Resolution Details"**. ### Facility deduplication `pullReferenceData()` deduplicates the `/api/v1/facilities` response by `id` before upserting. The server may return the same facility ID more than once (one row per contract assignment). Without deduplication, the same building appears twice in every picker. The dedup uses a `seenFacilityIds = Set()` filter on the iOS side AND the upsert map (`facilityMap`) on the server side. ### Idempotency Pattern All Phase B write endpoints accept `mobile_local_id` (UUID string from device). On receipt, check for existing record and return `{ 'duplicate': True }` without inserting. Web-created records have `mobile_local_id = NULL`. ### Score Calculation (Server-Side) `app/api/inspections.py::_compute_score()` mirrors `routes/inspections.py::_compute_score_from_form()` exactly. Rating value `0` = unanswered → excluded. Returns `float` 0–100 or `None` if no scoreable fields. --- ## 10. iPad Native App See the iOS app's own `CLAUDE.md` for full details. Key integration points: - App connects to `jqc.ltservicesinc.com` (primary) or `jqc1.ltservicesinc.com` (secondary) — **server is user-selectable at login and in Settings**. - Server selection is persisted to `UserDefaults` via `ServerConfig`. Switching server in Settings triggers a logout confirmation alert and clears all server-pulled SwiftData records (`serverId != nil`) before logout. - All photo evidence from the iPad routes through `mobile_photo_paths` on the server — never through `result_photos`. --- ## 11. Notification System ### Event Constants (`app/models/notification.py`) ``` EVENT_ISSUE_ASSIGNED = 'issue_assigned' EVENT_ISSUE_STATUS = 'issue_status' EVENT_ISSUE_COMMENT = 'issue_comment' EVENT_ISSUE_FOLLOW = 'issue_follow_update' EVENT_INSPECTION_DONE = 'inspection_completed' EVENT_SLA_ALERT = 'sla_alert' EVENT_ISSUE_FLAGGED = 'issue_flagged' EVENT_CUSTOMER_INSPECTION_DONE = 'customer_inspection_completed' EVENT_CUSTOMER_ISSUE_UPDATED = 'customer_issue_updated' EVENT_SCORE_ALERT = 'score_alert' ← Phase 27 EVENT_SCHEDULED_INSPECTION = 'scheduled_inspection' ← Phase 36 ``` ### Per-Contract Additional Recipients (Phase 33) `notify_by_matrix()` is the single dispatch point for all broadcast events. After routing to the global matrix roles + global custom emails, it calls `_notify_contract_recipients()`, which: 1. Resolves the owning contract via `_resolve_project_id(facility_id, issue_id, inspection_id)` — tries `facility_id`, then the issue's facility (or `issue.area.facility_id`), then the inspection's facility. 2. Loads `ContractNotificationRecipient` rows for that project and notifies each one whose `event_types` contains the firing event. 3. **Deduplicates** against users already notified this dispatch (shared `notified` set) and emails already sent (shared `sent_emails` set), so a user who is both a matrix role AND a contract recipient gets exactly one notification. Contract recipients fire **regardless of matrix role toggles** — they are additive, not gated by the matrix. Staff-user recipients use `respect_preferences=False` (contract config is authoritative, mirroring matrix broadcasts). Commit is the **caller's** responsibility, same as the rest of `notify_by_matrix()`. ### Cron Endpoints (all require `token=DIGEST_SECRET`) | Endpoint | Purpose | Schedule | |---|---|---| | `POST /notifications/send-digest` | Digest email delivery | `0 7 * * *` | | `POST /notifications/check-sla` | SLA breach/at-risk alerts | `*/30 * * * *` | | `POST /notifications/cleanup-tokens` | Purge expired API tokens | `0 3 * * *` | | `POST /notifications/check-score-trends` | Facility score drop alerts (Phase 27) | `0 8 * * *` | | `POST /scheduled-inspections/run` | Scheduled inspection reminders — advance/due to inspector, overdue to admin/director (Phase 36) | `*/30 * * * *` | --- ## 12. SLA Engine | Severity | Window | At-Risk | |---|---|---| | critical | 4h | 3h | | high | 24h | 18h | | medium | 72h | 54h | | low | 168h | 126h | `issue.sla_notified` prevents duplicate cron notifications. --- ## 13. Audit Trail - Admin-only at `/audit/` — director is excluded - Actions: `CREATE`, `UPDATE`, `DELETE`, `LOGIN`, `LOGOUT`, `EXPORT` - Mobile API routes call `log_action()` for all create/update operations - Immutable — never updated or deleted through the application --- ## 14. PDF Export ReportLab — `app/utils/pdf_export.py`. **12-column grid must be preserved** — do not collapse in print/PDF. --- ## 15. Scheduled Reports Types: `summary`, `facility`, `issues`. Frequencies: `daily`, `weekly`, `monthly`. Cron: `POST /scheduled-reports/run?secret=` --- ## 16. Rate Limiting ```python limiter = Limiter( key_func = get_remote_address, default_limits = [], storage_uri = os.environ.get('REDIS_URL', 'memory://'), ) ``` **Production:** Set `REDIS_URL=redis://127.0.0.1:6379/0`. --- ## 17. Alembic Migration Chain ``` phase1_projects_roles → phase6_features → phase7_mobile_api → phase8_notification_matrix → phase9_user_full_name → phase10_customer_password_setup → phase11_director_role → phase12_performance_indexes → phase_b_mobile_local_id → phase13_issue_facility → phase14_facility_created_at → phase15_audit_log_indexes → phase16_notifications_columns → phase17_notification_event_type → phase18_issue_reported_by → phase19_issue_mobile_photos → phase20_inspector_assignments → phase21_template_active → phase21_performance_indexes → phase22_comment_visibility → phase23_support_tickets → phase24_notify_defaults → phase25_inspection_gps → phase26_issue_vendor → phase27_score_alerts → phase28_fix_inspection_notify → phase29_broadcasts → phase30_device_registry → phase31_device_registry → phase32_device_token_columns → phase33_contract_recipients → phase34_facility_qr → phase35_issue_handler → phase36_scheduled_insp ← HEAD ``` ### phase21_performance_indexes Adds four composite indexes covering the highest-traffic multi-column query patterns: `(facility_id, inspection_date)` and `(inspector_id, inspection_date)` and `(status, inspection_date)` on `inspections`; `(facility_id, status)` on `issues`. All single-column indexes already exist from phase12. Uses `INFORMATION_SCHEMA.STATISTICS` existence check — safe to re-run. **Deploy order for phase21:** ```bash flask db upgrade sudo systemctl restart gunicorn ``` ### phase21_template_active Adds `active` boolean column to `inspection_templates` so templates can be deactivated without deletion. Inactive templates are hidden from the inspection-start form but remain accessible in the template management UI. Uses `INFORMATION_SCHEMA` column existence check — safe to re-run. ### phase23_support_tickets Creates `support_tickets` and `support_ticket_replies` tables. Uses table existence check — safe to re-run. **Deploy order:** ```bash flask db upgrade pip install groq # if not already installed # Set GROQ_API_KEY in environment / systemd unit sudo systemctl restart gunicorn ``` ### phase24_notify_defaults Data-only migration. Sets `enabled=True` for `('issue_created', 'admin')` and `('issue_created', 'director')` rows in `notification_matrix` if they already exist. Rows that do not yet exist are seeded at runtime by `MATRIX_DEFAULTS`. No schema change — no existence check needed, `UPDATE` on missing rows is a no-op. ### phase25_inspection_gps Adds `submit_latitude DECIMAL(10,7) NULL` and `submit_longitude DECIMAL(10,7) NULL` to `inspections`. Populated at submit time — by browser Geolocation API (web) or CoreLocation (iPad). Null for all existing rows. Uses `INFORMATION_SCHEMA` column existence check — safe to re-run. `inspections/view.html` shows a Google Maps embed (admin/director only) when both columns are non-null. **iPad behaviour:** `InspectionLocationManager` begins acquiring a fix when the submit confirm dialog appears. GPS is captured into `LocalInspection.submitLatitude`/`submitLongitude` and sent in the `POST /api/v1/inspections` body. The `PATCH` endpoint does not accept GPS — creation-time capture only. ### phase26_issue_vendor Adds three nullable columns to `issues`: | Column | Type | Purpose | |---|---|---| | `vendor_name` | `VARCHAR(100)` | External contractor or vendor name | | `vendor_contact` | `VARCHAR(200)` | Phone or email for the vendor | | `vendor_notes` | `TEXT` | Notes about what the vendor is handling | Displayed in `issues/view.html` and editable via `IssueForm` (`form.html`). Staff-only — not exposed in mobile API. Uses `INFORMATION_SCHEMA` existence check — safe to re-run. ### phase27_score_alerts Creates `facility_score_alerts` table. Used by `send_score_alerts()` in `sla.py` for 24-hour deduplication of score-drop notifications. Uses table existence check — safe to re-run. ### phase28_fix_inspection_notify Data-only migration. Resets the `notification_matrix` rows for `('inspection_completed', 'director')`, `('inspection_completed', 'admin')`, and `('inspection_completed', 'customer')` to `enabled=True`, matching `MATRIX_DEFAULTS`. These had been inadvertently disabled (likely via an accidental checkbox save on the matrix page), suppressing inspection-completed notifications from both web and mobile API. No schema change. ### phase29_broadcasts Creates the `broadcasts` table backing the admin broadcast feature (see §5 `Broadcast` and §7 `broadcast` blueprint). Uses table existence check — safe to re-run. ### phase30–32_device_registry (consolidation — read as a unit) These three migrations are the history of a **false start** in device tracking. Net effect after all three: the app tracks devices exclusively in **`api_device_tokens`** (`DeviceToken` model); the short-lived `device_registrations` table and its `DeviceRegistration` model no longer exist. - **phase30_device_registry** — created a separate `device_registrations` table (the abandoned approach). - **phase31_device_registry** — drops `device_registrations` (`DROP TABLE IF EXISTS`). - **phase32_device_token_columns** — the live path. Adds `ios_version VARCHAR(20)` and `last_seen_at DATETIME` to `api_device_tokens` (phase31's ALTERs were recorded-but-never-executed, so phase32 re-applies them via `INFORMATION_SCHEMA` existence checks) and drops the orphaned `device_registrations` table if still present. Safe to re-run. **The dead `DeviceRegistration` model, `app/api/devices.py` endpoint, and `api_devices` blueprint were removed (July 2026).** They defined a *second* `POST /api/v1/devices/register` that was shadowed at routing time by the `api_auth` copy and would have crashed anyway (it queried the dropped `device_registrations` table). Device registration now has a single implementation: `register_device()` in `app/api/auth.py`, writing to `api_device_tokens`. Do not reintroduce a competing device model or a duplicate register route. ### phase33_contract_recipients Creates the `contract_notification_recipients` table backing **per-contract additional notification recipients** (see §5 `ContractNotificationRecipient` and §11). Uses table existence check — safe to re-run. **Deploy order:** ```bash flask db upgrade sudo systemctl restart gunicorn ``` ### phase34_facility_qr Revision id `phase34_facility_qr` (file `phase34_facility_public_token.py`). Adds `facilities.public_token VARCHAR(48)` (unguessable, unique) and **backfills a token for every existing facility** in the migration body, then creates the `uq_facility_public_token` unique index. Backs the public QR landing pages (see §5 `Facility.public_token` and the Public Facility QR section in §7). Uses `INFORMATION_SCHEMA` checks — safe to re-run. **Deploy order:** ```bash pip install qrcode # new dependency (Pillow already present) flask db upgrade # adds + backfills public_token sudo systemctl restart gunicorn ``` ### phase35_issue_handler Revision id `phase35_issue_handler` (file `phase35_issue_handler_type.py`). Adds to `issues`: `handler_type ENUM('internal','facility','vendor') NOT NULL DEFAULT 'internal'` and `facility_handler_name/contact/notes`. **Backfills** existing rows with a non-empty `vendor_name` to `handler_type='vendor'`. Separates WHO handles an issue (see §5 Issue + the Handler section). `INFORMATION_SCHEMA` checks — safe to re-run. **Deploy order:** ```bash flask db upgrade sudo systemctl restart gunicorn ``` ### phase36_scheduled_insp Revision id `phase36_scheduled_insp` (file `phase36_scheduled_inspections.py`). Creates `scheduled_inspections` (planned/recurring inspection assignments) and adds `inspections.scheduled_inspection_id` (FK → scheduled_inspections, SET NULL) that links a completed inspection back to the schedule that prompted it. See §5 `ScheduledInspection` and the Scheduled Inspections notes in §7/§11. `INFORMATION_SCHEMA` checks — safe to re-run. **Deploy order:** ```bash flask db upgrade sudo systemctl restart gunicorn # Add to cron (reminders — advance/due to inspector, overdue to admin/director): # */30 * * * * curl -s -X POST https://yourdomain.com/scheduled-inspections/run \ # -d "token=YOUR_DIGEST_SECRET" ``` **Deploy order for phases 24–32:** ```bash flask db upgrade sudo systemctl restart gunicorn # Add to cron: # 0 8 * * * curl -s -X POST https://yourdomain.com/notifications/check-score-trends \ # -d "token=YOUR_DIGEST_SECRET" ``` ### phase22_comment_visibility Adds `is_customer_visible BOOLEAN NOT NULL DEFAULT FALSE` to `issue_comments`. Existing comments default to staff-only visibility. Uses `INFORMATION_SCHEMA` column existence check — safe to re-run. ### phase19_issue_mobile_photos Adds `mobile_photo_paths JSON NULL` to `issues` table. Stores extra evidence photos submitted from the iPad at issue-creation time, separate from `result_photos` (resolution photos) so they appear under "Photo Evidence" on the web. Uses `INFORMATION_SCHEMA` existence check — safe to re-run. **Deploy order for phase19:** ```bash flask db upgrade # add mobile_photo_paths column sudo systemctl restart gunicorn ``` ### MySQL ENUM Change Protocol (3 steps — always follow) ```sql -- 1. Expand ALTER TABLE users MODIFY COLUMN role ENUM('admin','supervisor','director',...) NOT NULL; -- 2. Migrate UPDATE users SET role = 'director' WHERE role = 'supervisor'; -- 3. Contract ALTER TABLE users MODIFY COLUMN role ENUM('admin','director',...) NOT NULL; ``` ### MySQL Compatibility Rules - **Revision ids must be ≤ 32 characters.** Alembic's `alembic_version.version_num` column is `VARCHAR(32)`. A longer `revision = '...'` value passes `flask db upgrade`'s DDL step but fails when Alembic writes the version row (`Data too long for column 'version_num'`), often leaving the schema changed but the version un-recorded. The *filename* may be longer (e.g. `phase24_issue_created_notify_defaults.py`), but the `revision` id inside must be short (`phase24_notify_defaults`). Count before committing a new migration. - **`CREATE INDEX IF NOT EXISTS`** — not supported on MySQL < 8.0.12. Always use `INFORMATION_SCHEMA.STATISTICS` check first. - **`batch_alter_table`** — SQLite-only workaround; do not use for MySQL migrations. - **Migration deploy order:** Always run `flask db upgrade` before swapping `app/__init__.py` if the new version imports models that reference the new columns. ### Deprecated SQLAlchemy Patterns ```python # WRONG Model.query.get(id) # CORRECT obj = db.session.get(Model, id) if obj is None: abort(404) ``` --- ## 18. Frontend Conventions ### Active Nav Tab Detected via `request.endpoint.startswith('.')` in each nav `` tag. ### Admin Nav Dropdown Admin-only tools (Users, Audit Trail, Notification Matrix, Broadcast, Devices) are consolidated into a single **Admin** dropdown in `base.html` (plain text items, no icons, no dividers — matching sibling top-level nav links). The dropdown toggle shows `active` when any of its endpoints is active (`admin_active` flag). The separate user-menu dropdown keeps its own dividers — don't `replace_all` on `dropdown-divider` across the file. ### Display Names Always use `user.display_name` in templates — never `.username` for display purposes. ### Status Label Map | DB value | Displayed as | |---|---| | `completed` | **Submitted** | | `in_progress` | In Progress | | `flagged` | Flagged | | `open` | Open | | `resolved` | Resolved | | `pending_verification` | Pending Verification | ### Forms - Flask-WTF CSRF auto-applied to all web forms - **Never nest `
` tags** — browsers silently discard inner forms ### Real-Time **SSE banned.** All "live" updates use polling. ### Issue Photo Evidence Display (view.html) `view.html` shows `photo_path` and `mobile_photo_paths` together under the **"Photo Evidence"** heading using a `d-flex flex-wrap gap-2` grid. `result_photos` (resolution photos) appear separately under **"Resolution Details"**. Do not merge these sections — they have different semantic meaning. ### Contract → Facility Cascade (filter bars and create form) The Contract selector is always a plain HTML `` (`#scoreContractFilter`) in the chart card header. It is **client-side only**: `reports.index()` attaches `project_id` + `contract` name to each `facility_scores` row and passes `score_contracts` (distinct `(project_id, name)` present, `0`/"No Contract" for unassigned). Selecting a contract filters both the Chart.js bars (`renderFacilityChart(pid)` mutates the existing chart) and the table rows (`.facility-score-row[data-project-id]`); default "All Contracts" shows everything. It does **not** reload the page or affect the top KPIs — only this section. Contracts shown are already role-scoped (customers/inspectors see only theirs). ### Reports — Phase R1: Issues Aging (`/reports/issues-aging`) Loads all non-resolved issues scoped by role, groups into five age buckets (`<24h`, `1–3 days`, `3–7 days`, `1–4 weeks`, `>4 weeks`). SLA status computed per-issue via `sla_status()`. Filters: severity, facility (both applied in Python after the main query to avoid double-outerjoin conflicts with customer scope). Excel export: `GET /reports/export/issues-aging` — one sheet, color-coded severity and SLA columns. Helper: `_load_open_issues_scoped(customer_facility_ids, severity_filter, facility_id_filter)` — extracted so both the HTML route and the Excel export share identical query logic. ### Reports — Phase R2: SLA Compliance (`/reports/sla-compliance`) Loads resolved issues in the date range, computes `within_sla()` per issue (compares elapsed hours to `SLA_HOURS[severity]`). Produces: - `overall_pct` — org/scope-wide compliance % - `by_severity` — dict with `total`, `met`, `pct`, `sla_hours` per severity tier - `by_facility` — list sorted by compliance % descending Helper: `_sla_within(issue)` — used by both the HTML route and the Excel export. Excel export: `GET /reports/export/sla-compliance` — 2 sheets: **By Severity** (with totals row) and **By Facility**. ### Reports — Phase R3: Follow-up Closure (`/reports/followup-closure`) `@supervisor_required`. Loads inspections with `follow_up_required=True` in date range. Determines which have been re-inspected via a separate `SELECT parent_inspection_id FROM inspections WHERE parent_inspection_id IN (...)` query — avoids iterating the dynamic `follow_ups` relationship. Annotates each inspection with `insp._has_followup = insp.id in followed_up_ids` (transient Python attribute, not an ORM column). Excel export: `GET /reports/export/followup-closure` — one sheet with color-coded "Followed Up?" column (green/red). ### Reports — Phase R4: Customer Facility PDF Summary `GET /reports/facility//summary-pdf` — available to all roles with facility access (customer scope enforced). Accepts `days` param (30/60/90/180/365; default 90). Calls `generate_facility_summary_pdf()` from `pdf_export.py`. Downloads directly as a PDF attachment. A **PDF Summary** button was added to `reports/scorecard.html` alongside the existing Full Report and period selector buttons. ### Support Chat — Customer UX `GET /support/chat` — customer only. Renders: - Greeting message with `current_user.display_name` (injected via `var userName = {{ current_user.display_name | tojson }}` — use `tojson` not inline interpolation to prevent XSS/quote breaks). - FAQ quick-reply chips: text stored in `data-faq="..."` HTML attribute (HTML-escaped with `| e`), read in JS via `btn.dataset.faq`. **Never use `| tojson` in an `onclick=""` attribute** — it emits double-quoted JSON inside a double-quoted attribute, breaking HTML parsing and truncating the `