@topy-ai/maggie 0.7.53 → 0.7.54

package/bundled-references/maggiedash-booking/ORAWELLNESS-INTEGRATION-AUDIT.md

@@ -1,270 +0,0 @@
-# ORA Wellness Booking integration audit
-
-Initial audit: 2026-09-21 · Stripe status refreshed: 2026-09-28
-Project: `/home/balalior/Dev/clients/orawellness.uk`
-Source: MaggieDash Booking `0.2.10` plus ORA host adapter
-
-## Short answer
-
-The host now has the main Fresha-style foundation: manager workspace, services,
-staff, resources, working hours, availability, holds, bookings, customer
-tokens, Stripe payment boundary, Resend notification outbox, audit records,
-email/password login, and separate Booking roles.
-
-It is not production-ready yet. The remaining work is deployment evidence and
-provider operations, not another UI shell. A 2026-09-28 read-only Chrome smoke
-found the live `/book` page advertising online booking; the direct customer
-page returned availability through 00:20, past the published closing time.
-No booking was submitted. The deployed version, payment readiness, and checkout
-outcome are unknown, so this is an active production exposure/schedule
-discrepancy to reconcile.
-
-The source audit found that the public availability adapter still used the
-generic duration-stepped query while customer hold creation used the host
-schedule planner. This explains why public starts could exceed venue hours or
-capacity constraints. The ORA working tree now routes both reads and holds
-through the same location/staff/resource-aware planner and requires the service
-to be enabled for online booking. Local adapter and rules regressions pass;
-a read-only staging API recheck returned assessment starts 17:45–20:15 local,
-ending by 20:50 before the 21:00 close. Production reconciliation remains open.
-
-BK-124 completed the follow-up audit of saved location closures. The shared
-planner now loads the requested tenant/location's closure intervals and applies
-them to both public availability and hold revalidation, including exact-edge
-boundary regressions. Local source/build checks pass; production remains
-unverified and unchanged.
-
-BK-125 also wires dated staff shifts into the same planner. Shifts constrain
-staff on the selected date in addition to recurring venue/staff hours, while a
-date without a shift retains the existing fallback behavior. Public slots and
-hold checks share this rule; production remains unverified and unchanged.
-
-The ORA `.env` contains a Stripe test secret under the existing
-`ST_SECRECT_KEY` compatibility name, a publishable test key under `ST_PUB_KEY`,
-and `STRIPE_WEBHOOK_SECRET`; no secret values are recorded here. The ai-cmo
-Booking setup checklist recognizes the legacy alias and reports the key pair
-as configured-pending-verification. A Stripe test-mode Checkout for £68 GBP
-was completed through the customer flow; Stripe readback showed a paid Checkout
-and succeeded PaymentIntent, and the staging Booking/customer history now agree
-on confirmed/paid. The configured sandbox identifies as APHRODITE FASHION
-LIMITED with charges disabled. Whether this is ORA's intended account and the
-authenticated Booking **Verify Stripe connection** check remain unconfirmed;
-test API availability is not account-identity or live-readiness evidence. A
-later approved direct test-mode probe also created/read/expired a £1 Checkout
-and confirmed a £1 `pm_card_visa` PaymentIntent. The account still reports
-`charges_enabled=false` and `payouts_enabled=false`, so online payment remains
-disabled.
-
-Current database gate: the explicitly targeted `orawellness-staging` database
-passes read-only core, Booking, and access schema checks. `DATABASE_URL` remains
-unclassified and is not release evidence; the approved production target has
-not been verified or migrated. The 2026-09-21 read-only preflight is historical:
-it found `maggiedash_booking_allocations` and
-`maggiedash_booking_user_roles` absent before the staging setup. Do not enable
-the production dashboard or scheduler until the owner confirms the production
-target, approves any migration, verifies backup/restore, creates the first
-owner, and captures authenticated runtime evidence.
-
-## Verified in the codebase
-
-| Capability | Evidence | State |
-|---|---|---|
-| Manager dashboard | `/_maggie/booking`, `_maggie/booking/booking.tsx` | Installed |
-| Traditional authentication | `src/lib/maggie/auth.ts`, registration and login routes | Installed |
-| Booking roles | `maggiedash_booking_user_roles`, Staff access panel, complete server-enforced capability registry for calendar/bookings/customers/waitlist/catalogue/packages/staff/resources/schedule/locations/payments/refunds/notifications/settings/reports/audit | Installed; explicit staff/finance grants and safe legacy defaults covered by BK-101 |
-| Staff account lifecycle | Booking Staff panel creates accounts, sends Resend invitations, supports one-time password setup and password reset | Installed; real delivery/browser proof pending |
-| Staff data scope | Linked `staff_id` passed into the server context and filtered in the repository | Installed; host migration/staging proof pending |
-| Services/treatments | Searchable catalogue with editable service/variant details, payment policy, price, preparation/cleanup buffers, active/inactive state, manager multi-treatment appointments, public multi-treatment holds/checkout, and live service/location selectors | Installed; legacy allocation backfill and staging data verification pending |
-| Treatment packages | Tenant-scoped manager catalogue, manager-granted entitlements, public package checkout/payment return and fully covered public customer redemption, webhook fulfillment, balance reads, expiry checks, atomic redemption, cancellation-safe package-credit restoration, guarded refunds, and package confirmation/refund Resend outbox events | Installed locally; real Stripe/DB migration, webhook, Resend, and staging delivery proof pending |
-| Locations | Tenant-scoped Locations screen and `locations.json` route for first-location setup, timezone, locale, address, active state, and online-booking controls; public catalogue exposes all active online-booking locations | Installed; staging data verification pending |
-| Staff/resources | Editable staff profiles, service/location assignments, bookable state, resources, capacity, resource service assignments, and overlap constraints | Installed; staging data verification pending |
-| Calendar/availability | Day/week calendar, working hours, shifts, time off, closures, holds | Installed |
-| Booking defaults | Settings screen edits venue timezone/currency, pauses new booking writes, and selects automatic/manual capture policy | Installed; staging policy verification pending |
-| Stripe | Injected SDK gateway, account capability row, signed webhook boundary | Host-wired; staging proof pending |
-| Resend | Notification outbox plus `scripts/maggie-booking-worker.mjs` dispatcher, including a separate 30-day sealed customer-manage link | Host-wired; scheduled delivery proof pending; worker waits for Booking schema |
-| Notification operations | Tenant-scoped Notifications screen, redacted delivery-state list, and owner/manager-only dead-letter replay with reason/idempotency/audit controls | Installed; ORA validators/build passed; real delivery proof pending |
-| Public self-booking | `/_maggie/booking/book`, catalog/location selector, location-scoped combined-duration availability, multi-treatment hold/checkout, return, token-bound segment-safe reschedule/cancel, and 30-day customer-manage history | Installed; staging proof pending |
-| Waitlist | Public no-slot join, tenant-scoped manager queue, manual notify/cancel/priority actions, transactional conversion to a linked booking, priority/FIFO worker matching, and `booking.waitlist.available` Resend intent | Installed; explicit worker scope, real migration, scheduler, and delivery proof pending |
-| Reports | `/reports.json` plus Booking Reports screen with period/service/staff/location breakdowns | Installed; staging data verification pending |
-| Bookability readiness | Overview reports active location, catalogue variant, assigned bookable staff, working hours, overall bookable state, and payment capability | Installed; staging data verification pending |
-| Customer history | Searchable tenant-scoped manager directory plus token-bound public customer-manage history with redacted appointment summaries | Installed; staging data verification pending |
-| Schedule rules | Searchable/editable working hours, staff shifts, time off, and location closures through the audited schedule route | Installed; staging data verification pending |
-| 24-hour reminders | Worker queues one idempotent `booking.reminder` email into the Resend outbox for each eligible confirmed booking | Installed; scheduled Resend delivery evidence pending |
-| Payment policy and balance | Service-level full/deposit/pay-later/no-payment policy, purpose-labelled attempts, paid/balance projection, and refund projection | Installed; migration and Stripe staging evidence pending |
-| Payment truth | Verified webhook/provider read projects payment and booking state | Implemented; Stripe event test pending |
-| Legacy `/book` | Request-by-email flow | Kept as fallback |
-
-## Fixes made during this audit
-
-1. Public catalogue now returns all active online-booking locations plus a
-   backwards-compatible first `locationId`. The browser displays the tenant
-   locations, scopes availability to the selected location, and posts that
-   selected ID instead of using the fake `location-1` fallback.
-2. Public origin and rate-limit failures now return safe 403/429 responses.
-3. Stripe account status and capabilities are upserted into
-   `maggiedash_booking_payment_accounts`; no secret value is stored there.
-4. Webhook records store a SHA-256 payload hash instead of using the provider
-   event ID as a misleading hash.
-5. Customer cancellation queues the Booking notification through the same
-   Resend outbox.
-6. Customer rescheduling now uses the same sealed token, transactional
-   allocation conflict checks, idempotent replay, and `booking.rescheduled`
-   Resend outbox path as manager rescheduling.
-7. Customer checkout now creates a short-lived payment-return token and a
-   separate 30-day `manage` token. The Resend worker reuses or creates the
-   manage token for booking notifications without storing a raw token in the
-   outbox.
-8. Verified payment events now project `pending_payment` to `confirmed` and
-   `paid`, or cancel failed payment bookings and release their allocations,
-   before the worker acknowledges the event. Confirmation/cancellation
-   notifications are then queued once.
-9. Booking Staff can now create an email/password account directly, link its
-   staff profile, assign permissions, and resend a secure invitation without
-   using a separate People screen.
-10. Added the `/_maggie/reset-password` middleware rewrite so invitation and
-password-reset links resolve to the Astro reset page.
-11. Added a manager Overview setup checklist that reads the existing payment
-    health response, shows Stripe status and test/live mode, and provides a
-    copyable webhook URL without exposing provider secrets.
-12. Fixed the installed UI validator to resolve ORA's `_maggie/booking`
-    workspace instead of assuming a source-package `maggiedash/booking/src`
-    directory.
-13. Added provider-neutral automatic waitlist matching. The worker matches one
-    eligible waiting customer per explicit service/location slot, persists the
-    offered interval, and queues an idempotent Resend notification without
-    auto-reserving the appointment.
-14. Added the public `GET /api/maggie/booking/public/manage.json` history
-    surface. The existing 30-day Resend manage token now resolves the current
-    customer's tenant-scoped appointments through a redacted DTO; payment
-    tokens and manager credentials are not accepted by this endpoint.
-15. Added manager multi-treatment appointments. The form can compose up to 12
-    service segments, while the host validates duration, availability, shared
-    location/currency, per-segment staff/resource allocation, and persists the
-    segments and allocations atomically with the booking.
-16. Added public multi-treatment booking and segment-safe rescheduling. Customer
-    holds persist `segments_json`, checkout sums all treatment prices, and both
-    customer and manager rescheduling shift each segment/allocation together
-    while checking conflicts independently and preserving the total duration.
-17. Removed install-time `location-1`/`service-1` assumptions. Catalog and
-    schedule reads now return tenant locations; manager forms derive defaults
-    from those responses, and resource writes persist service assignments.
-18. Added tenant-scoped location management so a blank project can create its
-    first venue before configuring services, staff, resources, and schedules.
-    The same audited location contract is mirrored in ORA's installed Booking
-    workspace.
-19. Fixed a runtime catalogue query that referenced the nonexistent
-    `service_variants.created_at` column. Variant reads now use stable existing
-    columns for ordering. Hardened the ORA initial catalogue seed so a partial
-    retry reuses matching services and upserts variants instead of creating
-    duplicate services.
-20. Closed the treatment catalogue UI parity gap: the manager can now manage
-    every variant under a service, including duration, price, currency, and
-    active state, while preserving the existing idempotent backend write.
-21. Aligned ORA public availability reads with the host schedule planner used
-    for customer holds. Public options now respect location hours, mapped staff
-    and resources, existing occupancy, and the online-booking service flag.
-    Local adapter, booking/rule, route-gate, contract, and build checks pass;
-    staging and browser re-verification are still required.
-
-## Installer productization update
-
-The MaggieDash distribution now declares an Astro host bootstrap. New Astro
-projects can use:
-
-```bash
-maggie booking install --project . --confirm
-```
-
-The installer adds missing Booking routes, email/password registration/login,
-PostgreSQL/Stripe adapter wiring, public booking route, middleware scaffold,
-schema command, Resend worker, and `.env.maggie-booking.example`. Existing
-host files are preserved. ORA already has host-owned versions of these files,
-so a repeat install should preserve ORA's middleware, auth, and adapter rather
-than overwrite them. Existing Astro middleware in either the full-context or
-common destructured-context form now receives the idempotent rewrite block;
-unknown middleware shapes remain fail-closed and are reported for manual review
-before the Booking URL is exposed.
-
-For hosts that use the installed Resend outbox and reminder worker, the CLI can
-also generate a reviewed scheduler artifact:
-
-```bash
-maggie booking install --project . --confirm --bootstrap --schedule systemd
-```
-
-The command writes the systemd service/timer under `deploy/` but does not
-enable or start it. Production still requires an approved service user,
-migration, backup/restore, alert routing, and authenticated runtime evidence.
-
-## Release blockers
-
-| Priority | Work | Why it matters | Owner |
-|---|---|---|---|
-| P0 | Verify the approved production database target and Booking/access schema state | The explicitly targeted staging database has core, Booking, and access tables ready. `DATABASE_URL` is unclassified, and no production schema check or migration is accepted as release evidence. Confirm the production target and backup/restore plan; perform read-only verification first, and apply schema only after explicit approval | ORA deployment |
-| P0 | Reconcile the live public Booking exposure and out-of-hours availability | Chrome read-only inspection found `/book` advertises online booking and the public page returns starts past the published close. This conflicts with the prior release assumption; deployed version, payment account, and checkout outcome are unverified | ORA + release owner |
-| P0 | Release the current MaggieDash source used by the default installer | The public `9d99de7` source is a validated `0.2.8` baseline, but the current 47-route/no-show changes remain uncommitted in the working tree | MaggieDash release owner |
-| P0 | Confirm the intended Stripe account and complete authenticated Booking connection verification | Direct test-mode Checkout and test-card PaymentIntent calls pass, but the configured sandbox reports charges/payouts disabled and is not confirmed as ORA's intended account. Keep `onlinePayment` disabled until the correct account is confirmed and the host verifies its capabilities | ORA + client |
-| P0 | Run worker every minute with alerting | Holds, payment projections, and Resend delivery otherwise remain pending; `maggie booking worker-schedule` now generates the reviewed systemd/cron artifact, but host enablement and alert routing remain pending | ORA operations |
-| P0 | Review Resend activity after the staging preview incident | Two pre-fix staging previews each reported one provider-accepted notification without persisting outbox state; a duplicate submission is possible. Review provider activity and assess any duplicate before a worker `--write` run | ORA operations |
-| P0 | Capture authenticated runtime/browser/ops evidence | Local build and reference fixtures cannot prove the real host | ORA + release owner |
-| P1 | Complete remaining Stripe test-mode scenarios | Checkout success and an expired unpaid Checkout are covered. Failure, delayed/duplicate webhook, refund, and the authenticated host connection still need evidence against the confirmed intended account | ORA + Stripe |
-| P1 | Capture Resend invitation/reset evidence | Booking notifications are wired; staff account invitation and password reset now use the same server-side Resend configuration | ORA + release owner |
-| P1 | Capture reminder delivery evidence | The worker now enqueues reminders; staging must prove scheduler timing, Resend acceptance, retry, and no duplicate send | ORA + release owner |
-| P1 | Verify customer-manage links in real Resend emails | Staging must prove the 30-day link opens the noindex customer page and reschedule/cancel remain token-bound | ORA + release owner |
-| P1 | Verify waitlist notification delivery and conversion workflow | Staging must prove queue scope, one-time notification behavior, Resend acceptance, conflict handling, and the linked booking/confirmation email | ORA + product owner |
-| P1 | Switch marketing CTAs from `/book` to `/_maggie/booking/book` | Avoid sending customers to the new flow before staging proves it | Product owner |
-| P2 | Add richer Fresha features | Package purchase/refund paths are implemented locally. Memberships, gift cards, advanced multi-location staff rules, and customer-side package/membership pricing remain roadmap items. Customer self-service history, bounded automatic waitlist matching, and segment-safe multi-treatment rescheduling still need real host delivery proof | Product roadmap |
-
-## Evidence already run
-
-- ORA `npm run build`: passed with no errors, warnings, or hints;
-  the Stripe setup checklist is included in the built Booking workspace.
-- ORA `npm audit --omit=dev --audit-level=high`: passed with zero
-  vulnerabilities after refreshing the Cloudflare/Wrangler lockfile chain.
-- ORA `maggie booking inspect --project .`: passed all installed workspace,
-  contract, schema, customer, worker, and ops checks.
-- ORA installed UI and customer UI validators: passed after resolving the
-  `_maggie/booking` workspace path.
-- Central and ORA Booking UI validators now also reject fixture location/service
-  IDs in the installed manager source; both copies passed.
-- Central and ORA location configuration, service-contract, route-handler, and
-  reference-host validators now cover the 47-route manager surface; both
-  installed UI copies passed.
-- ORA worker/runtime regression: passed for waitlist priority/FIFO matching,
-  one-time offered-slot persistence, and idempotent replay.
-- ORA customer reference-host regression: passed public multi-treatment
-  availability, hold/checkout, and token-bound multi-treatment rescheduling;
-  the PostgreSQL core regression also passed segment-safe rescheduling.
-- MaggieDash customer-flow, customer-UI, runtime-plan, worker-repository, and
-  syntax checks: passed.
-- ORA `maggie booking release-gate --project .`: static contract/workspace gate
-  passed; runtime, browser, ops, and board evidence were not supplied.
-- ORA `maggie booking setup --project .`: dependencies, database URL, public
-  URL, Booking token secret, Resend sender configuration, and a Stripe test
-  secret alias are present; the missing webhook secret keeps Stripe in pending
-  verification, while schema, first owner, and worker schedule remain explicit
-  verification steps.
-- Full required release gate was run read-only on 2026-09-21 and correctly
-  returned `blocked` for the missing runtime, browser, ops, and unfinished-board
-  evidence. It did not run migrations, create bookings, send email, or deploy.
-- ORA `npm run booking:schema -- --check`: `needs-migration` with core present,
-  Booking absent, and Booking access absent. This command was read-only; no
-  database migration was applied.
-- Disposable local ORA Astro runtime: first-owner registration HTTP 201,
-  password login HTTP 200, authenticated overview/settings/catalog/staff HTTP
-  200, and public catalog HTTP 200 against a temporary PostgreSQL database.
-  This caught the variant ordering and partial-seed defects above; it is not
-  production or staging evidence.
-- Central and ORA PostgreSQL core integrations now persist two treatment
-  variants, assert expanded allocation ranges after rescheduling, and reject a
-  buffer-overlapping adjacent booking. The reference hosts and customer
-  cursors also apply the same rule. The one-time
-  `schema/maggie-booking-buffer-backfill.sql` migration is included but still
-  needs staging/owner approval; no live ORA database was changed.
-
-## Decision
-
-Do not market this as a complete Fresha replacement yet. It is a valid Booking
-foundation and installable host integration. The next safe step is staging
-migration plus real Stripe/Resend/browser evidence, followed by a canary before
-changing the public CTA.