|
| 1 | +## /speckit.specify |
| 2 | + |
| 3 | +StormCom has three critical issues: (1) insecure checkout flow (no auth enforcement, trusts client-submitted prices, incomplete transactional boundaries, missing payment verification), (2) storefront multi-tenancy bypass (hardcoded storeId, inconsistent domain-based store resolution propagation), and (3) a non-functional newsletter signup path. Additional high/medium issues include inconsistent schema arrays vs strings, ad hoc error handling via string matching, absence of a formal caching/tag invalidation strategy, incomplete Prisma multi-tenant middleware enforcement, and partial transaction scope in certain service flows. |
| 4 | + |
| 5 | +This specification defines the objectives, constraints, acceptance criteria, and success measures for remediating these issues while aligning with Next.js 16 (App Router + proxy), React 19 Server Components-first design, strict TypeScript, Prisma tenant isolation, WCAG 2.1 AA accessibility, and performance budgets. |
| 6 | + |
| 7 | +Goals & Objectives: |
| 8 | +1. Secure checkout: Enforce authentication, re-verify prices server-side, validate payment intents, wrap all write operations in atomic transactions. |
| 9 | +2. Enforce multi-tenancy storefront: Implement canonical store resolution (domain/subdomain -> storeId) and eliminate all hardcoded identifiers. |
| 10 | +3. Implement functional newsletter signup (Server Action + validation + rate limit + audit logging + consent record creation). |
| 11 | +4. Standardize error handling (Error class hierarchy, typed error codes, unified API response pattern). |
| 12 | +5. Align data schema (migrate inconsistent string[]/string fields, add missing deletedAt where necessary, consider JSON column migrations for PostgreSQL). |
| 13 | +6. Strengthen Prisma middleware (guaranteed storeId injection for all tenant-scoped models; audit missing models). |
| 14 | +7. Expand transactional integrity (checkout, inventory adjustments, discount application, payment capture/refund flows). |
| 15 | +8. Introduce caching strategy (cache tags + revalidateTag w/ second arg + optional Cache Components adoption plan, selective stable fetch caching with "use cache"). |
| 16 | +9. Performance & accessibility validation (maintain budgets: LCP<2.5s mobile, CLS<0.1, JS bundle<200KB gzipped; Axe core zero blocking violations; multi-tenant queries optimized). |
| 17 | +10. Comprehensive test coverage uplift (≥80% services, 100% utilities; E2E coverage for checkout, tenancy resolution, newsletter; error handling cases; migration tests). |
| 18 | +11. Establish API middleware pipeline (auth, rate limit, request validation, structured logging with requestId header) eliminating string-based error matching. |
| 19 | +12. Correct REST semantics & response consistency (PUT requires full resource; PATCH partial; remove inconsistent `success` flags; uniform error payloads). |
| 20 | +13. Implement streaming CSV export with size limits & background job fallback for large order datasets. |
| 21 | +14. Elevate storefront SEO & accessibility (dynamic per-store metadata, Open Graph/Twitter, optional JSON-LD, figure/figcaption for charts, skip links, aria-live status components). |
| 22 | +15. Harden dashboard access (remove DEFAULT_STORE_ID fallback, enforce redirect for unauthenticated, introduce Suspense + skeleton patterns). |
| 23 | +16. Integrate GDPR cookie consent banner (ConsentRecord persistence, respect DNT) and align newsletter & tracking behavior. |
| 24 | +17. Improve analytics & chart accessibility (textual summaries, data transformation utilities, cache tags for expensive aggregations). |
| 25 | + |
| 26 | +Scope: |
| 27 | +IN-SCOPE: |
| 28 | +- Checkout route handlers/service logic (pricing, payment, inventory, discount, order creation). |
| 29 | +- Storefront domain resolution utility (server-only) + layout propagation. |
| 30 | +- Newsletter subscription pipeline (Server Action, GDPR consent, duplicate prevention, audit logging). |
| 31 | +- Error handling module refactor (new errors in src/lib/errors.ts + mapping layer). |
| 32 | +- Prisma middleware enhancements (src/lib/prisma-middleware.ts or integrated into db.ts). |
| 33 | +- Schema migration(s) (prisma/schema.prisma + migration generation) for arrays vs strings and deletedAt additions. |
| 34 | +- Caching strategy primitives (tag registry, usage docs, integration into product, category, page fetchers). |
| 35 | +- Test suites (unit, integration, E2E) additions & updates. |
| 36 | +- Documentation updates (design-system.md, testing-strategy.md, database/schema-guide.md, CHANGELOG.md). |
| 37 | + |
| 38 | +OUT-OF-SCOPE (Future or Separate Initiatives): |
| 39 | +- Payment provider abstraction overhaul beyond verification (e.g., multi-gateway expansion). |
| 40 | +- Full analytics subsystem redesign. |
| 41 | +- Search indexing engine (Elasticsearch/OpenSearch) adoption. |
| 42 | +- Full CDN edge caching strategy (beyond Next.js standard). |
| 43 | + |
| 44 | +Non-Functional Requirements (NFR): |
| 45 | +Performance: p95 API <500ms (checkout <650ms including payment), DB p95 queries <100ms. |
| 46 | +Reliability: All critical flows wrapped in transactions with rollback semantics. |
| 47 | +Security: Auth required for checkout; price calculated server-side; payment intent validated; rate limiting (100 req/min) for newsletter + checkout. |
| 48 | +Compliance: GDPR consent recorded; audit log entries for subscription and order creation; PCI boundaries respected (no raw card storage). |
| 49 | +Accessibility: Newsletter form & checkout maintain WCAG 2.1 AA; keyboard navigation, ARIA labels, focus ring consistency. |
| 50 | +Observability: Structured logs (level, module, correlationId) + error codes surfaced consistently. |
| 51 | +Maintainability: Files <300 lines, functions <50 lines, error class hierarchy documented; minimal client-side state. |
| 52 | +Testability: Deterministic test data fixtures; coverage thresholds enforced; E2E critical path stable across browsers. |
| 53 | + |
| 54 | +Functional Requirements (FR): |
| 55 | +FR-001: Secure checkout must reject unauthenticated requests. |
| 56 | +FR-002: Checkout recalculates line item totals and discounts server-side ignoring client-submitted prices. |
| 57 | +FR-003: Payment intent or token is validated before order creation; failed validation aborts transaction. |
| 58 | +FR-004: Order creation, inventory decrement, discount usage mark, and payment record are a single atomic transaction. |
| 59 | +FR-005: Storefront requests derive storeId from domain/subdomain mapping; fallback to 404 if unresolvable. |
| 60 | +FR-006: No hardcoded storeId remains in storefront components or services. |
| 61 | +FR-007: Newsletter subscription uses Server Action with Zod validation, deduplication (email+storeId), GDPR consent creation, optional double opt-in placeholder. |
| 62 | +FR-008: Error handling returns consistent shape `{ error: { code, message, details? } }` and success returns `{ data, meta?, message? }`. |
| 63 | +FR-009: All tenant-scoped Prisma queries enforce storeId filter either via middleware or explicit where clause. |
| 64 | +FR-010: Data schema consistency: targeted fields migrated to correct types (string[] vs CSV string) with backfill and forward validation. |
| 65 | +FR-011: Caching: Tag definitions for products, categories, pages; invalidation on create/update/delete (revalidateTag(tag,"max")). |
| 66 | +FR-012: Introduce Cache Components plan (flag disabled initially; documented enabling steps). |
| 67 | +FR-013: Test coverage thresholds enforced by CI; new tests for checkout fraud scenarios, multi-tenant isolation breach attempts, newsletter flows, error mapping. |
| 68 | +FR-014: API middleware pipeline enforces auth, rate limits (100 req/min IP baseline; stricter for login), request validation (Zod), structured logging with requestId. |
| 69 | +FR-015: Products endpoints: PUT requires full schema; PATCH allows partial; error payload uniform (no `success` field); uses error classes. |
| 70 | +FR-016: Orders CSV export streams response for <=10k rows; >10k triggers background job & downloadable link notification. |
| 71 | +FR-017: Dashboard pages redirect unauthenticated users; no DEFAULT_STORE_ID fallback present; list pages use Suspense + skeleton components. |
| 72 | +FR-018: Analytics & chart components include `<figure>` + `<figcaption>` or textual summary; axe accessibility audit passes with zero violations. |
| 73 | +FR-019: GDPR cookie consent banner writes ConsentRecord per store and honors DNT (no tracking or analytics beyond essential). |
| 74 | +FR-020: Storefront dynamic metadata (title, description, Open Graph, Twitter card) per store; optional JSON-LD for product & shop pages. |
| 75 | +FR-021: Request/response include `X-Request-Id` header on all API responses produced by middleware. |
| 76 | + |
| 77 | +Acceptance Criteria: |
| 78 | +AC-001: All critical issues resolved; manual penetration test reports 0 high severity findings. |
| 79 | +AC-002: Hardcoded storeId search yields zero results outside controlled fixtures/tests. |
| 80 | +AC-003: Checkout E2E test passes across Chromium/Firefox/WebKit and validates server-side price mismatch correction. |
| 81 | +AC-004: Newsletter E2E test shows successful subscription, audit log entry, consent record. |
| 82 | +AC-005: Prisma middleware logs storeId injection for all tenant models (verified via instrumentation test). |
| 83 | +AC-006: Migration(s) applied cleanly; no orphaned data; dev & prod schema parity. |
| 84 | +AC-007: Error responses standardized (sample audit shows 100% conformity for modified endpoints). |
| 85 | +AC-008: Cache tag invalidation observed (revalidateTag invoked with second argument) after product update test. |
| 86 | +AC-009: Coverage reports meet thresholds (≥80% services, 100% utilities). |
| 87 | +AC-010: Lighthouse CI and Axe tests pass budgets and accessibility checks. |
| 88 | +AC-011: Streaming CSV export integration test completes under memory threshold; large export job path validated. |
| 89 | +AC-012: All API responses include `X-Request-Id`; logs correlate (sampled verification with grep). |
| 90 | +AC-013: PUT/PATCH semantics verified by integration tests (PUT fails on partial; PATCH succeeds on partial) & consistent error payloads (no stray `success` flag). |
| 91 | +AC-014: Dashboard unauthenticated access redirects to /login; grep confirms absence of DEFAULT_STORE_ID fallback. |
| 92 | +AC-015: Storefront metadata dynamic per store; Open Graph tags present; optional JSON-LD validated in test snapshot. |
| 93 | +AC-016: Charts audited: each has `<figure>` & `<figcaption>`; accessibility scan shows zero violations in analytics page. |
| 94 | +AC-017: GDPR consent persisted; DNT requests bypass non-essential tracking (log sample demonstrates skip). |
| 95 | + |
| 96 | +Constraints: |
| 97 | +- Next.js 16 App Router only; async params/searchParams; proxy.ts for auth/rate limiting. |
| 98 | +- React 19 Server Components default; minimal Client Components. |
| 99 | +- TypeScript strict; no any. |
| 100 | +- Prisma only; no raw SQL; multi-tenant enforced. |
| 101 | +- Tailwind exclusively; no CSS-in-JS. |
| 102 | +- File/function line limits. |
| 103 | +- Implementation must not regress performance budgets. |
| 104 | + |
| 105 | +Risks & Mitigations: |
| 106 | +R1: Transaction complexity increases risk of deadlocks -> Use minimal locking scope; avoid unnecessary read-after-write inside same transaction. |
| 107 | +R2: Schema migrations could impact existing data -> Dry-run & backup; write idempotent migration scripts; add verification tests. |
| 108 | +R3: Payment intent validation integration complexity -> Start with stub/adapter; progressive hardening. |
| 109 | +R4: Caching misconfiguration -> Start with conservative tags; add observability counters; rollback plan (feature flag). |
| 110 | +R5: Error hierarchy adoption regressions -> Provide adapter shim mapping legacy strings to new error codes during transition. |
| 111 | + |
| 112 | +Glossary (Selected): |
| 113 | +StoreId: Tenant discriminator for all multi-tenant data. |
| 114 | +Cache Tag: Semantic identifier (e.g., product:<id>, products:list:store:<storeId>) used with revalidateTag. |
| 115 | +Server Action: `'use server'` function for form mutation or secure writes. |
| 116 | +Atomic Transaction: All-or-nothing database operation group. |
| 117 | +Consent Record: GDPR artifact tracking user consent. |
| 118 | + |
| 119 | +Out of Scope Clarifications: |
| 120 | +- Real-time inventory sync with external marketplaces. |
| 121 | +- Full theme versioning system (documented as future improvement). |
| 122 | +- Refund partial ledger (placeholder suggestion only). |
| 123 | + |
| 124 | +High-Level Data Flow (Checkout): |
| 125 | +Client Cart -> Server (Checkout Action/API) -> Re-fetch products & discounts -> Validate payment intent -> Begin Transaction -> Create Order -> Create OrderItems -> Adjust Inventory -> Record Payment -> Commit -> Emit Audit Log -> Return response. |
| 126 | + |
| 127 | +Initial Test Strategy Summary: |
| 128 | +- Unit: Price recalculation, payment validation stub, error mapping, store resolution. |
| 129 | +- Integration: Transaction success/rollback scenarios, middleware enforcement. |
| 130 | +- E2E: Checkout (price tampering attempt), Newsletter subscription, Multi-tenant isolation (cross-store data access attempt blocked). |
| 131 | +- Accessibility: Focus traversal on forms, labels, color contrast. |
| 132 | +- Performance: k6 smoke (light) & Lighthouse CI gating. |
0 commit comments