BeWell Booking — archived build
================================
Version:   0.5.3
Archived:  2026-07-27

WHAT'S IN THIS BUILD
--------------------
Core (0.1–0.4.0): 5-step booking wizard [bewell_booking]; Razorpay (checkout,
  signature verify, webhooks, test/live, offline); multi-timezone; tax/GST;
  invoices; .ics invites; cancel/reschedule (customer + admin); admin manual
  "Add Booking"; email (+SMTP) + Twilio WhatsApp; admin Bookings / Schedule /
  Operating Hours / Services / Categories / Notifications / Settings / Logs;
  hardening (DB-level unique slot key, hold-release cron, atomic invoicing,
  versioned migrations).

0.4.1–0.4.55 (see earlier archives, esp. v0.4.55): self-service toggle; Schedule
  views + CSV export; holidays/blocked dates; Twilio Messaging Service SID;
  6/7-var WhatsApp templates (real Twilio templates); Brevo SMTP preloaded; full
  LIGHT re-theme; calendar today-bold + selection-orange; 2h min lead time;
  wizard 1240px + Roboto; green success tick; HTML emails (green date/time,
  wp_editor); India phone default; weekly-off (default Sunday); country-code flag
  dropdown (intl-tel-input bundled locally, v18 -> v25 to fix flag sprites).

0.4.56–0.4.76 (this batch):
  0.4.56  Fixed booking-window end date; fixed test stub to serve avail config.
  0.4.57  Rolling booking window "book up to N days ahead" (default 7, on; 0=off).
  0.4.58  Calendar readability: no strike-through; dot for holiday/weekly-off;
          caption under the calendar for mobile.
  0.4.59  Rolling window skips closed days (on): 7 + one weekly off = 8 days.
  0.4.60  Fully-booked dates greyed + tooltip "Fully booked for this date".
  0.4.61  Weekly-off tooltip -> "Weekly holiday".
  0.4.62  Note placeholder -> "Describe the areas of concern."
  0.4.63  Emails left-aligned.
  0.4.64  Success screen: "Thank you, <name>" (bold) / tick / "Booking Confirmed"
          / "emailed and WhatsApped to you."
  0.4.65  BUGFIX: removing a holiday deleted the wrong entry (sorted vs unsorted).
  0.4.66  Holidays EDITABLE (dates + label) via remove-by-value replace.
  0.4.67  BUGFIX: holidays not greying — /catalog cacheable; nocache + cache-bust.
  0.4.68  BUGFIX (stronger): stale /catalog from HTTP cache; strongest no-store
          set on /catalog + /slots. Force-cache CDN still needs a purge +
          /wp-json/ bypass rule.
  0.4.69  Calendar caption: "Bookings open through" -> "Bookings open till".
  0.4.70  Starting appointment number setting (Settings). Blank = start at 1; a
          number (e.g. 510) starts there. Display offset on {order_id} across
          emails + WhatsApp + ICS.
  0.4.71  Booking wizard hides category tabs that have no services.
  0.4.72  Optional wizard heading setting (Settings). Blank by default = hidden.
          Per-page override [bewell_booking title="..."].
  0.4.73  BUGFIX: category tabs all vanished — REST sent category id as string vs
          service category_id int; strict-equality failed. REST casts id to int;
          JS comparisons type-tolerant (Number()).
  0.4.74  Categories DELETABLE (Actions column). Refused if the category still has
          services, to avoid orphaning them.
  0.4.75  Admin WhatsApp variable {{2}} now feeds {first_datetime} (date + time,
          was date-only); admin_body text updated to match. Still 7 vars in the
          same order, so the approved Twilio template needs NO re-approval.
          Re-seeded (seed_ver 8).
  0.4.76  Mobile pass (<=640px): stepper becomes a horizontal scrollable strip
          (was a tall vertical stack); calendar borders collapsed to a single
          clean grid (removes the stray right-edge vertical line); 44px min cell
          height for touch; tighter card padding + smaller title + caption.
          First pass — not a full mobile audit.

0.5.0 — MULTI-STAFF (P0). DB_VERSION 3 -> 4.
  The single-provider assumption is removed. Booking is now per provider: the
  same start time is independently bookable for each of them.

  Schema:
    + bewell_staff          name/photo/bio/email/phone/active/sort, plus
                            wp_user_id (NULLABLE — a provider never needs a WP
                            account), hours + leave_dates as JSON where NULL
                            means "inherit the clinic config".
    + bewell_staff_services many-to-many, with a nullable price_override that
                            stays unused (per-staff pricing is out of v1 scope).
    ~ appointments          + staff_id, + KEY staff_slot,
                            slot_key VARCHAR(20) -> VARCHAR(32).
    ~ slot_key              'date|HH:MM' -> 'date|HH:MM|staff_id'.

  Migration (v4): seeds one provider named after the site, maps it to every
  service, assigns all existing appointments to it, and appends '|<id>' to
  existing slot keys. Appending the same suffix to every row is bijective, so
  uniqueness holds at every intermediate state and the UNIQUE index can't be
  violated mid-migration. Cancelled rows keep slot_key = NULL. Guarded by
  NOT LIKE '%|%|%' so a re-run can't append twice. Existing bookings get a real
  provider, not a synthetic "Unassigned" that would appear on invoices.

  Behaviour:
    - slots_for_date($date, $staff_id) composes clinic-open AND provider-works
      AND not-on-leave. Clinic holidays/weekly-offs still override everything.
    - booked_starts_for_date / is_slot_free are provider-scoped.
    - fully_booked_dates greys a date only when EVERY working provider is full.
    - Wizard gains a Provider step with "Any available" (default), auto-hidden
      when fewer than two providers qualify — so a single-practitioner clinic
      sees exactly the previous five steps.
    - /slots takes staff + service; staff=0 returns the union across qualified
      providers, which is what "any available" then resolves to.
    - "Any available" assigns the first free qualified provider in sort order,
      and is cart-aware so two same-time lines get different providers.
    - Reschedule keeps the same provider (customer + admin).
    - Admin: Providers screen (CRUD, services, own-hours toggle, leave ranges,
      photo picker); provider column + filter on Bookings and Schedule; provider
      in the CSV export and on the booking detail; "Any available" on Add Booking.
    - Deleting a provider is refused while they hold active bookings.

  0.5.1  Memoise staff rows per request. fully_booked_dates() walks 90 days x
         every provider and asks each for hours + leave, so an uncached lookup
         turned one /catalog request into hundreds of identical queries.
         First build produced for testing.

  0.5.2  BUGFIX (critical, found before release): activating the plugin skipped
         the v4 data migration entirely. install() stamps bewell_db_version =
         DB_VERSION, so the later maybe_upgrade() saw no gap. An in-place file
         replacement was fine (activation doesn't re-run), but activating a
         copy installed BESIDE the old folder is exactly the path that broke.
         Unmigrated appointments keep staff_id = 0, and since availability is
         provider-scoped, every existing booking would have read as a FREE
         slot -- i.e. silent double-booking. Activation now calls
         migrate_to_v4() directly; it is idempotent.
         NOTE: two copies of this plugin must never be active at once -- the
         classes are redeclared and PHP fatals. Deactivate the old version
         BEFORE activating this one.

  0.5.3  BUGFIX (build tooling): the plugin zip installed as a SECOND plugin
         instead of upgrading the existing one. Compress-Archive on Windows
         PowerShell 5.1 writes entry paths with BACKSLASHES, which violates the
         ZIP spec. PHP on Linux then extracted 'bewell-booking\bewell-booking.php'
         as a literal filename containing a backslash, flat into
         wp-content/plugins/ -- WordPress read its header and listed it as a
         separate (broken) plugin, so no "Replace current with uploaded" prompt
         appeared. Zips are now written with explicit forward-slash entries, and
         the build fails if any backslash entry or a missing entry point is
         detected. Zips before 0.5.3 should be deleted, not installed.

  NOT RUN: none of this has executed against WordPress or MySQL. The migration
  in particular must be rehearsed against a COPY of production data before it
  touches the real database — see docs/P0-SCHEMA.md section 7 for the exact
  assertions (row count, non-NULL slot_key count, and distinct slot_key count
  must all be unchanged; distinct count dropping means uniqueness collapsed).

KNOWN / BY DESIGN / CAVEATS
---------------------------
  - Mobile: 0.4.76 is a FIRST pass fixing the stepper + calendar line. Other
    screens (cart, summary, slots) may still need tuning; verify on a device.
    CSS changes were not visually rendered here — confirm after install.
  - Admin WhatsApp {{2}} = first_datetime: check the approved Twilio template
    reads naturally with a date+time in {{2}} (no separate time placeholder).
  - Wizard heading + starting appointment number are on BeWell -> Settings. A
    pre-0.4.72 saved heading value can persist in the DB; clear the field + Save.
  - Deleting a category requires it to have no services first.
  - Stale front-end data (old holidays/categories/heading) = HTTP cache serving a
    stale /catalog. Admin (uncached) is truth. Fix: purge Breeze + CDN, add a
    "Bypass cache" rule for /wp-json/. On Cloudways also purge OPcache / restart
    PHP-FPM so updated PHP takes effect in wp-admin.
  - Upgrading applies the 7-day rolling window IMMEDIATELY (legacy configs -> 7).
  - EXPERIMENTAL live secrets in source AND seeded into the DB (Brevo SMTP key,
    Twilio SIDs/token/content SIDs). Externalise + ROTATE before production.
  - Email delivery needs Brevo sender verification + correct SMTP Login; WhatsApp
    needs a WhatsApp sender on the Messaging Service + approved templates
    (customer=6 vars, admin=7). Success screen states both were sent regardless.
  - Validation: email client + server (is_email). Phone loose — client >=10
    digits (not isValidNumber); server only non-empty.
  - Single-provider model; admin reschedule free-form; blocking/weekly-off/window
    changes do NOT auto-cancel existing bookings.
  - intl-tel-input bundled at public/lib/intl-tel-input — verify an image
    optimiser doesn't rewrite the flag sprite URLs.

Tests:  tests/smoke.php — 73/73 passing (verified). PHPUnit unit + WP integration
        suites included (integration NOT run here).

VERIFICATION STATUS
-------------------
VERIFIED (executed):   pure logic — tz, tax, slot keys, .ics, money, phone
                       normalisation, availability, self-service gating, schedule
                       range math, blocked dates (sorted-removal + remove-by-value
                       edit incl. label-only), weekly off, lead time, rolling +
                       fixed booking window, skip-closed-days, appointment
                       numbering offset, HTML email rendering.
NOT YET RUN in target: all WordPress/MySQL-dependent code (DB, REST, cron, admin,
                       gateways, CSV, SMTP, Twilio, category/service delete); the
                       browser wizard vs live APIs; no-store headers vs a real CDN;
                       the mobile CSS was not visually rendered here.
Before production:     follow BeWell-GoLive-Checklist.md — staging install; rotate
                       creds; save each settings page and confirm it persists;
                       Send Test Email + Test WhatsApp; a full TEST-key booking
                       verified end to end; verify mobile on a device; only then
                       switch to LIVE keys; add the /wp-json/ cache bypass.