Category Module - Feature List

1. Feature Overview

The category submodule manages hierarchical product grouping, storefront visibility, and slug continuity. It supports admin CRUD/reorder and public category browse/detail reads.

2. Route Ownership and Surfaces

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

3. Admin Feature Matrix

Feature	Behavior
List categories	Filter/search/sort/paginate
Get category	Numeric `:id` lookup
Create category	Validates parent depth and slug generation
Update category	Supports slug updates with history capture
Delete category	Blocked when child categories exist
Reorder categories	Batch reorder via `POST /admin/categories/reorder`

4. Customer/Mobile Feature Matrix

Feature	Behavior
Visible category list	Defaults `isVisible=true`
Category by slug	Resolves current slug first, then `category_slug_history`
Optional filtering	`parentId`, `search`, sorting, pagination
Public access	Endpoint marked `@Public()`

5. Key Business Rules

A category cannot be its own parent.
Category trees cannot exceed depth 3.
Moving a category into its descendant is rejected.
Delete is blocked when child categories exist.
Slug changes write previous slug to category_slug_history.

6. State Models

Category tree model

Root category: parentId = null
Child category: parentId = <category.id>
Depth cap: 3 levels

Visibility model

isVisible=true: included in storefront browse
isVisible=false: excluded by default customer query behavior

7. Caching Strategy

Key Prefix	Used For
`catalog:categories:list:`	Customer list cache
`catalog:category:slug:`	Detail-by-slug cache

TTL resolution in customer service:

CATALOG_CATEGORY_CACHE_TTL_SECONDS
fallback CATALOG_CACHE_TTL_SECONDS
fallback REDIS_CACHE_TTL_SECONDS

Admin invalidates:

catalog:categories:visible*
catalog:categories:list:*
catalog:category:slug:*

8. Rate Limiting

No explicit per-endpoint rate limiter is implemented in category controllers in this subphase.

9. Queue/Worker Features

No BullMQ queue or background worker flow is implemented for categories in this scope.

10. Error UX Mapping

errorCode	Typical UX Handling
`CATEGORY_NOT_FOUND`	Show not-found state for detail/edit pages
`CATEGORY_SELF_PARENT`	Inline parent-field validation error
`CATEGORY_MOVE_TO_DESCENDANT`	Block parent change and prompt valid parent
`CATEGORY_MISSING_PARENT`	Prompt admin to select existing parent
`CATEGORY_DEPTH_EXCEEDED`	Explain max depth (3) in form validation
`CATEGORY_HAS_CHILDREN`	Show conflict modal before delete
`CATEGORY_DUPLICATE_IDS`	Prompt reorder payload correction
`CATEGORY_INVALID_SORT`	Reset to default sort in client

11. Integration Flows

11.1 Category Tree Creation Flow

An admin creates a hierarchical category structure with depth validation.

Admin calls POST /api/admin/categories to create root category (no parent).
System generates slug and writes to category_slug_history.
Admin calls POST /api/admin/categories to create child category with valid parentId.
System validates parent depth < 3 and rejects if depth would exceed limit.
Admin calls POST /api/admin/categories/reorder to adjust display order within same level.

11.2 Customer Category Browse Flow

A customer browses categories on the storefront for product discovery.

Customer calls GET /api/categories to list visible categories (isVisible=true).
Customer calls GET /api/categories?parentId=X to browse child categories.
Customer calls GET /api/categories/:slug to view category detail.
System resolves current slug first, then falls back to category_slug_history for legacy URLs.
Customer can filter products by category ID on product list endpoint.

11.3 Category Restructuring Flow

An admin moves a category to a new parent with validation.

Admin calls PATCH /api/admin/categories/:id with new parentId.
System validates: category cannot be its own parent.
System validates: moving to new parent does not create a cycle (category cannot become descendant of itself).
System validates: resulting depth < 3.
On slug change, system writes previous slug to category_slug_history.

12. Release/QA Checklist

Verify admin CRUD + reorder under Categories_* permissions.
Verify depth/cycle guards for create and update.
Verify slug-history resolution for old category URLs.
Verify visibility defaults on customer/mobile list.
Verify cache invalidation after create/update/delete/reorder.

Category Module Feature List