Wishlist Module - Feature List

1. Feature Overview

Wishlist allows authenticated customers to save products for later purchase consideration without mutating cart or order state.

Execution model:

• synchronous customer API only
• no background jobs
• no stock reservation side effects

2. Route Ownership and Surfaces

Swagger tag used by controller:

• Wishlist (Mobile)

Notes:

• Runtime route is /api/wishlist/*.
• There is currently no /api/mobile/wishlist/* composition in MobileModule.

3. Customer Feature Matrix

4. Key Business Rules

• Wishlist is customer-scoped (userId + productId).
• Only sellable products can be added (products.isSellable = true).
• Duplicate add is blocked via service guard and DB unique index.
• List endpoint supports optional pagination (page, size, pagination).
• Delete endpoint is bulk and supports partial success semantics.

5. State and Lifecycle Model

There is no explicit status enum for wishlist records. Lifecycle is row-based:

• created on successful add
• returned on list
• deleted on remove

6. Data Ownership and Isolation

• Data is isolated per authenticated customer UUID.
• Every read/write operation is guarded by userId filter in service queries.
• Cross-user reads/updates are not possible through wishlist service methods.

7. Validation and Constraints

7.1 Add constraints

• productId must be integer >= 1.
• Product must exist and be sellable.
• Product must not already exist in customer wishlist.

7.2 List constraints

• Default pagination: page=1, size=20, pagination=true.
• When pagination=false, all wishlist rows for user are returned.

7.3 Delete constraints

• productIds array must contain 1..100 entries.
• Each product ID must be integer >= 1.
• If none of submitted IDs exist for user, endpoint returns WISHLIST_ITEM_NOT_FOUND.
• If some match and some do not, matched items are deleted and returned via deletedCount.

8. Error UX Mapping

9. Integration Flows

9.1 Add-to-wishlist flow

1. Client sends POST /api/wishlist/items with productId.
2. Backend validates product sellability and duplicate conditions.
3. Backend inserts row in wishlist_item.
4. Client updates wishlist toggle/count.

9.2 List flow

1. Client sends GET /api/wishlist/items.
2. Backend reads user-scoped rows ordered by addedAt DESC, joined with products, productTypes, and rating aggregates from order_reviews.
3. Backend returns list with full product card fields (productTitle, productSlug, productThumbnail, productType, productKind, unitMrp, unitSp, discount, averageRating, reviewCount), optionally with pagination metadata.
4. Client renders saved products state directly without needing additional product detail API calls.

9.3 Bulk remove flow

1. Client sends DELETE /api/wishlist/items with selected productIds.
2. Backend loads matching user rows.
3. Backend deletes matched row IDs.
4. Backend returns { deletedCount }.

10. Release/QA Checklist

• Add endpoint rejects unsellable/non-existent products.
• Duplicate add returns WISHLIST_ALREADY_EXISTS.
• List endpoint returns stable order by newest first.
• List/add response includes all product card fields (productTitle, productSlug, productThumbnail, productType, productKind, unitMrp, unitSp, discount, averageRating, reviewCount).
• discount value equals mrp - sp.
• averageRating and reviewCount correctly reflect only approved reviews.
• Pagination on/off behavior verified.
• Bulk delete returns correct deletedCount.
• Not-found delete path returns WISHLIST_ITEM_NOT_FOUND.

11. File Map

• apps/api/src/modules/wishlist/wishlist.module.ts
• apps/api/src/modules/wishlist/wishlist-customer/wishlist-customer.module.ts
• apps/api/src/modules/wishlist/wishlist-customer/wishlist-customer.controller.ts
• apps/api/src/modules/wishlist/wishlist-customer/wishlist-customer.service.ts
• apps/api/src/modules/wishlist/wishlist-customer/dto/*
• packages/db/src/schema/wishlist/wishlist-items.schema.ts

12. See Also

• API Reference: Wishlist API Reference
• Backend Reference: Wishlist Backend Documentation