docs(openspec): propose 8 tigshop migration changes (P0-P7) + migration plan

openspec/changes/add-product-reviews/specs/reviews/spec.md

@@ -0,0 +1,67 @@
+## ADDED Requirements
+
+### Requirement: One review per completed order line
+A signed-in customer SHALL create a review only for a product line of their own completed (received) order that has not been reviewed yet. A review SHALL carry a 1-5 star rating, text content, and optional image URLs, and the rating and content snapshot SHALL never change after creation. The database SHALL enforce at most one review per order line through a unique index on the order line, and creation SHALL validate the order-line precondition before insert.
+
+#### Scenario: review a completed order line
+- **WHEN** a customer reviews a product line of their own completed order
+- **THEN** the review is created with the submitted rating, text, and image URLs and the line can no longer be reviewed
+
+#### Scenario: second review of the same line is rejected
+- **WHEN** a customer submits a second review for an already reviewed order line
+- **THEN** the request is rejected and exactly one review row exists for that line
+
+#### Scenario: unreviewable line is rejected
+- **WHEN** a customer reviews a line from another customer's order or from an order that is not completed
+- **THEN** the request is rejected without creating a review
+
+### Requirement: Bilingual review content shape
+Review content and merchant replies SHALL be stored as `{en, zh}` localized JSONB content. A submission MAY populate only the shopper's or merchant's active locale, and every display SHALL fall back to the other locale when the active locale is empty.
+
+#### Scenario: single-locale submission renders everywhere
+- **WHEN** a shopper submits review text in only one locale
+- **THEN** both mall locales display the review through the non-empty locale fallback
+
+### Requirement: Single merchant reply per review
+Only a shop user of the review's own shop SHALL reply to a review, at most once. The reply SHALL be written with a guarded update that succeeds only while no reply exists, and a second or cross-shop reply attempt SHALL be rejected.
+
+#### Scenario: first reply succeeds
+- **WHEN** a merchant of the reviewed product's shop replies to a review
+- **THEN** the reply is stored with its audit timestamp and appears with the review
+
+#### Scenario: second reply is rejected
+- **WHEN** the same merchant submits another reply to a review that already has one
+- **THEN** the request is rejected and the existing reply is unchanged
+
+### Requirement: Platform moderation hides or deletes reviews
+Platform admins SHALL hide or delete any review. Hiding SHALL be a soft delete recorded through a guarded status transition that validates the prior visible state, and deletion SHALL remove the row. Hidden and deleted reviews SHALL be absent from storefront listings and rating summaries, while admin listings SHALL still show hidden reviews with their state.
+
+#### Scenario: hidden review leaves the storefront
+- **WHEN** a platform admin hides a visible review
+- **THEN** it disappears from the product's public review list and no longer contributes to the rating summary
+
+#### Scenario: hide transition validates prior state
+- **WHEN** a platform admin hides a review that is already hidden
+- **THEN** the guarded transition changes nothing and reports the conflict
+
+### Requirement: Visible-only paginated review listing
+A product's review list SHALL be publicly readable and paginated, containing only visible reviews with the reviewer's display name, rating, content, image URLs, creation time, and any merchant reply. Pagination totals SHALL count only visible reviews, and a customer's pending-review listing SHALL show only their own completed order lines without a review.
+
+#### Scenario: totals count only visible reviews
+- **WHEN** a product has visible and hidden reviews and the public list is requested
+- **THEN** only visible reviews are returned and `total` excludes the hidden ones
+
+#### Scenario: pending-review listing shrinks after submission
+- **WHEN** a customer reviews one of their pending order lines
+- **THEN** that line disappears from the pending-review listing
+
+### Requirement: SQL rating summary aggregation
+The product rating summary SHALL be computed with SQL aggregation over visible reviews only and SHALL report the review count, average rating, and per-star (1-5) distribution. A product without visible reviews SHALL report a zero count, zero average, and an empty distribution.
+
+#### Scenario: summary reflects only visible reviews
+- **WHEN** a product's summary is requested after one of its reviews is hidden
+- **THEN** the count, average, and star distribution exclude the hidden review
+
+#### Scenario: product without reviews
+- **WHEN** the summary is requested for a product with no visible reviews
+- **THEN** it reports a zero count and zero average