Setpoint Academy as a monthly-subscription academy system

Product

• Drag any card (court booking, academy group, individual) to a free court/time; drop on an occupied slot offers "swap courts".
• Conflicts use the existing coach and court rules and refuse with the reason; override needs a reason.
• Undo last move; keyboard and touch fallback (select card → arrows → Enter); every move is an audit entry.

Roles: manager may move; override is DECISION (Jose for coaching, Alvaro for courts). AUTO: conflict detection.

Technical

• Reuse PATCH /api/admin/lessons/[id] (moves the lesson and every court leg, runs findCourtConflicts, 409 on clash) and PATCH /api/admin/bookings for court bookings; the handler branches on card type because the bookings route refuses lesson legs.
• dnd-kit v6 is already a dependency; the week grid is a clean function of tick index (30 min, 28 px) and court index; Calendar and Planning share the same grid components, so one implementation lands on both.
• Fix first: the lessons PATCH drops availability_override (editableFields omits it), so a move outside coach hours cannot carry an override today.
• No push to coaches exists; the move writes an audit row and, once J ships, a message.

Product

• A group has slots (weekday, time, duration, court preference, coach) and a class template.
• "Generate lessons" for a month; roster by package coverage; "needs package" members excluded unless overridden with a reason code.
• Lapsed members leave future rosters after the grace window; a waitlist offers released seats with a timed claim.

Roles: generate = manager (STANDING RULE); override = owner/admin (DECISION); waitlist offer = AUTO.

Technical

• Today academy_groups is roster + free-text level only, explicitly not linked to classes or lessons (migration header 20260722032430).
• New academy_group_slots, academy_groups.class_id, lessons.academy_group_id; generation extends api/admin/lessons/recurring and its series cap must read the reservation-aware balance; two-slot groups spread seats across the month.
• Persisted package selection on the seat; advisory lock per package in the insert; lesson_waitlist modelled on the parked programs waitlist (program_enrollments, timed claim).
• Nightly dispatch_roster_sync (pg_cron) with the paid-seat exclusion and a 24 h cutoff; roster changes already emit OpenRally events (emit_group_lesson_player_event), so consumers see them.

Product

• Student page: package, balance, reserved, consumed, history with reasons and actors.
• Lesson page: attendance state per player; one tap "Done" / "No-show" for the coach; manager correction within 48 h with a reason.
• The four visual states are the language everywhere: outline, filled, struck, faded.

Roles: mark done = coach or staff (D8); correction = manager with reason; auto no-show = club setting, off until check-in is habitual (D9).

Technical

• lesson_players.attendance_state (CHECK), attendance_marked_at/by; new RPC mark_attendance writes the consume row in the same transaction (DEC-319/320 pattern) with the flavour in metadata.
• academies.ledger_mode flag; on_add keeps today's path; on_done makes create_lesson_atomic and the group-seat RPCs reserve instead of consume; exhaustion moves to done time; the PWA check-in (qr_checkin_screen.dart) gains the two buttons via the existing coach RPC family.
• Renewal boundary: a seat consumes under the period of the lesson date; reset_package_sessions must not zero next-period reservations.
• Backfill and switch: §12 of the spec; inverse migration written and tested first.

Product

• Subscriptions view: state per student, period, next request, last payment, pause before the 26th.
• On the 1st the system issues every request with a payment link (card or PromptPay) and pay-at-club instructions; day 3 past due; day 7 freeze.
• Settings card with every rule visible.

Roles: issuing = AUTO; pause = DECISION (Alvaro) executed by Abby; a saved-card charge is opt-in per student, later.

Technical

• process-package-billing already rolls the cycle, writes payment_requests (unique per subject + period), queues reminders and advances next_billing_date; it grants no sessions and mints no link (AC-41 skips stripe_subscription_id rows, which keep their invoice.paid path).
• New: mint a Stripe Checkout/Payment Link per request (checkout_url), webhook checkout.session.completed → payments row (the POS bridge trigger fires) → settle request → grant sessions; past_due and paused states; dispatcher selects active or past due; resume re-anchors.
• No off-session charge: customers.stripe_customer_id exists but no SetupIntent or saved method is ever collected, and most academy money is cash, transfer or PromptPay (red team). Opt-in saved-card charge later, with an idempotency key from (package, period) and a persisted attempt row against the hourly re-fire.
• Gate: Setpoint's Stripe on live keys for Pad Thai Padel.

Product

• Step 1 (Academy Health) shows the proposed bridge and tier on the worklist before anything is charged.
• Step 3 puts the same computation inside billing: the first request of a mid-cycle start carries the bridge amount and tier; then full price.
• Session banks never prorated; 7 days or fewer waits for the 1st.

Roles: the number is AUTO; Abby sends what the list shows (STANDING RULE); any other amount is Alvaro's DECISION.

Technical

• compute_bridge(price_amount, days_to_next_1st) in packages/common and mirrored in SQL; payment_requests.bridge_tier, bridge_days; proration_mode setting (none | weekly_quarters).
• The current function writes amount_amount = template.price_amount unconditionally; the branch is new. Amounts are satang.
• PRORATE codes stay on Alvaro's external Stripe links until Setpoint mints its own links (D); then the bridge is the request amount itself and codes are not needed.
• Gate: one real cycle (1 Oct) checked against Step 1's list.

Product

• Email keeps sending (Resend). WhatsApp moves to the Meta Cloud API with approved utility templates; the wa.me manual lane stays as fallback.
• Schedule tied to billing states: day 26 renewal, day 1 request, day 3 past due, day 7 freeze notice.
• Queue with status per message and error text; opt-out respected.

Roles: AUTO sends approved templates; anything custom is Abby via wa.me (STANDING RULE); NEVER message an opt-out.

Technical

• Provider seam exists (apps/admin/src/lib/messaging/providers/): email real; whatsapp-manual returns the wa.me link and records sent_manual; whatsapp-cloud throws by design (DEC-323).
• Requirements: verified Meta business, dedicated number, approved templates (utility category), per-message pricing; the free 24 h reply window ends 1 Oct 2026, so every reminder is a paid template message.
• payment_reminders already has channel, template key, status, idempotency (request, template, channel, instant); new template keys and an opt-in table.
• Gate: Meta approval. If it slips, everything still works on the manual lane.

Product

• Nightly report: payments ↔ package or lesson ↔ POS row; unmatched, duplicates (same amount within 3 days), POS variance.
• Attach a Stripe payment to a recorded payment, or mark cash, with a reason.

Roles: matching = AUTO; attaching = Abby (STANDING RULE); write-offs = Alvaro (DECISION).

Technical

• Step 1 ships the in-database version (payments without a provider reference, duplicates). The persistent version is a report table refreshed nightly, keyed on payments.stripe_payment_id and payment_requests.checkout_id, joined to the POS mirror (pos_orders channel academy).
• Partial payments: the POS bridge mirrors each payments row as a complete order; the report flags requests with more than one payment.
• Real Stripe verification needs live keys (gate); until then the control panel's restricted-key pull is the source.

Product

• Per student per month: training without paying, and paid but not training; badge on the student page; month toggle.
• Primary action: issue requests to the unpaid list.

Roles: AUTO flags; Abby issues (STANDING RULE); exceptions are Alvaro's.

Technical

• Step 1's tab first (read-only join, Group Coaching name rule included). Persistent: a view over lesson_players × lessons × player_packages × payment_requests, materialised nightly, plus one badge component.

Product

• Lead → contacted → trial → converted or lost; source (website Sheet, Instagram, walk-in, referral), owner, next action and due date, waiting days.
• Convert creates no duplicate person: links to the existing customer by phone or email or creates one.
• Import from the website Sheet with phone dedupe.

Roles: Abby owns every lead (D12); price exceptions escalate to Alvaro.

Technical

• No lead concept exists; facility_customers is not in production (two migration headers record it), so leads link to users/customers through crm_customer_directory semantics, not to that table.
• New leads and lead_events; conversion RPC; importer for the Sheet CSV export the control panel already reads.

Product

• Message a lesson's players or a group from the page: templates for reminder, schedule change, cancellation; per-recipient channel; opt-outs greyed.
• Sent history per lesson. No push in this release (D14): email and WhatsApp.

Roles: templates = AUTO or STANDING RULE; custom text = Abby; NEVER an opt-out.

Technical

• Reuses message_templates (one seeded key today) and the provider seam; adds keys, a message log, and an audience resolver from lesson_players / academy_group_members.
• Push does not exist anywhere (the coach PWA is Flutter with no messaging); deferred.

Product

• Export bookings, transactions (payments + ledger), lessons; filters: date range, type, coach, group, package; columns include total price and coach hours; per-coach hours summary.

Roles: any staff role; read-only.

Technical

• Zero CSV export in admin today; POS has one and the shared csvCell helper is importable. Streaming endpoint, 12-month cap, no stored files (D15). Coach hours = lesson duration, not a timesheet.

Product

• Who changed what, before and after, on rosters, packages, payments, schedule moves, attendance corrections; reason shown; filter by entity, actor, date; read-only; CSV.

Roles: owner and admin read; every write feature above writes.

Technical

• No admin-wide log exists; pos_activity_logs swallows errors by design and a decision entry rejects that for anything with stakes. New admin_audit_log written inside the same transaction by a helper; the reversal pattern on payments.reverses_payment_id is the model.
• Ships early (PR 4) because B, C, A and D depend on it.

Product

• Card contract. Every card on the Staff PWA calendar, the admin calendar and the admin lists states five things: what it is (Court · Private lesson · Group coaching · Event · Match), who coaches it or Unassigned, who is on it as confirmed / capacity, how many are on the waitlist, and where it came from (Setpoint or TPS) with its payment state. Same fields, same order, on every screen; a card never shows "Guest" for a coaching or event row.
• Type chosen at creation. Creating from a slot asks "what is this?" first. Event is a program occurrence that mirrors to TPS so players join there; group coaching is a class with a roster; court stays a court booking. Match is created by players in TPS and only shown. The internal "event" guest label is retired once every event is a program.
• Filter by coach in both apps, with Me and Unassigned chips; the type filter gains Group coaching and Events. Unassigned is a worklist, not a state: Abby owns a daily "Unassigned" queue on Academy Health, and any event within 48 h with no coach is named in the daily schedule message.
• Add a player from any card in the PWA by name, phone or email, or as a guest. A full event never overbooks from the phone: the player goes to the waitlist with a position, and promoting past capacity is an owner/admin confirm with a reason. Staff and manager add to any card; a coach adds to their own lessons only, never to an event (D20). Payment shows as one of three chips, Paid on TPS · Due at desk · Unpaid, so a prepaid player is never charged twice and a walk-in who owes is never waved through.
• Coach on events, both ways. Assigning a coach on an event in Setpoint makes them a co-organiser on the TPS event. A TPS co-organiser whose email matches a Setpoint coach is suggested, and becomes the coach once that coach or an admin confirms the link the first time; after that the pair is remembered. "Reassign coach" is one action that updates both sides together, so a late Jose covered by Elisabeth shows Elisabeth on TPS within the minute.
• Events created on TPS are imported as programs marked from TPS with roster and waitlist read from TPS, read-only until the club switches event creation to Setpoint (D19).

Roles: AUTO card fields, source, waitlist position, coach match by email, the unassigned worklist · STANDING RULE (Abby) add players, assign the coach the schedule names, clear the Unassigned queue daily · DECISION Jose picks the coach when two are free and confirms a new coach link; Alvaro decides when event creation moves to Setpoint and any overbook past capacity · NEVER the software charges a player added at the desk, overbooks from the phone, deletes a TPS registration, or changes a coach without an audit row.

Technical

• Staff PWA (apps/calendar_pwa, Flutter): widgets/filter_bar.dart offers Court / Coaching / Other and normalises every lesson-like type into coaching (_normaliseType, lines 35–36), so an event is "Court" or "Other"; it has no coach chip; services/data_service.dart already loads coaches (line 230), so the chip row is a filter on data the app holds. widgets/slot_action_sheet.dart (Book Court / Book Coaching / Set Availability, lines 120–147) gains Event and the private/group choice inside Book Coaching (classes.class_type is already fetched). widgets/booking_detail_sheet.dart shows Coach only when coach_name is set and its _PlayersSection only for lesson-linked bookings; it gains the five-field header, an events roster from program_enrollments, and an "Add player" sheet reusing the customer search from create_booking_sheet.dart. Fix first: booking_detail_sheet.dart prints notes raw, so the recurring-series tag reaches staff; strip it with the same regex the admin app uses (lib/recurring-bookings.ts). No push (D14): the unassigned worklist rides on the daily Slack schedule and Academy Health.
• Admin: lib/booking-category-filter.ts defines Court Booking / Events / Coaching where "events" is guest_booking_category='event'; it gains group (lesson class_type='group') and event (program occurrence) predicates, and a coach multiselect beside calendar-category-filter (testid calendar-coach-filter). calendar-grid.tsx already carries coach_name and player_count on cards; it adds capacity, waitlist and source. Programs have no per-occurrence row: the mirror emits one session per program from program_next_occurrence (earliest slot from today, 20260616000100 lines 37–52, 92–131). So an americano or first-time padel is a one-day program (one row = one occurrence) and a recurring clinic renders per date with an occurrence key program_id + date; a true occurrence table is a later decision, called out under D19.
• Events = programs. programs (types clinic / league / round_robin / camp / group_coaching / other, instructor_id, max_participants, court_id) and program_enrollments (enrolled / waitlisted / cancelled, waitlist_position) are already two-way with TPS through OpenRally: program_session_payload mirrors out, confirm_program_enrollment and cancel_session_enrollment_by_guest take TPS joins and leaves, and admin enrolls emit session_joined / session_left to TPS event_participants (migration 20260617140000). New: programs.source and programs.external_event_id (M-M1). Echo guard: the outbound mirror stamps external_event_id from the TPS acknowledgement in the same transaction and the importer skips any TPS event carrying Setpoint's origin marker, so a mirrored event can never come back as a second program. Capacity and waitlist have one writer: program_enrollments once source='setpoint', TPS once source='tps'; TPS deleted=true maps to a cancelled program, never a delete. americano and first_time added to program_type.
• Coach both ways. program_session_payload carries no instructor today (zero mentions in 20260616000100 and 20260616120000); M-M3 adds instructor (id, name, email) to the payload and TPS maps it to event_organizers by coach email, the same convention the daily schedule bot already uses. Inbound, a co-organiser email that matches coaches only suggests: instructor_id is set when the coach or an admin confirms the link once (email equality is not identity: TPS users have no Setpoint auth row), and the confirmed pair is stored so the next event matches automatically; no match leaves the card Unassigned with the name shown. emit_program_event inserts into or_events with no dedupe key (20260616000100 lines 171, 226), so the instructor change gets a "did it actually change" guard before it emits.
• Source on bookings. Setpoint bookings carry no TPS reference (TPS holds booking_third_party_references); M-M2 adds bookings.source ('setpoint' | 'tps') written by the OpenRally confirm RPC so a court card can say where it came from. Payment state reads the existing payment_status / payment_method; a player added at the desk is pay_at_venue until Abby records the payment.
• Roles and tests. Add-player uses the existing coach and staff RLS on lesson_players (20260721091646); for events, program_enrollments INSERT/UPDATE is granted to owner and admin only today (initial schema lines 9439, 9650), so M-M4 adds a scoped policy for manager and staff on the enrollment columns only (never external_payment_ref or hold_expires_at); coaches get no write on events and are limited to lessons where lessons.coach_id is theirs. Playwright: one spec per surface with data-testid on card fields (card-type, card-coach, card-players, card-source).