# POS System Build Plan

## Objectives
- Provide a lightweight MVC-style POS web app written in PHP 8 with PDO for MySQL.
- Deliver secure authentication, cart management, and transactional checkout.
- Ensure touch-friendly UI with AJAX-powered cart updates.

## Data Model
```sql
users (
  id INT PK AI,
  username VARCHAR(50) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  role ENUM('cashier','manager') DEFAULT 'cashier',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

products (
  id INT PK AI,
  name VARCHAR(100) NOT NULL,
  sku VARCHAR(40) UNIQUE,
  price DECIMAL(10,2) NOT NULL,
  stock_quantity INT NOT NULL DEFAULT 0,
  display_order INT NOT NULL DEFAULT 0,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
)

transactions (
  id INT PK AI,
  user_id INT NOT NULL REFERENCES users(id),
  total DECIMAL(10,2) NOT NULL,
  payment_method ENUM('cash','card','mobile') NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

transaction_items (
  id INT PK AI,
  transaction_id INT NOT NULL REFERENCES transactions(id),
  product_id INT NOT NULL REFERENCES products(id),
  quantity INT NOT NULL,
  unit_price DECIMAL(10,2) NOT NULL,
  line_total DECIMAL(10,2) NOT NULL
)
```

## PHP Components
- `config.php`: centralizes DB credentials + session defaults.
- `db_connect.php`: exposes a reusable PDO instance with strict error handling.
- `auth_process.php`: handles login POST, verifies password, starts session, and redirects.
- `logout.php`: destroys session and redirects to `login.php`.
- `cart_handler.php`: AJAX endpoint to add/remove/update items in `$_SESSION['cart']` and return JSON totals.
- `checkout_process.php`: finalizes cart, wraps DB writes in a transaction, adjusts inventory, clears cart.
- `services/product_service.php`: shared helpers for creating products and managing their display order.
- `services/report_service.php`: aggregation helpers that calculate daily/monthly KPIs for the manager reports.
- `product_handler.php`: manager-only AJAX endpoint for catalog creation and ordering.
- `sales_report.php`: secured manager page that surfaces sales analytics.

## Views & Assets
- `login.php`: minimal login form with messages rendered via escaped PHP.
- `pos.php`: three-column layout (product grid, cart summary, keypad/actions) with embedded JS hooking into AJAX endpoints.
- `assets/css/style.css`: responsive styles optimized for touch display.
- `assets/js/pos.js`: handles POS UI interactions, AJAX cart updates, and checkout submission.
- `product_admin.php` & `product_order.php`: manager views for catalog maintenance and arranging tile order, powered by `assets/js/product_order.js`.
- `sales_report.php`: split panels for daily and monthly KPIs, leveraging the shared report service and existing design system.

## Security Practices
- Enforce `session_start()` on every entry file and regenerate IDs post-login.
- Require HTTPS in production; include CSRF token for AJAX requests stored in session.
- Sanitize all outputs with `htmlspecialchars()`.
- Catch PDO exceptions, log via `error_log()`, and send safe responses to clients.

## Build Steps
1. Scaffold directories (`assets/css`, `assets/js`, `database`).
2. Implement config + DB utilities.
3. Build auth, cart, and checkout controllers.
4. Create views and assets hooking into controllers.
5. Provide SQL schema and README instructions.
6. Smoke-test flows locally via PHP built-in server (`php -S localhost:8000`).