29 — Milestone 1 Delivery Plan (Blueprint §9.1)

29 — Milestone 1 Delivery Plan (Blueprint §9.1)

Source: 02-Implementation-Blueprint.md — §9 Release Plan → Milestone 1 (2 weeks).

Milestone 1 blueprint scope:

• DB schema + migrations
• Campaign CRUD
• Request creation from order webhook

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

Related: 20 (DB), 17/18 (campaign screens), 07 (request pipeline), 21 (route map), 24 (build standards).

---

0) Goal (one sentence)

Ship a stable foundation where merchants can configure campaigns and order webhooks reliably create scheduled per-product testimonial request rows.

---

1) Scope lock (what is included)

In scope

1. Prisma testimonial base schema and migrations:

   • TestimonialCampaign
   • TestimonialCampaignProduct
   • TestimonialTemplate (minimum defaults)
   • TestimonialRequest
   • TestimonialRequestEvent
   • required Shop testimonial config fields

2. Campaign management:

   • list screen
   • create/edit screen
   • pause/resume/archive/duplicate

3. Order webhook ingestion:

   • webhook verification
   • campaign eligibility
   • one request row per eligible product line item
   • idempotent writes

Out of scope

• Public submission page (/t/:token)
• Media upload/processing
• Moderation screens
• Storefront widgets
• Analytics and billing pages

---

2) Deliverables

D1 — Schema and migrations

• Migration files applied on dev/staging
• Prisma client regenerated
• nullable-first strategy for phased rollout

D2 — Campaign CRUD

Routes:

• /app/testimonial-campaigns
• /app/testimonial-campaigns/:id

Capabilities:

• create campaign
• edit settings
• set status active/paused/archived
• duplicate with target cloning

D3 — Webhook request creator

Routes:

• webhooks.orders.paid
• webhooks.orders.fulfilled

Behavior:

• verify HMAC
• load active campaigns
• evaluate audience/trigger
• persist TestimonialRequest + initial TestimonialRequestEvent

---

3) Technical acceptance criteria

1. Schema

   • Migrations run cleanly on fresh DB and upgraded DB.
   • Unique constraints enforce no duplicate campaign-product mappings and no duplicate tokens.

2. Campaign CRUD

   • Merchant can create active campaign with valid rules.
   • Invalid config blocked by server validation.
   • Duplicate campaign starts paused by default.

3. Webhook flow

   • Valid webhook creates expected request rows.
   • Replay of same webhook creates zero duplicates.
   • Inactive campaign does not generate requests.
   • scheduledFor respects delayDays (UTC).

---

4) Test matrix (minimum)

Webhook scenarios

1. order paid, one eligible product, one campaign -> 1 request
2. order fulfilled, 3 eligible products -> 3 requests
3. order paid, no active campaign -> 0 requests
4. webhook replay -> no additional requests
5. bad HMAC -> no writes

Campaign scenarios

1. all-products campaign save
2. targeted products campaign save
3. pause/resume status transitions
4. duplicate campaign copies mappings

---

5) Risks and mitigations

1. Duplicate sends from duplicate requests

   • Mitigation: unique business key + idempotent webhook logic.

2. Campaign misconfiguration

   • Mitigation: activation guardrails and required field checks.

3. Timezone drift in scheduling

   • Mitigation: persist and compute all schedule timestamps in UTC.

---

6) Suggested implementation order (Cursor)

1. Implement schema migration subset for Milestone 1 only.
2. Scaffold campaign list/create-edit routes and validations.
3. Implement webhook routes with verification and idempotency.
4. Add request creation service and event writes.
5. Add minimal seed/default templates for pipeline compatibility.
6. Run integration tests and webhook replay tests.

---

7) Done definition (Milestone 1)

Milestone 1 is complete when:

• campaigns are merchant-editable and status-controlled,
• order events generate deterministic request rows,
• duplicate deliveries are safe,
• groundwork is ready for Milestone 2 public submission flow.

---

8) References

• 02-Implementation-Blueprint.md — §9 Milestone 1
• 20-database-design-and-migrations-blueprint-section-5.md
• 17-campaigns-list-screen-2.md
• 18-campaign-create-edit-screen-3.md
• 07-email-sms-request-delivery-pipeline.md

---

9) Note on numbering

This folder already includes 05 through 28 plans. This file is 29-....