43 — Shop Model Extension for Testimonials (Blueprint §5.1)

43 — Shop Model Extension for Testimonials (Blueprint §5.1)

Source: 02-Implementation-Blueprint.md — §5.1 Extend Shop model.

This document is a build spec only. No code changes are implied until a task references this file.

Related: 04 (cleanup/what to keep), 20 (database sequencing), 12 (moderation settings), 05 (widget settings), 08 (consent/privacy).

---

0) Goal (one sentence)

Add testimonial feature defaults at the tenant root (Shop) so all screens and pipelines can read a single authoritative configuration baseline.

---

1) Blueprint field set

Blueprint §5.1 proposes adding:

• testimonialEnabled Boolean @default(true) @map("testimonial_enabled")
• testimonialWidgetLayout String? @default("carousel") @map("testimonial_widget_layout")
• testimonialPrimaryColor String? @map("testimonial_primary_color")
• testimonialAutoApprovePhotos Boolean @default(false) @map("testimonial_auto_approve_photos")
• testimonialConsentVersion String? @map("testimonial_consent_version")

These should be added without breaking existing shops.

---

2) Scope boundaries

In scope

• Shop column additions and defaults
• read/write ownership boundaries per field
• migration safety and backfill strategy

Out of scope

• adding all future settings fields in one step (can be phased)
• deep settings UI implementation (covered in screen-specific plans)

---

3) Field ownership map

Field	Primary owners	Used by
testimonialEnabled	Global settings/admin	public submission route gate, widget API gate
testimonialWidgetLayout	Widget settings screen	storefront widget default render mode
testimonialPrimaryColor	Widget settings screen	storefront/theme styling
testimonialAutoApprovePhotos	Moderation settings screen	submit/moderation rule engine
testimonialConsentVersion	Settings/moderation policy config	submit API consent snapshot

Explicit ownership avoids conflicting writes across screens.

---

4) Defaults and fallback behavior

Recommended defaults:

• testimonialEnabled=true
• testimonialWidgetLayout='carousel'
• testimonialPrimaryColor nullable; UI fallback to brand default
• testimonialAutoApprovePhotos=false
• testimonialConsentVersion nullable until merchant sets policy

Runtime fallback policy:

• if consent version null, submit API can still require consent and store a generated fallback version string (e.g. v1-default) only if product approves this behavior.

---

5) Migration strategy

5.1 Phase 1 (safe add)

• Add columns as nullable/defaulted exactly as blueprint suggests.
• No immediate backfill required beyond DB defaults.

5.2 Phase 2 (optional hardening)

• Backfill missing consent version for active shops.
• Tighten constraints if product requires non-null values later.

Keep migration reversible and low-risk for existing installs.

---

6) Runtime usage contracts

6.1 testimonialEnabled

When false:

• public submission routes return disabled state
• widget API returns empty or disabled response
• campaign send worker should skip new sends (product choice; recommended)

6.2 testimonialAutoApprovePhotos

Read during submit/moderation rule evaluation:

• photo submissions can auto-transition to approved when true.

6.3 testimonialConsentVersion

Snapshot copied into each submission at submit time; old submissions are immutable.

---

7) Validation rules for write paths

• testimonialWidgetLayout must be in allowed list (carousel, grid, masonry, etc. per screen design)
• testimonialPrimaryColor must be valid color token/hex format
• testimonialConsentVersion max length and safe characters

Server-side validation required even if UI validates.

---

8) Cross-plan alignment

This Shop extension should be treated as the base layer for:

• 05 widget defaults
• 12 moderation defaults
• 06 consent snapshot behavior
• 08 privacy/compliance handling

Avoid duplicating these values in separate singleton tables unless a later refactor is intentional.

---

9) Acceptance criteria

• New columns appear in schema/migration with correct defaults and maps.
• Existing shops load without runtime errors.
• Settings writes correctly persist and are readable by dependent routes.
• Submit/moderation/widget paths honor shop-level flags.

---

10) Suggested implementation order (for Cursor)

1. Add Shop columns in Prisma schema + migration.
2. Update server types/selects that read Shop.
3. Wire reads into dependent modules (submit, moderation, widget API).
4. Add/update admin settings controls.
5. Add tests for enabled/disabled and auto-approve/consent version behavior.

---

11) References

• 02-Implementation-Blueprint.md — §5.1
• 04-Delete All Existing Code and DB Tables.md
• 20-database-design-and-migrations-blueprint-section-5.md
• 05-storefront-widgets-and-read-api.md
• 12-moderation-settings-screen-9.md
• 08-security-compliance-and-privacy.md

---

12) Note on numbering

This folder already includes 05 through 42 plans. This file is 43-....