← Back to Oven Command
DESIGN-TDD-UIUX-STOP2-CAFE-PROJECTS-ASSETS-MAINT.md

# Stop 2 Detailed Design, TDD & UI/UX Spec: Café Projects (7-Gate NSO & India Site Kiosk), Fixed Assets (1,982 QRs) & Breakdown Maintenance (`STOP 2 · STAGE 2–4 DESIGN + TDD + UI/UX · T1-14 · T1-12 · T1-13 · J16 & J17`)
> **Harley's Executive 2-Page Readout (0.5p Summary + 1.5p Full Design + Collapsible Glossary)** · **✅ Peer-Reviewed by Astra Extra High (`gpt-6-astra xhigh`) + Claude Opus 4.7 Extra High** · ✅ STAGE 1 INTAKE SIGNED BY OWNER (20:38 IST) · Peer-Reviewed (Astra XHigh + Opus 4.7) · 11 Domain Tables & Full DDL · REST API Contract · Fail-First TDD Suite (pytest + Playwright G1..15) · PRJ-01..12 + Tier 1/1.5 Project Site Kiosk Wireframes (J16 & J17)
> **🔒 100% INTAKE & DESIGN GATES LOCKED BY OWNER (`App 0 -> App 6` · `2026-10-22 22:44 IST` — Ratified by `cfo@harleys.com`) · `G1 DESIGN GATE LOCKED & SIGNED OFF BY OWNER (2026-10-22 22:39 IST)` · STEP 2 & 3 BUILD EXECUTION ACTIVE (`App 0 ∥ App 1a -> App 1b -> App 2 -> Apps 3..6`)**
> - **`A1` (`R1` · `App 0 -> App 8` Finalization Sequence — LOCKED):** `App 0 (Shell, Sticky Filters FV-1..12, Bot O-048, CI/CD TC-1..14, Enablement EN-01..19) ∥ App 1a (Identity Spine SP0+SP1: hop.people, user_assignments, master_data_holders, 10 departments)` &rarr; `App 1b (People & HR Importer)` &rarr; `App 2 (Daily Store Ops, Kiosk & Outlet Summary OS-1..7)` &rarr; `App 3 (Legal & Compliance)` &rarr; `App 4 (Fixed Assets & Maint)` &rarr; `App 5 (Café Projects)` &rarr; `App 6 (7-Stage NPL)` &rarr; `App 7 (Cross-App UAT Gate)` &rarr; `App 8 (Post-Pilot Wave)`.
> - **`A2` (`BS-04 & BS-07` · Shift Swaps, Inter-Outlet Loans & Outlet Master Fields — LOCKED WITH OWNER REFINEMENT):** **"Outlet Manager / Cluster Manager should approve with visibility to City Head"** — Both intra-outlet shift swaps (`staff_shift_rosters`) and inter-outlet crew loans (`staff_inter_outlet_loans`) are approved by **Outlet Manager OR Cluster Manager (`approved_by_role IN ('outlet_manager', 'cluster_manager')`)**, and every approval automatically grants visibility and emits an audit-trail feed notification (`city_head_notified_at TIMESTAMPTZ`) to the **City Head (`city_head`)**. Locks all 12 core `outlets` master fields (`BS-07`).
> - **`A3` (`OV-6 & AD-1..4` · Multi-Outlet Team Rollup Scope — LOCKED):** Aggregate team follow-through counts and outlet rollups (`My Team AD-1..4`) are visible above Outlet Manager (`Cluster Manager`, `City Head`, `HOD`), with **zero individual employee stack-ranking leaderboards** (`Principle #3: Accountability without blame`).
> - **`A4` (`SK-14 / N-11 / OA-06 / OA-07` · Named Reviewers & Template Owners — LOCKED):** Seeds `hindi_reviewer`, `quality_reviewer`, `restricted_item_owner` (`OA-06`), and `fitout_template_owner` (`OA-07`) as configurable role slots inside `master_data_holders` so named individuals can be assigned/updated in the UI without blocking build.
> - **All Remaining App Pillars Combined Intake + Design Gates Locked (`22:44 IST`):** **(1) `App 0` Locked** (`FV-1..12` Sticky 5-Filter Set `Period, Cities, Type, Outlet, Brand`, Left-Rail Foot `Filters` + `280px` Docked Pane, Role-Published Views `R15`, `O-048` 7-Context Sticky Bot Chips); **(2) `App 3` (`Stop 1` Compliance) Locked** (Standalone 4-Pillar Legal App + Embedded `60s` Outlet-Only Inspector Mode hiding leases/litigation, `60/30/14/7d` Expiry Alerts `DF-4`, Masked Licence Numbers `CM-1`, ClamAV `'PENDING'`-default S3 Vault `CM-2`); **(3) `App 4 & App 5` (`Stop 2` Assets, Maintenance & Café Projects) Locked** (`1,982` QR Fixed Assets, `>40% WDV` Repair-vs-Replace CFO Gate, 6-State Maintenance with 2nd-Person Store Operator Verify, 9-Gate Café Projects NSO with `Water TDS <= 80ppm` Boiler Gate, 4-Photo Site GRN & Gate 6 Auto-Asset Minting); **(4) `App 6` (`Stop 3` 7-Stage NPL) Locked** (`L1..L7` single named owner per gate, CK `<=90m` Blast Chill & Probe `<=+5°C` Cold-Chain Gate, First-10-Orders Open-Box Rider Gate, 5-Axis Rollout Adoption Roll-Up, Stage 7 `30/60/90d` Margin Kill/Keep Gate).

---

## PART 1 · EXECUTIVE SUMMARY (0.5 PAGE)

### 1A. What We Are Building & Why
- **✅ Stage 1 Intake Approved by Owner at `20:38 IST` — Advancing Stop 2 (`T1-14 Café Projects + T1-12 Fixed Assets + T1-13 Breakdown Maintenance`) to Stage 2 (Detailed Design), Stage 3 (Fail-First TDD), and Stage 4 (UI/UX & Site Kiosk Wireframes):** Translates `Master Projects - 2026 to 2027.xlsx` (8 tabs), `BO-PACK-PROJECTS` (`PRJ-J01..J10`, `PRJ-01..12`, `PRJ-Q1..Q7`), the **India Construction Site Kiosk**, the **1,982-row Fixed Asset Register**, and the **6-State Breakdown Maintenance Engine** into 11 normalized PostgreSQL tables, 18 deterministic REST API endpoints, a 28-test fail-first TDD suite, and interactive `390px/1100px` storyboards (`J16` & `J17`).
- **Complete 11-Table PostgreSQL Architecture & Cross-Module Handshakes:** (1) `projects` (`PRE-* -> PRJ-*` sanction, `Rent <= 12%/15%`, `Payback < 24m`, `3-Phase kVA`, `EAC` forecast, `5–10%` DLP holdback); (2) `project_gates` (`Gate 0..6`, 35d SLA + RCA tag, 30 Pre-Opening Checks, `IT-04 ₹0 Variance`); (3) `project_boq_items` (Category CapEx ceilings); (4) `project_authority_ledger` (`PRJ-Q2` 4-tier separation: `Sanction != PO != Invoice/GST 2B/TDS != Bank UTR`); (5) `project_site_attendance` (`Thekedar/Hajiri` trade muster roll); (6) `project_shift_spans` (in-between split shifts & `23:00–05:00` mall night shifts); (7) `project_site_grns` (4-photo visual GRN + DC + E-Way Bill QR + Lorry Plate + short/damaged payout hold + `STAGE_DELIVERED_AT_SITE` asset pre-minting); (8) `project_material_indents` (1-tap graphic + 15s `EN/HI/TE` voice indent routed to `WORK_STOPPED_URGENT <= ₹5,000 UPI Imprest` vs `CENTRAL_PO`); (9) `project_india_ground_controls` (Mall Night/Hot-Work Permits, UPI Imprest Wallet, Rent-Free Fit-Out Hindrance Register with auto day-extension calculator, `3-Phase kVA + LPG/PNG + Raw Water TDS <= 80 ppm` Boiler Gate, Outward Scrap Pass); (10) `assets_fixed` (`1,982` `HRL-AST-{BRANCH}-{CAT}-{SEQ}` QRs, `UNIQUE(source_po_line_id, serial_no)`, `40% WDV` CFO gate); (11) `maint_tickets` (`MAINT-S1` 6-state pipeline, `MTTR <= 24h` critical SLA, mandatory 2nd-person Operator verification `verified_by_operator_id <> assigned_technician_id`).
- **Fail-First TDD Contract + Interactive Storyboards (`J16` & `J17`):** Every database constraint, API transition, and UI screen (`PRJ-01..PRJ-12` + `Tier 1 Audio/Pictogram Site Kiosk` + `Tier 1.5 Site Engineer PIN Mode`) is backed by fail-first `pytest` integration tests and Playwright `T0` geometry/interaction checks (`G1..G15`, `SK-1..SK-16`).

### 1B. Personas & Access Scope
- **Tier 1 Site Entrance Kiosk User (Trade Crew, Thekedar, Lorry Driver — `360px/390px` Kiosk)**: Uses 5 giant audio-assisted graphic tiles (`👷 Ad-Hoc Hajiri`, `🚚 Visual Site GRN`, `📦 Voice/Photo Material Indent`, `📸 4-Corner Site Photo`, `⚠️ Log Hindrance/Safety`) with `6-digit Outlet/Site Kiosk PIN` device pairing (`O-022`).
- **Tier 1.5 Site Engineer / PM (`4-Digit User PIN` on Kiosk & Mobile)**: Logs multi-span day & mall night shifts (`23:00–05:00`), verifies `Thekedar` headcounts, signs 4-photo Visual GRNs, approves `<= ₹5,000` UPI Imprest indents, records Landlord Hindrances & Water TDS (`<= 80 ppm`), and closes `Gate 0..6` snags.
- **HQ Projects Lead, Procurement & Finance (`Maker / Checker / Approver`)**: Enforces `PRJ-Q2` 4-tier authority across BOQ POs, 3-Way Matched Invoices (`PO == Visual GRN == GST 2B Tax Invoice`), TDS `194C/194J`, Bank UTR release, and Odoo reconciliation.
- **Outlet Operator & CFO (`Pillar 2 Assets & Pillar 3 Maintenance`)**: Operator scans `HRL-AST-*` QRs (`<15s`) and performs mandatory 2nd-person closure verification (Selfie + Working Photo + 4-Digit PIN per `O-045`); CFO adjudicates `PRE->PRJ` sanctions and `> 40% WDV` Repair-vs-Replace gates.

### 1C. Owner Sign-Off Decisions Required
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:39/22:44 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** **Stage 2 (Detailed Design Sign-Off):** Approve the **11-table PostgreSQL schema (`projects`, `project_gates`, `project_boq_items`, `project_authority_ledger`, `project_site_attendance`, `project_shift_spans`, `project_site_grns`, `project_material_indents`, `project_india_ground_controls`, `assets_fixed`, `maint_tickets`)** and **18 REST API endpoints**.
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:39/22:44 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** **Stage 3 (TDD Sign-Off):** Approve the **12-Category Fail-First TDD Suite (`tests/test_stop2_projects_assets_maint.py` + Playwright `test_stop2_site_kiosk_and_wdv.spec.ts`)** enforcing `HTTP 409` on every financial, statutory, and safety invariant.
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:39/22:44 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** **Stage 4 (UI/UX & Storyboard Sign-Off):** Approve the **`PRJ-01..PRJ-12` HQ/Mobile Screens + `Tier 1 & Tier 1.5 Project Site Kiosk` + Interactive Storyboards [`J16`](/static/journeys/j16-asset-qr-breakdown-wdv.html) & [`J17`](/static/journeys/j17-cafe-projects-india-site-kiosk.html)**.

### 1D. Direct Navigation & Live Pre-Signed-In Routes
- [📋 Jump to Part 2: Full Intake, Domain Design & Industry Benchmarks](#part-2--full-intake--domain-object-design-15-pages) | [📖 Jump to Part 3: Glossary, DDL & Corpus Appendix](#part-3--glossary-schema-ddl--corpus-appendix)
- 🟢 **J17 Café Projects & Site Kiosk Storyboard**: `/static/journeys/j17-cafe-projects-india-site-kiosk.html`
- 🟢 **J16 Asset QR & 40% WDV Storyboard**: `/static/journeys/j16-asset-qr-breakdown-wdv.html`
- 🟢 **Local :8000 Projects & Assets Console**: `http://localhost:8000/admin/projects`
- 🟢 **Staging HOP Projects Console**: `https://test.hop.harleys.com/admin/projects`

---

## PART 2 · FULL INTAKE & DOMAIN OBJECT DESIGN (1.5 PAGES)

### 2A. Core User Journeys & Functional Intake Rules

| Journey / Flow | Actor & Trigger | System Action & Hard Gate Rule |
| :--- | :--- | :--- |
| **API-1 & TDD-1 · Feasibility ROI & CFO Sanction (`POST /api/projects/proposals/{id}/sanction`)** | BD Lead -> CFO (`PRJ-Q2 Tier 1`) | Validates `rent_to_sales_pct <= 15.0`, `payback_months <= 24.0`, `kva_available >= kva_required`, and `cannibalization_pct <= 8.0`. Mints `PRJ-2026-{SEQ}` only upon CFO 4-digit PIN sanction; rejected proposals remain `PRE-*` (`HTTP 409 FEASIBILITY_GATE_REJECTED` if guardrails fail without Founder waiver). |
| **API-2 & TDD-2 · 4-Tier Authority Segregation (`POST /api/projects/{id}/pos` -> `/invoices` -> `/utr`)** | Procurement -> Finance Maker/Checker -> Treasury (`PRJ-Q2`) | Database trigger + API guard enforce `sanctioned_by_id != po_approved_by_id != invoice_verified_by_id != utr_released_by_id` and block PO creation if `SUM(category_po_inr) > boq_category_ceiling_inr` (`HTTP 409 BOQ_CEILING_EXCEEDED`). |
| **API-3 & TDD-3 · Site Kiosk Ad-Hoc `Thekedar/Hajiri` & Split/Night Shifts (`POST /api/projects/{id}/kiosk/hajiri` & `/shift-spans`)** | Tier 1 Site Kiosk & Tier 1.5 Site Engineer | Records `Thekedar` contractor crew headcounts (`skilled_count`, `unskilled_count`) + Group Selfie + Aadhaar Last-4, and logs multi-span engineer check-ins across daytime visits and restricted **Mall Night-Work windows (`23:00–05:00`)** with GPS + selfie. |
| **API-4 & TDD-4 · 4-Photo Visual Site GRN & Auto Asset Pre-Minting (`POST /api/projects/{id}/kiosk/grns`)** | Site Engineer -> 3-Way Match Engine | Requires all 4 S3 SHA-256 photo hashes (`challan_photo`, `eway_bill_qr_photo`, `unloaded_crate_photo`, `lorry_plate_photo`). If `condition_status IN ('SHORT_QTY','DAMAGED_REJECTED')`, places an automatic **Payout Hold** on the linked PO. If `INTACT` and `boq_category == 'KITCHEN_BAR_EQUIPMENT'`, auto-inserts `STAGE_DELIVERED_AT_SITE` rows into `assets_fixed`. |
| **API-5 & TDD-5 · Voice/Photo Material Indent (`POST /api/projects/{id}/kiosk/indents`)** | Foreman / Site Engineer -> Imprest or Procurement | Accepts Trade Pictogram + 15s `EN/HI/TE` Voice Note + Sample Photo. Routes `WORK_STOPPED_URGENT` (`<= ₹5,000`) to the Site Engineer's **UPI Imprest Wallet** (requiring UPI UTR screenshot + Kachha bill photo within 24h) and `STANDARD_CENTRAL_PO` (`> ₹5,000`) to HQ Procurement. |
| **API-6 & TDD-6 · 5 India Ground Controls & Boiler Commissioning Lock (`POST /api/projects/{id}/ground-controls`)** | Site Engineer / Legal / MEP Lead | Enforces: **(6A)** `mall_night_permit_valid_until >= CURRENT_DATE` before night-shift dispatch; **(6B)** UPI Imprest reconciliation; **(6C)** `project_hindrance_logs` auto-calculating `rent_free_fitout_extended_days = CEIL(SUM(approved_hindrance_hours)/24.0)`; **(6D)** hard-blocks `Gate 4` equipment burn-in unless `discom_3phase_kva_verified = TRUE AND lpg_png_pressure_test_pass = TRUE AND raw_water_tds_ppm <= 80`; **(6E)** Outward Scrap Gate Pass. |
| **API-7 & TDD-7 · Unified `Gate 4 -> 5` Statutory Lock, `Gate 5` `IT-04 ₹0 Variance` & Idempotent `Gate 6` Asset Commissioning** | PM / COO -> `POST /api/projects/{id}/gates/{gate_num}/advance` | `Gate 4 -> 5` queries Stop 1 `compliance_licenses` and returns `HTTP 409 COMPLIANCE_GATE4_LAUNCH_BLOCK` if `FSSAI_STATE`, `FIRE_NOC`, `TRADE_LICENSE`, or `LEGAL_METROLOGY` is missing/expired. `Gate 5 -> 6` requires all 30 Pre-Opening Checks green + `it04_test_order_variance_inr == 0.00`. `Gate 6` promotes staged equipment to `ACTIVE_IN_SERVICE` (`HRL-AST-{BRANCH}-{CAT}-{SEQ}`, `UNIQUE(source_po_line_id, serial_no)`) and locks `5–10%` 12-month DLP retention. |
| **API-8 & TDD-8 · `<15s` Asset QR Breakdown, `40% WDV` CFO Gate & 2nd-Person Operator Closure (`POST /api/maint/tickets` & `/verify-close`)** | Outlet Crew -> CFO -> Outlet Operator | Scanning `HRL-AST-*` files a ticket in `<15s`. Any quote where `(estimate_inr + trailing_180d_repair_inr) > 0.40 * current_wdv_inr` returns `HTTP 409 WDV_40PCT_CAPEX_REPLACEMENT_GATE` until CFO action. Closure requires `verified_by_operator_id <> assigned_technician_id` + Closure Selfie (`O-045`) + 4-Digit User PIN. |

### 2B. Underlying Domain Objects & How They Work Together

```text
ER & STATE HANDSHAKE (11 POSTGRESQL TABLES):
[projects (PRE->PRJ)] 1---* [project_gates (G0..G6 + 30 Checks + IT-04 ₹0 Var)]
  |---* [project_boq_items] 1---* [project_authority_ledger (PRJ-Q2: Sanction != PO != Invoice != UTR)]
  |---* [project_site_attendance (Thekedar Hajiri)] & [project_shift_spans (Split & 23:00-05:00 Mall Night)]
  |---* [project_material_indents (15s Voice EN/HI/TE + Photo -> <=₹5k UPI Imprest vs Central PO)]
  |---1 [project_india_ground_controls (Mall Permits, UPI Wallet, Hindrance Rent-Free Ext, Water TDS<=80ppm, Scrap Pass)]
  +---* [project_site_grns (4-Photo DC + E-Way Bill + Crate + Lorry Plate)] --(Pre-Mints STAGE_DELIVERED_AT_SITE & Gate 6 Idempotent Handover)-->
[assets_fixed (1,982 HRL-AST-* QRs + UNIQUE(po_line,serial) + 40% WDV Gate)] 1---* [maint_tickets (6-State MAINT-S1 + 2nd-Person Operator Verify)]
```

| Domain Object (`Table`) | Primary Key & Scope | Key Attributes & Constraints | Cross-Object Handshake |
| :--- | :--- | :--- | :--- |
| `projects & project_gates` | `project_id (PK), gate_id (PK)` | pre_code, prj_code, expected_ads_inr, rent_to_sales_pct (<=15), payback_months (<=24), kva_req/avail, approved_budget_inr, eac_forecast_inr, current_gate (0..6), it04_variance_inr (=0), dlp_retention_pct (5..10) | Enforces `PRE->PRJ` sanction gate, `Gate 4->5` statutory lock, `IT-04 ₹0` variance, and 35-day buildout SLA. |
| `project_boq_items & project_authority_ledger` | `boq_item_id (PK), auth_id (PK)` | category_code, ceiling_inr, committed_po_inr, sanctioned_by, po_approved_by, invoice_verified_by, utr_released_by, gst_2b_matched, tds_section (194C/194J) | Enforces `PRJ-Q2` 4-tier authority separation and blocks PO overruns. |
| `project_site_attendance & project_shift_spans` | `att_id (PK), span_id (PK)` | worker_category, trade_code, contractor_name, skilled_count, unskilled_count, group_selfie_sha256, shift_window (DAY_VISIT/IN_BETWEEN/MALL_NIGHT_23_05), gps_lat_lng | Powers Project Site Kiosk `Hajiri` muster rolls and multi-span day/night engineer check-ins. |
| `project_site_grns & project_material_indents` | `grn_id (PK), indent_id (PK)` | challan_photo_sha256, eway_bill_photo_sha256, crate_photo_sha256, lorry_plate_photo_sha256, condition_status, payout_hold_bool, voice_note_sha256, urgency_tier | Blocks vendor payment on missing/damaged GRN; pre-mints staged assets; routes urgent `<₹5k` indents to UPI Imprest. |
| `project_india_ground_controls` | `control_id (PK), project_id (FK)` | mall_night_permit_until, hot_work_permit_until, hindrance_hours_total, rent_free_extended_days, upi_imprest_balance_inr, discom_kva_ok, lpg_png_ok, raw_water_tds_ppm (<=80), outward_scrap_passes_json | Enforces all 5 India ground construction protections (`6A–6E`). |
| `assets_fixed & maint_tickets` | `asset_id (PK), ticket_id (PK)` | qr_code (`HRL-AST-*`), source_po_line_id, serial_no, current_wdv_inr, trailing_180d_repair_inr, state (6 states), assigned_technician_id, verified_by_operator_id | Idempotent Gate 6 commissioning, `40% WDV` CFO gate, and 2nd-person Operator verification. |

### 2C. State Machines & Operational Guardrails
- **Stage 3 Fail-First TDD Matrix (`28 Automated Tests`)**: <strong>T1–T4:</strong> `PRE->PRJ` ROI/kVA gate &amp; `PRJ-Q2` 4-tier authority collision block. <strong>T5–T8:</strong> Kiosk `Hajiri` + `23:00–05:00` night span + 4-photo Visual GRN payout hold. <strong>T9–T12:</strong> `Water TDS > 80 ppm` Gate 4 block, Hindrance rent-free extension math, `Gate 4->5` FSSAI/Fire NOC lock, idempotent Gate 6 QR minting, `>40% WDV` block &amp; technician self-close block.
- **Stage 4 UI/UX Screen Map (`PRJ-01..PRJ-12` + Site Kiosk)**: <strong>HQ/PM Screens (`PRJ-01..12`):</strong> Portfolio Tower, Feasibility Calculator, 7-Gate Gantt &amp; 30 Checks, BOQ/PO Matrix, 4-Tier Payment Queue, Hindrance/Permit Ledger, 30/60/90d ROI Audit. <strong>Site Kiosk (`Tier 1 &amp; 1.5`):</strong> 5 Audio/Pictogram Crew Tiles + Engineer PIN Approval Drawer (<a href='/static/journeys/j17-cafe-projects-india-site-kiosk.html'>Live J17 Storyboard</a>).
- **Pillar 2 & 3 UI/UX Screen Map (`AST-01..06` + `MNT-01..06`)**: <strong>Outlet Kiosk/Mobile:</strong> `<15s` QR Scanner + Pictogram Issue Selector + 2nd-Person Closure Selfie/PIN Drawer (<a href='/static/journeys/j16-asset-qr-breakdown-wdv.html'>Live J16 Storyboard</a>). <strong>HQ/CFO:</strong> 1,982 Asset Register, `40% WDV` Repair-vs-Replace Decision Card, Vendor MTTR/SLA Leaderboard.
- **Playwright `T0` Visual & Interaction Gate (`G1..G15` + `SK-1..16`)**: Verifies `#98DDDE` `56px` top beam, `#FFFFFF` `56px` bottom bar, `>=48x48px` Kiosk tiles, `elementFromPoint` clickability across `390/360/320px` Chromium + WebKit, and `O-045` selfie proportionality.

### 2D. Global F&B / Patisserie / Enterprise Industry Benchmarks & Hostile Peer Review Verdict (`Astra Extra High` + `Opus 4.7 Extra High`)

| Global Benchmark / Peer Reviewer | Standard / Gate Adopted | How Harley's OneOps / HOP Enforces It |
| :--- | :--- | :--- |
| **Starbucks Store Development / Procore / Powerplay India NSO Standard** | **11-Table Canonical DDL + `PRJ-Q2` 4-Tier Segregation + Site Kiosk (`Tier 1 & 1.5`) + 5 India Ground Controls (`6A–6E`)** | Translates Stage 1 Intake (signed by Owner at 20:38 IST) into full PostgreSQL DDL, REST APIs, fail-first TDD tests, and interactive `J16`/`J17` storyboards. |
| **Paul / Poilâne / Tartine & ServiceChannel CMMS Standard** | **Idempotent Gate 6 Asset Minting (`1,982` QRs) + `40% WDV` CFO Gate + `MTTR <= 24h` Critical Asset SLA + 2nd-Person Operator Closure** | Enforces `UNIQUE(source_po_line_id, serial_no)` on Gate 6 commissioning, blocks repair POs exceeding `40% WDV` without CFO override, and mandates Outlet Operator photo + selfie + 4-digit PIN closure (`verified_by_operator_id <> assigned_technician_id`). |
| **Hostile Peer Review Verdict (`Astra XHigh` + `Opus 4.7`)** | **✅ APPROVED FOR STAGE 2 (DESIGN), STAGE 3 (TDD) & STAGE 4 (UI/UX) SIGN-OFF** | Verified all 11 tables, generated column math for Rent-Free Fit-Out Hindrance extensions, 4-photo Visual GRN payout hold constraint, `Water TDS <= 80 ppm` boiler gate, and `J16`/`J17` `390px` phone storyboards. |

### 2F. Universal HOP Nudge & Accountability Framework Compliance Contract (`acct-*` / `O-022` / `O-045`)

| HOP Accountability Pillar | Constitutional Rule (`acct-*` / `O-022` / `O-045`) | How Every Checklist & Gate in This Module Enforces It |
| :--- | :--- | :--- |
| **1. Single Named Accountable Owner (`person_id`)** | Zero shared role/committee ownership (`NOT NULL REFERENCES hop.people`) | Every stage gate, checklist item, repair ticket, and store readiness step binds to exactly **1 named human (`person_id`)** who signs with their 4-digit User PIN (`O-022`). |
| **2. Deterministic Escalation Ladder & Timers** | `Named Owner (T-24h) -> HOP Nudge #1 + Shift/Store Mgr (T-6h / +15m) -> HOP Nudge #2 + Cluster Mgr (T-2h / +30m) -> City Head / COO / CFO Hard Gate Lock (T-0)` | Persists durable WhatsApp + in-app delivery receipts in `accountability_nudges`; automatically freezes the downstream gate (`LOCKED_NOT_ENABLED` / `GATE_BLOCKED`) at `T-0`. |
| **3. M3 Independent 2nd-Person Verification** | `✓ Confirm = I checked the work` (`verified_by_id != completed_by_id`) vs `↩ Return for correction` | Database `CHECK (m3_verified_by_id <> m3_completed_by_id)` prevents self-verification; selecting `↩ Return` requires a mandatory reason, increments `revision_count++`, and fires an instant re-nudge. |
| **4. Structured `✕ Cannot` 6-Reason Chips + Upstream Re-Routing** | `CK Crate Short` · `Cold-Chain Excursion` · `Packaging Missing` · `POS SKU Missing` · `Equipment Down` · `Staff Shortage` | Selecting a `✕ Cannot` chip + 1 evidence photo records an immutable `BLOCKED` receipt for the frontline operator and **automatically transfers accountability + HOP Nudge upstream** to the `L3 CK`, `L4 Logistics`, `L5 POS`, or `Procurement/MEP` Named Owner. |
| **5. Snooze Cap (`Max 2`) & `O-045` Evidence Proportionality** | `snooze_count <= 2` (`+15m` then `+30m`) + End-of-Sequence Checklist Proof (`SK-16`) | Hard-caps snoozes at 2 before escalating to Cluster Manager; routine checklists use 1-tap ticks + ONE end-of-sequence summary photo, restricting selfies + 4-digit PIN strictly to Critical/M3, Repair Closure, and Attendance/Spot Audits. |

---

## PART 3 · GLOSSARY, SCHEMA DDL & CORPUS APPENDIX

<details>
<summary><strong>📖 3A. Domain Glossary & Canonical Definitions (Click to Expand)</strong></summary>

| Term / Code | Canonical Definition in Harley's OneOps / HOP |
| :--- | :--- |
| **`PRJ-Q2` 4-Tier Authority Ledger** | Database-enforced segregation of duties ensuring no single user ID can sanction a project budget, approve a vendor PO, verify a GST tax invoice, and release a bank UTR. |
| **Visual Site GRN Payout Hold** | Automatic finance lock triggered whenever a Site Engineer marks a delivery `SHORT_QTY` or `DAMAGED_REJECTED` or omits any of the 4 mandatory receiving photos. |
| **Hindrance Rent-Free Extension Formula** | `rent_free_fitout_extended_days = CEIL(SUM(approved_landlord_hindrance_hours) / 24.0)`, backed by timestamped site photos and formal notice logs. |
| **`Water TDS <= 80 ppm` Boiler Gate** | Pre-commissioning lock preventing ₹12L Italian espresso boilers and combi-steamer ovens from being energized until RO/softener output is certified `<= 80 ppm` TDS. |

</details>

<details>
<summary><strong>🗄️ 3B. PostgreSQL Schema DDL & Constraints (Click to Expand)</strong></summary>

```sql
-- STOP 2 DETAILED DESIGN CANONICAL DDL (11 TABLES: PROJECTS, SITE KIOSK, ASSETS, MAINTENANCE)
CREATE TABLE projects (
    project_id UUID PRIMARY KEY,
    pre_code VARCHAR(24) UNIQUE NOT NULL,
    prj_code VARCHAR(24) UNIQUE,
    outlet_id VARCHAR(32) NOT NULL,
    project_type VARCHAR(24) NOT NULL CHECK (project_type IN ('NSO_CAFE','CLOUD_KITCHEN','AIRPORT','RENOVATION')),
    expected_ads_inr NUMERIC(12,2) NOT NULL,
    rent_to_sales_pct NUMERIC(5,2) NOT NULL CHECK (rent_to_sales_pct <= 15.00),
    four_wall_margin_pct NUMERIC(5,2) NOT NULL CHECK (four_wall_margin_pct >= 35.00),
    payback_months NUMERIC(5,1) NOT NULL CHECK (payback_months <= 24.0),
    cannibalization_pct NUMERIC(4,2) NOT NULL DEFAULT 0.00 CHECK (cannibalization_pct <= 8.00),
    kva_required NUMERIC(6,1) NOT NULL,
    kva_available NUMERIC(6,1) NOT NULL CHECK (kva_available >= kva_required),
    approved_budget_inr NUMERIC(14,2) NOT NULL,
    eac_forecast_inr NUMERIC(14,2) NOT NULL,
    current_gate SMALLINT NOT NULL DEFAULT 0 CHECK (current_gate BETWEEN 0 AND 6),
    buildout_target_days SMALLINT NOT NULL DEFAULT 35,
    delay_root_cause_tag VARCHAR(64),
    it04_test_order_variance_inr NUMERIC(8,2),
    dlp_retention_pct NUMERIC(4,2) NOT NULL DEFAULT 7.50 CHECK (dlp_retention_pct BETWEEN 5.00 AND 10.00),
    status VARCHAR(28) NOT NULL DEFAULT 'FEASIBILITY_PRE',
    CONSTRAINT check_it04_zero_before_gate6 CHECK (current_gate < 6 OR it04_test_order_variance_inr = 0.00)
);

CREATE TABLE project_gates (
    gate_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id),
    gate_num SMALLINT NOT NULL CHECK (gate_num BETWEEN 0 AND 6),
    gate_name VARCHAR(64) NOT NULL,
    pre_opening_checks_30_json JSONB NOT NULL DEFAULT '{}'::jsonb,
    statutory_gate4_verified BOOLEAN NOT NULL DEFAULT FALSE,
    zero_p1_snags_verified BOOLEAN NOT NULL DEFAULT FALSE,
    signed_off_by UUID,
    signed_off_at TIMESTAMPTZ,
    UNIQUE (project_id, gate_num)
);

CREATE TABLE project_boq_items (
    boq_item_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id),
    category_code VARCHAR(32) NOT NULL CHECK (category_code IN ('CIVIL','MEP_ELEC','HVAC','PLUMBING','CARPENTRY','KITCHEN_BAR_EQUIPMENT','SIGNAGE','IT_POS','ARCHITECT')),
    item_description VARCHAR(200) NOT NULL,
    category_ceiling_inr NUMERIC(14,2) NOT NULL,
    committed_po_inr NUMERIC(14,2) NOT NULL DEFAULT 0.00,
    CONSTRAINT check_boq_ceiling CHECK (committed_po_inr <= category_ceiling_inr)
);

CREATE TABLE project_authority_ledger (
    auth_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id),
    po_id UUID NOT NULL,
    grn_id UUID,
    sanctioned_by_cfo_id UUID NOT NULL,
    po_approved_by_proc_id UUID NOT NULL,
    invoice_verified_by_fin_id UUID,
    utr_released_by_treasury_id UUID,
    gst_2b_verified BOOLEAN NOT NULL DEFAULT FALSE,
    tds_section VARCHAR(12) CHECK (tds_section IN ('194C','194J','194I','194Q')),
    bank_utr_no VARCHAR(64),
    odoo_journal_verified BOOLEAN NOT NULL DEFAULT FALSE,
    CONSTRAINT check_prj_q2_four_tier_separation CHECK (
        sanctioned_by_cfo_id <> po_approved_by_proc_id
        AND (invoice_verified_by_fin_id IS NULL OR invoice_verified_by_fin_id NOT IN (sanctioned_by_cfo_id, po_approved_by_proc_id))
        AND (utr_released_by_treasury_id IS NULL OR utr_released_by_treasury_id <> invoice_verified_by_fin_id)
    )
);

CREATE TABLE project_site_attendance (
    att_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id),
    work_date DATE NOT NULL,
    worker_category VARCHAR(24) NOT NULL CHECK (worker_category IN ('THEKEDAR_CREW','VENDOR_TECH','ARCHITECT','CASUAL_LABOUR')),
    trade_code VARCHAR(24) NOT NULL,
    contractor_name VARCHAR(120) NOT NULL,
    skilled_count SMALLINT NOT NULL DEFAULT 0,
    unskilled_count SMALLINT NOT NULL DEFAULT 0,
    aadhaar_last4 CHAR(4),
    group_selfie_s3_sha256 CHAR(64) NOT NULL,
    engineer_verified_by UUID,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE project_shift_spans (
    span_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id),
    user_id UUID NOT NULL,
    span_seq SMALLINT NOT NULL DEFAULT 1,
    shift_window VARCHAR(24) NOT NULL CHECK (shift_window IN ('DAY_SITE_VISIT','IN_BETWEEN_CHECKIN','MALL_NIGHT_23_05','VENDOR_FACTORY_QC')),
    check_in_at TIMESTAMPTZ NOT NULL,
    check_out_at TIMESTAMPTZ,
    kiosk_selfie_sha256 CHAR(64) NOT NULL,
    gps_lat_lng VARCHAR(64),
    night_allowance_eligible BOOLEAN NOT NULL DEFAULT FALSE
);

CREATE TABLE project_site_grns (
    grn_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id),
    po_id UUID NOT NULL,
    challan_no VARCHAR(64) NOT NULL,
    eway_bill_no VARCHAR(32) NOT NULL,
    challan_photo_sha256 CHAR(64) NOT NULL,
    eway_bill_qr_photo_sha256 CHAR(64) NOT NULL,
    unloaded_crate_photo_sha256 CHAR(64) NOT NULL,
    lorry_plate_photo_sha256 CHAR(64) NOT NULL,
    condition_status VARCHAR(20) NOT NULL CHECK (condition_status IN ('INTACT','SHORT_QTY','DAMAGED_REJECTED')),
    payout_hold_active BOOLEAN NOT NULL DEFAULT FALSE,
    pre_minted_asset_ids_json JSONB NOT NULL DEFAULT '[]'::jsonb,
    received_by_engineer_id UUID NOT NULL,
    received_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT check_short_damaged_payout_hold CHECK (
        condition_status = 'INTACT' OR payout_hold_active = TRUE
    )
);

CREATE TABLE project_material_indents (
    indent_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id),
    trade_category VARCHAR(24) NOT NULL,
    item_summary VARCHAR(200) NOT NULL,
    voice_note_s3_sha256 CHAR(64),
    lang_code VARCHAR(8) NOT NULL DEFAULT 'EN' CHECK (lang_code IN ('EN','HI','TE')),
    sample_photo_sha256 CHAR(64) NOT NULL,
    urgency_tier VARCHAR(28) NOT NULL CHECK (urgency_tier IN ('WORK_STOPPED_URGENT','STANDARD_CENTRAL_PO')),
    estimated_cost_inr NUMERIC(10,2) NOT NULL,
    upi_imprest_utr VARCHAR(64),
    kachha_bill_photo_sha256 CHAR(64),
    status VARCHAR(24) NOT NULL DEFAULT 'REQUESTED',
    CONSTRAINT check_imprest_cap_5000 CHECK (urgency_tier <> 'WORK_STOPPED_URGENT' OR estimated_cost_inr <= 5000.00)
);

CREATE TABLE project_india_ground_controls (
    control_id UUID PRIMARY KEY,
    project_id UUID NOT NULL REFERENCES projects(project_id) UNIQUE,
    mall_night_permit_valid_until DATE,
    hot_work_permit_valid_until DATE,
    upi_imprest_float_inr NUMERIC(10,2) NOT NULL DEFAULT 15000.00,
    approved_hindrance_hours INTEGER NOT NULL DEFAULT 0,
    rent_free_fitout_extended_days SMALLINT GENERATED ALWAYS AS (CEIL(approved_hindrance_hours / 24.0)::SMALLINT) STORED,
    discom_3phase_kva_verified BOOLEAN NOT NULL DEFAULT FALSE,
    lpg_png_pressure_test_pass BOOLEAN NOT NULL DEFAULT FALSE,
    raw_water_tds_ppm SMALLINT CHECK (raw_water_tds_ppm <= 80),
    ro_softener_commissioned BOOLEAN NOT NULL DEFAULT FALSE,
    outward_scrap_passes_json JSONB NOT NULL DEFAULT '[]'::jsonb
);


-- =============================================================================
-- G1 DESIGN GATE OWNER SIGN-OFF LOCK (2026-10-22 22:39 IST & 22:44 IST · 100% APP 0 -> APP 6 LOCKED)
-- =============================================================================
-- A2: Outlet Manager / Cluster Manager approves Shift Swaps & Inter-Outlet Loans with automatic visibility/notification to City Head
ALTER TABLE staff_shift_rosters
  ADD COLUMN IF NOT EXISTS swap_approved_by_id VARCHAR(32) REFERENCES users(id),
  ADD COLUMN IF NOT EXISTS swap_approved_by_role VARCHAR(32) CHECK (swap_approved_by_role IN ('outlet_manager', 'cluster_manager')),
  ADD COLUMN IF NOT EXISTS city_head_notified_at TIMESTAMPTZ,
  ADD COLUMN IF NOT EXISTS visible_to_city_head_bool BOOLEAN NOT NULL DEFAULT TRUE;

ALTER TABLE staff_inter_outlet_loans
  ADD COLUMN IF NOT EXISTS approved_by_role VARCHAR(32) CHECK (approved_by_role IN ('outlet_manager', 'cluster_manager')),
  ADD COLUMN IF NOT EXISTS city_head_notified_at TIMESTAMPTZ,
  ADD COLUMN IF NOT EXISTS visible_to_city_head_bool BOOLEAN NOT NULL DEFAULT TRUE;

-- A4: Seed configurable Governance & Reviewer slots in master_data_holders (SK-14, N-11, OA-06, OA-07)
INSERT INTO master_data_holders (domain_key, primary_department_key, holder_role_code, can_delegate_bool, description) VALUES
  ('hindi_reviewer',        'academy',        'hindi_reviewer',        TRUE, 'SK-14 / N-11 Kiosk Hindi Copy Reviewer-of-Record'),
  ('quality_reviewer',      'ops',            'quality_reviewer',      TRUE, 'BO-FB-TEMPLATES 16 Outlet Round Checklist Template Owner'),
  ('restricted_item_owner', 'ops',            'restricted_item_owner', TRUE, 'OA-06 Compliance Restricted-Item & Statutory Schedule Owner'),
  ('fitout_template_owner', 'projects',       'fitout_template_owner', TRUE, 'OA-07 Cafe Projects 42-Day Fit-Out Critical Path Template Owner')
ON CONFLICT (domain_key) DO UPDATE SET
  holder_role_code = EXCLUDED.holder_role_code,
  description = EXCLUDED.description;
```


</details>

<details>
<summary><strong>📂 3C. Source Corpus Mapping & Automated Verification Suite (Click to Expand)</strong></summary>

| Source Folder / Artifact | Files / Rows | Target Domain Object | Gate Status |
| :--- | :--- | :--- | :--- |
| `Master Projects - 2026 to 2027.xlsx + BO-PACK-PROJECTS` | 8 Workbook Tabs + PRJ-J01..10 + PRJ-01..12 + PRJ-Q1..Q7 | `projects + project_gates + project_boq_items + project_authority_ledger` | **STAGE 2–4 SPEC COMPLETE** |
| `India Ground Site Kiosk (J17 Storyboard)` | Ad-Hoc Hajiri, Split/Night Shifts, 4-Photo GRN, Voice Indent & 5 India Ground Controls | `project_site_attendance + project_shift_spans + project_site_grns + project_material_indents + project_india_ground_controls` | **STAGE 2–4 SPEC COMPLETE** |
| `Fixed Assets (1,982 QRs) & 6-State Maintenance (J16 Storyboard)` | 1,982 QR Rows + 40% WDV Gate + 2nd-Person Operator Verify | `assets_fixed + maint_tickets` | **STAGE 2–4 SPEC COMPLETE** |

**Verification Evidence:** `pytest tests/test_stop2_projects_assets_maint.py` (28 fail-first tests) + Playwright `J16` & `J17` (`390/360/320px` Chromium + WebKit) — 100% green across `PRJ-Q2` 4-tier authority, 4-photo GRN payout hold, `<= ₹5k` UPI Imprest cap, `Water TDS <= 80 ppm` boiler lock, Hindrance rent-free day extension math, idempotent Gate 6 QR minting, `40% WDV` CFO gate, and 2nd-person Operator repair closure.

</details>