# Point of Sale (POS) Counter Operations Manual

This document provides a comprehensive operational, technical, and architectural manual for the in-store Point of Sale (POS) terminal system designed for counter cashiers, floor supervisors, and store managers at **Eniceberny Bakery and Culinary Hub**.

---

## 🧭 1. Operational Philosophy & Architecture

Rather than operating as a disconnected offline register, Eniceberny's POS terminal is fully integrated into our unified multi-channel commerce platform:

```mermaid
graph TD
    A[Cashier Terminal /admin/pos] -->|Product Selection & Portions| B(Reactive Alpine.js Ticket)
    B -->|Tender Cash / MoMo / Card| C[POST /admin/pos/checkout]
    C -->|Database Transaction Lock| D[(Unified Database)]
    D --> E[Create Order source: pos]
    D --> F[Create OrderItems snapshot]
    D --> G[Record PaymentTransaction]
    D --> H[Decrement InventoryMovement]
    C -->|Return Success JSON| I[Launch ESC/POS Thermal Receipt Window]
```

### Core Tenets:
1. **Real-time Atomic Transactions**: Walk-in sales instantly update central catalog stock, financial ledgers, and executive dashboard metrics without batch delays.
2. **Sub-15-Second Turnaround**: Ergonomically structured for touchscreens, barcode scanners, and keyboard shortcuts, enabling cashiers to ring up patrons during morning and lunchtime peak queues in seconds.
3. **Multi-Tender Ghanaian Currency Support**: Built-in support for Physical Cash (with automated change calculation), MTN Mobile Money, Telecel Cash, and Bank Cards.

---

## 🖥️ 2. Terminal Interface Zones & Controls (`/admin/pos`)

The POS interface is split into two synchronized zones:

```
┌───────────────────────────────────────────────┬──────────────────────────────────────┐
│  LEFT ZONE: Menu Catalog & Explorer           │  RIGHT ZONE: Active Register Ticket  │
│  [ Category Tabs: Pastries | Jollof | Cakes ] │  Order Type: [ Takeaway ] [ Dine-in ]│
│  [ Search: 'meat pie' _____________________ ] │  ----------------------------------- │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐       │  2x Meat Pie (Single)    GH₵ 36.00   │
│  │ Meat Pie │ │ Croissant│ │ Sobolo   │       │  1x Jollof Platter       GH₵ 45.00   │
│  │ GH₵ 18   │ │ GH₵ 15   │ │ GH₵ 10   │       │  ----------------------------------- │
│  └──────────┘ └──────────┘ └──────────┘       │  Subtotal:               GH₵ 81.00   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐       │  Discount:               GH₵  0.00   │
│  │ RedVelvet│ │ Jollof   │ │ Fufu Soup│       │  TOTAL DUE:              GH₵ 81.00   │
│  │ GH₵ 280  │ │ GH₵ 45   │ │ GH₵ 50   │       │  Tender: [Exact] [50] [100] [200]    │
│  └──────────┘ └──────────┘ └──────────┘       │  Change Due:             GH₵ 19.00   │
│                                               │  [ COMPLETE SALE & PRINT RECEIPT ]   │
└───────────────────────────────────────────────┴──────────────────────────────────────┘
```

### 2.1 Left Zone: Catalog Explorer
- **Category Filter Pills**: Fast one-tap filtering between:
  - *Pastries & Bakehouse*
  - *Continental Dishes*
  - *Authentic Ghanaian Cuisine*
  - *Celebration Cakes*
  - *Fresh Drinks & Juices*
  - *All Delicacies*
- **Instant Search Input**: Real-time keystroke filtering by item name or SKU. Typing `"jol"` immediately filters the grid to Jollof options.
- **Out of Stock Prevention**: Items with zero inventory display a distinct "Sold Out" overlay and are disabled to prevent accidental overselling.

### 2.2 Right Zone: Active Register Ticket
- **Order Packaging Toggle**:
  - **Takeaway Button (Default)**: Flags order packaging for disposable leak-proof containers, paper cutlery, and carrier bags (`order_type = 'takeaway'`).
  - **Dine-In Button**: Flags ticket for table service, ceramic ware, and tray presentation (`order_type = 'dine_in'`).
- **Line Items List**:
  - Item name, portion variant badge, unit price, and line subtotal.
  - **Increment Button (`+`)**: Adds one unit to item quantity.
  - **Decrement Button (`-`)**: Decreases item quantity. Reaching zero removes the line.
  - **Trash Button**: Instantly deletes the line item from the ticket.
- **Discount Override Input**: Allows authorized cashiers to enter a fixed promotional discount (`GH₵`) deducted immediately from the subtotal.
- **Dynamic Totals Display**: Computes Subtotal, Discount, and Total Due using monospace tabular numerals (`tabular-nums`) to prevent visual jitter.

---

## 💵 3. Tender Calculations & Quick Cash Keys

### 3.1 Quick Cash Tender Buttons
To eliminate manual arithmetic errors during high-speed queues, the terminal provides one-tap tender shortcuts:

| Tender Key | Cashier Action | Automated System Calculation |
| :--- | :--- | :--- |
| **Exact** | Patron provides exact total | Sets tender equal to total due; Change Due displays `GH₵ 0.00`. |
| **GH₵ 20** | Patron hands a 20 Cedis note | Computes change: `GH₵ 20.00 - Total`. |
| **GH₵ 50** | Patron hands a 50 Cedis note | Computes change: `GH₵ 50.00 - Total`. |
| **GH₵ 100** | Patron hands a 100 Cedis note | Computes change: `GH₵ 100.00 - Total`. |
| **GH₵ 200** | Patron hands a 200 Cedis note | Computes change: `GH₵ 200.00 - Total`. |
| **Custom Tender** | Arbitrary cash sum entered | Live reactive calculation of customer change. |

> [!TIP]
> **High-Contrast Change Alert**: Change due is calculated reactively and rendered in bold high-contrast emerald text (`text-emerald-700 font-bold text-xl`). If the amount tendered is less than the total due, a red warning badge indicates the remaining balance.

### 3.2 Mobile Money (MoMo) Mode
1. Click the **"📱 Mobile Money"** tender button.
2. Enter the patron's 10-digit mobile number or have them scan the counter QR code / send funds to our official merchant SIM number.
3. Confirm the incoming SMS notification on the store merchant phone.
4. Click **"Complete Sale & Print Receipt"**.

### 3.3 Bank Card (POS Terminal) Mode
1. Click the **"💳 Card"** tender button.
2. Tap or insert the patron's Visa or Mastercard on the countertop card terminal.
3. Verify the "Transaction Approved" slip from the card terminal.
4. Click **"Complete Sale & Print Receipt"**.

---

## ⚡ 4. Transaction Processing & Database Locking

When the cashier clicks **"Complete Sale & Print Receipt"**, the following atomic workflow executes:

1. **Client-Side Validation**:
   - Ticket must have at least one line item.
   - Tendered amount must be $\ge$ total due (for cash transactions).
2. **Payload Dispatch**: An asynchronous POST request is dispatched to `/admin/pos/checkout`:
   ```json
   {
     "customer_name": "Walk-in Guest",
     "customer_phone": "0532342126",
     "payment_method": "cash",
     "order_type": "takeaway",
     "discount_amount": 0.00,
     "items": [
       { "id": 4, "quantity": 2, "price": 18.00, "name": "Golden Flaky Beef Meat Pie" },
       { "id": 7, "quantity": 1, "price": 12.00, "name": "Buttery Croissant" }
     ]
   }
   ```
3. **Database Transaction (`DB::transaction`)**:
   - `Order` record created with `status: 'completed'`, `payment_status: 'paid'`, `source: 'pos'`.
   - `OrderItem` records created snapshotting exact prices and names.
   - `PaymentTransaction` record created with status `'success'`.
   - `InventoryMovement` entries recorded with movement type `pos_sale`.
4. **Receipt Window Launch**: The server returns HTTP 200 with the receipt URL, and the browser automatically launches the thermal receipt print dialog:
   ```json
   {
     "success": true,
     "order_id": 142,
     "order_number": "EB-20260927-9912",
     "receipt_url": "/orders/EB-20260927-9912/receipt"
   }
   ```

---

## 🧾 5. Thermal Receipt Format (`receipt.blade.php`)

The thermal receipt is engineered for standard 80mm and 58mm thermal rolls:

- **Brand Header**: Official Eniceberny crest and full business title.
- **Location & Contacts**: Physical bakery address, hotline, and website.
- **Ticket Identifiers**: Unique Order Number (`EB-YYYYMMDD-XXXX`), date/time, and cashier name.
- **Service Mode**: Prominent bold badge: `*** TAKEAWAY ***` or `*** DINE-IN ***`.
- **Itemized Table**: Quantity, item name, and price aligned right.
- **Financial Breakdown**: Subtotal, discount (if applied), tax/levies, and `TOTAL DUE`.
- **Tender Summary**: Amount tendered and change given.
- **Offline QR Code**: High-resolution QR code encoding the online invoice verification link.
- **Footer**: Dynamic receipt note and thank-you message.

---

## 🔄 6. Daily Shift Balancing & Handover

At the conclusion of each shift:
1. Print the **Shift Summary Report** by visiting `/admin/reports?source=pos`.
2. Count physical cash in drawer.
3. Compare against the system `total_cash` metric.
4. Follow the reconciliation protocol in the [Accounts and Financial Ledgers Guide](accounts.md).
5. For technical troubleshooting (paper jams, cash drawer kick failures), refer to the [System Troubleshooting Runbook](troubleshooting.md).

---

*For staff onboarding protocols, refer to the [Staff Training SOP](staff-training.md).*