Part AExisting App
A1. Entry and navigation
▸ Open stock_control.php
- Not signed in → Login (username + password)
- wrong details → "Invalid username or password" → stay on Login
- correct → Dashboard (new home; marks "seen today")
- Signed in → last requested page
Navigation is the hamburger menu (top right):
| Section | Item | Who |
|---|---|---|
| Home | Dashboard | All |
| Stock | Stock, Products | All |
| Production Planner | Production Planning, Tartlet Orders | All (edit = admin) |
| Admin | Users | Admin |
| Sync | Sync from XLSM | Admin |
| Export | Stock levels .xlsx, Transactions .xlsx | All |
| — | Logout | All |
A2. Stock (home) — record stock in / out
▸ Stock page
- Type in search box (code or name) → dropdown of matches (live, 160 ms debounce)
- Pick product → Product card: live units, boxes + partial, pack size, last 25 movements
- Stock IN or Stock OUT → choose Units or Boxes → qty + note → Submit
- OUT more than live stock → error "Cannot remove N units — only M in stock"
- success → green (IN) / red (OUT) flash → card refreshes
Empty state: greeting card and search box only.
A3. Products
▸ Products → table (Code · Name · Category · Subcategory · Pack · Base · Live)
- Filter: search text, Category, Subcategory (subcategory list narrows by category) → "Clear all ×"
- Admin: Add Product (modal) / Edit (modal) / Delete (confirm)
- Admin: click Live stock cell → type target → Enter → adjustment transaction created
A4. Sync from XLSM (admin)
▸ Hamburger → Sync from XLSM (or Products toolbar button)
- Modal: drag & drop or browse .xlsm / .xlsx → Upload & Sync
- Server parses: "main data" (catalog) + QUICHE / PIES / OTHER / SWEETS / GEMA ORDERS (stock)
- nothing found → error flash explaining expected sheets
- found → Products page with Preview panel (code, current, new, difference)
- Apply → catalog upserted + adjustment transactions → "Applied N, skipped M"
- Discard → preview cleared, nothing changed
A5. Production Planning (airline orders)
▸ Production Planning → matrix: product rows grouped by category × (destination, date) columns
- Each row shows: CTN qty · Live stock · Boxes · order cells · Total · Stock after · To produce
- Admin edits a cell → autosave → totals and "stock after" recalc; red when negative
- Cell ▼ → pick colour (yellow = ordered/red text, green = done/black text)
- ＋ Add Column (dest + date) / ＋ Add Week (copies last week +7 days) / edit header / delete column
- 💾 Save Plan (name + notes) → snapshot; Saved plans → Load / Delete
- 🖨 Print → landscape print with colours kept
A6. Tartlet Orders
▸ Tartlet Orders → "as at" date (click → date picker → Apply)
- Order rows (client, DATE DUE OUT, type DELIVERY/PICK UP, notes) × 16 tartlet sizes
- DATE DUE OUT header click → sort ↑ / ↓
- Admin: add order row, edit cells (autosave), ▼ colour per cell, delete row
- Footer: TOTAL ORDERED · TOTAL IN STOCK · NEED TO MAKE ( (n) red = shortfall, n green = surplus )
- Save / Load snapshots, Print
A7. Users (admin) and password
▸ Users → list → Add (username, password, role) / Edit / Delete (cannot delete last admin)
- Change Password → current + new → saved
A8. Export
Hamburger → Export → Stock levels or Transactions → .xlsx download.
Part BOrders & Dispatch (new)
B1. Primary journey (both lanes)
▸ Order received (email / PO / phone)
- Orders › NewCreate order (customer, PO, dates, lines)
- same screen(Non-airline) Availability check & delivery date
- Record Xero invoice no. (SkyCrest or Annie Makes Cakes) [Order › Invoice]
- Order › PrintPrint kitchen ticket → bring to kitchen
- Order › ConfirmSend confirmation to customer
- PackingPacking team checks stock
- enough → Allocate (reserve stock)
- not enough → Short → Alex (planner / missing items) → make product → Stock IN → Allocate
- Dispatch ScheduleDay before dispatch: delivery schedule prepared
- Dispatch ScheduleBook pick-up / Roadmaster / driver
- DispatchDispatch → stock removed automatically
B2. Airline lane (SkyCrest)
▸ Email orders from airlines (all by PO)
- New order: customer = airline, port (SYD/MEL/BNE/ADL), dispatch date, lines
- Invoice in SkyCrest Xero → record invoice no.
- Lines appear on Production Planning automatically (column = port + date)
- Print order → kitchen → confirmation email
- Packing checks stock
- enough → allocate
- not enough → Alex checks Production Planner → make product
- Day before dispatch
- Interstate (MEL, BNE …): filter by date & port → book pick-up → book Roadmaster
- Intrastate (SYD): filter by date → delivery schedule → book driver
- Dispatch → remove from stock
B3. Non-airline lane (Annie Makes Cakes)
▸ Orders by email (PDF PO, HTML PO, email text), bespoke enquiry, or phone
- New order: customer, source, lines (bespoke = free-text line)
- Check stock → availability per line + suggested delivery date → user confirms date
- Invoice in Annie Makes Cakes Xero → record invoice no.
- Print order → kitchen → confirmation email
- Packing checks stock
- enough → allocate
- not enough → "Inform Alex" → missing-items list → make product
- Day before dispatch: filter by date (all customers) → book pick-up / delivery schedule
- Dispatch → remove from stock
B4. Screen details
Orders list (?page=orders)
- Purpose: see every order and its status.
- Filters: status, lane (Airline / Non-airline), dispatch date range, customer, search (order no. / PO).
- Columns: Order no. · Customer · Lane · PO · Dispatch date · Port · Status chip · Invoice no. · Allocation % · Actions.
- Primary action: ＋ New order. Secondary: Export.
- Empty state: "No orders yet — create your first order" + button.
New / Edit order
- Inputs: customer (search, ＋ new customer inline), PO no., source, order date, dispatch date, delivery method, port (prefilled), notes, attachment.
- Lines: product search → qty (units / cartons toggle) → live stock, allocated, available shown inline.
- Non-airline: "Check availability" → green/amber/red per line, suggested date.
- Validation: customer and dispatch date required; ≥ 1 line; qty > 0; dispatch date not in the past (warning, not block); duplicate PO warning.
- Save → status NEW → redirect to Order detail.
Order detail
- Header: status chip, lane, entity (which Xero), customer, dates.
- Timeline of events (created, invoiced, printed, confirmed, allocated, short, booked, dispatched) with user and time.
- Actions by status: Record invoice · Print ticket · Copy confirmation email · Allocate · Mark short / Inform Alex · Cancel.
- Errors: allocation fails because stock changed → message + refreshed availability.
Packing (?page=packing)
- Purpose: tablet-friendly list for the packing team.
- Default filter: dispatch date = today and tomorrow.
- Each order card: lines with ✅ available / ⚠ short by N. Big Allocate and Mark short buttons.
- Empty state: "Nothing to pack for the selected dates".
Dispatch schedule (?page=dispatch)
- Purpose: the day-before schedule.
- Date picker (defaults to tomorrow). Three groups: Airline · Interstate (sub-grouped by port), Airline · Sydney, Non-airline.
- Per group: booking type (Roadmaster / Driver / Pick-up), booking ref, booked ✓.
- Actions: Print schedule, Export .xlsx, Dispatch (per order or per group, with confirm dialog listing stock that will be removed).
- Blocked: dispatch when a line is not fully allocated → message; admin override with reason.
Customers (?page=customers)
- List, add, edit, deactivate. Fields per
TRD.md§5.1.
Dashboard (?page=dashboard) — see DASHBOARD.md
- Purpose: one screen per role with today's work. Opening it (≥ 10 s visible) marks the user as seen today.
- Tiles: dispatching today / tomorrow, new orders, short items, awaiting action, bot proposals, stock alerts, expected orders.
- Empty state: "All clear for today ✓".
Airline analytics (?page=analytics)
- Weekly cartons by port, top products with trend, kitchen order rhythm, menu-change list. Filters: date range, port, product.
B5. Secondary flows
- Cancel order: Order → Cancel → reason → confirm → allocations released → status CANCELLED.
- Change after allocation: edit qty → allocations for that line released → re-allocate.
- Undo dispatch (admin): Order → Undo dispatch → reason →
intransactions created → status back to SCHEDULED. - Short then made: Stock IN recorded on Stock page → Packing shows line as available → Allocate.
- Not seen dashboard (Hermes): check-in time passes → WhatsApp/Telegram (+15 min) → SMS (+30) → phone call (+45, opt-in) → manager (+60). Opening the dashboard or replying "OK" stops the ladder.
- Bespoke enquiry: free-text line → office links to a product (or creates a product) before allocation.
B6. Important states
Loading · Empty · Validation error · Saved · Network error (autosave failed → value reverts + message) · Short · Fully allocated · Booked · Dispatched · Cancelled · Bot proposal waiting (see Part C).
Part CWhere the bots fit
▸ Inbox ──► Order Intake Bot drafts order ──► [human confirms] ──► NEW
- NEW ──► Availability Bot suggests date / feeds planner
- INVOICED? no ──► Invoice Prep Bot drafts Xero invoice ──► [human approves in Xero]
- CONFIRMED? no ──► Confirmation Bot drafts email ──► [human sends]
- Packing ──► Allocation Bot proposes allocation ──► [packer confirms]
- SHORT ──► Production Bot adds to Alex's make-list + alert
- Day before 14:00 ──► Dispatch Scheduler Bot drafts schedule + Roadmaster/driver messages ──► [human books]
- DISPATCHED ──► Stock Reconciler Bot checks ledger
- Every morning 07:00 ──► Hermes: each person's to-do list (WhatsApp / Telegram)
- Not seen by check-in ──► Hermes: message → SMS → call → manager
- 06:30 ──► Order Pattern Bot: expected-order watch + forecast for make-list
Rule: bots prepare, people decide. Anything that moves stock, money or a promise to a customer needs a named person to press the button.