Tag Module - Feature List

1. Feature Overview

The tag submodule manages typed label taxonomy for product discovery. It supports admin CRUD and public tag browse/detail with slug-history continuity.

2. Route Ownership and Surfaces

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

3. Admin Feature Matrix

Feature	Behavior
List tags	Filter/search/sort/paginate
Get tag by id	Numeric `:id` (`ParseIntPipe`)
Create tag	Enforces unique name and slug generation
Update tag	Supports name/type update with slug-history capture
Delete tag	Deletes by id and invalidates caches

4. Customer/Mobile Feature Matrix

Feature	Behavior
Tag list	Public endpoint with optional `type` filter
Tag by slug	Resolves current slug first, then `tag_slug_history`
Sorting	Customer allowlist: `name`, `createdAt`
Pagination	Supported (`pagination=false` by default)

5. Key Business Rules

Tag names must be unique.
Tag slug generation avoids conflicts with both current and historical slugs.
Tag type must be one of enum-backed values.
Customer sort fields are constrained to a small allowlist.

6. State Models

Tag type enum

general
book
newsletter

Tag lifecycle

7. Caching Strategy

Key Prefix	Used For
`catalog:tags:list:`	Customer tag list cache
`catalog:tag:slug:`	Tag detail-by-slug cache

TTL resolution in customer service:

CATALOG_TAG_CACHE_TTL_SECONDS
fallback CATALOG_CACHE_TTL_SECONDS
fallback REDIS_CACHE_TTL_SECONDS

Admin invalidates:

catalog:tags:list:*
catalog:tag:slug:*

8. Rate Limiting

No explicit tag-specific rate limiter is implemented in admin or customer tag controllers.

9. Queue/Worker Features

No BullMQ queue or worker is implemented for tag flows in this scope.

10. Error UX Mapping

errorCode	Typical UX Handling
`TAG_NOT_FOUND`	Show not-found state for detail/edit pages
`TAG_NAME_EXISTS`	Inline duplicate-name validation message
`TAG_INVALID_SORT`	Reset client sort to supported default

11. Integration Flows

11.1 Tag Creation Flow

An admin creates tags with type classification for product organization.

System validates unique name constraint.
System generates unique slug avoiding conflicts with current and historical slugs.
System creates tag and records initial slug in tag_slug_history.
Tag is now available for association with products.

11.2 Customer Tag Browse Flow

A customer browses tags to filter products on the storefront.

Customer calls GET /api/tags to list all public tags.
Customer calls GET /api/tags/:slug to view tag detail with associated products.
System resolves current slug first, then falls back to tag_slug_history for legacy URLs.
Customer can use tag slug to filter product list: GET /api/products?tags=tag-slug.

11.3 Tag Update Flow

An admin updates a tag name or type with slug history tracking.

Admin calls PATCH /api/admin/tags/:id to update name or type.
If name changes and creates new slug, system writes previous slug to tag_slug_history.
System validates slug uniqueness against both current and historical slugs.
System invalidates customer tag cache after update.
All products associated with the tag remain valid.

12. Release/QA Checklist

Verify admin CRUD + Tags_* permissions.
Verify duplicate-name conflict behavior.
Verify slug-history resolution for old tag slugs.
Verify customer type filter and sort allowlist.
Verify cache invalidation on create/update/delete.

Tag Module Feature List