fix: close release preflight gaps

Route public health checks to the API, backfill and synchronize job opportunities, stabilize SPA smoke tests, and document operator-only production steps.
2026-07-31 20:18:30 +02:00
parent ce76046a29
commit 955182b7c2
18 changed files with 350 additions and 52 deletions
@@ -0,0 +1,60 @@
+# Stripe activation
+
+The application code is complete. Activate it in Stripe test mode first; test and live mode have
+different API keys, price ids, webhook endpoints/signing secrets, and customer data.
+
+Official references:
+
+- https://docs.stripe.com/subscriptions
+- https://docs.stripe.com/customer-management/integrate-customer-portal
+- https://docs.stripe.com/webhooks?lang=dotnet
+
+## Test-mode setup
+
+1. Create one recurring monthly Premium product/price.
+2. Enable the customer portal for subscription management and cancellation.
+3. Register `https://jobs.cesnimda.uk/api/billing/webhook` as an HTTPS webhook endpoint for:
+   - `customer.subscription.created`
+   - `customer.subscription.updated`
+   - `customer.subscription.deleted`
+4. Add the test-mode values to `/opt/job-tracker/shared/.env`:
+
+   ```text
+   STRIPE_SECRET_KEY=<test secret key>
+   STRIPE_PRICE_PREMIUM=<test recurring price id>
+   STRIPE_WEBHOOK_SECRET=<test endpoint signing secret>
+   ```
+
+5. Restart/redeploy the backend without printing those values.
+
+Never put the values in Git, chat, screenshots, issue text, or CI logs. Stripe requires the raw
+request body for signature verification; the implemented endpoint reads it before constructing the
+signed event.
+
+## Acceptance check
+
+Use a disposable, authenticated Jobbjakt account:
+
+1. Account settings reports billing enabled and offers Upgrade.
+2. Upgrade opens Stripe-hosted Checkout for the configured monthly price.
+3. Completing a Stripe test subscription returns to `/settings?billing=success`.
+4. The signed subscription webhook stores the Stripe customer/subscription/status and grants the
+   `Premium` role.
+5. `/api/auth/me` exposes Premium entitlements and the UI unlocks Premium capabilities.
+6. Manage billing opens the Stripe customer portal.
+7. Cancel in the portal and confirm an updated/deleted subscription webhook removes Premium when the
+   subscription is no longer active or trialing.
+8. Replay one event from Stripe Workbench and confirm role/state remain idempotent.
+
+## Live-mode cutover
+
+Repeat the product/price, portal, and webhook setup in live mode. Replace all three environment values
+as one change; never mix a test price or endpoint secret with a live API key. Complete one real
+low-risk subscription and cancellation, confirm the webhook delivery log is green, then remove the
+disposable account if it is no longer needed.
+
+## Rollback
+
+Removing all three environment values disables new Checkout/portal sessions without deleting billing
+history. Do not manually remove Premium roles while Stripe still reports an active subscription; fix
+webhook delivery and replay the authoritative subscription event instead.