Docs: add PROJECT_REFERENCE, TESTING_CHECKLIST, update session instructions for Phase 4+5 completion
This commit is contained in:
@@ -6,15 +6,17 @@ Paste it (or reference it) at the start of each session to give Claude Code full
|
||||
---
|
||||
|
||||
## Project Summary
|
||||
We are building a local-first restaurant POS system. Full architecture and specs live in the `/pos-build-guide/` folder. Always read the relevant guide file before starting work on any component.
|
||||
We are building a local-first restaurant POS system. Full architecture and specs live in the `PLANS AND STRATEGIES/` folder. Always read the relevant guide file before starting work on any component. For a complete picture of the entire system read `PROJECT_REFERENCE.md`.
|
||||
|
||||
## Guide Files
|
||||
- `00_PROJECT_OVERVIEW.md` — Architecture, stack, build order
|
||||
- `01_LOCAL_BACKEND.md` — FastAPI backend (build this first)
|
||||
- `02_WAITER_PWA.md` — Waiter-facing PWA (build second)
|
||||
- `03_MANAGER_DASHBOARD.md` — Manager web app (build third)
|
||||
- `04_CLOUD_BACKEND.md` — Cloud licensing backend (build fourth)
|
||||
- `05_SYSADMIN_PANEL.md` — Sysadmin cloud panel (build last)
|
||||
- `01_LOCAL_BACKEND.md` — FastAPI backend spec
|
||||
- `02_WAITER_PWA.md` — Waiter-facing PWA spec
|
||||
- `03_MANAGER_DASHBOARD.md` — Manager web app spec
|
||||
- `04_CLOUD_BACKEND.md` — Cloud licensing backend spec
|
||||
- `05_SYSADMIN_PANEL.md` — Sysadmin cloud panel spec
|
||||
- `TESTING_CHECKLIST.md` — End-to-end testing guide (step-by-step)
|
||||
- `PROJECT_REFERENCE.md` — Master reference: full system description, wiring, all env vars
|
||||
|
||||
## Git Workflow
|
||||
- The project uses git. **Commit after every meaningful milestone** (e.g. after scaffolding a phase, after a feature is working, after a bug fix).
|
||||
@@ -32,13 +34,17 @@ We are building a local-first restaurant POS system. Full architecture and specs
|
||||
7. **The `unit_price` on `order_items` is a snapshot** — it must be copied from the product price at the time of ordering, not referenced dynamically.
|
||||
8. **Printer failures must never block order saves.** Log and continue.
|
||||
|
||||
---
|
||||
|
||||
## Current Build Phase
|
||||
> Update this line as you progress:
|
||||
> Phase 1: Local Backend — [x] Complete. Smoke tested: health, auth, products, tables, orders, printer routing all working.
|
||||
> Phase 2: Waiter PWA — [x] Complete. Smoke tested end-to-end: login, table list, open order, add items, select/pay with confirmation, close order. See "Phase 2 Known Issues & Fixes" below.
|
||||
> Phase 3: Manager Dashboard — [x] Complete. Scaffolded and smoke tested. Known issues remain (see below) — not blockers for Phase 4.
|
||||
> Phase 4: Cloud Backend — [ ] Not Started
|
||||
> Phase 5: Sysadmin Panel — [ ] Not Started
|
||||
> All 5 phases are built. Now in testing / polish.
|
||||
> Phase 1: Local Backend — [x] Complete. Smoke tested.
|
||||
> Phase 2: Waiter PWA — [x] Complete. Smoke tested end-to-end.
|
||||
> Phase 3: Manager Dashboard — [x] Complete. Scaffolded and smoke tested. Known rough edges remain.
|
||||
> Phase 4: Cloud Backend — [x] Complete. Built, not yet smoke tested end-to-end with a real site.
|
||||
> Phase 5: Sysadmin Panel — [x] Complete. Built, not yet smoke tested.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 Known Issues & Fixes Applied
|
||||
- `OrderItemOut` schema now includes `product { id, name }` via `ProductNameOut` — required for item names to show correctly in the PWA.
|
||||
@@ -68,38 +74,76 @@ We are building a local-first restaurant POS system. Full architecture and specs
|
||||
- Auto-migration on startup adds new columns to existing SQLite DB without dropping data.
|
||||
|
||||
## Phase 3 Known Remaining Issues (to revisit)
|
||||
- Some PWA/manager interactions still have rough edges — to be addressed in a dedicated polish pass before or after Phase 5.
|
||||
- Some PWA/manager interactions still have rough edges — to be addressed in a dedicated polish pass.
|
||||
- Product image upload requires the product to already exist (no upload on creation, only on edit).
|
||||
|
||||
## Phase 2 Dev Data (seeded manually, not in seed.py)
|
||||
- Tables 1–6 exist (table 1 was from Phase 1 smoke test)
|
||||
- Category "food" (id=1) exists from Phase 1 smoke test — contains product "arakas"
|
||||
## Phase 4 — What Was Built
|
||||
- Cloud Backend: FastAPI, SQLite (dev) / PostgreSQL (prod), JWT auth. Port 8001.
|
||||
- Endpoints: `POST /api/auth/login`, `GET|POST|PUT|DELETE /api/sites/:id`, lock/unlock actions, `POST /api/heartbeat/`.
|
||||
- Admin account seeded from env vars on first startup (`ADMIN_USERNAME`, `ADMIN_PASSWORD`).
|
||||
- Heartbeat: local backend posts every 6 hours with `X-Site-ID` + `X-Site-Key` headers; cloud returns license status.
|
||||
- `cloud_sync.py` in local backend runs as background asyncio task, persists state to `license_state.json`.
|
||||
- Grace period: if cloud unreachable, local backend continues operating for `LICENSE_GRACE_HOURS` (default 24h).
|
||||
- Docker Compose service: `cloud_backend`, depends on nothing, data volume at `./data/cloud`.
|
||||
|
||||
## Phase 5 — What Was Built
|
||||
- Sysadmin Panel: React+Vite, TailwindCSS, dark theme, cyan accent. Port 5175.
|
||||
- Points to cloud backend (`VITE_CLOUD_URL`), NOT the local backend.
|
||||
- Pages: LoginPage (username+password), SitesPage (card grid, 30s polling, summary counts), SiteDetailPage (lock/unlock/extend license/delete with confirmation modals), RegisterSitePage (form + one-time secret key display with copy button).
|
||||
- Token stored as `sysadmin_token` in localStorage (separate key from manager dashboard).
|
||||
- Docker Compose service: `sysadmin_panel`, depends on `cloud_backend`.
|
||||
|
||||
## Dev Data (seeded / created during development)
|
||||
- Tables 1–6 exist in local DB
|
||||
- Category "food" (id=1) + arakas product from Phase 1 smoke test
|
||||
- Categories: Ποτά, Σαλάτες, Κυρίως — 3 products each
|
||||
- Printer zones can now be assigned via ProductsPage in the Manager Dashboard.
|
||||
- Printer zones assignable via ProductsPage in Manager Dashboard
|
||||
- Cloud DB: admin `sysadmin` / `changeme` seeded on first startup
|
||||
|
||||
## Environment Variables
|
||||
---
|
||||
|
||||
### Local Backend (.env)
|
||||
## Environment Variables (current actual values)
|
||||
|
||||
### Local Backend (`local_backend/.env`)
|
||||
```
|
||||
SITE_ID=
|
||||
CLOUD_URL=https://your-vps.com
|
||||
SECRET_KEY=generate-a-long-random-string
|
||||
SITE_ID=<from sysadmin panel site registration>
|
||||
SITE_KEY=<secret key shown once at registration>
|
||||
CLOUD_URL=http://cloud_backend:8001
|
||||
SECRET_KEY=<long random string>
|
||||
LICENSE_GRACE_HOURS=24
|
||||
DATABASE_URL=sqlite:///./pos.db
|
||||
```
|
||||
|
||||
### Waiter PWA (.env)
|
||||
### Waiter PWA (`waiter_pwa/.env`)
|
||||
```
|
||||
VITE_API_URL=http://192.168.1.10:8000
|
||||
VITE_API_URL=http://<local-machine-ip>:8000
|
||||
```
|
||||
|
||||
### Manager Dashboard (.env)
|
||||
### Manager Dashboard (`manager_dashboard/.env`)
|
||||
```
|
||||
VITE_API_URL=http://192.168.1.10:8000
|
||||
VITE_API_URL=http://<local-machine-ip>:8000
|
||||
```
|
||||
|
||||
### Cloud Backend (.env)
|
||||
### Cloud Backend (`cloud_backend/.env`)
|
||||
```
|
||||
SECRET_KEY=different-long-random-string
|
||||
DATABASE_URL=postgresql://... (or sqlite for dev)
|
||||
SECRET_KEY=<long random string — different from local>
|
||||
DATABASE_URL=sqlite:////app/data/cloud.db
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=60
|
||||
ADMIN_USERNAME=sysadmin
|
||||
ADMIN_PASSWORD=<your password>
|
||||
```
|
||||
|
||||
### Sysadmin Panel (`sysadmin_panel/.env`)
|
||||
```
|
||||
VITE_CLOUD_URL=http://localhost:8001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ports
|
||||
| Service | Port |
|
||||
|---|---|
|
||||
| Local Backend | 8000 |
|
||||
| Cloud Backend | 8001 |
|
||||
| Waiter PWA | 5173 |
|
||||
| Manager Dashboard | 5174 |
|
||||
| Sysadmin Panel | 5175 |
|
||||
|
||||
Reference in New Issue
Block a user