# FormBuilder Pro — Booking Module Upgrade (v1 → v2)

This document describes every change made from v1 to v2 and how to deploy them.

---

## What's New

### 1. 🏷️ Promo / Discount Codes
**Files:** `lib.php`, `api/booking.php`, `plans.php`, `admin/booking-plans.php`

- New `bk_promo_codes` DB table (auto-created on boot)
- Supports **percentage** and **fixed-amount** discounts
- Per-code: max uses, date window, plan restriction, active toggle
- Public route `POST /api/booking/validate-promo` — validates a code in real time
- `plans.php` checkout sheet now has a promo code field with live Apply button
  - Shows strikethrough original price + green discounted price instantly
- **Admin panel**: new "🏷️ Promo Codes" tab in `admin/booking-plans.php`
  - Full CRUD: create, edit, delete codes
  - Table shows discount, uses count, validity window, active status
- Stripe checkout automatically applies discount as a negative line item

### 2. ⏰ Automated Appointment Reminders
**Files:** `lib.php`, `api/booking.php`, `cron/send-reminders.php`

- New columns `reminder_24h_sent` and `reminder_1h_sent` on `bk_appointments`
- Cron script: `cron/send-reminders.php`
  - Sends **24h reminder** for appointments starting in 23–25 hours
  - Sends **1h reminder** for appointments starting in 55–65 minutes
  - Idempotent: safe to run every 15 minutes, never double-sends
  - Logs sent/error counts to stdout (or cPanel log file)
- Admin endpoint `POST /api/booking/admin/send-reminders` to trigger manually

**Setup in cPanel Cron Jobs:**
```
*/15 * * * * php /home/YOURUSER/public_html/formbuilder/cron/send-reminders.php >> /home/YOURUSER/logs/reminders.log 2>&1
```

Or add `define('CRON_SECRET', 'your_random_string');` to `config.php` and call via HTTP:
```
https://yourdomain.com/formbuilder/cron/send-reminders.php?secret=your_random_string
```

### 3. ⭐ Provider Ratings & Reviews
**Files:** `lib.php`, `api/booking.php`, `customer/dashboard.php`

- New `bk_ratings` DB table — one rating per appointment
- Public route `POST /api/booking/rate` — submit by appointment ref + email
- Public route `GET /api/booking/provider-ratings?provider_id=X` — reviews feed
- **Customer dashboard**: shows star-rating prompt for recent completed sessions
  - Interactive 5-star widget (hover + click)
  - Disappears after submission — no page reload needed
- Admin routes `GET|PUT|DELETE /api/booking/admin/ratings` — moderate reviews

### 4. 🏆 Loyalty Badges (Customer Dashboard)
**Files:** `customer/dashboard.php`

- Shows **Points** and **Total Sessions** stat cards at the top of the portal
- Membership status badge: 🌱 Member → 🥈 Regular → 🥇 Pro Member → 🏆 Champion
- DB columns `loyalty_points` and `total_bookings` added to `bk_customers`
  - Increment `total_bookings` when an appointment is completed (wire to your status update logic)
  - Increment `loyalty_points` by any value you choose on booking/completion

### 5. 🧊 Membership Freeze / Unfreeze
**Files:** `lib.php`, `api/booking.php`

- New columns `frozen_at`, `frozen_days` on `bk_memberships`
- Admin routes:
  - `POST /api/booking/admin/memberships/:id/freeze` — freezes the membership
  - `DELETE /api/booking/admin/memberships/:id/freeze` — unfreezes and auto-extends expiry by the number of frozen days

### 6. 📣 Waitlist Notification
**Files:** `api/booking.php`

- Admin route `POST /api/booking/admin/waitlist/:id/notify`
- Sends a "spot opened up" email to the waitlist customer with a direct link to book
- Call this after cancelling an appointment to notify the next person in line

---

## Database Changes (all auto-applied on boot)

| Table | Change |
|---|---|
| `bk_promo_codes` | **NEW** — discount code system |
| `bk_ratings` | **NEW** — provider reviews |
| `bk_reminders` | **NEW** — reminder log |
| `bk_memberships` | +`frozen_at`, +`frozen_days`, +`promo_code`, +`discount_amount` |
| `bk_appointments` | +`reminder_24h_sent`, +`reminder_1h_sent`, +`cancellation_reason` |
| `bk_customers` | +`loyalty_points`, +`total_bookings` |

All `ALTER TABLE` statements use `ADD COLUMN IF NOT EXISTS` — safe to run on existing databases.

---

## Deployment Steps

1. **Back up your database** before deploying
2. Upload all changed files over your existing v1 installation:
   - `lib.php`
   - `api/booking.php`
   - `lib/StripeBooking.php`
   - `plans.php`
   - `admin/booking-plans.php`
   - `customer/dashboard.php`
   - `cron/send-reminders.php` *(new file)*
   - `UPGRADE_README.md` *(this file)*
3. Visit any page that calls `init_booking_db()` — new tables and columns are created automatically
4. Set up the cron job in cPanel (see Reminders section above)
5. Optionally add `define('CRON_SECRET', 'your_secret');` to `config.php`

---

## New API Reference

| Method | Route | Auth | Description |
|---|---|---|---|
| POST | `/api/booking/validate-promo` | Public | Validate a promo code |
| POST | `/api/booking/rate` | Public | Submit a rating (ref + email required) |
| GET | `/api/booking/provider-ratings` | Public | Get reviews for a provider |
| GET | `/api/booking/admin/promo-codes` | Admin | List all promo codes |
| POST | `/api/booking/admin/promo-codes` | Admin | Create a promo code |
| PUT | `/api/booking/admin/promo-codes/:id` | Admin | Update a promo code |
| DELETE | `/api/booking/admin/promo-codes/:id` | Admin | Delete a promo code |
| POST | `/api/booking/admin/send-reminders` | Admin | Trigger reminder emails now |
| GET | `/api/booking/admin/ratings` | Admin | List all ratings |
| PUT | `/api/booking/admin/ratings/:id` | Admin | Toggle review visibility |
| DELETE | `/api/booking/admin/ratings/:id` | Admin | Delete a review |
| POST | `/api/booking/admin/memberships/:id/freeze` | Admin | Freeze membership |
| DELETE | `/api/booking/admin/memberships/:id/freeze` | Admin | Unfreeze membership |
| POST | `/api/booking/admin/waitlist/:id/notify` | Admin | Email a waitlist customer |
