308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
# Guide 01 — Local Backend (FastAPI)
|
|
|
|
## Overview
|
|
The local backend is the heart of the entire system. It runs on a Linux machine on the restaurant's LAN, operates fully without internet, and handles all business logic: orders, tables, waiters, products, and printer routing.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
local_backend/
|
|
├── main.py # FastAPI app entry point
|
|
├── config.py # Settings (printer IPs, secret keys, cloud URL, etc.)
|
|
├── database.py # SQLAlchemy engine + session
|
|
├── models/
|
|
│ ├── user.py
|
|
│ ├── table.py
|
|
│ ├── product.py
|
|
│ ├── order.py
|
|
│ └── printer.py
|
|
├── schemas/ # Pydantic request/response models (mirror models/)
|
|
├── routers/
|
|
│ ├── auth.py
|
|
│ ├── tables.py
|
|
│ ├── products.py
|
|
│ ├── orders.py
|
|
│ ├── waiters.py
|
|
│ ├── reports.py
|
|
│ └── system.py
|
|
├── services/
|
|
│ ├── printer_service.py # Routing logic + escpos calls
|
|
│ └── cloud_sync.py # Periodic check-in with cloud backend
|
|
├── middleware/
|
|
│ └── license_check.py # Validates local license token, blocks if expired
|
|
└── requirements.txt
|
|
```
|
|
|
|
---
|
|
|
|
## Database Schema
|
|
|
|
### `users` table
|
|
```
|
|
id INTEGER PK
|
|
username TEXT UNIQUE NOT NULL
|
|
pin_hash TEXT NOT NULL # bcrypt hash of PIN
|
|
role TEXT NOT NULL # 'waiter' | 'manager' | 'sysadmin'
|
|
is_active BOOLEAN DEFAULT TRUE
|
|
created_at DATETIME
|
|
```
|
|
|
|
### `assistant_assignments` table
|
|
```
|
|
id INTEGER PK
|
|
primary_waiter_id INTEGER FK(users.id)
|
|
assistant_waiter_id INTEGER FK(users.id)
|
|
assigned_at DATETIME
|
|
# If waiter B is assistant to waiter A, waiter B can manage all of A's tables
|
|
```
|
|
|
|
### `tables` table
|
|
```
|
|
id INTEGER PK
|
|
number INTEGER UNIQUE NOT NULL # Table number shown to users
|
|
label TEXT # Optional custom label
|
|
is_active BOOLEAN DEFAULT TRUE # Manager can deactivate
|
|
floor_x FLOAT # For future floorplan feature
|
|
floor_y FLOAT # For future floorplan feature
|
|
```
|
|
|
|
### `categories` table
|
|
```
|
|
id INTEGER PK
|
|
name TEXT NOT NULL
|
|
color TEXT # Hex color for UI display
|
|
sort_order INTEGER DEFAULT 0
|
|
```
|
|
|
|
### `products` table
|
|
```
|
|
id INTEGER PK
|
|
name TEXT NOT NULL
|
|
category_id INTEGER FK(categories.id)
|
|
base_price FLOAT NOT NULL
|
|
is_available BOOLEAN DEFAULT TRUE
|
|
printer_zone_id INTEGER FK(printers.id) # Which printer zone gets this product
|
|
```
|
|
|
|
### `product_options` table
|
|
```
|
|
id INTEGER PK
|
|
product_id INTEGER FK(products.id)
|
|
name TEXT NOT NULL # e.g. "Size", "Temperature"
|
|
extra_cost FLOAT DEFAULT 0.0
|
|
```
|
|
|
|
### `product_ingredients` table
|
|
```
|
|
id INTEGER PK
|
|
product_id INTEGER FK(products.id)
|
|
name TEXT NOT NULL # e.g. "Onions", "Ice"
|
|
# Can be removed by waiter when ordering
|
|
```
|
|
|
|
### `printers` table
|
|
```
|
|
id INTEGER PK
|
|
name TEXT NOT NULL # e.g. "Kitchen", "Bar"
|
|
ip_address TEXT NOT NULL
|
|
port INTEGER DEFAULT 9100
|
|
is_active BOOLEAN DEFAULT TRUE
|
|
```
|
|
|
|
### `orders` table
|
|
```
|
|
id INTEGER PK
|
|
table_id INTEGER FK(tables.id)
|
|
opened_by INTEGER FK(users.id) # Waiter who opened it
|
|
opened_at DATETIME
|
|
status TEXT # 'open' | 'partially_paid' | 'paid' | 'closed' | 'cancelled'
|
|
closed_at DATETIME NULL
|
|
closed_by INTEGER FK(users.id) NULL
|
|
notes TEXT NULL
|
|
```
|
|
|
|
### `order_waiters` table
|
|
```
|
|
id INTEGER PK
|
|
order_id INTEGER FK(orders.id)
|
|
waiter_id INTEGER FK(users.id)
|
|
assigned_at DATETIME
|
|
# Supports multiple waiters per table (manager can add/remove)
|
|
```
|
|
|
|
### `order_items` table
|
|
```
|
|
id INTEGER PK
|
|
order_id INTEGER FK(orders.id)
|
|
product_id INTEGER FK(products.id)
|
|
added_by INTEGER FK(users.id)
|
|
quantity INTEGER NOT NULL
|
|
unit_price FLOAT NOT NULL # Price AT TIME OF ORDER (snapshot)
|
|
selected_options TEXT NULL # JSON array of option ids chosen
|
|
removed_ingredients TEXT NULL # JSON array of ingredient ids removed
|
|
notes TEXT NULL # Freetext note per item
|
|
status TEXT DEFAULT 'active' # 'active' | 'paid' | 'cancelled'
|
|
added_at DATETIME
|
|
printed BOOLEAN DEFAULT FALSE
|
|
```
|
|
|
|
### `print_log` table
|
|
```
|
|
id INTEGER PK
|
|
order_id INTEGER FK(orders.id)
|
|
printer_id INTEGER FK(printers.id)
|
|
printed_at DATETIME
|
|
item_ids TEXT # JSON array of order_item ids printed
|
|
success BOOLEAN
|
|
error_message TEXT NULL
|
|
```
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
### Auth — `/api/auth`
|
|
```
|
|
POST /login
|
|
Body: { username, pin }
|
|
Returns: { access_token, user: { id, username, role } }
|
|
Note: JWT token, short expiry (8h), auto-refresh on activity
|
|
|
|
POST /refresh
|
|
Header: Bearer token
|
|
Returns: new access_token
|
|
|
|
POST /logout
|
|
Invalidates token server-side (token blacklist in memory or DB)
|
|
```
|
|
|
|
### Tables — `/api/tables`
|
|
```
|
|
GET / # All tables with current status (manager/waiter)
|
|
POST / # Create table (manager only)
|
|
PUT /:id # Edit table number/label (manager only)
|
|
DELETE /:id # Deactivate table (manager only)
|
|
GET /:id/status # Single table status + active order summary
|
|
PUT /:id/floorplan # Update x/y position (manager only, future feature)
|
|
```
|
|
|
|
### Products — `/api/products`
|
|
```
|
|
GET / # All products with options + ingredients (all roles)
|
|
POST / # Create product (manager only)
|
|
PUT /:id # Edit product (manager only)
|
|
DELETE /:id # Deactivate product (manager only)
|
|
|
|
GET /categories # All categories
|
|
POST /categories # Create category (manager only)
|
|
PUT /categories/:id # Edit category (manager only)
|
|
DELETE /categories/:id # Delete category (manager only)
|
|
```
|
|
|
|
### Orders — `/api/orders`
|
|
```
|
|
GET / # All orders, filterable by status/date/waiter (manager only)
|
|
GET /my # Current waiter's active orders
|
|
GET /:id # Full order detail with items
|
|
POST / # Open new order { table_id }
|
|
POST /:id/items # Add batch of items to order
|
|
Body: { items: [{ product_id, quantity, selected_options, removed_ingredients, notes }] }
|
|
Triggers: printer routing for new items
|
|
PUT /:id/items/:item_id # (manager only) edit item
|
|
DELETE /:id/items/:item_id # (manager only) cancel/remove item
|
|
POST /:id/pay # Mark items as paid
|
|
Body: { item_ids: [...] } # Supports partial payment
|
|
POST /:id/close # Close order (waiter who owns it, or manager)
|
|
DELETE /:id # Cancel entire order (manager only)
|
|
PUT /:id/assign-waiter # Add waiter to order (manager only)
|
|
DELETE /:id/waiters/:waiter_id # Remove waiter from order (manager only)
|
|
```
|
|
|
|
### Waiters — `/api/waiters`
|
|
```
|
|
GET / # All waiter accounts (manager only)
|
|
POST / # Create waiter account (manager only)
|
|
PUT /:id # Edit waiter (manager only)
|
|
PUT /:id/reset-pin # Reset PIN (manager only)
|
|
PUT /:id/block # Block/unblock waiter (manager only)
|
|
DELETE /:id # Delete waiter (manager only)
|
|
POST /:id/assign-assistant # Assign assistant waiter (manager only)
|
|
DELETE /:id/assistant # Remove assistant assignment (manager only)
|
|
```
|
|
|
|
### Reports — `/api/reports`
|
|
```
|
|
GET /shift # End-of-shift summary
|
|
Query: ?date=YYYY-MM-DD&waiter_id=X
|
|
Returns: per-waiter breakdown of orders + totals
|
|
|
|
GET /orders/history # Paginated order history with filters
|
|
Query: ?from=&to=&waiter_id=&status=
|
|
|
|
GET /tables/summary # Current snapshot of all tables
|
|
```
|
|
|
|
### System — `/api/system`
|
|
```
|
|
GET /health # Liveness check (no auth required, used by cloud)
|
|
GET /status # System info: version, uptime, printer statuses
|
|
POST /printers/test # Send test print to a printer (manager/sysadmin)
|
|
PUT /printers/:id # Edit printer config (sysadmin only)
|
|
POST /lock # Lock the system (cloud backend calls this)
|
|
POST /unlock # Unlock (requires valid cloud token)
|
|
```
|
|
|
|
---
|
|
|
|
## Business Logic Notes
|
|
|
|
### Printer Routing (printer_service.py)
|
|
When items are submitted via `POST /orders/:id/items`:
|
|
1. Group items by their `product.printer_zone_id`
|
|
2. For each group, format an ESC/POS receipt: table number, waiter name, timestamp, list of items with options/notes
|
|
3. Send to the corresponding printer IP
|
|
4. Log result in `print_log`
|
|
5. Mark items as `printed = TRUE`
|
|
6. If a printer fails, log the error but do NOT fail the order submission — the order is saved regardless
|
|
|
|
### Authorization Rules
|
|
- Waiter can only access orders where their `user.id` is in `order_waiters` OR they are assigned as assistant to the order's primary waiter
|
|
- Manager can access everything on the local system
|
|
- Token middleware should attach user role to every request
|
|
|
|
### License Check Middleware
|
|
- On every request, check in-memory license state
|
|
- License state is refreshed by `cloud_sync.py` background task every 6 hours
|
|
- If cloud is unreachable, use last known state + grace period (24h)
|
|
- If license is expired/locked, return `HTTP 402` or `HTTP 423` on all endpoints except `/api/system/health`
|
|
|
|
### cloud_sync.py
|
|
- Runs as a FastAPI background task (lifespan event)
|
|
- Every 6 hours: POST to cloud backend with site ID + heartbeat
|
|
- Cloud responds with: `{ licensed: bool, locked: bool, expires_at: datetime }`
|
|
- Store response locally (SQLite or a flat JSON file)
|
|
|
|
---
|
|
|
|
## Environment / Config (config.py)
|
|
```python
|
|
SITE_ID = "..." # Unique ID registered on cloud
|
|
CLOUD_URL = "https://..."
|
|
SECRET_KEY = "..." # JWT signing key
|
|
LICENSE_GRACE_HOURS = 24
|
|
DATABASE_URL = "sqlite:///./pos.db"
|
|
```
|
|
|
|
---
|
|
|
|
## Running Locally
|
|
```bash
|
|
pip install fastapi uvicorn sqlalchemy python-escpos bcrypt pyjwt
|
|
uvicorn main:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
The `--host 0.0.0.0` is critical — this makes it accessible from other devices on the LAN.
|
|
Set a static IP on the host machine at the router level (DHCP reservation).
|