AMA: paid one-to-one booking system

Description

## Problem Statement The v2 site intentionally retains `/ama`, but the v1 page only shows an Alipay QR code and sends guests to Cal.com. That split flow cannot verify payment, protect availability, support international guests, or manage the full booking lifecycle. Cali needs a personal bilingual AMA page and a reliable first-party system that accepts payment, coordinates calendars, creates the selected meeting, and recovers safely when an external provider is unavailable. ## Solution Rebuild AMA as one US$99, 60-minute one-to-one offering. The public `/ama` page presents it as “A focused hour with Cali” in the v2 editorial language and sends guests to a focused `/ama/book` flow. Guests select one or more topics, explain what would make the hour valuable, choose a genuinely available time in their own time zone, choose Google Meet or Tencent Meeting, and complete Stripe-hosted Checkout. The start time is held for 15 minutes. A verified Stripe event creates the Booking, then durable work finalizes the calendar event, meeting link, confirmation, reminders, and private Manage Link. Guests never create accounts. An owner-only AMA admin area manages weekly availability, Google Calendar connection, Bookings, Alternate Time Requests, refunds, provider retries, and recovery. ## User Stories 1. As a visitor, I want to understand the AMA offer, price, duration, and cancellation terms, so that I can decide with confidence. 2. As a visitor, I want complete Chinese and English content, so that either locale feels first-class. 3. As a visitor, I want concise evidence of Cali's relevant experience, so that I can judge fit without reading a résumé. 4. As a visitor, I want readable anonymous testimonials, so that I can understand outcomes previous guests received. 5. As a guest, I want to select multiple topics including “Something else,” so that the conversation does not feel artificially constrained. 6. As a guest, I want to explain what would make the hour valuable and add optional links, so that Cali can prepare. 7. As a guest, I want slots shown in my detected time zone with a visible selector, so that I do not perform manual conversion. 8. As a guest, I want to see only times that satisfy Cali's availability, calendar conflicts, notice, horizon, buffers, holds, and existing Bookings. 9. As Cali, I want recurring availability interpreted in Asia/Taipei, so that my working hours remain predictable. 10. As Cali, I want 24 hours of notice, a rolling 30-day window, and 15-minute buffers before and after each session. 11. As a guest, I want my start time held for 15 minutes during Checkout, so that another person cannot take it while I pay. 12. As a guest, I want an authoritative hold countdown and automatic release after abandonment. 13. As a guest, I want to pay through Stripe-hosted Checkout, so that card entry is trustworthy. 14. As a guest, I want Google Meet selected by default and Tencent Meeting available as an alternative. 15. As a Tencent Meeting guest, I want the Tencent link carried in a Google Calendar invitation. 16. As a guest, I want payment confirmation based on a verified Stripe event, not a browser redirect. 17. As a guest, I want a paid Booking to show “being finalized” when a provider is temporarily unavailable, so that a recoverable failure does not look like a lost purchase. 18. As Cali, I want provider work retried idempotently, so that recovery cannot duplicate Bookings, meetings, events, refunds, or emails. 19. As Cali, I want unresolved failures visible in admin with manual retry, repair, and refund actions. 20. As a guest, I want immediate confirmation plus reminders 24 hours and 1 hour before the session. 21. As a guest, I want a private Manage Link, so that I can manage the Booking without an account. 22. As a guest, I want to reschedule until 24 hours before the session using freshly checked availability. 23. As a guest, I want a full automatic refund when I cancel at least 24 hours before the session. 24. As a guest, I want the no-automatic-refund policy inside 24 hours explained before payment. 25. As Cali, I want to grant manual refund exceptions. 26. As a guest, I want to request another time when no available slot works, without paying or reserving inventory. 27. As Cali, I want Alternate Time Requests separate from paid Bookings. 28. As Cali, I want owner-only magic-link authentication without a permanent identity vendor. 29. As Cali, I want to configure weekly Availability Windows without deploying code. 30. As Cali, I want to connect Google Calendar and see its current connection status. 31. As Cali, I want to inspect upcoming and past Bookings, Booking Briefs, payment status, meeting details, and lifecycle history. 32. As Cali, I want to cancel, reschedule, refund, or retry a Booking from admin. 33. As Cali, I want Booking Brief text and supporting links deleted 90 days after the session. 34. As Cali, I want minimal financial and Booking records retained for reconciliation after private context is deleted. 35. As Cali, I want aggregate funnel events without names, email addresses, topics, URLs, Booking Briefs, or payment identifiers. 36. As a keyboard user, I want to complete every public and management action without a pointer. 37. As a touch user, I want 44px controls and no hover-only behavior. 38. As a motion-sensitive user, I want the complete experience with reduced motion enabled. 39. As a visitor, I want `/ama` included in site navigation, metadata, and the sitemap as a native v2 route. 40. As Cali, I want provider credentials, raw tokens, and signing secrets to remain server-only. 41. As Cali, I want the system to prevent concurrent guests from claiming overlapping effective intervals. 42. As a guest, I want clear inline validation and recovery instructions when my hold expires, payment fails, or a slot becomes unavailable. ## Implementation Decisions - AMA Session is one US$99, 60-minute product with no public student verification or regional price. - The editorial service page and focused booking flow are separate routes. - Content is fully bilingual using the site's static-DOM locale model, including locale-correct accessible names and metadata. - The public page uses the existing narrow editorial column, 14px hierarchy, technical-print vocabulary, tokenized themes, and restrained transform/opacity motion. - The v1 Alipay QR, Cal.com link, screenshot presentation, and broad résumé treatment are not ported. - Existing testimonials become faithful, concise, anonymous text excerpts. - Intake is name, email, multi-select topics, one required Booking Brief, optional URLs, and meeting-provider choice. File uploads are excluded. - Availability combines owner-defined weekly Availability Windows with Google free/busy, active Slot Holds, and Bookings. - Google Calendar is the only source of date-specific unavailability. No second exceptions editor is added. - Slot policy is 24-hour notice, 30-day horizon, and 15-minute buffers. Slot computation is deterministic and time-zone aware. - A Slot Hold lasts 15 minutes. The server is authoritative; the browser countdown only reflects it. - The booking write path uses a database exclusion guarantee so overlapping holds and Bookings cannot both succeed. - Stripe-hosted Checkout is the only payment-entry surface. A signed Stripe webhook is authoritative for completion. - Stripe provider event IDs and idempotency keys are persisted before dispatching side effects. Duplicate and out-of-order events are safe. - A paid Booking may be Finalizing while recoverable provider work is pending. - External side effects use durable operations with leases, retry counts, next-attempt times, and terminal failure states. An authenticated Vercel Cron endpoint drives scheduled work. - Google OAuth uses state and PKCE, encrypted refresh credentials, least-privilege calendar scopes, and server-only token handling. - Google Meet is created through the Calendar event conference contract. - Tencent Meeting reuses the proven ZATS MCP pattern: server-only URL and token, `X-Tencent-Meeting-Token`, pinned skill version, tool discovery, schema-aware argument mapping, and defensive result parsing. - Tencent Bookings receive an ordinary Google Calendar event containing the Tencent URL. - Meeting providers share a small create contract and explicit lifecycle capabilities. Tencent cancellation limitations remain visible provider constraints. - Guests use high-entropy Manage Links backed by stored token hashes. Raw tokens are never stored. - Rescheduling preserves Booking and payment history while moving the effective session time. - Automatic refund eligibility is calculated from cancellation time and session start. Inside 24 hours requires owner action. - Transactional mail uses Resend. Confirmation, reminder, and operational delivery is idempotent and retryable. - Owner authentication follows ADR-0004: one allowlisted email, rate-limited request, hashed single-use 15-minute token, and a signed secure httpOnly SameSite=Lax session cookie of about 30 days. - The owner admin manages availability, Google connection, Bookings, Alternate Time Requests, refunds, provider failures, and retries. - Booking Brief text and URLs are purged 90 days after the session by scheduled durable work. - Funnel analytics contain only anonymous aggregate context. - One server-only environment contract validates all required provider credentials and signing keys. - AMA migrations preserve production subscriber and newsletter tables; they do not recreate, drop, or rename them. ## Testing Decisions - Tests assert public behavior and durable state transitions, not internal call order. - The highest stable seam is the public booking and signed-management HTTP contract against a real test database, with mocked providers and an injected clock. - Slot calculation has deterministic tests for time zones, DST, notice, horizon, buffers, busy intervals, active holds, and Bookings. - Concurrency tests prove two simultaneous overlapping claims cannot both succeed. - Stripe tests cover signature validation, duplicate and out-of-order delivery, abandoned Checkout, expired holds, provider failure, and eventual finalization. - Google OAuth tests cover state and PKCE verification, denied scope, callback failure, revoked credentials, and secret non-disclosure. - Meeting adapter contract tests cover Google and Tencent creation, defensive parsing, idempotency, timeout, retryable failure, and terminal failure. - Reminder tests cover due selection, lease recovery, transient failure, retry cap, and duplicate suppression. - Authentication tests cover allowlisting, rate limiting, expiry, one-time token consumption under concurrency, session expiry, and cookie flags. - Management tests cover rescheduling conflicts, refund boundaries, manual exceptions, cancellation, and unauthorized or expired Manage Links. - Retention tests prove private brief content is removed after 90 days without deleting required financial records. - UI tests cover bilingual content, locale switching mid-flow, persistent labels, inline errors, keyboard completion, focus restoration, touch targets, reduced motion, and Finalizing states. - Small browser journeys cover successful Google Meet and Tencent Meeting Bookings with provider fakes. - Build, typecheck, migration validation, localization, domain, route, and browser tests form one release gate. ## Out of Scope - Multiple durations or public products - Public discounts, subscriptions, packages, coupons, or regional prices - Guest accounts or a general customer dashboard - Group sessions, round-robin hosts, or multiple owner calendars - File uploads, recording, transcription, or AI-generated notes - A date-exceptions system outside Google Calendar - Automatic approval of Alternate Time Requests - Native card-entry UI - Newsletter migration or editor work beyond auth dependencies - Replacing Google Calendar as the availability source - Guaranteed Tencent room deletion when the provider exposes no cancellation tool ## Further Notes - Cali will connect production Stripe, Google, Resend, Tencent MCP, database, rate-limit, encryption, and signing credentials. - Production cutover remains subject to the existing Next.js stable and URL-compatibility gates. - Reuse the behavior of ZATS's Tencent MCP adapter while adding durable idempotency and recovery coverage that ZATS does not currently have.