## 1. Persistence and shared contract

- [ ] 1.1 Add migration `0017_product_reviews.sql` (0016 is taken by membership/messaging) creating `product_reviews` with an `order_item_id` unique index, cascading order-item/order/product/shop/customer foreign keys, a `rating` 1-5 check, bilingual `content` and `reply` JSONB `{en, zh}` columns, optional `image_urls`, a visibility `status` column, reply audit columns, and product/status and shop listing indexes.
- [ ] 1.2 Add shared `Review`, `ReviewInput`, `ReviewSummary`, `ReviewableOrderItem`, and review query types plus `listProductReviews`, `getProductReviewSummary`, `listReviewableItems`, `createReview`, `listShopReviews`, `replyReview`, `listModerationReviews`, `hideReview`, and `deleteReview` methods to `@vmall/shared`.
- [ ] 1.3 Implement `apps/api/src/modules/review/` repository, service (returning `ApiResult<Dto>`), DTO, handlers, and module registration with customer routes, merchant routes declaring roles and scoping shop resources through `own_shop`, and admin routes declaring the platform role.
- [ ] 1.4 Implement completed-order-line precondition checks, duplicate-review rejection backed by the unique index, a single guarded merchant reply (`UPDATE ... WHERE reply IS NULL`), guarded visibility transitions (`UPDATE ... WHERE status = ...`), visible-only public filtering, and SQL-aggregated rating summaries (average, count, per-star counts) over visible reviews.

## 2. Backend behavioral proof

- [ ] 2.1 Add API integration coverage in `apps/api/tests/` reusing `tests/common/mod.rs` fixtures for creation preconditions and unique-index enforcement, customer ownership and role checks, `own_shop` scoping on merchant routes, one-reply enforcement, guarded hide/delete transitions, hidden-review filtering from public lists and summaries, and rating aggregation with hidden rows excluded.
- [ ] 2.2 Run the focused review integration tests twice to prove pagination totals stay correct against the shared non-truncated test database.

## 3. Mall review surfaces and adapter

- [ ] 3.1 Implement the nine review client methods in `apps/mall/mock/api.ts` with per-session mutable fixture state and the same one-review-per-line, one-reply, and visible-only behavior as the live backend.
- [ ] 3.2 Add the `reviews` domain and exact shared-client method picks to `LIVE_PICKS` in `apps/mall/plugins/api.ts` and enable it in `DEFAULT_LIVE_DOMAINS`.
- [ ] 3.3 Add or adjust bilingual review loading, submission, reply, and failure strings through the existing Mall locale source without per-page hard-coded copy.
- [ ] 3.4 Replace the product-detail display-only comment placeholder and the "no reviews tab" comment in `apps/mall/pages/goods/[id].vue` with the real review tab: rating summary (average, count, star distribution), paginated visible reviews with images and merchant replies, and pagination totals from the API.
- [ ] 3.5 Add the buyer-center "pending review" entry and submission form: list completed order lines awaiting review with counts, submit rating, text, and optional image URLs once per line, and refresh the pending list after submission.

## 4. Merchant and platform consoles

- [ ] 4.1 Add a shop-admin review list/reply page scoped to the merchant's own shop with pagination and one-reply submission through the shared contract.
- [ ] 4.2 Add the admin review moderation list with hide (soft delete) and delete actions plus console navigation.

## 5. Verification and tracker cleanup

- [ ] 5.1 Seed a deterministic completed order with unreviewed lines, run the API plus Mall, and browser-smoke review submission from the buyer center, product-detail summary and paginated list refresh, merchant reply in shop-admin, admin hide removing the review from the storefront and its summary, and the fixed-adapter review flow.
- [ ] 5.2 Run the review integration tests in `apps/api/tests/` (reusing `tests/common/mod.rs` fixtures) and build all three frontends because the shared contract changes: `pnpm --filter @vmall/mall build`, `pnpm --filter @vmall/shop-admin build`, and `pnpm --filter @vmall/admin build`.
- [ ] 5.3 Mark Reviews implemented in `docs/TBD-marketing.md` and update the README mock boundary, check every OpenSpec task, and run `openspec change validate add-product-reviews --strict` plus `openspec validate --all --strict`.