# Baa Baa POS implementation roadmap

This file tracks the user's phased implementation plan. “In progress” means part of the capability exists but still needs the listed work before it is complete.

## Phase 1 — Foundation

- [x] 4.x Staff authentication and user management: active staff login, login audit, password hashing/reset, account enable/disable, role assignment and protection against disabling the final active administrator.
- [x] 5.x Members/Loyalty database integration: existing member, NFC, QR, loyalty account, reward and ledger tables back member lookup, checkout earning and redemption workflows.
- [x] 6.1 Project structure: application modules, configuration, route tables and public interfaces are established; modules will grow with later phases.
- [x] 6.2 Existing configuration/database integration: PDO uses the existing `baabaa_pos` database and environment-overridable connection values.
- [x] 6.3 Authentication/session consolidation: active staff roles and permissions reload from the database; session IDs rotate at login; logout is a CSRF-protected POST. Shared permission checks use `user_id`, active roles and `permission_code`.
- [x] 6.4 Error handling: shared exception/error handling logs a request reference and returns safe HTML/JSON errors.
- [x] 6.5 Routing/request/response: explicit web/API route tables, request helpers, response helpers and one front controller.
- [x] 6.6 Security middleware: security headers, strict session cookie settings and shared CSRF checks. The NFC callback remains exempt until device authentication is delivered in Phase 6.

## Phase 2 — Core POS

- [x] 7 Products: catalog, categories, cashier menu and soft delete/restore.
- [x] 8 Product pricing: effective-dated cashier price history, future scheduling/cancellation and audit entries.
- [x] 9 Options/add-ons: reusable option groups and per-product attachment/editing.
- [x] 10 Cart: browser cart with product options and quantity controls.
- [x] 11 Orders: transactional checkout, item/options snapshots and order history.
- [x] 12 Payments: one selected payment method, cash tender/change and reference capture; multi-tender/processor integration remains.
- [x] 13 Discounts: PWD, Senior Citizen, Special, Manual and Promo discounts with non-VAT calculations.
- [x] 14 Order modification: staff with `ORDER_EDIT` can change quantities/notes or remove lines before production starts; price deltas, audit history and loyalty point adjustments are recorded. Discounted or started orders require refund/recreation.
- [x] 15 Cancellation/refund: `ORDER_CANCEL` and `PAYMENT_REFUND` protect the respective actions; the adjustment flow records reason, amount and reference, updates order/payment status and reverses earned points proportionally.

## Phase 3 — Production

- [x] 16 Barista department ticket queue.
- [x] 17 Kitchen department ticket queue.
- [x] 18 Pastry department ticket queue.
- [x] 19 Production orders created during checkout.
- [x] 20 KDS with role-filtered queue and start/ready/complete actions.
- [x] 21 Printing: browser printing for customer receipts and individual production tickets, with printer selection handled by the workstation OS. Network printer/device administration remains.

## Phase 4 — Cash Control

- [x] 22 Cashier shifts: open/close, opening float, actual count, expected amount and variance; checkout requires the cashier's shift to be open.
- [x] 23 Cash movements: paid-in, paid-out and cash refunds are assigned to a shift and included in expected drawer cash.
- [x] 24 X reading: current expected cash snapshot is audit logged without closing the shift.
- [x] 25 Z reading: shift closure stores expected cash, counted cash and variance as the final reading.
- [x] 26 End-of-day reconciliation: manager report totals closed shifts for a selected business date and shows any still-open shifts separately.

## Phase 5 — Loyalty

- [x] 27 Member management: member profiles, active/inactive state, membership assignment, directory search and loyalty account creation.
- [x] 28 Membership types: tier CRUD/activation and points multipliers.
- [x] 29 NFC card registration and management: pending registration, activation, revocation, hashed UID storage and expiry-aware lookup.
- [x] 30 QR card management: one-time random scan secret, hashed storage, pending/active/revoked states, expiry and last-use tracking. Printable QR image generation remains in Phase 7.
- [x] 31 Loyalty rules administration: earn rate, minimum purchase, active periods and overlap prevention.
- [x] 32 Points ledger and adjustments: permission-gated member balance/history, audited manual point adjustments, and order adjustment/refund reversals.
- [x] 33 Rewards catalog: free product, fixed discount and percentage discount definitions with points cost, validity and quantity limits.
- [x] 34 Redemption: cashiers can issue 30-day member vouchers, reserve points, accept a member-presented code, and apply free-product/fixed/percentage rewards in checkout. Voucher use, order, payment, points ledger reference and reward count commit together; managers can cancel pending vouchers to restore points, and expired vouchers are released on member reward lookup or redemption administration.
- [x] 35 Refund/reversal integration: order refunds reverse earned points without allowing a negative balance; cancelling an uncompleted order restores points spent on its reward vouchers. A completed reward stays spent after refund because the reward may already have been delivered.

## Phase 6 — NFC

- [x] 36 `nfc_bridge.py` prototype USB HID reader polling (VID `0483`, PID `4343`) with a PC/SC backend option and POS scan callback.
- [x] 37 Scan API and member lookup.
- [x] 38 Card registration through member administration; NFC UIDs are hashed before storage.
- [x] 39 Card activation for pending NFC cards, requiring an active member.
- [x] 40 Card revocation requires `MEMBER_CARD_REVOKE`, a reason and an audit record.
- [x] 41 Scan logging for registered and unknown UIDs.
- [x] 42 POS member identification.

## Phase 7 — Member Web Portal

- [x] 43 Member authentication: separate member session cookie, in-person 24-hour activation codes stored as hashes, password hashing, session rotation, inactive-account checks and temporary lockout after repeated failures.
- [x] 44 Member dashboard with membership summary, active card states and pending vouchers.
- [x] 45 Current and lifetime points balances.
- [x] 46 Member reward catalog and voucher issue flow; points are reserved and vouchers are applied at POS checkout.
- [x] 47 Recent points transaction history.
- [x] 48 Printable QR membership card image: authenticated members can replace a lost/old QR credential and print its locally generated QR card; the previous credential is revoked and secrets remain hash-only in MySQL.
- [x] 49 NFC and QR card statuses, last-use dates and expiration information.

## Phase 8 — Reporting

- [x] 50 Sales: `REPORT_SALES`-gated orders grouped by paid date, subtotal, discounts and net sales after recorded refunds/cancellations attributed to the original order date.
- [x] 51 Product performance: units ordered, gross sales, discounts and net sales after proportional refund allocation.
- [x] 52 Customer/member analytics: current active and new-in-range counts, repeat purchase rate, member spend, average net per member order and membership tier breakdown.
- [x] 53 Loyalty analytics: points ledger activity by type and current status of vouchers issued in the selected date range.
- [x] 54 Cashier reports: cashier sales/refunds and shift expected-versus-counted reconciliation, with open shifts counted separately and cash totals from closed shifts only.
- [x] 55 Inventory: current on-hand quantities, reorder alerts and dated inventory movement totals. Automatic recipe deduction remains outside this report.
- [x] 56 Audit reports: date-filtered current and legacy audit log activity, with a 500-row display cap.

## Next implementation slice

Next: Add the inventory adjustment workflow and require `INVENTORY_ADJUST` at its service boundary. Review the complete POS flow on the WAMP workstation and refine report definitions as store data accumulates. NFC callback device authentication remains an infrastructure hardening item before exposing the bridge beyond the trusted store LAN.