Catalog Product - Feature List

1. Feature Overview

The product submodule owns sellable catalog items used by cart and order flows for physical products. It supports admin CRUD, public/customer discovery, featured storefront listing, and historical slug resolution.

2. Route Ownership and Surfaces

Admin controller: apps/api/src/modules/catalog/admin/product/product-admin.controller.ts
- Base path: /api/admin/products
Customer controller: apps/api/src/modules/catalog/customer/product/product-customer.controller.ts
- Base path: /api/products
Mobile composition: apps/api/src/modules/mobile/mobile.module.ts
- Same customer controller additionally exposed as /api/mobile/products

3. Admin Feature Matrix

Feature	Behavior
List products	Filter/search/sort/paginate with permission `Products_READ`
Get product by id	Numeric `:id` (`ParseIntPipe`)
Create product	Validates pricing/category/tags and writes product + product_tag
Update product	Supports partial updates, status transition validation, slug-history capture
Delete product	Hard delete by id with cache invalidation
Audit activity	Create/update/delete activity records when actor context is present

4. Customer/Mobile Feature Matrix

Feature	Behavior
Product list	Published + sellable products only
Featured products list	Returns products linked through featured rows that are active and in date window
Product by slug	Resolves current slug first, then `product_slug_history` fallback
Search	Title/description/category/tag ILIKE + title similarity threshold
Pagination	Supported for list and featured list

5. Key Business Rules

Pricing rule: sp <= mrp.
Status transitions are constrained: draft -> published -> unlisted -> archived.
Customer reads always enforce status = published and isSellable = true.
Slug changes persist previous slug in product_slug_history.
Tag IDs are de-duplicated before persistence and must all exist.

6. State Models

Product lifecycle

Product type enum

thangka
singing_bowl
statue
jewellery

Physical detail fields

delivery: shipping/delivery information text.
materials: non-empty array of materials used in the product.
certificate: certificate identifier string.
isMasterGrade: master-grade marker for premium artifacts.
isBestSeller: bestseller marker for storefront merchandising.
size: physical size object; shape depends on productType.

Size shape contract by product type

productType	shape	Structure
`thangka`	`rectangular`	`inch: { width, height }`, `cm: { width, height }`
`singing_bowl`	`radius`	`inch: number`, `cm: number`
`statue`	`radius`	`inch: number`, `cm: number`
`jewellery`	`circumference`	`inch: number`, `cm: number`

7. Caching Strategy

Key Prefix	Used For
`catalog:products:list:`	Customer list responses
`catalog:product:slug:`	Product detail-by-slug responses
`catalog:products:featured:`	Customer featured product list

TTL resolution in customer service:

CATALOG_PRODUCT_CACHE_TTL_SECONDS
fallback CATALOG_CACHE_TTL_SECONDS
fallback REDIS_CACHE_TTL_SECONDS

Admin write invalidation covers:

catalog:products:list:*
catalog:product:slug:*
catalog:products:featured:*

8. Rate Limiting

Search/list endpoints apply Redis sliding-window throttling in controllers:

Admin: CATALOG_ADMIN_PRODUCT_SEARCH_RATE_LIMIT, CATALOG_ADMIN_PRODUCT_SEARCH_RATE_WINDOW_SECONDS
Customer/mobile: CATALOG_CUSTOMER_PRODUCT_SEARCH_RATE_LIMIT, CATALOG_CUSTOMER_PRODUCT_SEARCH_RATE_WINDOW_SECONDS
Exceeded requests throw RateLimitExceededException (RATE_LIMIT_EXCEEDED).

9. Queue/Worker Features

No BullMQ queue or worker is implemented inside catalog product flows for this subphase.

10. Error UX Mapping

errorCode	Typical UX Handling
`PRODUCT_NOT_FOUND`	Show not-found page/toast and stop detail flow
`PRODUCT_CATEGORY_NOT_FOUND`	Prompt admin to choose valid category
`PRODUCT_TAG_NOT_FOUND`	Prompt admin to fix tag selection
`PRODUCT_SP_EXCEEDS_MRP`	Inline pricing validation error
`PRODUCT_INVALID_STATUS_TRANSITION`	Block invalid status update with guidance
`PRODUCT_INVALID_SORT`	Fallback UI to default sort option
`PRODUCT_CREATE_FAILED`	Generic admin retry/error banner
`RATE_LIMIT_EXCEEDED`	Backoff + retry after delay

11. Integration Flows

11.1 Product Creation Flow

An admin creates a product with category and tag associations.

Admin calls POST /api/admin/products with title, description, pricing (sp, mrp), category, and tag IDs.
System validates sp <= mrp and all category/tags exist.
System creates product and associates tags via product_tag table.
System captures product slug in product_slug_history on creation.
Admin calls PATCH /api/admin/products/:id to transition status to published.

11.2 Customer Discovery Flow

A customer discovers and searches products via storefront.

Customer calls GET /api/products to browse published + sellable products.
Customer applies search query via GET /api/products?search=....
System performs ILIKE on title/description and similarity scoring.
Customer calls GET /api/products/featured to see featured products.
Customer calls GET /api/products/:slug to view product detail.
System resolves current slug first, then falls back to product_slug_history for legacy URLs.

11.3 Product Lifecycle Flow

An admin manages product status transitions with slug history.

Product starts as draft status.
Admin publishes product: draft -> published.
Admin unlists product: published -> unlisted.
Admin archives product: unlisted -> archived.
On any slug change, system writes previous slug to product_slug_history for backward compatibility.

12. Release/QA Checklist

Verify admin CRUD permissions (Products_*) and swagger endpoints.
Verify list search against title/description/category/tag and similarity behavior.
Verify slug-history resolution for old product URLs.
Verify cache invalidation after create/update/delete.
Verify admin and customer rate-limit behavior in Redis-backed environments.

Catalog Product Feature List