Featured placement feature contract for admin and customer/mobile catalog surfaces.

Featured Module - Feature List

1. Feature Overview

The featured submodule manages curated storefront placements linked to products, with activation windows (startDate/endDate) and ordering.

2. Route Ownership and Surfaces

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

3. Admin Feature Matrix

Feature	Behavior
List featured rows	Filter/search/sort/paginate
Get featured row	Numeric `:id` lookup
Create featured row	Validates date window and optional category existence
Update featured row	Partial updates with same validation rules
Delete featured row	Deletes by id and invalidates cache

4. Customer/Mobile Feature Matrix

Feature	Behavior
Active featured list	Public endpoint (`@Public()`)
Date-window filtering	Includes only records active at request time
Optional filters	`search`, `categoryId`, `isActive`
Sorting	Customer allowlist: `order`, `createdAt`
Pagination	Supported (`pagination=false` by default)

5. Key Business Rules

Date invariant: startDate <= endDate when both are present.
Optional categoryId must refer to an existing category on admin writes.
Customer listing defaults to active records and valid date window.
Display ordering is controlled through integer order.

6. State Models

Active-window state model

active now: isActive=true and within [startDate, endDate] (null bounds allowed)
scheduled future: start date in future
expired: end date in past
inactive: isActive=false

7. Caching Strategy

Key Prefix	Used For
`catalog:featured:list:`	Customer featured list cache

TTL resolution in customer service:

CATALOG_FEATURED_CACHE_TTL_SECONDS
fallback CATALOG_CACHE_TTL_SECONDS
fallback REDIS_CACHE_TTL_SECONDS

Admin invalidates:

catalog:featured:active*
catalog:featured:list:*

8. Rate Limiting

No explicit featured-specific rate limiter is implemented in featured controllers for this scope.

9. Queue/Worker Features

No BullMQ queue or worker is implemented for featured flows.

10. Error UX Mapping

errorCode	Typical UX Handling
`FEATURED_NOT_FOUND`	Show not-found state for edit/detail
`FEATURED_INVALID_DATE_RANGE`	Inline date-range validation message
`FEATURED_INVALID_SORT`	Reset customer sort to supported default
`CATEGORY_NOT_FOUND`	Prompt admin to choose an existing category

11. Integration Flows

11.1 Featured Placement Flow

An admin creates a featured product placement with date window.

Admin calls POST /api/admin/featured with productId, startDate, endDate, and optional categoryId.
System validates: date window (startDate <= endDate when both present).
System validates: categoryId exists if provided.
System sets order based on creation timestamp or explicit value.
Admin calls PATCH /api/admin/featured/:id to adjust dates or toggle isActive.

11.2 Customer Featured Discovery Flow

A customer views active featured products on the storefront.

Customer calls GET /api/featured to see active featured products.
System filters: isActive = true and current time within [startDate, endDate] (null bounds allowed).
System returns products ordered by order field.
Customer can filter by categoryId or apply search query.
Customer can sort by order or createdAt.

11.3 Featured Management Flow

An admin reorders and manages featured placements.

Admin calls POST /api/admin/featured/reorder with ordered array of featured IDs.
System updates order values for all affected rows.
Admin calls DELETE /api/admin/featured/:id to remove a featured placement.
System deletes row and invalidates customer featured cache.

12. Release/QA Checklist

Verify admin CRUD + Featured_* permissions.
Verify date window validation on create/update.
Verify customer active-window filtering.
Verify cache invalidation after admin writes.
Verify mobile and non-mobile public route behavior parity.

Featured Module Feature List