# shiftops-frontend-core Full Instructions

## ShiftOps Frontend Purpose

User-facing workflow for ShiftOps lead generation tool: search, analysis, report display, lead capture.

## Data Flow (Unique to ShiftOps Frontend)

### Essential Mode (Loading Screen)

**localStorage key:** `shiftops_report_data`

**Contains:**

- Complete business info (name, address, website, rating, reviews, photos, etc.)
- ShiftOps score (total_score, pillar_scores, grade)
- Cost savings (team size, potential savings, ROI)
- Location analysis
- Online presence
- Context data (holidays, weather, seasonal trends)
- Competitive positioning (may be null in essential mode)
- Recommendations (structured: quick_wins, high_value, strategic)
- Customer match info (is_ordio_customer, customer_match_confidence)

**Flow:**

1. User searches business using Google Places autocomplete
2. POST to `/v2/api/shiftops.php` with `mode='essential'` (includes all Google Places data)
3. Store complete essential data in localStorage: `shiftops_report_data`
4. Redirect to `/shiftops-report` (or `/v2/pages/shiftops-report.php`)
5. Show loading screen with preliminary score and rotating messages
6. Background fetch enhanced data while loading screen displays

### Enhanced Mode (Full Analysis)

**localStorage key:** `shiftops_enhanced_data`

**Contains:**

- Complete enhanced analysis object
- Full competitive positioning data
- Enhanced recommendations with ROI estimates

**Flow:**

1. After essential mode redirect, background fetch enhanced data
2. POST to `/v2/api/shiftops.php` with `mode='enhanced'` (includes place_id from essential data)
3. Store enhanced data in localStorage: `shiftops_enhanced_data`
4. Update UI with enhanced data when available
5. Show enhanced score, competitive positioning, detailed recommendations

### Gated Content Pattern

**Unlock Flow:**

1. User views report (essential or enhanced data)
2. Email form overlay appears (if not already unlocked)
3. User submits email
4. POST to `/v2/api/shiftops.php` with `action='unlock'`
5. Store unlock status: `shiftops_unlocked = 'true'`
6. Remove overlay, show full report content

**localStorage Keys:**

- `shiftops_unlocked` - Boolean flag (string 'true'/'false')
- `shiftops_email` - Email address used for unlock
- `shiftops_unlock_timestamp` - Timestamp of unlock

---

## UI / UX Patterns (Unique to ShiftOps)

### Forms

**Search Form (shiftops.php):**

- Google Places autocomplete
- Real-time validation
- Loading states during search
- Error handling (no results, API errors)

**Email Unlock Form (shiftops-report.php):**

- Overlay modal design
- Email validation (client-side and server-side)
- Success/error states
- Auto-dismiss on success

### Gated Content

**Blur Pattern:**

- Values blurred until email submitted
- CSS filter: `blur(4px)` on `.gated-value` class
- Smooth transition on unlock (`transition: filter 0.3s ease`)

**Overlay Pattern:**

- Full-screen overlay on mobile
- Centered modal on desktop
- Backdrop blur effect
- Close button (X) in top-right

### PDF Export

**Implementation:**

- Server-side PDF generation (`/v2/api/shiftops-pdf.php`)
- Includes full report content
- Ordio branding (logo, colors)
- Download button in report header

**Trigger:**

- Click "PDF herunterladen" button
- POST to `/v2/api/shiftops-pdf.php` with report data
- Returns PDF file download

### Responsive Behavior

**Mobile:**

- Full-screen overlays
- Touch-friendly buttons (min 44px height)
- Swipe gestures for navigation
- Optimized font sizes

**Desktop:**

- Centered modals
- Hover states on interactive elements
- Keyboard navigation support
- Larger touch targets

---

## Integration Checks (Unique to ShiftOps)

### API Calls

**Essential Mode:**

- Endpoint: `/v2/api/shiftops.php`
- Method: POST
- Payload: `{ mode: 'essential', ...googlePlacesData }`
- Response: `{ success: true, data: {...essentialData} }`

**Enhanced Mode:**

- Endpoint: `/v2/api/shiftops.php`
- Method: POST
- Payload: `{ mode: 'enhanced', place_id: '...' }`
- Response: `{ success: true, data: {...enhancedData} }`

**Unlock:**

- Endpoint: `/v2/api/shiftops.php`
- Method: POST
- Payload: `{ action: 'unlock', email: '...', ... }`
- Response: `{ success: true, unlocked: true }`

### HubSpot Submission

**Form ID:** `804459f7-c18d-4da6-8a0b-a81f44bb8275`

**Fields:**

- Email (required)
- Business name (from analysis)
- Team size (from analysis or user input)
- ShiftOps score
- ShiftOps grade
- UTM parameters (preserved from initial page load)

**Trigger:**

- After email unlock form submission
- Submit to HubSpot Forms API v3
- Include `hubspotutk` for session tracking

### CTA Buttons and Carousel

**Primary CTA:**

- "Jetzt kostenlos testen" button
- Links to `/demo` or `/kontakt`
- Preserves UTM parameters

**Carousel:**

- Rotating testimonials or features
- Auto-advance every 5 seconds
- Manual navigation (dots, arrows)
- Pause on hover

---

## localStorage Keys (ShiftOps-Specific)

### Primary Data Storage

**Essential Data:**

- `shiftops_report_data` - Complete essential analysis object (JSON string)
- Contains: business info, score, recommendations, cost savings

**Enhanced Data:**

- `shiftops_enhanced_data` - Complete enhanced analysis object (JSON string)
- Contains: enhanced analysis, competitive positioning, ROI estimates

**Unlock Status:**

- `shiftops_unlocked` - Boolean flag ('true'/'false')
- `shiftops_email` - Email address used for unlock
- `shiftops_unlock_timestamp` - ISO timestamp of unlock

### Status Keys

**Search Status:**

- `shiftops_search_completed` - Boolean flag
- `shiftops_analysis_started` - Timestamp
- `shiftops_analysis_completed` - Timestamp

**Report Status:**

- `shiftops_report_viewed` - Timestamp
- `shiftops_report_unlocked` - Timestamp
- `shiftops_pdf_downloaded` - Timestamp

### Legacy/Backup Keys

**Deprecated (may exist in older sessions):**

- `shiftops_data` - Old format (replaced by `shiftops_report_data`)
- `shiftops_score` - Old format (now in `shiftops_report_data.total_score`)

**Migration:**

- Check for old keys on page load
- Migrate to new format if found
- Clear old keys after migration

### Key Management Best Practices

**Set Keys:**

```javascript
localStorage.setItem("shiftops_report_data", JSON.stringify(data));
localStorage.setItem("shiftops_unlocked", "true");
```

**Get Keys:**

```javascript
const reportData = JSON.parse(
  localStorage.getItem("shiftops_report_data") || "{}"
);
const unlocked = localStorage.getItem("shiftops_unlocked") === "true";
```

**Clear Keys:**

```javascript
// Clear all ShiftOps keys
Object.keys(localStorage).forEach((key) => {
  if (key.startsWith("shiftops_")) {
    localStorage.removeItem(key);
  }
});
```

---

## Team Size Display Consistency (ShiftOps-Specific)

### Data Source Priority Order

1. **User Input** (if provided in form)
2. **Analysis Estimate** (from ShiftOps API)
3. **Fallback** (default: 10)

### Code Locations

**Display Logic:**

- `v2/pages/shiftops-report.php` - Main report page
- `v2/js/shiftops-report.js` - JavaScript logic

**Validation:**

- Client-side: Check if value exists and is valid number
- Server-side: Validate in API endpoint

### Validation Logging

**Log when fallback used:**

```javascript
if (!teamSize || teamSize === 10) {
  console.warn("ShiftOps: Using fallback team size (10)");
  // Log to tracking system
}
```

### Consistency Requirements

- Same team size displayed throughout report
- Same team size sent to HubSpot
- Same team size used in cost calculations
- No discrepancies between sections

### Documentation

See `docs/systems/shiftops/TEAM_ESTIMATION_CHANGELOG.md` for complete changelog and `docs/systems/shiftops/TEAM_ESTIMATION_QUICK_REFERENCE.md` for quick reference.

## NPS Survey Feature (ShiftOps-Specific)

### Overview

NPS survey collects user feedback on ShiftOps tool after they view their report.

### Frontend Implementation

**Location:** `v2/pages/shiftops-report.php` (lines 4247-4252, 17910-18226)

**Display Logic:**

- Shows after user unlocks report content
- Checks `shiftops_nps_submitted` and `shiftops_nps_dismissed` localStorage keys
- One-time display per user session

**UI Pattern:**

- Modal-style survey card
- NPS score selector (0-10)
- Optional feedback text input
- Submit and dismiss buttons

### API Integration

**Endpoint:** `POST /v2/api/shiftops-nps.php`

**Required Fields:**

- `email`: Valid email address
- `nps_score`: Integer 0-10

**Optional Fields:**

- `nps_feedback`: Free text feedback
- `shiftops_business_name`: Business name from analysis
- `shiftops_index`: ShiftOps score (0-100)
- `shiftops_grade`: ShiftOps grade (A+, A, B, C, D, F)
- `shiftops_place_id`: Google Places place_id

**Response:**

- Success: `{success: true, message: "...", nps_data: {...}}`
- Error: `{success: false, error: "...", details: "..."}`

### localStorage Keys

- `shiftops_nps_submitted`: Set to `'true'` when survey submitted
- `shiftops_nps_dismissed`: Set to `'true'` when survey dismissed
- Both cleared when user starts new search

### HubSpot Integration

- Portal ID: `145133546`
- Form ID: `804459f7-c18d-4da6-8a0b-a81f44bb8275`
- Logs to: `logs/shiftops-nps.log`

### Documentation

See `docs/systems/shiftops/SHIFTOPS_API_DOCUMENTATION.md` for complete NPS endpoint documentation.

## Related Documentation

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping.

**Key Documentation:**

- [docs/systems/shiftops/README.md](../../docs/systems/shiftops/README.md) - `docs/systems/shiftops/README.md` - ShiftOps system index
- [docs/systems/shiftops/](../../docs/systems/shiftops/) - `docs/systems/shiftops/` - All ShiftOps documentation files
- [docs/guides/PAGE_TYPE_GUIDES.md](../../docs/guides/PAGE_TYPE_GUIDES.md) - `docs/guides/PAGE_TYPE_GUIDES.md` - ShiftOps workflow patterns