E-commerce & Payments Template - Chronological Implementation TODO Plan (Template repo: ai-eng-template-ecommerce-payments) ============================================================================== INTENT ============================================================================== A small, focused e-commerce template for product brands with a tight catalog (typically 5-200 SKUs), one or two product variants per item, Stripe-powered checkout, and an operator console for orders and inventory. The template deliberately stops short of marketplace, multi-vendor, B2B procurement, or heavy ERP integration; for those, the studio builds bespoke. OUT OF SCOPE: multi-vendor marketplaces, complex tax/VAT engines beyond Stripe Tax, subscription bundles with metered billing, dropshipping orchestration, B2B quoting/RFQ. High-level summary - Goal: a forkable small-shop starter with Stripe Checkout, an order pipeline, an inventory ledger, and an operator console. - Platform target: Next.js App Router, Firebase Auth + Firestore + Cloud Functions + Cloud Storage, Stripe Checkout + Stripe Tax (optional), Resend or SendGrid for transactional email. - Performance/security target: zero client-side trust on price; the cart total is always recomputed server-side at checkout creation time. - Rough delivery estimate: 3-6 weeks per customer customization. Phase 0 - Scope freeze, product definitions, and delivery guardrails (Effort: Medium) Dependencies: customer discovery workshop output. [ ] Freeze template scope: - [ ] confirm the template ships with: product catalog, product detail page, cart (server-persisted for signed-in users, local for guests), Stripe Checkout, order confirmation page, order status emails, inventory ledger, operator console (orders, inventory, products, discounts). - [ ] confirm explicit OUT-OF-SCOPE: marketplaces, complex tax engines, subscriptions, B2B quoting, multi-warehouse. Phase 1 - Repository skeleton, tooling, and CI (Effort: Small) Dependencies: scope freeze. [ ] Standard skeleton mirroring the SaaS MVP template, plus: - [ ] image pipeline pre-configured for product images (`next/image` + Cloud Storage). - [ ] currency helpers using `Intl.NumberFormat` plus a `Money` value object that stores amount in minor units (cents) and never floats. Phase 2 - Design system and token foundation (Effort: Small) Dependencies: Phase 1. [ ] Tokens and primitives plus shop-specific components: - [ ] ProductCard, ProductDetail, PriceLabel, VariantSelector, AddToCart, MiniCart, CartLine, CheckoutSummary, OrderStatusBadge. Phase 3 - Catalog data model (Effort: Medium) Dependencies: Phase 1. [ ] Firestore collections: - [ ] `products/{productId}` (slug, name, description, brand, mainImage, gallery, basePriceMinor, currency, taxCategory, status, publishedAt). - [ ] `productVariants/{productId}/variants/{variantId}` (sku, option1, option2, priceMinor, stock). - [ ] `inventoryLedger/{ledgerId}` (variantSku, delta, reason, actor, timestamp) - append-only. - [ ] `discounts/{code}` (kind: percent|fixed, value, minSubtotal, startsAt, endsAt, usageLimit, usageCount). - [ ] `carts/{cartId}` (uid?, sessionToken?, lines, lastTouched). - [ ] `orders/{orderId}`. [ ] Security rules: - [ ] anonymous users can read published products only. - [ ] writes to inventory and orders go through Cloud Functions only. Phase 4 - Catalog UI (Effort: Medium) Dependencies: Phase 3. [ ] Public routes: - [ ] `/`, `/shop`, `/shop/[slug]`, `/categories/[slug]` (if categories enabled), `/cart`, `/checkout/return`, `/account/orders` (signed-in). [ ] Static generation: - [ ] product pages use ISR with revalidation on `product.published` event. [ ] SEO and structured data: - [ ] JSON-LD `Product`, `Offer`, `AggregateRating` (if reviews enabled), `BreadcrumbList`. Phase 5 - Cart and checkout (Effort: Large) Dependencies: Phases 3-4. [ ] Cart: - [ ] guest carts persisted to `localStorage` with a server-side `carts` mirror keyed by `sessionToken`. - [ ] signed-in carts persisted under the user uid. [ ] Checkout: - [ ] `createCheckoutSession` Cloud Function rebuilds the cart from the server-side `carts` document, recomputes totals (NEVER trusts the client's price), and creates a Stripe Checkout session. - [ ] Stripe Tax optional, configurable per environment. - [ ] return URL flips the order from `pending` to `paid` via the Stripe webhook, NOT via the browser redirect. Potential gotchas: - [ ] the only acceptable source of truth for payment status is the Stripe webhook; the return URL is just UX. Phase 6 - Order pipeline and inventory (Effort: Large) Dependencies: Phase 5. [ ] Stripe webhook handler: - [ ] on `checkout.session.completed`: create `orders/{orderId}`, decrement inventory atomically with the ledger write, send confirmation email. - [ ] on `charge.refunded`: reverse the ledger entries, write a credit note, send a refund email. - [ ] idempotency keyed off `event.id`. [ ] Order statuses: `pending`, `paid`, `packed`, `shipped`, `delivered`, `refunded`, `cancelled`. [ ] Operator console: - [ ] `/operator/orders` with filter and bulk actions. - [ ] `/operator/inventory` showing per-variant stock and the ledger. - [ ] `/operator/products` to manage catalog. - [ ] `/operator/discounts` to manage discount codes. Potential gotchas: - [ ] inventory decrement and ledger write MUST be in the same transaction; a partial failure that decrements stock without ledger entry is a real data-corruption bug. Phase 7 - Transactional emails (Effort: Small) Dependencies: Phase 6. [ ] Email templates: order confirmation, shipment notification, refund confirmation, abandoned-cart reminder (optional, feature-flagged). [ ] Sender configured via `EMAIL_FROM` env var; reply-to configurable per customer. Phase 8 - SEO and merchandising (Effort: Medium) Dependencies: Phase 4. [ ] Sitemap covers every published product; refresh on publish. [ ] OpenGraph image per product generated at build/publish time. [ ] Optional review surface (`reviews/{productId}/items/{reviewId}`) with moderation queue. Phase 9 - Observability, security, accessibility (Effort: Medium) Dependencies: Phases 5-7. [ ] App Check, structured logs with `orderId` correlation, CSP/HSTS, Lighthouse a11y >= 95. [ ] PCI scope: card data never touches the studio's servers; Stripe Elements or Stripe-hosted Checkout only. Phase 10 - Testing strategy (Effort: Medium) Dependencies: Phases 3-9. [ ] Vitest unit tests on cart recomputation (most-buggy area) covering: discount stacking, expired discount, out-of-stock variant, currency rounding, mixed-tax cart. [ ] Firestore Security Rules tests for anonymous catalog reads. [ ] Playwright smoke: browse catalog, add to cart, checkout with Stripe test card, verify webhook flips status, verify inventory ledger entry. Phase 11 - Customization handbook (Effort: Small per customer) Dependencies: Phases 0-10. [ ] `docs/customization.md` records, per customer: - [ ] catalog size and variant axes. - [ ] currency, tax strategy (Stripe Tax / manual / none), shipping strategy (flat / weight-based / pickup only). - [ ] discount code policy. - [ ] email provider and brand templates. - [ ] return/refund policy text. - [ ] data retention and GDPR posture. Phase 12 - Public showcase integration (Effort: Small) Dependencies: this plan, ecosystem Phase 26. [ ] Register in `apps/web/src/lib/showcase.ts` with id `ecommerce-payments`. [ ] Public staging deployed with a fictional catalog and Stripe test mode; embedded as a sandboxed iframe on `/showcase/ecommerce-payments`. [ ] The preview clearly labels Stripe test cards on the checkout page. [ ] The preview ledger and orders are wiped every 24 hours. Potential gotchas: - [ ] never enable Stripe live mode on the showcase preview; assert on every deploy that `STRIPE_MODE === 'test'`.