**Prepared by:** Oditha

**Date:** 23 January 2026

**Version:** 1.0

**Status:** Draft

---

## 1. Executive Summary

The **Lion HoReCa Excellence Field Operations & Workflow Management System** is a comprehensive solution designed to streamline field sales operations, compliance audits, and POSM tracking across Hotels, Restaurants, and Cafés (HoReCa) outlets. The system integrates with the existing **Commercial Excellence Flutter Mobile App** for field operations and the **Commercial Excellence Laravel System Admin** for management and configuration.

### Project Objectives

-   Enable structured outlet visit workflows with configurable process flows
-   Automate POSM audit scheduling and compliance tracking
-   Implement intelligent service request generation and management
-   Provide real-time visibility into field operations through dashboards and reports
-   Support hierarchical data access and geolocation-based outlet prioritization

### System Architecture

-   **Mobile App:** Flutter (existing Commercial Excellence app)
-   **System Admin:** Laravel (existing Commercial Excellence admin)
-   **Database:** MySQL
-   **Key Integrations:** Geolocation services, file storage for photos

---

## 2. User Roles & Permissions

### 2.1 Field Users (Mobile App)

**LSR (Local Sales Representative)**

-   Execute workflows at assigned outlets
-   Check-in/check-out with geolocation tracking
-   Submit photos, responses, and remarks
-   Report equipment issues
-   Execute POSM audits
-   View assigned outlets only

**TM (Territory Manager)**

-   All LSR capabilities
-   View and manage LSRs in their territory
-   Review and update POSM audit status
-   Access dashboard for territory performance
-   View outlets assigned to their LSRs

**SM (Sales Manager)**

-   All TM capabilities
-   View and manage multiple TMs and their territories
-   Access regional dashboard
-   View all outlets under their hierarchy

### 2.2 Admin Users (System Admin)

**System Administrator**

-   Workflow management (create, edit, configure)
-   Service request configuration (categories, templates, assignment rules)
-   Outlet configuration (workflows, brands, equipment, norms)
-   POSM module management
-   User role assignment
-   Full system access

**Regional/Territory Managers (Admin Access)**

-   View dashboards and reports for their hierarchy
-   Export reports
-   Limited configuration access

---

## 3. Functional Requirements

### Module 1: Workflow Management (System Admin)

#### FR-WM-001: Workflow Creation

**Description:** System administrators can create custom workflows for different outlet visit types.

**Requirements:**

-   Create workflow with name and description
-   Define workflow category (Impulse, Cooler, Branding, Pouring Material, Competitor, Audit, Custom)
-   Set workflow status (Active/Inactive)
-   Add icon and color coding for visual identification

**Acceptance Criteria:**

-   Workflow name must be unique
-   Description supports rich text (max 500 characters)
-   Inactive workflows are not visible in mobile app

#### FR-WM-002: Workflow Step Configuration

**Description:** Each workflow consists of sequential steps that guide field users through the process.

**Requirements:**

-   Add/edit/delete/reorder workflow steps
-   Configure step attributes:
    -   Step name and description
    -   Step order/sequence
    -   Mandatory flag (required to complete workflow)
    -   Question type: **Selection** or **Text Area**
    -   For Selection type: define options (yes/no, multiple choice, single choice)
    -   Sample photo attachment (for reference)
    -   Instructions text
    -   Enable/disable remarks field
    -   Enable/disable skip option with reason

**Acceptance Criteria:**

-   Minimum 1 step required per workflow
-   Step order must be sequential (1, 2, 3...)
-   Mandatory steps cannot be skipped without reason
-   Sample photos are optional but recommended

#### FR-WM-003: Conditional Logic

**Description:** Workflow steps can have conditional visibility based on previous step responses.

**Requirements:**

-   Define conditional rules: "Show step X if step Y answer = Z"
-   Support AND/OR logic for multiple conditions
-   Visual flow builder showing conditional branches
-   Validate that conditional logic does not create infinite loops

**Example:**

-   Step 2: "Is cooler available?" (Yes/No)
-   Step 3: "Is cooler functional?" (only shown if Step 2 = Yes)
-   Step 4: "Report cooler issue" (only shown if Step 3 = No)

**Acceptance Criteria:**

-   Conditional steps are hidden in mobile app until condition is met
-   System validates logic on save to prevent circular dependencies
-   Conditional rules are displayed clearly in admin UI

#### FR-WM-004: Workflow Group Template Management

**Description:** Workflow Group Templates bundle multiple workflows together for simplified outlet assignment.

**Requirements:**

-   Create/edit/delete Workflow Group Templates
-   Template attributes:
    -   Template name and description
    -   Icon and color coding
    -   Status (Active/Inactive)
-   Add multiple workflows to a template
-   Configure workflow execution order (optional/sequential)
-   Set template-level configuration:
    -   All workflows mandatory or optional per workflow
    -   Default workflow execution sequence
-   Clone existing templates for quick setup
-   Preview template workflow list before saving

**Example Templates:**

-   **"Restaurant Standard"** → Includes: Impulse + Cooler + Branding + POSM Audit
-   **"Bar Premium"** → Includes: Impulse + Cooler + Branding + Pouring Material + Competitor + POSM Audit
-   **"Café Basic"** → Includes: Impulse + Branding + POSM Audit

**Acceptance Criteria:**

-   Template name must be unique
-   At least one workflow must be added to a template
-   Inactive templates are not available for outlet assignment
-   Deleting a workflow removes it from all templates (with warning)
-   Mobile app displays all workflows from assigned template

#### FR-WM-005: Service Request Trigger Configuration

**Description:** Workflow step responses can automatically trigger service request creation.

**Requirements:**

-   For each step with Selection type, configure trigger rules:
    -   Select which option(s) trigger service request
    -   Map to service request category
    -   Map to service request template
    -   Auto-assignment based on hierarchy (configured in SR module)
-   Support multiple triggers per workflow
-   Preview trigger logic before activation

**Example:**

-   Step: "Cooler functional?" → Option: "No" → Trigger: Service Request Category "Equipment Repair" → Template "Cooler Repair Request" → Assigned to: TM

**Acceptance Criteria:**

-   Service request is created immediately upon step submission
-   User receives confirmation notification in mobile app
-   Triggered service requests include all relevant context (outlet, workflow, step, response)

---

### Module 2: Service Request Management (System Admin + Mobile App)

#### FR-SR-001: Service Request Categories

**Description:** Administrators can define and manage service request categories.

**Requirements:**

-   Create/edit/delete service request categories
-   Category attributes:
    -   Category name
    -   Description
    -   Priority level (Low, Medium, High, Critical)
    -   SLA duration (hours)
    -   Default assignment hierarchy (LSR → TM → SM → Regional Manager)
-   Set category status (Active/Inactive)

**Acceptance Criteria:**

-   Active categories are available for workflow trigger mapping
-   SLA tracking starts from service request creation timestamp

#### FR-SR-002: Service Request Templates

**Description:** Predefined templates streamline service request creation and standardize information capture.

**Requirements:**

-   Create/edit/delete service request templates
-   Template attributes:
    -   Template name
    -   Linked category
    -   Pre-filled description text with dynamic placeholders:
        -   {outlet_name}
        -   {workflow_name}
        -   {step_name}
        -   {response}
        -   {user_name}
        -   {date_time}
    -   Additional custom fields (text, dropdown, checkbox)

**Example Template:**

```
Title: Cooler Repair Request
Category: Equipment Repair
Description:
Cooler reported as non-functional at {outlet_name} during {workflow_name} execution.
Reported by: {user_name} on {date_time}
Workflow Step: {step_name}
Response: {response}
```

**Acceptance Criteria:**

-   Placeholders are replaced with actual data on service request creation
-   Templates can be previewed before saving

#### FR-SR-003: Service Request Lifecycle

**Description:** Service requests follow a defined lifecycle with status updates and assignment tracking.

**Requirements:**

-   Service request statuses:
    -   **Open:** Newly created, awaiting action
    -   **In Progress:** Assigned user is working on resolution
    -   **Resolved:** Issue fixed, pending closure
    -   **Closed:** Verified and closed
    -   **Cancelled:** Request cancelled with reason
-   Status transitions:
    -   Open → In Progress (assigned user accepts)
    -   In Progress → Resolved (user marks as fixed)
    -   Resolved → Closed (admin/TM verifies)
    -   Any status → Cancelled (with mandatory reason)
-   Auto-assignment based on category configuration
-   Manual reassignment capability
-   Activity log tracking all status changes, comments, and reassignments

**Acceptance Criteria:**

-   Only assigned user and admins can update status
-   SLA breach alerts trigger when duration exceeds category SLA
-   Notifications sent on status changes to relevant users

#### FR-SR-004: Service Request Viewing (Mobile App)

**Description:** Field users can view service requests they created or are assigned to.

**Requirements:**

-   List view showing:
    -   Service request ID
    -   Title
    -   Status badge
    -   Priority indicator
    -   Created date
    -   Assigned to
    -   SLA countdown
-   Filter by status, category, date range
-   Detail view showing full context, activity log, and attachments
-   Push notifications for status updates

**Acceptance Criteria:**

-   LSRs see only their created/assigned requests
-   TMs see requests from their LSRs + their own
-   SMs see all requests in their hierarchy

---

### Module 3: Outlet Configuration (System Admin)

#### FR-OC-001: Outlet Master Data

**Description:** Centralized outlet information management.

**Requirements:**

-   Outlet attributes:
    -   Outlet name
    -   Address (text + geolocation coordinates)
    -   Contact details (phone, email)
    -   Outlet type (Restaurant, Hotel, Café, Bar, etc.)
    -   Territory/region assignment
    -   User assignment (LSR, TM, SM hierarchy)
    -   Status (Active/Inactive)
-   Import outlets via CSV
-   Export outlet list

**Acceptance Criteria:**

-   Geolocation coordinates must be valid latitude/longitude
-   Each outlet must be assigned to at least one LSR
-   Hierarchical assignment auto-populates (outlet → LSR → TM → SM)

#### FR-OC-002: Workflow Group Template Assignment to Outlets

**Description:** Assign a Workflow Group Template to each outlet to determine which workflows are available during visits.

**Requirements:**

-   Assign one Workflow Group Template per outlet
-   Change template assignment (migrates outlet to new template)
-   For each workflow in the assigned template:
    -   Enable/disable specific workflows (override template defaults)
    -   Enable/disable specific steps within workflows
    -   Add custom outlet-specific steps
    -   Modify step order (within constraints)
    -   Set step-level mandatory flags (override workflow defaults)
-   Preview final workflow configuration before saving
-   Bulk assign template to multiple outlets

**Example:**

-   Outlet "ABC Restaurant" assigned **"Restaurant Standard"** template
    -   Template includes: Impulse + Cooler + Branding + POSM Audit
    -   Admin disables "Cooler" workflow (outlet has no cooler)
    -   Admin customizes Impulse workflow Step 5 (adds outlet-specific instruction)
-   Outlet "XYZ Bar" assigned **"Bar Premium"** template
    -   Template includes all 6 workflow types
    -   All workflows remain enabled as per template

**Acceptance Criteria:**

-   Every active outlet must have exactly one template assigned
-   Changing outlet template warns if workflows are disabled that have historical data
-   Custom steps follow same configuration rules as standard steps
-   Mobile app loads workflows from assigned template
-   Template updates propagate to all assigned outlets (unless outlet has customizations)

#### FR-OC-003: Brand Configuration

**Description:** Define brands that must be available or can be optionally available at each outlet.

**Requirements:**

-   Create brand master list (Admin → Brand Management)
-   For each outlet, configure:
    -   **Must-have brands:** Required to be available (triggers alerts if unavailable)
    -   **Optional brands:** Nice to have, tracked for reporting
-   Brand tracking integrated into workflow execution
-   Bulk assign brands to multiple outlets

**Acceptance Criteria:**

-   Brand availability is captured during workflow execution
-   "No" response for must-have brand can trigger service request (based on workflow config)
-   Brand availability data feeds into dashboard reports

#### FR-OC-004: Equipment & Material Configuration

**Description:** Configure coolers, branding materials, and pouring equipment per outlet.

**Requirements:**

-   For each outlet, define:
    -   **Coolers:** Quantity, type, serial numbers (optional)
    -   **Branding Materials:** Type (signage, posters, etc.), quantity
    -   **Pouring Materials:** Type (taps, dispensers), quantity
-   Equipment inventory syncs with POSM norms
-   Mobile app loads this data for validation during workflow execution

**Acceptance Criteria:**

-   Equipment list is displayed in mobile app for reference
-   Discrepancies between configured vs observed equipment can be reported

---

### Module 4: POSM Module & Audit Scheduling (System Admin + Mobile App)

#### FR-PM-001: POSM Norms Management

**Description:** Define standard quantities of POSM materials per outlet or outlet type.

**Requirements:**

-   Create norms sheet structure:
    -   Material name
    -   Material category (signage, cooler, branding, pouring)
    -   Standard quantity per outlet type
-   Assign norms to outlets (by outlet type or individually)
-   Import/export norms via CSV
-   Version control for norms (track changes over time)

**Example Norms:**

| Material       | Category  | Outlet Type: Restaurant | Outlet Type: Bar |
| -------------- | --------- | ----------------------- | ---------------- |
| Lion Poster A1 | Branding  | 2                       | 3                |
| Cooler (300L)  | Equipment | 1                       | 2                |
| Tap Handle     | Pouring   | 2                       | 4                |

**Acceptance Criteria:**

-   Norms are reference documents for audit comparison
-   Mobile app displays norms during POSM audit execution

#### FR-PM-002: POSM Audit Scheduling

**Description:** Automated audit task generation every 20 days after last completed audit.

**Requirements:**

-   System automatically generates audit task:
    -   20 days after last completed audit for each outlet
    -   Task assigned to outlet's primary TM
    -   Task includes:
        -   Outlet name
        -   Scheduled audit date (20 days after last completion)
        -   Audit due date (scheduled date + 5 days buffer)
        -   Norms sheet reference
-   Notification sent to TM on task creation
-   Task appears in mobile app "My Audits" list

**Acceptance Criteria:**

-   First audit task created manually or on outlet activation
-   Subsequent audits auto-generate on completion of previous audit
-   Tasks cannot be deleted, only completed or flagged

#### FR-PM-003: POSM Audit Execution (Mobile App)

**Description:** TMs execute POSM audits via mobile app during outlet visits.

**Requirements:**

-   Audit workflow:
    1. TM selects "POSM Audit" from outlet menu
    2. System displays norms sheet for reference
    3. TM verifies and updates actual quantities per material
    4. System auto-calculates variance (actual vs norm)
    5. TM adds remarks for variances
    6. TM identifies restocking needs
    7. TM submits audit
-   Check-in/check-out timestamps auto-captured
-   Audit status: Draft, Submitted, Completed
-   5-day buffer for TM to complete restocking and finalize audit

**Acceptance Criteria:**

-   Audit submission triggers next audit task (20 days from completion)
-   Variance data feeds into dashboard reports
-   Geolocation verified during audit execution

#### FR-PM-004: Overdue Audit Flagging

**Description:** System flags audits not completed by due date (scheduled date + 5 days).

**Requirements:**

-   Daily cron job checks for overdue audits
-   Overdue criteria:
    -   Current date > audit due date
    -   Audit status ≠ Completed
-   Flag overdue audits:
    -   Mark task as "Overdue" in system
    -   Send escalation notification to TM's SM
    -   Display in "Red Flags" dashboard section
    -   Generate weekly overdue audit report

**Acceptance Criteria:**

-   Overdue flag is removed once audit is completed
-   Escalation hierarchy: TM → SM → Regional Manager (configurable)
-   Overdue audits impact TM performance metrics

---

### Module 5: Mobile App - Field Operations

#### FR-MO-001: Outlet List & Filtering

**Description:** Field users view and filter their assigned outlets.

**Requirements:**

-   List view showing:
    -   Outlet name
    -   Address (1 line)
    -   Distance from current location
    -   Last visit date
    -   Status indicators (overdue audit, pending service request)
-   **Geotag-based sorting:**
    -   Primary sort: Distance from user's current location (nearest first)
    -   Configurable radius threshold (default: 5km, admin-configurable)
    -   Manual refresh to update distances
-   Search by outlet name (fuzzy search)
-   Filter by:
    -   Territory/region
    -   Outlet type
    -   Assigned workflows
    -   Audit status
    -   Service request status
-   Hierarchical visibility:
    -   LSR: Assigned outlets only
    -   TM: LSR outlets + own assignments
    -   SM: All outlets in hierarchy

**Acceptance Criteria:**

-   Geolocation permission required for distance calculation
-   Outlets beyond configurable radius are grouped as "Other Outlets"
-   Search results update in real-time

#### FR-MO-002: Check-in / Check-out

**Description:** Mandatory check-in/check-out to track visit time and geolocation.

**Requirements:**

-   **Check-in:**
    -   User taps outlet → "Check In" button
    -   System captures:
        -   Check-in timestamp
        -   Geolocation coordinates
        -   Distance from outlet address (validation)
    -   Geofence validation: Warn if >100m from outlet (configurable)
    -   User can proceed with reason if outside geofence
-   **Check-out:**
    -   User taps "Check Out" button
    -   System captures:
        -   Check-out timestamp
        -   Auto-calculates time spent
    -   User selects visit outcome:
        -   Workflows completed
        -   Partial completion (with reason)
        -   No action taken (with reason)
-   Visit log stored for reporting

**Acceptance Criteria:**

-   Users cannot execute workflows without checking in
-   Multiple check-ins per day allowed for same outlet
-   Visit duration calculation: Check-out time - Check-in time
-   Forgot to check out? System prompts on next app launch

#### FR-MO-003: Workflow Execution

**Description:** Field users execute assigned workflows step-by-step.

**Requirements:**

-   After check-in, user selects workflow to execute
-   Step-by-step wizard interface:
    -   Display step number, name, instructions
    -   Show sample photo (if configured)
    -   Render question type:
        -   **Selection:** Radio buttons or checkboxes
        -   **Text Area:** Multi-line text input
    -   Enable remarks field (if configured)
    -   Enable skip button (if configured and step not mandatory)
        -   Skip requires reason (dropdown + text)
-   **Conditional logic:**
    -   Steps hidden until condition met
    -   Navigation adjusted dynamically
    -   Progress bar reflects visible steps only
-   **Photo capture:**
    -   Steps configured for photo submission
    -   Multiple photos per step (configurable limit: 1-10)
    -   Camera or gallery selection
    -   Photo preview before submission
-   Progress saved locally (offline support)
-   Submit workflow on completion
-   Can submit partial workflow (if not all mandatory steps completed, warn user)

**Acceptance Criteria:**

-   Mandatory steps block workflow submission
-   Skipped steps log reason for reporting
-   Workflow submission triggers service request creation (if configured)
-   Offline mode: Workflows saved locally, synced on connectivity

#### FR-MO-004: Brand Availability Tracking

**Description:** Capture brand availability during workflow execution.

**Requirements:**

-   Workflow step type: "Brand Availability Check"
-   Displays outlet's configured brands (must-have + optional)
-   For each brand:
    -   Yes/No toggle
    -   Remarks field (optional)
-   Logic integration:
    -   "No" for must-have brand can trigger service request (based on workflow config)
    -   "No" responses feed into brand availability reports
    -   Integration with norms: Compare availability vs expected quantity

**Acceptance Criteria:**

-   Brand list auto-populated from outlet configuration
-   Service request triggered per workflow trigger rules

#### FR-MO-005: Equipment Issue Reporting

**Description:** Report broken coolers, taps, or other equipment during workflow execution.

**Requirements:**

-   Workflow step type: "Equipment Status Check"
-   Displays outlet's configured equipment list
-   For each equipment:
    -   Status: Functional / Non-functional / Missing
    -   If non-functional: Issue description (text area)
    -   Photo attachment (optional)
-   "Non-functional" or "Missing" status triggers service request (if configured)

**Acceptance Criteria:**

-   Equipment list synced from outlet configuration
-   Service request includes equipment details, issue description, and photo

---

### Module 6: Dashboard & Reporting (System Admin)

#### FR-DR-001: Static Dashboard

**Description:** Predefined dashboard with fixed KPI widgets and visualizations for monitoring field operations.

**Requirements:**

-   **Dashboard Layout:**
    -   Role-based views (SM sees hierarchy, TM sees territory, LSR sees own metrics)
    -   Responsive design (desktop, tablet, mobile)
    -   Auto-refresh every 5 minutes
    -   Manual refresh button
    -   Date range selector (Today, Last 7 days, Last 30 days, Custom)
-   **KPI Widgets (Top Section):**
    1. **Outlets Visited Today** - Count with trend vs yesterday
    2. **Workflows Completed Today** - Count with completion rate %
    3. **Pending Service Requests** - Count with SLA breach warnings
    4. **Overdue POSM Audits** - Count with list of outlets
-   **Visualizations (Middle Section):**
    1. **Visit Coverage Chart** - Bar chart showing outlets visited vs assigned (by user or territory)
    2. **Workflow Completion Trend** - Line chart showing daily workflow completions over selected period
    3. **Service Request Status** - Pie chart showing Open/In Progress/Resolved/Closed breakdown
    4. **Brand Availability Score** - Horizontal bar chart showing % availability by brand
-   **Red Flags Section (Bottom):**
    -   List view with tabs for each red flag category
    -   Click to navigate to detail view
    -   Badge count per category
-   **Drill-Down Capability:**
    -   Click any widget to view detailed report
    -   Hierarchy drill-down: National → Region → Territory → SM → TM → LSR → Outlet
    -   Filters persist across drill-down levels

**Acceptance Criteria:**

-   Dashboard loads within 3 seconds
-   Data accuracy matches underlying reports
-   Role-based filtering applied automatically
-   Export snapshot as PDF
-   Mobile-responsive layout adjusts widget size

#### FR-DR-002: Visit Coverage Reports

**Description:** Track field user activity and outlet visit coverage.

**Metrics:**

-   Total outlets assigned vs visited (by user, by period)
-   Visit frequency per outlet (avg days between visits)
-   Time spent per outlet (avg, min, max)
-   Check-in/check-out compliance (missed check-outs)
-   Geolocation compliance (visits within geofence)
-   Visit outcomes (completed workflows, partial, no action)

**Filters:**

-   Date range
-   User (LSR, TM, SM)
-   Territory/region
-   Outlet type

**Export:** CSV, PDF

#### FR-DR-003: Workflow Compliance Reports

**Description:** Measure workflow execution quality and completion rates.

**Metrics:**

-   Workflows executed (count by type, by user)
-   Completion rate (completed vs partial vs abandoned)
-   Mandatory step compliance (% completed)
-   Steps skipped (count, reasons breakdown)
-   Avg time per workflow
-   Photos submitted (count per workflow type)

**Drill-down:** Workflow type → Outlet → User → Step details

**Export:** CSV, PDF

#### FR-DR-004: POSM Audit Reports

**Description:** Track POSM audit compliance and material variances.

**Metrics:**

-   Audits completed on time vs overdue (by period)
-   Avg variance % (actual vs norm)
-   Material-level variance trends (which materials consistently under-stocked)
-   Restocking cycle time (audit completion to restock)
-   Audits flagged/escalated

**Drill-down:** Region → Territory → Outlet → Audit details

**Export:** CSV, PDF

#### FR-DR-005: Service Request Reports

**Description:** Monitor service request volume, resolution time, and SLA compliance.

**Metrics:**

-   Service requests created (count by category, by period)
-   Avg resolution time (by category, by assigned user)
-   SLA compliance rate (resolved within SLA vs breached)
-   Status breakdown (open, in progress, resolved, closed)
-   Assignment distribution (requests per user)
-   Top categories (most frequent issues)

**Drill-down:** Category → Status → Assigned User → Request details

**Export:** CSV, PDF

#### FR-DR-006: Brand Availability Reports

**Description:** Track brand stockout frequency and availability trends.

**Metrics:**

-   Brand availability rate (% outlets with brand available)
-   Stockout frequency (must-have brands reported unavailable)
-   Availability trends over time (by brand, by outlet type)
-   Outlet-level availability scorecard

**Drill-down:** Brand → Outlet type → Outlet → Visit details

**Export:** CSV, PDF

#### FR-DR-007: Competitor Intelligence Reports

**Description:** Analyze competitor presence and activity at outlets.

**Metrics:**

-   Competitor stock presence (% outlets with competitor products)
-   Competitor POSM presence (signage, branding observed)
-   Competitor pouring materials presence (taps, dispensers)
-   Competitor activity trends (by brand, by region)

**Drill-down:** Competitor → Outlet type → Outlet → Visit details

**Export:** CSV, PDF

#### FR-DR-008: Red Flags Dashboard

**Description:** Consolidated view of critical issues requiring immediate attention.

**Red Flag Categories:**

1. **Overdue POSM Audits:** List of outlets with audits past due date
2. **SLA Breached Service Requests:** Service requests exceeding SLA
3. **Must-Have Brand Stockouts:** Outlets missing critical brands
4. **Unvisited Outlets:** Outlets not visited in X days (configurable threshold)
5. **Pending Service Requests:** High/critical priority requests in "Open" status
6. **Geolocation Compliance Issues:** Check-ins outside geofence

**Requirements:**

-   Real-time updates (refresh every 15 minutes)
-   Separate list view per category
-   Click item to drill into details
-   Escalation workflow: Assign red flag to user for resolution
-   Alert notifications for new red flags

**Acceptance Criteria:**

-   Red flags auto-clear when issue resolved
-   Hierarchical visibility (users see red flags in their scope)

---

## 4. Phase 02 Features (Future)

### FR-PH2-001: PICOS Step Wizard Enhancements

**Description:** Advanced photo capture workflow with angle guidance and multi-photo requirements.

**Features:**

-   Sample angle overlay on camera preview
-   Photo quality validation (resolution, focus)
-   Before/after photo comparison
-   Photo annotation tools

### FR-PH2-002: Snap Stock Quick Action

**Description:** Quick inventory snapshot feature accessible from outlet list.

**Features:**

-   One-tap stock capture (photo + quantity)
-   AI-powered product recognition
-   Quick submit without full workflow
-   Integration with inventory management

---

## 5. Non-Functional Requirements

### NFR-001: Performance

-   Mobile app load time: < 2 seconds
-   Dashboard load time: < 3 seconds
-   Report generation time: < 5 seconds for standard reports
-   API response time: < 500ms (95th percentile)
-   Offline mode support: Core workflows functional without connectivity

### NFR-002: Security

-   Role-based access control (RBAC) enforced at API level
-   Data encryption in transit (HTTPS/TLS 1.3)
-   Sensitive data encrypted at rest
-   Session timeout: 30 minutes inactivity
-   Password policy: Min 8 characters, complexity requirements

### NFR-003: Scalability

-   Support 500+ concurrent mobile users
-   Database design supports 10,000+ outlets
-   Image storage: S3 or equivalent with CDN

### NFR-004: Availability

-   System uptime: 99.5% (excluding planned maintenance)
-   Planned maintenance windows: Sundays 02:00-04:00 IST

### NFR-005: Usability

-   Mobile app supports Android 8.0+ and iOS 13+
-   Responsive admin UI (desktop, tablet)
-   Multi-language support (English, Sinhala, Tamil - Phase 02)

### NFR-006: Data Retention

-   Visit logs: 3 years
-   Photos: 2 years
-   Service requests: 5 years
-   Audit records: 5 years

---

## 6. Database Schema Overview

### Core Tables

**users**

-   id, name, email, password, role, status, created_at, updated_at

**outlets**

-   id, name, address, latitude, longitude, outlet_type, territory_id, region_id, status, assigned_lsr_id, assigned_tm_id, assigned_sm_id, created_at, updated_at

**workflows**

-   id, name, description, category, icon, color, status, created_at, updated_at

**workflow_steps**

-   id, workflow_id, step_order, name, description, question_type, is_mandatory, allow_skip, allow_remarks, sample_photo_url, instructions, created_at, updated_at

**workflow_step_options**

-   id, step_id, option_text, option_value, triggers_service_request, service_request_category_id, service_request_template_id, created_at, updated_at

**workflow_step_conditions**

-   id, step_id, condition_step_id, condition_operator, condition_value, created_at, updated_at

**workflow_group_templates**

-   id, name, description, icon, color, status, created_at, updated_at

**workflow_group_template_workflows**

-   id, template_id, workflow_id, is_mandatory, execution_order, created_at, updated_at

**outlets** (updated)

-   id, name, address, latitude, longitude, outlet_type, territory_id, region_id, status, assigned_lsr_id, assigned_tm_id, assigned_sm_id, **workflow_group_template_id**, created_at, updated_at

**outlet_workflow_customizations**

-   id, outlet_id, workflow_id, is_enabled, created_at, updated_at

**outlet_workflow_steps**

-   id, outlet_workflow_id, step_id, is_enabled, custom_step_order, created_at, updated_at

**outlet_brands**

-   id, outlet_id, brand_id, is_must_have, created_at, updated_at

**outlet_equipment**

-   id, outlet_id, equipment_type, equipment_name, quantity, serial_numbers, created_at, updated_at

**posm_norms**

-   id, outlet_type, material_name, material_category, standard_quantity, version, effective_date, created_at, updated_at

**posm_audits**

-   id, outlet_id, assigned_tm_id, scheduled_date, due_date, completed_date, status, is_overdue, created_by, updated_at

**posm_audit_items**

-   id, audit_id, material_name, norm_quantity, actual_quantity, variance, remarks, created_at

**service_request_categories**

-   id, name, description, priority, sla_hours, assignment_hierarchy, status, created_at, updated_at

**service_request_templates**

-   id, category_id, name, description_template, custom_fields, created_at, updated_at

**service_requests**

-   id, title, description, category_id, outlet_id, workflow_id, step_id, created_by, assigned_to, status, priority, sla_due_date, resolved_date, closed_date, created_at, updated_at

**service_request_activities**

-   id, service_request_id, user_id, action_type, old_value, new_value, comment, created_at

**outlet_visits**

-   id, outlet_id, user_id, check_in_time, check_in_lat, check_in_lng, check_out_time, time_spent_minutes, visit_outcome, created_at

**workflow_executions**

-   id, visit_id, outlet_id, workflow_id, user_id, started_at, completed_at, status, created_at, updated_at

**workflow_execution_responses**

-   id, execution_id, step_id, response_value, response_text, remarks, is_skipped, skip_reason, photo_urls, created_at

---

## 7. API Endpoints Overview

### Mobile App APIs

The system provides RESTful APIs for the Flutter mobile application. The Laravel System Admin uses server-side rendering and does not require API endpoints.

**Authentication**

-   POST /api/mobile/auth/login - User login
-   POST /api/mobile/auth/logout - User logout
-   POST /api/mobile/auth/refresh-token - Refresh authentication token

**Outlets**

-   GET /api/mobile/outlets - Get outlet list with geotag sorting
-   GET /api/mobile/outlets/{id} - Get outlet details
-   GET /api/mobile/outlets/{id}/workflows - Get assigned workflows for outlet

**Check-in/Check-out**

-   POST /api/mobile/outlets/{id}/check-in - Check in to outlet
-   GET /api/mobile/visits/{id} - Get visit details
-   POST /api/mobile/visits/{id}/check-out - Check out from outlet
-   GET /api/mobile/visits/history - Get visit history

**Workflows**

-   GET /api/mobile/workflows/{id} - Get workflow details (steps, config)

**Workflow Execution**

-   POST /api/mobile/workflows/{id}/start - Start workflow execution
-   GET /api/mobile/executions/{id} - Get execution details and responses
-   POST /api/mobile/executions/{id}/step-response - Submit step response
-   POST /api/mobile/executions/{id}/complete - Complete workflow
-   GET /api/mobile/executions/{id}/next-step - Get next step (conditional logic)
-   GET /api/mobile/executions/history - Get execution history

**POSM Audits**

-   GET /api/mobile/audits/my-audits - Get assigned audits
-   GET /api/mobile/audits/{id} - Get audit details
-   POST /api/mobile/audits/{id}/execute - Submit audit data
-   POST /api/mobile/audits/{id}/complete - Complete audit

**Service Requests**

-   GET /api/mobile/service-requests - Get my service requests
-   GET /api/mobile/service-requests/{id} - Get request details
-   POST /api/mobile/service-requests/{id}/update-status - Update status

**File Upload**

-   POST /api/mobile/files/upload - Upload photos and attachments
-   GET /api/mobile/files/{id} - Get file URL

**Sync**

-   POST /api/mobile/sync - Sync offline data (bulk upload)
-   GET /api/mobile/sync/status - Get sync status

---

## 8. UI/UX Guidelines

### Mobile App

-   Material Design 3.0 (Android) / iOS Human Interface Guidelines
-   Bottom navigation: Home, Outlets, Audits, Service Requests, Profile
-   Floating action button: Quick check-in (when near outlet)
-   Offline indicator: Persistent banner when offline
-   Progress indicators: Linear progress for workflows, circular for loading
-   Pull-to-refresh: All list views

### System Admin

-   Responsive layout: Bootstrap 5 or Tailwind CSS
-   Sidebar navigation: Collapsible on mobile
-   Data tables: Sortable, filterable, paginated
-   Form validation: Real-time with clear error messages
-   Confirmation dialogs: For destructive actions

---

## 9. Integration Points

### Existing Systems

-   **Commercial Excellence Flutter App:** Integrate HoReCa module as new section
-   **Commercial Excellence Laravel Admin:** Add HoReCa management modules
-   **User Management:** Leverage existing user auth and role system

### Third-Party Services

-   **Geolocation:** Google Maps API or Mapbox
-   **File Storage:** AWS S3 or Google Cloud Storage
-   **Push Notifications:** Firebase Cloud Messaging
-   **SMS Notifications:** Twilio or local provider (optional)

---

## 10. Success Metrics

### Operational Metrics

-   Outlet visit frequency increased by 30%
-   POSM audit completion rate > 95%
-   Service request resolution time reduced by 40%
-   Must-have brand availability maintained at > 90%

### User Adoption Metrics

-   Mobile app daily active users > 80% of field staff
-   Avg workflows executed per user per day > 5
-   Admin user satisfaction score > 4.0/5.0

### System Performance Metrics

-   API uptime > 99.5%
-   Mobile app crash rate < 1%
-   Dashboard load time < 3 seconds
-   Report generation time < 5 seconds

---

## 11. Risks & Mitigation

| Risk                                    | Impact | Mitigation                                            |
| --------------------------------------- | ------ | ----------------------------------------------------- |
| Poor mobile connectivity in field       | High   | Robust offline mode, data sync on connectivity        |
| User resistance to new workflows        | Medium | Training program, phased rollout, feedback loops      |
| Data quality issues (photos, responses) | Medium | Validation rules, mandatory fields, sample references |
| Complex conditional logic errors        | Medium | Visual flow builder, validation on save, testing      |
| Service request overload                | Medium | Priority/SLA management, escalation automation        |

---

## 12. Project Timeline (Indicative)

**Phase 01 (16 weeks)**

-   Weeks 1-2: Requirements finalization, DB design
-   Weeks 3-6: System admin development (workflow, SR, outlet config)
-   Weeks 7-10: Mobile app development (outlets, check-in, workflows)
-   Weeks 11-12: POSM module & audit scheduling
-   Weeks 13-14: Dashboard & reporting
-   Weeks 15-16: Testing, UAT, deployment

**Phase 02 (8 weeks)**

-   PICOS enhancements, Snap Stock, advanced features

---

## 13. Appendix

### A. Glossary

-   **HoReCa:** Hotels, Restaurants, Cafés
-   **PICOS:** Picture of Success (step-based photo compliance workflow)
-   **POSM:** Point of Sale Materials
-   **LSR:** Local Sales Representative
-   **TM:** Territory Manager
-   **SM:** Sales Manager
-   **SLA:** Service Level Agreement

### B. References

-   [HoReCa Draft Notes](https://www.notion.so/HoReCa-Draft-Notes-2cb8ca0ec9b0803391a6c5eb1bc2ae2d?pvs=21)
-   Commercial Excellence existing system documentation
-   RFID project FRD (reference for structure)

---

**Document Status:** Draft

**Next Steps:** Review with stakeholders, finalize DB schema, API specifications, and wireframes