SurfSense/_bmad-output/implementation-artifacts/deferred-work.md

# Deferred Work

## Deferred from: code review of story 3-5-model-selection-via-quota (2026-04-14)

- **stripe_subscription_id has no unique constraint** [surfsense_backend/app/db.py] — Column added without UNIQUE constraint. Should be enforced once Stripe integration (Epic 5) is implemented to prevent duplicate subscription mappings.
- **load_llm_config_from_yaml reads API keys directly from YAML file, not env vars** [surfsense_backend/app/config.py] — Pre-existing: YAML config stores API keys inline. Spec Task 1.2 says "đọc API keys từ env vars" but this is the existing pattern used throughout the project. To be refactored when security hardening is prioritized.

## Deferred from: code review of story 5-1 (2026-04-14)

- `ref` cast `as any` on Switch component in `pricing.tsx:99` — pre-existing issue, not introduced by this change. Should use proper `React.ComponentRef<typeof Switch>` type.

## Deferred from: code review of story 5-2 (2026-04-14)

- Webhook handler needs to distinguish `mode='subscription'` from `mode='payment'` in `checkout.session.completed` and update User's `subscription_status`, `plan_id`, `stripe_subscription_id` — scope of Story 5.3.
- Subscription lifecycle events (`invoice.paid`, `customer.subscription.updated/deleted`, `invoice.payment_failed`) not handled — scope of Story 5.3.
- `_get_or_create_stripe_customer` can create orphaned Stripe customers if `db_session.commit()` fails after `customers.create`. Consider idempotency key in future.
feat(story-3.5): add cloud-mode LLM model selection with token quota enforcement Implement system-managed model catalog, subscription tier enforcement, atomic token quota tracking, and frontend cloud/self-hosted conditional rendering. Apply all 20 BMAD code review patches including security fixes (cross-user API key hijack), race condition mitigation (atomic SQL UPDATE), and SSE mid-stream quota error handling. Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com> 2026-04-14 17:01:21 +07:00			`# Deferred Work`

			`## Deferred from: code review of story 3-5-model-selection-via-quota (2026-04-14)`

			`- stripe_subscription_id has no unique constraint [surfsense_backend/app/db.py] — Column added without UNIQUE constraint. Should be enforced once Stripe integration (Epic 5) is implemented to prevent duplicate subscription mappings.`
			`- load_llm_config_from_yaml reads API keys directly from YAML file, not env vars [surfsense_backend/app/config.py] — Pre-existing: YAML config stores API keys inline. Spec Task 1.2 says "đọc API keys từ env vars" but this is the existing pattern used throughout the project. To be refactored when security hardening is prioritized.`
feat(story-5.1): add subscription pricing UI with Stripe checkout integration Replace PAYG pricing tiers with subscription model (Free/Pro/Enterprise), enable Monthly/Yearly billing toggle, wire Pro CTA to Stripe checkout with authenticatedFetch, toast error feedback, double-click guard, checkout_url validation, and offline graceful degradation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-04-14 23:28:14 +07:00
			`## Deferred from: code review of story 5-1 (2026-04-14)`

			- `ref` cast `as any` on Switch component in `pricing.tsx:99` — pre-existing issue, not introduced by this change. Should use proper `React.ComponentRef<typeof Switch>` type.
feat(story-5.2): add Stripe subscription checkout with session verification Add POST /api/v1/stripe/create-subscription-checkout endpoint with get_or_create_stripe_customer (SELECT FOR UPDATE), plan_id→price_id mapping from env vars, active subscription guard (409), and session_id in success URL. Add GET /verify-checkout-session endpoint for server-side payment verification. Add /subscription-success frontend page with loading/verified/failed states. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-04-14 23:58:57 +07:00
			`## Deferred from: code review of story 5-2 (2026-04-14)`

			- Webhook handler needs to distinguish `mode='subscription'` from `mode='payment'` in `checkout.session.completed` and update User's `subscription_status`, `plan_id`, `stripe_subscription_id` — scope of Story 5.3.
			- Subscription lifecycle events (`invoice.paid`, `customer.subscription.updated/deleted`, `invoice.payment_failed`) not handled — scope of Story 5.3.
			- `_get_or_create_stripe_customer` can create orphaned Stripe customers if `db_session.commit()` fails after `customers.create`. Consider idempotency key in future.