vmall/openspec/changes/add-product-reviews/tasks.md

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.