📍 INTAKE, DESIGN, INDUSTRY BENCHMARKS & TDD SPEC: MANAGER PHYSICAL OUTLET CHECK-IN, 2–3/DAY VISIT QUOTA, 100% WEEKLY COVERAGE NUDGE & OUTLET-PAGE AUDIT SUMMARY (AUD-VISIT-1..10 · APP 3.5 EXTENSION · J21 / J23)

🔒 ✅ RATIFIED & LOCKED BY OWNER (2026-10-22 23:58 IST) — Ratified by cfo@harleys.com (Gates A1–A4 100% Locked)

Summary (12 Lines — IM-6 / PROCESS-OWNER-REVIEW.md Mandatory Top Digest)

• What: End-to-end Intake, Industry Research, Anti-Couch-Audit Check-In Protocol, Algorithmic Visit Assignment & Nudge Engine, and 360° Outlet/Audit Visibility spec for Manager Physical Outlet Visits & Quick Spot Reviews (AUD-VISIT-1..10) inside the Enterprise Audit Module (App 3.5) and Outlet Summary Page (/outlets/:code Section I).
• Direct Owner Intake Mandate (23:39 IST): "I still have not seen the manager check in on the outlet scenarios; this should be part of audit module where there should be a manager quick review of the outlets under them and do a check in and mark it complete! Physical visits to at least 2/3 outlets every day; make sure all the outlets are covered atleast once in a week and posting pics of audits. Push for a detailed intake of industry research on spot audit assignment to managers where they should be nudged to go to an outlet and the entire audit summary is tracked and visible for manager and above for all outlets under them and in outlet page."
• Global Industry Benchmarks Adopted: Synthesizes Starbucks District Manager (DM) Store Walk & QASA, McDonald's PACE / Field Consultant Store Visit, Domino's OER (Operations Evaluation Report), Chipotle Restaurateur Field Walk, and Zenput / Crunchtime Geo-Verified Multi-Unit Manager Walks.
• Daily 2–3 Outlets/Day Quota & 100% Weekly Coverage Mandate (AUD-VISIT-1..2): Every Cluster Manager / Area Lead / QA Lead must physically visit and check into at least 2 to 3 outlets per day, and 100% of outlets in their scope must be visited at least once every 7 rolling days (Mon–Sun). The 08:30 IST Algorithmic Visit Scheduler assigns each manager's daily 2–3 outlet route ranked by: (1) Mandatory Coverage Lock (days_since_last_visit >= 5) and (2) Composite Outlet Anomaly Score (recent Top-20 stock-outs, late opening checks, chiller >+5°C excursions, cash variances, open repairs), followed by 08:30 IST, 14:00 IST, and 18:30 IST nudges with automatic visibility to City Head (A2).
• Anti-Couch-Audit Dual-Factor Physical Check-In & 8-Minute 5-Point Quick Review (AUD-VISIT-3..4): Visiting managers cannot check in from home or car: they must (1) tap [📍 Manager Outlet Check-In] on the store's Shared Kiosk (rail='visibility' + 4-digit PIN) OR scan the rotating 60s Kiosk Screen QR within <=150m GPS geofence, (2) capture a live WebRTC Arrival Selfie at the counter with the Store Manager on duty (90s server_nonce), and (3) complete the 5-Point Quick Outlet Review with mandatory live camera audit photos (>=8 min on-site dwell guard).
• 360° Visibility on /audits & /outlets/:code Section I (AUD-VISIT-5..10): Renders a 7-Day Outlet Coverage Matrix & Heatmap + Manager 2/3 Today Quota Tracker + Live Photo Stream on /audits for Manager & Above, AND embeds a dedicated 📍 Section I: Manager Physical Visits & Spot-Audit Summary card on every Outlet Summary Page (/outlets/:code).
• Status: READY FOR OWNER SIGN-OFF · Peer-Reviewed by Claude Opus 4.7 Max & Codex Astra Extra High (AUD-VISIT-6..10 Hardened) · Styled in O-052 (Pastel Aqua #98DDDE + Victorian Gold #C5A059 + Raised Beams + Deep Teal #0D5C63).

1. Industry Benchmark Research: Multi-Unit Manager Store Walks & Spot-Audit Assignment

2. Core Functional Requirements & Lifecycle Specification (AUD-VISIT-1..10)

2.1 AUD-VISIT-1 · Daily 2–3 Outlets/Day Quota & 100% Weekly Coverage Mandate

1. Who Is Governed by the Visit Quota:
   • Every Cluster Manager (cluster_manager), Area Operations Lead (area_lead), and Field QA Lead (qa_lead) holding multi-outlet scope in user_assignments.
2. Hard Daily & Weekly Quotas:
   • Daily Visit Quota: Must physically check in, complete the 5-Point Quick Outlet Review, and post mandatory live audit photos at at least 2 outlets per day (target = 3/day for clusters with >= 8 outlets; min(2, scoped_outlet_count) if a manager supervises <2 outlets).
   • Weekly 100% Coverage Rule (Rolling 7 Days & Mon–Sun Calendar Week): 100% of active outlets (status = 'ACTIVE') under a Cluster Manager's scope must have at least 1 completed physical manager visit (status = 'COMPLETED') every 7 rolling days. Any outlet reaching days_since_last_visit >= 5 enters COVERAGE_DUE_URGENT (AMBER); any outlet reaching days_since_last_visit >= 7 enters COVERAGE_BREACH (RED) and escalates to City Head (A2).

2.2 AUD-VISIT-2 · Morning 08:30 IST Algorithmic Visit Assignment & 3-Stage Nudge Ladder

Every morning at 08:30 IST, the HOP Scheduler (visitAssignmentTick in src/scheduler.js) computes each Cluster Manager's Assigned Visit Route Today (2–3 Specific Outlets) using a deterministic two-tier priority formula:

$$\text{VisitPriorityScore}(o) = \underbrace{1000 \cdot \mathbb{I}(\text{days\_since\_last\_visit}(o) \ge 5)}_{\text{Tier 1: Hard 7-Day Coverage Lock}} + \underbrace{15 \cdot \text{ days\_since\_last\_visit}(o)}_{\text{Recency Weight}} + \underbrace{\text{AnomalyScore}_{14\text{d}}(o)}_{\text{Tier 2: Operational Risk (0..100)}}$$

where the Composite Outlet Anomaly Score (0..100) sums:

• +25 pts if the outlet had >= 2 Top-20 or Watch Ghost Stock-Outs in the last 48h (stockouts);
• +25 pts if the outlet had any chiller/freezer excursion >+5.0°C or open P1 maintenance breakdown (maintenance_cases);
• +20 pts if the outlet had <85% on-time opening/closing checklist adherence (acct_rollup_view) or unverified shift handover in the last 72h;
• +15 pts if the outlet had a cash drawer or petty-cash variance > ±₹100 (audit_count_submissions / petty_cash_vouchers);
• +15 pts if the outlet has an open overdue CAPA (audit_capa_actions) or licence expiring <=30d.

Deterministic 3-Stage Daily Nudge & Escalation Ladder (accountability_nudges):

2.3 AUD-VISIT-3 · Anti-Couch-Audit Dual-Factor Physical Check-In at the Outlet

To eliminate "couch audits", parking-lot check-ins, or backdated WhatsApp photos, a Manager cannot start an Outlet Visit or Quick Review without passing Dual-Factor Physical Presence Verification:

1. Factor 1 — In-Store Kiosk Handshake (Two Supported Paths):
   • Path A (Direct Tap on Store's Shared Kiosk /kiosk-board): The visiting Manager walks up to the outlet's physical wall/counter Kiosk, taps [📍 Manager Outlet Check-In], enters their 4-digit Manager PIN (kiosk_can_open_manager_view rail='visibility'), and either completes the walk on the Kiosk or taps "[Continue Walk on My Phone]" (which binds their mobile session to that Kiosk's hardware kiosk_id for 45 minutes).
   • Path B (Scan Rotating 60s Kiosk Screen QR from Manager's Phone + <=150m GPS): The Manager opens /audits/visit-checkin on their phone within <= 150 meters GPS geofence of outlets.lat_lng AND scans the 60-second rotating TOTP QR code (HMAC-SHA256(kiosk_secret, floor(epoch/60))) displayed on the corner of the store's Kiosk screen. (Works even if the store's broadband is temporarily degraded — AUD-VISIT-9!)
2. Factor 2 — Mandatory Live Arrival Selfie at Counter with Store Manager / Shift Lead on Duty (audit_capture_challenges):
   • Immediately upon Kiosk handshake, the camera opens with a 90-second server challenge nonce (server_nonce) requiring a live WebRTC Arrival Selfie showing the visiting Cluster Manager at the store counter alongside the on-duty Shift Lead / Store Manager (gallery file-picker <input type="file"> without capture="environment" is disabled at the DOM and API level; server verifies nonce_issued_at delta <=90s and phash` uniqueness).

2.4 AUD-VISIT-4 · 8-Minute 5-Point Manager Quick Outlet Review & Mandatory Live Audit Photos

Once checked in (status = 'CHECKED_IN_ON_SITE'), the Manager steps through a streamlined, high-signal 5-Point Quick Outlet Review designed to take 8 to 12 minutes on the shop floor (with >= 4 mandatory live camera audit photos):

2.5 AUD-VISIT-5 · 360° Visibility on /audits AND Embedded on Every Outlet Summary Page (/outlets/:code Section I)

Per the Owner's explicit mandate ("the entire audit summary is tracked and visible for manager and above for all outlets under them and in outlet page"), every physical visit and spot audit is surfaced in two synchronized executive & operational views:

1. View A — On /audits (Manager & Above Multi-Outlet Visit & Audit Command):
   • Top Strip — Manager Daily Visit Quota & Weekly Coverage Bar:
     • Shows each Cluster Manager's live quota: 📍 Today's Outlet Visits: 2 of 3 Completed (NAN ✓ 94%, JUB ✓ 89% · KOK Pending by 18:30 IST) and 📅 7-Day Cluster Coverage: 11 of 12 Outlets Visited (91.7% — 1 Due Today: KOK).
   • Middle Grid — 7-Day Outlet Coverage Matrix & Heatmap (All Outlets Under Manager):
     • Every scoped outlet row displays: Outlet Code & Name · Last Physical Visit (Timestamp + Days Ago Badge) · Visiting Manager Name · Dwell Duration (11 mins) · Quick Review Score (94% GREEN) · 4-Thumbnail Audit Photo Strip (Arrival Selfie, FOH Showcase, BOH Probe, Crew Grooming) · Open Visit CAPAs (1) · 1-Tap [🔔 Nudge Manager to Visit Now] / [📋 Assign Spot Audit].
2. View B — On Every Outlet Summary Page (/outlets/:code — New Section I: 📍 Manager Physical Visits & Spot-Audit Summary):
   • Mounted directly inside GET /api/v2/outlets/:code/summary (OutletRecordV2.tsx alongside Sections A–H, visible to Shift Manager & above on own device and in PIN-gated Kiosk Manager View):
   • Displays:
     • Status Word & Coverage Badge: Good · Covered This Week (Visited 2h ago by Jay · Cluster Mgr) | Check · 5 Days Since Last Visit (Assigned Today) | Act now · >7 Days Unvisited OR Score <75% RED.
     • Last 3 Physical Visits & Spot Audits Roll-Up: Visit timestamp, Manager Name, On-Site Duration (11m), Score (94% GREEN), Coaching Note summary, and clickable 4-photo strip (Arrival Selfie, FOH Medovik Case, BOH +3.8°C Probe, Crew Grooming).
     • Active Visit CAPAs & Follow-Ups: Direct chips linking to open MyTasks / maintenance_cases spawned during the manager's walk.
     • Primary On-Site Action Button: [📍 Start Manager Outlet Check-In & Quick Review] right at the top of /outlets/:code!

3. Peer-Review Hardening (Claude Opus 4.7 Max & Codex Astra Extra High — AUD-VISIT-6..10)

4. PostgreSQL Schema DDL & Triggers (AUD-VISIT-1..10 · Hardened by Claude Opus 4.7 Max)

-- =============================================================================
-- AUD-VISIT-1..10: MANAGER PHYSICAL OUTLET CHECK-IN, 2-3/DAY QUOTA & 7D COVERAGE
-- =============================================================================

-- Opus 4.7 Max P0-1: Single-Use Kiosk 60s QR Nonce Ledger (Blocks WhatsApp QR Relay)
CREATE TABLE IF NOT EXISTS kiosk_qr_nonces (
  jti                        UUID PRIMARY KEY,
  outlet_code                VARCHAR(32) NOT NULL REFERENCES outlets(code),
  kiosk_id                   UUID NOT NULL,
  issued_at                  TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
  expires_at                 TIMESTAMPTZ NOT NULL DEFAULT (clock_timestamp() + INTERVAL '60 seconds'),
  consumed_at                TIMESTAMPTZ,
  consumed_by_person_id      VARCHAR(32) REFERENCES users(id)
);
CREATE UNIQUE INDEX IF NOT EXISTS ux_kiosk_jti_consumed
  ON kiosk_qr_nonces (jti) WHERE consumed_at IS NOT NULL;


CREATE TABLE IF NOT EXISTS manager_visit_assignments (
  assignment_id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  business_date              DATE NOT NULL,
  manager_person_id          VARCHAR(32) NOT NULL REFERENCES users(id),
  outlet_code                VARCHAR(32) NOT NULL REFERENCES outlets(code),
  rank_order                 SMALLINT NOT NULL CHECK (rank_order BETWEEN 1 AND 5),
  days_since_last_visit      INT NOT NULL,
  is_mandatory_7d_lock       BOOLEAN NOT NULL DEFAULT FALSE,
  anomaly_score_14d          NUMERIC(5,2) NOT NULL DEFAULT 0.00,
  priority_score_total       NUMERIC(7,2) NOT NULL DEFAULT 0.00,
  anomaly_reasons_json       JSONB NOT NULL DEFAULT '[]'::jsonb,
  delegated_from_person_id   VARCHAR(32) REFERENCES users(id),
  morning_nudge_sent_at      TIMESTAMPTZ,
  midday_nudge_sent_at       TIMESTAMPTZ,
  evening_escalation_sent_at TIMESTAMPTZ,
  city_head_notified_at      TIMESTAMPTZ,
  fulfilled_by_visit_id      UUID,
  status                     VARCHAR(24) NOT NULL DEFAULT 'ASSIGNED'
                             CHECK (status IN ('ASSIGNED','CHECKED_IN','COMPLETED','MISSED_ESCALATED','REASSIGNED_LEAVE')),
  UNIQUE (business_date, manager_person_id, outlet_code)
);

CREATE TABLE IF NOT EXISTS manager_outlet_visits (
  visit_id                   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  business_date              DATE NOT NULL DEFAULT CURRENT_DATE,
  outlet_code                VARCHAR(32) NOT NULL REFERENCES outlets(code),
  manager_person_id          VARCHAR(32) NOT NULL REFERENCES users(id),
  manager_role_code          VARCHAR(32) NOT NULL,
  on_duty_store_mgr_id       VARCHAR(32) REFERENCES users(id),
  audit_run_id               UUID NOT NULL, -- Links 1:1 to T24 audit_runs (execution_mode='SPOT_VISIT')
  checkin_method             VARCHAR(32) NOT NULL
                             CHECK (checkin_method IN ('KIOSK_PIN_DIRECT','KIOSK_TOTP_QR_60S')),
  kiosk_id                   UUID NOT NULL,
  checkin_gps_lat            NUMERIC(9,6),
  checkin_gps_lng            NUMERIC(9,6),
  checkin_distance_meters    NUMERIC(7,2) CHECK (checkin_distance_meters IS NULL OR checkin_distance_meters <= 150.0),
  arrival_selfie_media_id    UUID NOT NULL,
  foh_showcase_media_id      UUID,
  boh_probe_lot_media_id     UUID,
  crew_grooming_media_id     UUID,
  stock_or_cash_media_id     UUID,
  check_in_ts                TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
  check_out_ts               TIMESTAMPTZ,
  dwell_minutes              NUMERIC(6,2) GENERATED ALWAYS AS (
                               CASE WHEN check_out_ts IS NOT NULL
                                    THEN ROUND((EXTRACT(EPOCH FROM (check_out_ts - check_in_ts)) / 60.0)::numeric, 2)
                                    ELSE NULL END
                             ) STORED,
  overall_score_pct          NUMERIC(5,2),
  knockout_failed_bool       BOOLEAN NOT NULL DEFAULT FALSE,
  coaching_notes_text        TEXT,
  spawned_capa_count         INT NOT NULL DEFAULT 0,
  status                     VARCHAR(24) NOT NULL DEFAULT 'CHECKED_IN_ON_SITE'
                             CHECK (status IN ('CHECKED_IN_ON_SITE','COMPLETED','ABORTED_INCOMPLETE')),
  city_head_notified_at      TIMESTAMPTZ,
  CONSTRAINT ck_visit_complete_requires_photos_and_dwell CHECK (
    status <> 'COMPLETED' OR (
      foh_showcase_media_id IS NOT NULL AND
      boh_probe_lot_media_id IS NOT NULL AND
      crew_grooming_media_id IS NOT NULL AND
      stock_or_cash_media_id IS NOT NULL AND
      check_out_ts >= check_in_ts + INTERVAL '8 minutes'
    )
  )
);

CREATE INDEX IF NOT EXISTS ix_manager_visits_outlet_completed
  ON manager_outlet_visits (outlet_code, check_out_ts DESC)
  WHERE status = 'COMPLETED';

CREATE INDEX IF NOT EXISTS ix_manager_visits_mgr_date
  ON manager_outlet_visits (manager_person_id, business_date, status);

5. Owner Sign-Off Block (AUD-VISIT-1..10)

• ☑ [READY FOR OWNER SIGN-OFF] Approve AUD-VISIT-1..2 (2–3 Outlets/Day Quota, 100% Weekly Coverage Lock & 08:30 / 14:00 / 18:30 IST Nudge Ladder): Every Cluster Manager / Area Lead / QA Lead visits 2–3 outlets/day so 100% of scoped outlets are visited every 7 rolling days, with 08:30 IST anomaly + coverage routing and 18:30 IST missed-quota escalation to City Head (A2).
• ☑ [READY FOR OWNER SIGN-OFF] Approve AUD-VISIT-3..4 (Dual-Factor Kiosk + Selfie Check-In & 8-Minute 5-Point Quick Outlet Review with 4 Mandatory Live Audit Photos): Requires Kiosk PIN or 60s Kiosk QR (<=150m GPS) + Arrival Selfie with Store Manager on duty + 4 live station photos (FOH Showcase, BOH Probe/Lot, Crew Grooming, Blind Stock/Cash) + >=8 min on-site dwell guard (AUD-VISIT-6).
• ☑ [READY FOR OWNER SIGN-OFF] Approve AUD-VISIT-5..10 (360° Visibility on /audits & /outlets/:code Section I + Anti-Tip-Off Surprise Protection): Surfaces the 7-Day Outlet Coverage Matrix, Manager Daily Quota (2/3 Today), and Photo Stream on /audits, and embeds 📍 Section I: Manager Physical Visits & Spot-Audit Summary on every /outlets/:code page while hiding incoming same-day assignments from store staff until check-in.