Skip to content

Design Review System

This document describes the hybrid design review workflow for custom designs.

Overview

The design review system uses a hybrid approach: - Auto-approve: Designs containing only text and clipart are automatically finalized - Manual review: Designs with user-uploaded images require staff review for print quality

This balances customer experience (fast turnaround for simple designs) with quality control (uploaded images need resolution/quality checks).

Implementation status (verified 2026-11-01, v1.57)

The review flow is driven by explicit actions rather than automatic upload-detection:

  • Customer requests review: POST /api/designs/{id}/request_approval/ moves a draft or rejected design to pending_review (CustomDesignViewSet.request_approval, backend/apps/designs/views.py). A guest (no account) sends an email with it (v1.54, feedback #54): stored as CustomDesign.guest_email (migration designs/0012), used for the review mails and shown in the admin as the customer email. It is cleared when the design is claimed by an account and 12 months after the last change of a design without an order (designs.purge_guest_emails); guest designs without an order are deleted after 90 days (designs.purge_guest_designs, apps/designs/retention.py).
  • Admin decides: POST /api/admin/designs/{id}/approve/ (pending_review → approved, unblocks checkout) or POST /api/admin/designs/{id}/reject/ (pending_review → rejected, reason stored in review_note). With notify_customer: false (the checkbox "Klant niet mailen" in the admin, v1.50) no email is sent and the reason is optional; otherwise it is required. Both stamp reviewed_at / reviewed_by and write an audit log (backend/apps/designs/admin_views.py).
  • Approving clears the attention flag on the customer's orders when every design on the order is approved/finalized and no ⚠ note remains (resolve_artwork_review in backend/apps/orders/services.py, v1.46).
  • Publishing to the collection (POST /api/admin/designs/{id}/publish_to_collection/) also sets approved when the design was not yet approved/finalized.
  • Finalize (PATCH /api/designs/{id}/finalize/) is a separate "lock for production" action that sets finalized unconditionally.
  • The upload-detection helper CustomDesign.has_user_uploaded_images() still exists on the model but is not wired into an automatic pending-review trigger — moving to pending_review is an explicit customer/admin action.
  • Checkout is blocked while the cart contains a pending_review (or rejected) design (OrderService._validate_design_status in backend/apps/orders/services.py).

Design Status Workflow

stateDiagram-v2
    [*] --> draft
    draft --> pending_review: request_approval
    rejected --> pending_review: request_approval
    pending_review --> approved: admin approve
    pending_review --> rejected: admin reject (reason)
    approved --> finalized: finalize (lock)
    draft --> finalized: finalize (lock)

Customer actions on the left (request_approval, finalize), staff decisions in the middle; a rejected design can be fixed and re-requested.

Status Description When Used
draft Design is being edited Default status, active editing
pending_review Awaiting staff review Customer requested approval (request_approval); requesting again while pending is a no-op (feedback #54)
approved Passed staff review Admin approve or publish_to_collection — unblocks checkout
rejected Rejected by staff Admin reject, optionally with a reason (shown to the customer unless "Klant niet mailen")
finalized Locked for production finalize action
in_production Defined in STATUS_CHOICES but never set by code —

Email Notifications

Design Pending Review

Trigger: Design status changes to pending_review

Template: design_pending_review.html / .txt

Subject: Je ontwerp voor {product_name} wordt beoordeeld

Content: - Explains uploaded images are being checked for print quality - Sets expectation: review within 24 hours - Preview thumbnail of the design - Link to view/edit the design

Design Approved

Trigger: Design status changes to approved or finalized

Template: design_approved.html / .txt

Subject: Je ontwerp voor {product_name} is goedgekeurd!

Content: - Confirms design is approved and ready for production - Preview thumbnail - Link to designer or cart

Design Rejected

Trigger: Design status changes to rejected, unless staff rejected with notify_customer: false ("Klant niet mailen")

Template: design_rejected.html / .txt

Subject: Je ontwerp voor {product_name} heeft aanpassing nodig

Content: - Explains the design was not approved, including the rejection reason - Link back to the designer (/designer?design=<id>) so the customer can adjust and re-request approval

Status-change emails are dispatched from backend/apps/designs/signals.py (handle_design_status_emails, via transaction.on_commit) using the model's FieldTracker. The reject action sets a one-save flag _skip_status_email when the customer must not be mailed; a later status change mails again.

Email Recipient Logic

The system uses a fallback pattern for email recipients:

def get_recipient_email(design):
    # 1. Prefer user's account email
    if design.user:
        return design.user.email

    # 2. Fallback to order email for guest checkout
    order_item = design.orderitem_set.select_related('order').first()
    if order_item and order_item.order:
        return order_item.order.email

    # 3. The address a guest gave when requesting the check (v1.54)
    return design.guest_email or None

This ensures guests who checkout without an account, or who ask for the free check before ordering, still receive design status emails (get_recipient_email in apps/designs/signals.py).

Detecting User Uploads

The has_user_uploaded_images() method checks if a design contains user-uploaded images:

def has_user_uploaded_images(self):
    for view in ["front", "back", "left", "right"]:
        view_json = getattr(self, f"design_json_{view}", {})
        for obj in view_json.get("objects", []):
            if obj.get("type") in ("image", "Image"):
                src = obj.get("src", "")
                # User uploads in /uploads/, clipart in /clipart/
                if "/uploads/" in src or src.startswith("data:"):
                    return True
    return False

Detection logic: - User uploads are stored in /uploads/ directory - Clipart is stored in /clipart/ directory - Base64 data URLs (data:) are treated as user uploads

Frontend Components

Cart: request the check

Location: frontend/components/designs/DesignApprovalControls.tsx

The button "Vraag gratis ontwerpcontrole aan" is shown for draft and rejected designs in the cart. A guest first fills in "Je e-mailadres" (logged-in customers see no field). After the request the control shows "In beoordeling" right away; a repeated tap returns the current state instead of an error (v1.52, feedback #54). Approved designs show "Goedgekeurd", rejected ones "Aanpassing gevraagd" with the reason.

ImageTab Info Banner

Location: frontend/components/ProductDesigner/components/tabs/ImageTab.tsx

A blue info banner warns users that uploaded images require review:

Let op: Geuploade afbeeldingen worden door ons team gecontroleerd op printkwaliteit. Je ontvangt binnen 24 uur een e-mail zodra je ontwerp is goedgekeurd.

Order Progress Stepper

Location: frontend/components/orders/OrderProgressStepper.tsx

Shows order fulfillment progress:

Betaald → In behandeling → Wordt bedrukt → Verzonden → Afgeleverd

Also displays: - Design review notice when status is pending_review - Waiting for payment notice when status is pending

Design Status Badges

On the order detail page, each order item shows a design status badge: - 🔍 Ontwerp wordt beoordeeld - pending_review - ✓ Ontwerp goedgekeurd - finalized

Admin Workflow

The primary review UI is the frontend admin (/admin), backed by the /api/admin/designs/{id}/approve/ and /reject/ actions:

  1. Open Ontwerpen (/admin/designs; the sidebar badge and the Vandaag work list show how many designs wait) and filter by status pending_review
  2. Review the design preview images and uploaded-image quality/resolution
  3. Approve (pending_review → approved) — unblocks checkout and clears the order's automatic attention flag, or Reject (pending_review → rejected) with a reason shown to the customer. Tick "Klant niet mailen" (components/admin/designs/DesignReviewActions.tsx) to skip the email; the reason is then optional
  4. A status email is sent automatically (see the signals above), except after a reject without mail

The Django admin can still be used for ad-hoc status changes (status is editable there), but approve/reject with audit + review metadata is the intended path.

API Endpoints

Method & path Actor Effect
POST /api/designs/{id}/request_approval/ Customer draft/rejected → pending_review
POST /api/admin/designs/{id}/approve/ Staff pending_review → approved (unblocks checkout)
POST /api/admin/designs/{id}/reject/ Staff pending_review → rejected; body {"reason": "..."}, or {"reason": "", "notify_customer": false} to skip the mail
POST /api/admin/designs/{id}/publish_to_collection/ Staff marks the design as a collection item; sets approved if needed
POST /api/admin/designs/{id}/generate_print_file/ Staff renders the print PDF from the view previews
PATCH /api/designs/{id}/finalize/ Customer/system → finalized (locks the design)

The generic PATCH /api/designs/{id}/ still exists; status is a writable serializer field, so it can also be set directly (e.g. from the Django admin).

Database

The current STATUS_CHOICES on CustomDesign (backend/apps/designs/models.py):

STATUS_CHOICES = [
    ("draft", "Draft"),
    ("pending_review", "Pending Review"),
    ("approved", "Approved"),
    ("rejected", "Rejected"),
    ("finalized", "Finalized"),
    ("in_production", "In Production"),
]

The model also carries review metadata (review_note, reviewed_at, reviewed_by) populated by the admin approve/reject actions.

Testing

Backend Tests

cd backend
pytest apps/designs/test_approval.py apps/designs/test_approval_attention.py apps/designs/test_guest_email.py apps/designs/tests.py

Frontend Tests

cd frontend
npm test -- --testPathPatterns="DesignReviewActions|OrderDetailPage"
npx playwright test --project=chromium-admin e2e/admin-design-review.spec.ts   # needs a seeded admin

Manual E2E Test

  1. Upload image in designer → see info banner
  2. Move the design to pending_review (customer request_approval, Django admin, or API PATCH) → checkout with this design in the cart is blocked with a notice
  3. Check pending-review email received (user email, order email, or the address a guest typed under "Je e-mailadres" in the cart)
  4. Admin: approve the design (pending_review → approved)
  5. Check approval email received; checkout is possible again
  6. (Alternatively) Admin reject with a reason → rejected email is sent and checkout stays blocked until the customer re-requests and it's approved; with "Klant niet mailen" no email arrives
  7. Order detail page shows progress stepper

Configuration

No additional configuration is required. The feature uses existing environment variables:

Variable Purpose
FRONTEND_URL Base URL for designer links in emails
RESEND_API_KEY Email delivery via django-anymail (Resend); development writes to logs/emails.jsonl