Care Package Module - Feature List

1. Feature Overview

Care Package is a service contract attached to a physical product purchase. A care package grants the buyer a set of features (pick_drop, repair, service, priority_support, diagnostics, on_site, parts_coverage, warranty_extension) for a fixed duration.

Each care package has a URL-safe slug auto-generated from its name (e.g., "Basic Care" → "basic-care"). Historical slugs are preserved in care_package_slug_history to support SEO-preserving URL redirects. An optional link to a shared seo record enables per-package meta title, description, Open Graph tags, Twitter card metadata, and JSON-LD structured data.

Supported product type: care_package (productKind on products table).

Purchase model: customer selects a care package + pricing tier for a specific cart item, then checks out normally. Payment success triggers subscription creation and activation.

Subscription lifecycle: pending_activation → active → expired (or cancelled / suspended).

2. Route Ownership and Surfaces

3. Admin Feature Matrix

Admin Care Packages

Admin Subscriptions

Admin Redemptions

4. Customer/Mobile Feature Matrix

5. Key Business Rules

• Eligibility is defined per care package via care_package_eligibility_rules. Rules use a dimension (category, subcategory, brand, brand_series, product, or price_range) and a mode (include/exclude).
• One care package per cart item — cartCarePackageItems has unique index on (cart_item_id) — one per cart item.
• carePackageSnapshot and pricingSnapshot are written at subscription creation and are immutable after that point. They capture the care package definition and pricing tier at purchase time.
• Subscription activation is triggered by the BullMQ job care_package.activate_subscription dispatched on order payment success. See subscription-lifecycle.mdx.
• Feature quota enforcement: care_package_feature_usage tracks usedCount per (subscriptionId, featureType). Raise-time check compares usedCount against usageCount in the snapshot.
• isUnlimited = true features skip quota checks entirely.
• Redemption status transitions are strictly gated — see redemption.mdx for VALID_STATUS_TRANSITIONS table.
• suspend requires status = "active". unsuspend requires status = "suspended". manualActivate requires status = "pending_activation".

6. Subscription Status State Machine

pending_activation
       │  ← order.payment_success (BullMQ activate job)
       ▼
     active ──────────────────────────────► expired  (daily sweep OR expiryDate ≤ today)
       │                                      ▲
       │  ← admin suspend                     │ unsuspend when expiryDate past
       ▼                                      │
   suspended ─────────── unsuspend ──────── active
       │
       │  ← order cancel / admin cancel job
       ▼
   cancelled

   (also: any active/pending → cancelled via care_package.cancel_subscription job)

Full state machine detail: subscription-lifecycle.mdx.

7. Redemption Request State Machine

pending → accepted → in_progress → completed
pending → in_progress → completed
pending → in_progress → rejected
pending → rejected
accepted → completed
cancelled  (terminal, customer-initiated from pending)

Full state machine detail: redemption.mdx.

8. Error UX Mapping

9. Integration Flows

9.1 Care Package Purchase Flow

1. Customer calls GET /api/mobile/care-packages/available to browse eligible care packages for a product.
2. Guest customers may include { carePackage: { carePackageId, pricingTierId } } on the product line in POST /api/mobile/cart/guest/quote for read-only totals.
3. After login, POST /api/mobile/cart/sync persists the same optional care package selection while replacing the authenticated cart from the guest/local snapshot.
4. Authenticated customers with an existing cart item may also call POST /api/mobile/cart/items/:cartItemId/care-package with { carePackageId, pricingTierId }.
5. Backend validates: cart item exists + belongs to customer when using the direct add endpoint, product is physical, care package is active, eligibility rules match the product, and tier is active. Writes cartCarePackageItems row with selected IDs and unitPrice.
6. Customer proceeds to checkout (POST /api/mobile/orders/checkout). Order service reads cartCarePackageItems, creates order_item rows for each, and creates care_package_subscriptions rows with status = "pending_activation".
7. On payment success, order.payment_success BullMQ job runs. Processor enqueues care_package.activate_subscription job per subscription.
8. CarePackageProcessor.processActivation() sets status = "active", calculates startDate / expiryDate from pricingSnapshot.durationMonths, schedules 30d and 7d reminder jobs.

9.2 Redemption Flow

1. Customer calls POST /api/mobile/me/care-packages/:subscriptionId/requests with { featureType, description, attachmentUrls? }.
2. Backend validates: subscription is active, feature is enabled in snapshot, quota not exceeded.
3. Admin calls PUT /api/admin/care-package-redemptions/:id/status with { status: "accepted" }.
4. On accept: DB transaction increments care_package_feature_usage.usedCount and updates request status.
5. Admin advances through status machine (in_progress, completed).

10. Release/QA Checklist

• GET /api/mobile/care-packages/available returns only active packages matching product eligibility rules.
• Adding a care package to a cart item enforces 1-per-item constraint.
• Guest quote and login sync preserve selected care package add-ons.
• Cart total includes care package prices; care package lines do not trigger shipping.
• Checkout creates care_package_subscriptions rows with status = "pending_activation".
• Payment success enqueues care_package.activate_subscription jobs.
• Activation sets status = "active", calculates dates from pricingSnapshot, schedules reminders.
• Expiry sweep runs daily (cron) and bulk-expires active subscriptions past expiryDate.
• Customer GET /api/mobile/me/care-packages/:id returns remainingDays and feature slot usage.
• Redemption raise validates active status, feature enabled, quota.
• Admin accepted transition increments carePackageFeatureUsage.usedCount in a transaction.
• suspend/unsuspend/manualActivate enforce correct status guards.
• unsuspend restores to active if expiryDate future, expired if past.
• Ownership disclosure: customer GET /me/care-packages/:id returns same 404 code for not-found and wrong-owner.