Architect — F-025 Reviews module

Feature

F-025 adds verified-purchase reviews with moderation and rating aggregates.

Design

Module boundaries

Create project/src/modules/reviews/ with domain/application/infrastructure/api/tests. Reviews owns review persistence and aggregates. Catalog is the source of product truth.

Data model

Add migration 019_reviews.js:

reviews_reviews: id, user_id, product_id, order_id uuid, order_item_id uuid, rating int 1..5, title, body, status text default 'pending', created_at, updated_at.
CHECK status IN ('pending','published','rejected') and rating BETWEEN 1 AND 5.
UNIQUE (order_item_id) to allow one review per order item.
Index (product_id, status) for public listing.

Use cases

submitReview(userId, input) requires an order owned by the user whose items contain the target order item and whose state is DELIVERED. Otherwise 403.
moderateReview(reviewId, status) admin-only, transitions pending -> published or rejected.
listPublishedForProduct(productId) public, returns only published reviews plus aggregate averageRating and count.

API

POST /reviews authenticated, returns 201/403.
GET /reviews?productId= returns published reviews and aggregate.
PATCH /reviews/:id/moderate admin-only.

Acceptance trace

No delivered order item -> 403.
Second review on same order item -> 409 (unique constraint).
Pending reviews never appear on product listing.

1.4 KiB Raw Blame History