Categories
Postman Doc: https://documenter.getpostman.com/view/20499442/[merchant-collection-id]

--------------------------------------------------------------------------------
API: Create Category
--------------------------------------------------------------------------------
    POST /merchant/api/v1/domains/:domain_id/categories [Seller Catalog & Inventory, Orchestration]

    Description: Create a category within a domain. Supports parent-child hierarchy,
                 ordering, images, and metadata for navigation and SEO.

    Request Body:
        {
            "name": "Coffee",
            "handle": "coffee",
            "parent_id": null,
            "position": 1,
            "image_url": "https://cdn.example.com/cat-coffee.jpg",
            "description": "All coffee products",
            "visible": true
        }

    Flow Sequence:
        # Step 1: Validate domain and caller permissions
        # Step 2: Ensure handle uniqueness within domain
        # Step 3: Create category record in Product Service
        # Step 4: Attach image via CloudOperations if provided
        # Step 5: Reindex navigation/search
        # Step 6: Invalidate category cache and emit event

    Response: 201 Created
        {
            "id": "cat_123",
            "name": "Coffee",
            "handle": "coffee",
            "parent_id": null,
            "position": 1,
            "image_url": "https://...",
            "created_at": "2024-10-14T12:00:00Z"
        }

    Errors:
        400 Bad Request - missing name
        409 Conflict - handle already exists

--------------------------------------------------------------------------------
API: List Categories
--------------------------------------------------------------------------------
    GET /merchant/api/v1/domains/:domain_id/categories [Seller Catalog & Inventory, Orchestration]

    Query Params: ?tree=true&depth=2&visible=true
    Flow Sequence:
        # Step 1: Validate Token and Domain
        # Step 2: Fetch Category Tree from Catalogue Service
        GET /api/categories?domain_id=:domain_id&tree=true [Catalogue Service, Core Microservices]
        # Step 3: Apply Visibility Filters and Pagination
        # Step 4: Return Result

    Response: { "categories": [...], "pagination": {...} }

--------------------------------------------------------------------------------
API: Get / Update / Delete Category
--------------------------------------------------------------------------------
    GET /merchant/api/v1/domains/:domain_id/categories/:id
    PATCH /merchant/api/v1/domains/:domain_id/categories/:id
    DELETE /merchant/api/v1/domains/:domain_id/categories/:id

    Description: Retrieve, partially update, or soft-delete categories. Updates trigger reindex and cache invalidation.

    PATCH Request Body (example):
        { "name": "Coffee & Tea", "position": 2, "visible": false }

    Response: 200 OK with updated category

    Flow Sequence (GET):
        # Step 1: Validate Token and Domain
        # Step 2: Get Category from Catalogue Service
        GET /api/categories/:id [Catalogue Service, Core Microservices]

    Flow Sequence (PATCH):
        # Step 1: Validate Token and Permissions
        # Step 2: Update Category in Catalogue Service
        PATCH /api/categories/:id [Catalogue Service, Core Microservices]
        # Step 3: Invalidate Cache
        DELETE /api/cache/categories/:id [Caching Service, Shared Services]

    Flow Sequence (DELETE):
        # Step 1: Validate Token and Permissions
        # Step 2: Soft-delete Category in Catalogue Service
        DELETE /api/categories/:id [Catalogue Service, Core Microservices]
        # Step 3: Invalidate Cache
        DELETE /api/cache/categories/:id [Caching Service, Shared Services]