openapi: 3.0.3
info:
  title: BeyondLabel MDM API
  description: |
    Master Data Management API for BeyondLabel Fashion Platform.

    ## Overview
    This API manages all master data for the BeyondLabel recommendation engine including:
    - **Categories**: Fashion item categories and attribute categories
    - **Items**: 297 fashion items across 8 main categories and 42 subcategories
    - **Attributes**: Colors (47), Materials (27), Textures (31), Patterns (11), Fits (6), Lengths (9), Silhouettes, Heel Heights (5)
    - **Parameters**: Emotions (6), Activities (36), Weather (17)
    - **Scores**: Item-Parameter scoring matrix (-10 to +10)
    - **Rules**: Essential/Supportive/Avoid styling rules
    - **Profane Words**: Social moderation dictionary
    - **Recommendation**: MCDM algorithm endpoints
    - **Analytics**: Scoring coverage and patterns

    ## MCDM Algorithm Weights
    - Emotion: 40%
    - Activity: 35%
    - Weather: 25%

    ## Score Range
    All scores range from **-10** (worst match) to **+10** (best match).

    ## Response Format
    All responses follow the BeyondLabel standard format:
    ```json
    {
      "success": true,
      "message": "Description of result",
      "code": 200,
      "data": { ... }
    }
    ```

  version: 1.0.0
  contact:
    name: BeyondLabel Dev Team
    email: dev@beyondlabel.io
  license:
    name: Proprietary
    url: https://beyondlabel.io/license

servers:
  - url: http://localhost:3002
    description: Local json-server Mock (db.json)
  - url: https://uat.beyondlabel.io/json-svr
    description: Mock json-server (Dev)
  - url: https://uat.beyondlabel.io/api/v1/mdm
    description: UAT Server
  - url: https://api.beyondlabel.io/v1/mdm
    description: Production

tags:
  - name: Categories
    description: Fashion item and attribute categories (8 main + 42 subcategories)
  - name: Items
    description: Fashion items (297 items across 8 categories)
  - name: Attributes
    description: Item attributes (Color, Material, Texture, Pattern, Fit, Length, Silhouette, HeelHeight)
  - name: Parameters
    description: Scoring parameters (Emotions, Activities, Weather)
  - name: Scores
    description: Item-Parameter scoring matrix
  - name: Rules
    description: Essential/Supportive/Avoid styling rules
  - name: Rule Prioritizations
    description: Rule prioritization configurations
  - name: Form Options
    description: Backoffice dropdown options
  - name: General Settings
    description: System-wide settings
  - name: Notification Settings
    description: Notification configuration
  - name: Profane Words
    description: Social moderation dictionary (NEW in v2)
  - name: Recommendation
    description: MCDM recommendation endpoints (NEW in v2)
  - name: Analytics
    description: Scoring analytics and coverage (NEW in v2)
  - name: Brands
    description: Brand management
  - name: Pages
    description: CMS pages
  - name: Size Standard
    description: Size standards and import
  - name: Import
    description: Data import endpoints

paths:
  # ============================================
  # CATEGORIES
  # ============================================
  /categories:
    get:
      tags: [Categories]
      summary: List all categories
      description: |
        Returns all categories. Use query parameters to filter.
        - type=0: Item categories (Tops, Bottoms, etc.)
        - type=1: Attribute categories (Colors, Materials, etc.)
      parameters:
        - $ref: '#/components/parameters/QuerySearch'
        - name: parent_id
          in: query
          schema:
            type: integer
          description: Filter by parent category ID
        - name: type
          in: query
          schema:
            type: integer
            enum: [0, 1]
          description: "0=ITEM, 1=ATTRIBUTE"
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QuerySort'
        - $ref: '#/components/parameters/QueryOrder'
      responses:
        '200':
          description: Categories retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponse'
    post:
      tags: [Categories]
      summary: Create or update category
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryInput'
      responses:
        '200':
          description: Category saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'

  /categories/{id}:
    get:
      tags: [Categories]
      summary: Get category by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Category details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Categories]
      summary: Delete category
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'
        '404':
          $ref: '#/components/responses/NotFound'

  # ============================================
  # ITEMS
  # ============================================
  /items:
    get:
      tags: [Items]
      summary: List all items
      description: Returns all 297 fashion items
      parameters:
        - $ref: '#/components/parameters/QuerySearch'
        - name: category_id
          in: query
          schema:
            type: integer
          description: Filter by category
        - name: subcategory_id
          in: query
          schema:
            type: integer
          description: Filter by subcategory
        - name: is_starter_pack
          in: query
          schema:
            type: boolean
          description: Filter starter pack items
        - name: is_active
          in: query
          schema:
            type: boolean
          description: Filter active items
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QuerySort'
        - $ref: '#/components/parameters/QueryOrder'
      responses:
        '200':
          description: Items retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemsResponse'
    post:
      tags: [Items]
      summary: Create or update item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemInput'
      responses:
        '200':
          description: Item saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'

  /items/{id}:
    get:
      tags: [Items]
      summary: Get item by ID
      description: Returns item with all scores
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Item details with scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemDetailResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Items]
      summary: Delete item
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # ATTRIBUTES
  # ============================================
  /attributes:
    get:
      tags: [Attributes]
      summary: List all attributes
      description: |
        Returns attributes by category:
        - Colors (47)
        - Materials (27)
        - Textures (31)
        - Patterns (11)
        - Fits (6)
        - Lengths (9)
        - Silhouettes
        - Heel Heights (5)
      parameters:
        - $ref: '#/components/parameters/QuerySearch'
        - name: category_id
          in: query
          schema:
            type: integer
          description: Filter by attribute category
        - name: subcategory
          in: query
          schema:
            type: string
          description: Filter by subcategory (for silhouettes)
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QuerySort'
        - $ref: '#/components/parameters/QueryOrder'
      responses:
        '200':
          description: Attributes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributesResponse'
    post:
      tags: [Attributes]
      summary: Create or update attribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeInput'
      responses:
        '200':
          description: Attribute saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeResponse'

  /attributes/{id}:
    get:
      tags: [Attributes]
      summary: Get attribute by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Attribute details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Attributes]
      summary: Delete attribute
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # PARAMETERS
  # ============================================
  /parameters:
    get:
      tags: [Parameters]
      summary: List all parameters
      description: |
        Returns parameters by type:
        - type=0: Emotions (6)
        - type=1: Weather (17)
        - type=2: Activities (36)
      parameters:
        - $ref: '#/components/parameters/QuerySearch'
        - name: type
          in: query
          schema:
            type: integer
            enum: [0, 1, 2]
          description: "0=EMOTION, 1=WEATHER, 2=ACTIVITY"
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QuerySort'
        - $ref: '#/components/parameters/QueryOrder'
      responses:
        '200':
          description: Parameters retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParametersResponse'
    post:
      tags: [Parameters]
      summary: Create or update parameter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParameterInput'
      responses:
        '200':
          description: Parameter saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterResponse'

  /parameters/{id}:
    get:
      tags: [Parameters]
      summary: Get parameter by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Parameter details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Parameters]
      summary: Delete parameter
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  /parameters/items/{parameterId}:
    get:
      tags: [Parameters]
      summary: Get items for parameter
      description: Returns all items with their scores for a specific parameter
      parameters:
        - name: parameterId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Parameter items with scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterItemsResponse'

  # ============================================
  # SCORES
  # ============================================
  /scores:
    get:
      tags: [Scores]
      summary: List all scores
      description: Returns item-parameter scores
      parameters:
        - name: item_id
          in: query
          schema:
            type: integer
          description: Filter by item
        - name: parameter_id
          in: query
          schema:
            type: integer
          description: Filter by parameter
        - name: attribute_id
          in: query
          schema:
            type: integer
          description: Filter by attribute
        - name: score_gte
          in: query
          schema:
            type: integer
          description: Score greater than or equal
        - name: score_lte
          in: query
          schema:
            type: integer
          description: Score less than or equal
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QuerySort'
        - $ref: '#/components/parameters/QueryOrder'
      responses:
        '200':
          description: Scores retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoresResponse'
    post:
      tags: [Scores]
      summary: Create or update score
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScoreInput'
      responses:
        '200':
          description: Score saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResponse'

  /scores/bulk:
    post:
      tags: [Scores]
      summary: Bulk create/update scores
      description: Create or update multiple scores at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scores:
                  type: array
                  items:
                    $ref: '#/components/schemas/ScoreInput'
      responses:
        '200':
          description: Scores saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkScoreResponse'

  /scores/{id}:
    get:
      tags: [Scores]
      summary: Get score by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Score details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Scores]
      summary: Delete score
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # RULES (NEW in v2)
  # ============================================
  /rules:
    get:
      tags: [Rules]
      summary: List all rules
      description: Returns Essential/Supportive/Avoid styling rules
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [essential, supportive, avoid]
          description: Filter by rule type
        - name: parameter_id
          in: query
          schema:
            type: integer
          description: Filter by parameter
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          description: Rules retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesResponse'
    post:
      tags: [Rules]
      summary: Create or update rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleInput'
      responses:
        '200':
          description: Rule saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleResponse'

  /rules/{id}:
    get:
      tags: [Rules]
      summary: Get rule by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Rule details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Rules]
      summary: Delete rule
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # RULE PRIORITIZATIONS
  # ============================================
  /rule-prioritizations:
    get:
      tags: [Rule Prioritizations]
      summary: List all rule prioritizations
      parameters:
        - $ref: '#/components/parameters/QuerySearch'
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          description: Rule prioritizations retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulePrioritizationsResponse'
    post:
      tags: [Rule Prioritizations]
      summary: Create or update rule prioritization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RulePrioritizationInput'
      responses:
        '200':
          description: Rule prioritization saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulePrioritizationResponse'

  /rule-prioritizations/{id}:
    get:
      tags: [Rule Prioritizations]
      summary: Get rule prioritization by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Rule prioritization details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulePrioritizationResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Rule Prioritizations]
      summary: Delete rule prioritization
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # PARAMETER RULES
  # ============================================
  /parameter-rule-items/{parameter_id}:
    get:
      tags: [Rules]
      summary: Get item rules for parameter
      parameters:
        - name: parameter_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Parameter item rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterRulesResponse'
    post:
      tags: [Rules]
      summary: Set item rules for parameter
      parameters:
        - name: parameter_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParameterRulesInput'
      responses:
        '200':
          description: Rules saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterRulesResponse'

  /parameter-rule-attributes/{parameter_id}:
    get:
      tags: [Rules]
      summary: Get attribute rules for parameter
      parameters:
        - name: parameter_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Parameter attribute rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterRulesResponse'
    post:
      tags: [Rules]
      summary: Set attribute rules for parameter
      parameters:
        - name: parameter_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParameterRulesInput'
      responses:
        '200':
          description: Rules saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterRulesResponse'

  # ============================================
  # FORM OPTIONS
  # ============================================
  /form-options:
    get:
      tags: [Form Options]
      summary: List all form options
      parameters:
        - $ref: '#/components/parameters/QuerySearch'
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          description: Form options retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormOptionsResponse'
    post:
      tags: [Form Options]
      summary: Create form option
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormOptionInput'
      responses:
        '200':
          description: Form option created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormOptionResponse'

  /form-options/bulk:
    post:
      tags: [Form Options]
      summary: Bulk create form options
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                options:
                  type: array
                  items:
                    $ref: '#/components/schemas/FormOptionInput'
      responses:
        '200':
          description: Form options created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormOptionsResponse'

  /form-options/{id}:
    get:
      tags: [Form Options]
      summary: Get form option by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Form option details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormOptionResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [Form Options]
      summary: Update form option
      parameters:
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormOptionInput'
      responses:
        '200':
          description: Form option updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormOptionResponse'
    delete:
      tags: [Form Options]
      summary: Delete form option
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # GENERAL SETTINGS
  # ============================================
  /general-settings:
    get:
      tags: [General Settings]
      summary: List all settings
      responses:
        '200':
          description: Settings retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingsResponse'
    post:
      tags: [General Settings]
      summary: Create or update setting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneralSettingInput'
      responses:
        '200':
          description: Setting saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingResponse'

  /general-settings/{id}:
    get:
      tags: [General Settings]
      summary: Get setting by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Setting details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralSettingResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [General Settings]
      summary: Delete setting
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # NOTIFICATION SETTINGS
  # ============================================
  /notification-settings:
    get:
      tags: [Notification Settings]
      summary: List all notification settings
      responses:
        '200':
          description: Notification settings retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSettingsResponse'
    post:
      tags: [Notification Settings]
      summary: Create or update notification setting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSettingInput'
      responses:
        '200':
          description: Notification setting saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSettingResponse'

  /notification-settings/{id}:
    get:
      tags: [Notification Settings]
      summary: Get notification setting by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Notification setting details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSettingResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Notification Settings]
      summary: Delete notification setting
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # PROFANE WORDS (NEW in v2)
  # ============================================
  /profane-words:
    get:
      tags: [Profane Words]
      summary: List all profane words
      description: Returns profane words for Social Service moderation cache
      parameters:
        - name: severity
          in: query
          schema:
            type: string
            enum: [mild, moderate, severe]
          description: Filter by severity level
        - name: action
          in: query
          schema:
            type: string
            enum: [flag, block, replace]
          description: Filter by action type
        - name: is_active
          in: query
          schema:
            type: boolean
          description: Filter active words only
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          description: Profane words retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfaneWordsResponse'
    post:
      tags: [Profane Words]
      summary: Add profane word
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfaneWordInput'
      responses:
        '200':
          description: Profane word added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfaneWordResponse'

  /profane-words/{id}:
    get:
      tags: [Profane Words]
      summary: Get profane word by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Profane word details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfaneWordResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [Profane Words]
      summary: Update profane word
      parameters:
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfaneWordInput'
      responses:
        '200':
          description: Profane word updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfaneWordResponse'
    delete:
      tags: [Profane Words]
      summary: Delete profane word (soft delete)
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # RECOMMENDATION (NEW in v2)
  # ============================================
  /recommend:
    post:
      tags: [Recommendation]
      summary: Get recommendations
      description: |
        Returns recommended items based on MCDM algorithm.

        Weights:
        - Emotion: 40%
        - Activity: 35%
        - Weather: 25%
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendationRequest'
      responses:
        '200':
          description: Recommendations retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationResponse'

  /recommend/outfit:
    post:
      tags: [Recommendation]
      summary: Get complete outfit recommendation
      description: Returns a complete outfit (top, bottom, accessories, etc.)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutfitRecommendationRequest'
      responses:
        '200':
          description: Outfit recommendation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutfitRecommendationResponse'

  # ============================================
  # ANALYTICS (NEW in v2)
  # ============================================
  /analytics/coverage:
    get:
      tags: [Analytics]
      summary: Get scoring coverage statistics
      description: Returns statistics about scored items and parameters
      responses:
        '200':
          description: Coverage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsCoverageResponse'

  /analytics/patterns:
    get:
      tags: [Analytics]
      summary: Get scoring patterns analysis
      description: Returns analysis of scoring patterns across parameters
      parameters:
        - name: parameter_type
          in: query
          schema:
            type: integer
            enum: [0, 1, 2]
          description: Filter by parameter type
      responses:
        '200':
          description: Patterns analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsPatternsResponse'

  # ============================================
  # BRANDS
  # ============================================
  /brands:
    get:
      tags: [Brands]
      summary: List all brands
      parameters:
        - $ref: '#/components/parameters/QuerySearch'
        - $ref: '#/components/parameters/QueryPage'
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          description: Brands retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandsResponse'
    post:
      tags: [Brands]
      summary: Create or update brand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandInput'
      responses:
        '200':
          description: Brand saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandResponse'

  /brands/{id}:
    get:
      tags: [Brands]
      summary: Get brand by ID
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Brand details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Brands]
      summary: Delete brand
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # PAGES
  # ============================================
  /pages:
    get:
      tags: [Pages]
      summary: List all pages
      responses:
        '200':
          description: Pages retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagesResponse'
    post:
      tags: [Pages]
      summary: Create page
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageInput'
      responses:
        '200':
          description: Page created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'

  /pages/{slug}:
    get:
      tags: [Pages]
      summary: Get page by slug
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Page details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /pages/{id}:
    put:
      tags: [Pages]
      summary: Update page
      parameters:
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageInput'
      responses:
        '200':
          description: Page updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResponse'
    delete:
      tags: [Pages]
      summary: Delete page
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          $ref: '#/components/responses/DeleteSuccess'

  # ============================================
  # SIZE STANDARD
  # ============================================
  /size-standard:
    get:
      tags: [Size Standard]
      summary: List all size standards
      responses:
        '200':
          description: Size standards retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SizeStandardsResponse'

  /size-standard/download-sample:
    get:
      tags: [Size Standard]
      summary: Download sample CSV template
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
                format: binary

  /size-standard/import:
    post:
      tags: [Size Standard]
      summary: Import size standards from CSV
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Import successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'

  # ============================================
  # IMPORT
  # ============================================
  /import/item-paramater-score/activity-weather:
    post:
      tags: [Import]
      summary: Import activity/weather scores
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Import successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'

  /import/item-paramater-score/emotion:
    post:
      tags: [Import]
      summary: Import emotion scores
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Import successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'

  /import/item-paramater-rule/activity-weather:
    post:
      tags: [Import]
      summary: Import activity/weather rules
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Import successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'

  /import/item-paramater-rule/emotion:
    post:
      tags: [Import]
      summary: Import emotion rules
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Import successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'

  # ============================================
  # MISC
  # ============================================
  /parameter-score-value:
    get:
      tags: [Parameters]
      summary: Get parameter score values
      description: Returns score value reference data
      responses:
        '200':
          description: Score values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParameterScoreValueResponse'

# ============================================
# COMPONENTS
# ============================================
components:
  parameters:
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: Resource ID

    QuerySearch:
      name: q
      in: query
      schema:
        type: string
      description: Full-text search (json-server compatible)

    QueryPage:
      name: _page
      in: query
      schema:
        type: integer
        default: 1
      description: Page number (json-server format)

    QueryLimit:
      name: _limit
      in: query
      schema:
        type: integer
        default: 20
      description: Items per page (json-server format)

    QuerySort:
      name: _sort
      in: query
      schema:
        type: string
      description: Sort field (json-server format)

    QueryOrder:
      name: _order
      in: query
      schema:
        type: string
        enum: [asc, desc]
      description: Sort direction (json-server format)

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    DeleteSuccess:
      description: Resource deleted successfully
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: true
              message:
                type: string
                example: "Resource deleted successfully."
              code:
                type: integer
                example: 200

    Unauthorized:
      description: Unauthorized - Invalid or missing authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'

    Forbidden:
      description: Forbidden - User does not have permission to access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenResponse'

    ValidationError:
      description: Validation Error - Request data failed validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'

    InternalServerError:
      description: Internal Server Error - An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerErrorResponse'

  schemas:
    # ========== BASE SCHEMAS ==========
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Resource not found."
        code:
          type: integer
          example: 404

    UnauthorizedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Unauthorized. Please provide valid credentials."
        code:
          type: integer
          example: 401

    ForbiddenResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Forbidden. You don't have permission to access this resource."
        code:
          type: integer
          example: 403

    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          example: "The name field is required. (and 2 more errors)"
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            name: ["The name field is required."]
            type: ["The type must be an integer."]

    InternalServerErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Internal server error. Please try again later."
        code:
          type: integer
          example: 500

    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total_rows:
          type: integer
          example: 100

    # ========== CATEGORY ==========
    Category:
      type: object
      properties:
        id:
          type: integer
          example: 1
        parent_id:
          type: integer
          nullable: true
          example: null
        name:
          type: string
          example: "Tops"
        description:
          type: string
          example: "Upper body garments"
        type:
          type: integer
          enum: [0, 1]
          description: "0=ITEM, 1=ATTRIBUTE"
          example: 0
        level:
          type: integer
          description: "1=category, 2=subcategory"
          example: 1
        image:
          type: string
          nullable: true
          example: "https://cdn.beyondlabel.io/categories/tops.jpg"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CategoryInput:
      type: object
      required: [name, type]
      properties:
        id:
          type: integer
        parent_id:
          type: integer
          nullable: true
        name:
          type: string
        description:
          type: string
        type:
          type: integer
          enum: [0, 1]
        image:
          type: string

    CategoriesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Categories retrieved successfully."
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Category'

    CategoryResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Category'

    CategoriesPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
            rows:
              type: array
              items:
                $ref: '#/components/schemas/Category'

    # ========== ITEM ==========
    Item:
      type: object
      properties:
        id:
          type: integer
          example: 1
        category_id:
          type: integer
          example: 1
        subcategory_id:
          type: integer
          example: 2
        name:
          type: string
          example: "Long sleeved shirt"
        description:
          type: string
          example: "Classic long sleeved shirt"
        image:
          type: string
          nullable: true
        is_starter_pack:
          type: boolean
          example: true
        is_active:
          type: boolean
          example: true
        attributes:
          type: object
          description: "JSONB for item attributes"
          example:
            color_ids: [1, 2]
            material_ids: [3, 4]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ItemInput:
      type: object
      required: [category_id, name]
      properties:
        id:
          type: integer
        category_id:
          type: integer
        subcategory_id:
          type: integer
        name:
          type: string
        description:
          type: string
        image:
          type: string
        is_starter_pack:
          type: boolean
        is_active:
          type: boolean
        attributes:
          type: object

    ItemsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Items retrieved successfully."
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Item'

    ItemResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Item'

    ItemDetailResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          allOf:
            - $ref: '#/components/schemas/Item'
            - type: object
              properties:
                scores:
                  type: array
                  items:
                    $ref: '#/components/schemas/Score'

    ItemsPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
            rows:
              type: array
              items:
                $ref: '#/components/schemas/Item'

    # ========== ATTRIBUTE ==========
    Attribute:
      type: object
      properties:
        id:
          type: integer
          example: 1
        category_id:
          type: integer
          example: 9
          description: "Links to attribute type category (Colors, Materials, etc.)"
        name:
          type: string
          example: "Bright Red"
        description:
          type: string
          example: "Vivid, saturated red tones"
        subcategory:
          type: string
          nullable: true
          description: "For silhouettes - subcategory grouping"
          example: "Red"
        metadata:
          type: object
          description: "Additional data (hex codes for colors, etc.)"
          example:
            hex: "#FF0000"
            group: "Red"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AttributeInput:
      type: object
      required: [category_id, name]
      properties:
        id:
          type: integer
        category_id:
          type: integer
        name:
          type: string
        description:
          type: string
        subcategory:
          type: string
        metadata:
          type: object

    AttributesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Attributes retrieved successfully."
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'

    AttributeResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Attribute'

    AttributesPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
            rows:
              type: array
              items:
                $ref: '#/components/schemas/Attribute'

    # ========== PARAMETER ==========
    Parameter:
      type: object
      properties:
        id:
          type: integer
          example: 1
        category_id:
          type: integer
          example: 1
        name:
          type: string
          example: "Enjoyment / Joy"
        type:
          type: integer
          enum: [0, 1, 2]
          description: "0=EMOTION, 1=WEATHER, 2=ACTIVITY"
          example: 0
        description:
          type: string
          example: "Positive affect - maximize"
        image:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ParameterInput:
      type: object
      required: [name, type]
      properties:
        id:
          type: integer
        category_id:
          type: integer
        name:
          type: string
        type:
          type: integer
          enum: [0, 1, 2]
        description:
          type: string
        image:
          type: string

    ParametersResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Parameters retrieved successfully."
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Parameter'

    ParameterResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Parameter'

    ParametersPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
            rows:
              type: array
              items:
                $ref: '#/components/schemas/Parameter'

    ParameterItemsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            parameter:
              $ref: '#/components/schemas/Parameter'
            items:
              type: array
              items:
                type: object
                properties:
                  item:
                    $ref: '#/components/schemas/Item'
                  score:
                    type: integer
                    minimum: -10
                    maximum: 10

    ParameterScoreValueResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            type: object
            properties:
              value:
                type: integer
              label:
                type: string
              description:
                type: string

    # ========== SCORE ==========
    Score:
      type: object
      properties:
        id:
          type: integer
          example: 1
        item_id:
          type: integer
          example: 1
        parameter_id:
          type: integer
          example: 1
        attribute_id:
          type: integer
          nullable: true
          example: null
        score:
          type: integer
          minimum: -10
          maximum: 10
          example: 7
        rule_id:
          type: integer
          nullable: true
          example: null
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ScoreInput:
      type: object
      required: [item_id, parameter_id, score]
      properties:
        id:
          type: integer
        item_id:
          type: integer
        parameter_id:
          type: integer
        attribute_id:
          type: integer
        score:
          type: integer
          minimum: -10
          maximum: 10
        rule_id:
          type: integer

    ScoresResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Scores retrieved successfully."
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Score'

    ScoreResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Score'

    ScoresPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
            rows:
              type: array
              items:
                $ref: '#/components/schemas/Score'

    BulkScoreResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "10 scores saved successfully."
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            created:
              type: integer
            updated:
              type: integer

    # ========== RULE ==========
    Rule:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Business Formal Essential"
        type:
          type: string
          enum: [essential, supportive, avoid]
          example: "essential"
        parameter_id:
          type: integer
          example: 1
        conditions:
          type: object
          description: "Rule conditions"
        priority:
          type: integer
          example: 1
        is_active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    RuleInput:
      type: object
      required: [name, type, parameter_id]
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum: [essential, supportive, avoid]
        parameter_id:
          type: integer
        conditions:
          type: object
        priority:
          type: integer
        is_active:
          type: boolean

    RulesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Rules retrieved successfully."
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Rule'

    RuleResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Rule'

    ParameterRulesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            parameter_id:
              type: integer
            essential:
              type: array
              items:
                type: integer
            supportive:
              type: array
              items:
                type: integer
            avoid:
              type: array
              items:
                type: integer

    ParameterRulesInput:
      type: object
      properties:
        essential:
          type: array
          items:
            type: integer
        supportive:
          type: array
          items:
            type: integer
        avoid:
          type: array
          items:
            type: integer

    # ========== RULE PRIORITIZATION ==========
    RulePrioritization:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Default Prioritization"
        parameters:
          type: object
          description: "Parameter weights"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    RulePrioritizationInput:
      type: object
      required: [name]
      properties:
        id:
          type: integer
        name:
          type: string
        parameters:
          type: object

    RulePrioritizationsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/RulePrioritization'

    RulePrioritizationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/RulePrioritization'

    RulePrioritizationsPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
            rows:
              type: array
              items:
                $ref: '#/components/schemas/RulePrioritization'

    # ========== FORM OPTION ==========
    FormOption:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "score_values"
        options:
          type: array
          items:
            type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    FormOptionInput:
      type: object
      required: [name, options]
      properties:
        id:
          type: integer
        name:
          type: string
        options:
          type: array
          items:
            type: object

    FormOptionsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/FormOption'

    FormOptionResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/FormOption'

    # ========== GENERAL SETTING ==========
    GeneralSetting:
      type: object
      properties:
        id:
          type: integer
          example: 1
        key:
          type: string
          example: "mcdm_emotion_weight"
        value:
          type: string
          example: "0.40"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    GeneralSettingInput:
      type: object
      required: [key, value]
      properties:
        id:
          type: integer
        key:
          type: string
        value:
          type: string

    GeneralSettingsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/GeneralSetting'

    GeneralSettingResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/GeneralSetting'

    GeneralSettingsPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            meta:
              $ref: '#/components/schemas/PaginationMeta'
            rows:
              type: array
              items:
                $ref: '#/components/schemas/GeneralSetting'

    # ========== NOTIFICATION SETTING ==========
    NotificationSetting:
      type: object
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          example: "push"
        settings:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    NotificationSettingInput:
      type: object
      required: [type, settings]
      properties:
        id:
          type: integer
        type:
          type: string
        settings:
          type: object

    NotificationSettingsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/NotificationSetting'

    NotificationSettingResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/NotificationSetting'

    # ========== PROFANE WORD (NEW in v2) ==========
    ProfaneWord:
      type: object
      properties:
        id:
          type: integer
          example: 1
        word:
          type: string
          example: "inappropriate"
        severity:
          type: string
          enum: [mild, moderate, severe]
          example: "mild"
        action:
          type: string
          enum: [flag, block, replace]
          example: "flag"
        replacement:
          type: string
          nullable: true
          example: "****"
        is_active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ProfaneWordInput:
      type: object
      required: [word, severity, action]
      properties:
        id:
          type: integer
        word:
          type: string
        severity:
          type: string
          enum: [mild, moderate, severe]
        action:
          type: string
          enum: [flag, block, replace]
        replacement:
          type: string
        is_active:
          type: boolean

    ProfaneWordsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Profane words retrieved successfully."
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProfaneWord'

    ProfaneWordResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/ProfaneWord'

    # ========== RECOMMENDATION (NEW in v2) ==========
    RecommendationRequest:
      type: object
      required: [emotion_id]
      properties:
        emotion_id:
          type: integer
          description: "Emotion parameter ID"
          example: 1
        activity_id:
          type: integer
          description: "Activity parameter ID"
          example: 10
        weather_id:
          type: integer
          description: "Weather parameter ID"
          example: 20
        wardrobe_item_ids:
          type: array
          items:
            type: integer
          description: "User's wardrobe items to consider"
        exclude_item_ids:
          type: array
          items:
            type: integer
          description: "Items to exclude from recommendations"
        limit:
          type: integer
          default: 10
          description: "Number of recommendations"
        category_ids:
          type: array
          items:
            type: integer
          description: "Filter by categories"

    RecommendationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Recommendations generated successfully."
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            recommendations:
              type: array
              items:
                type: object
                properties:
                  item:
                    $ref: '#/components/schemas/Item'
                  score:
                    type: number
                    format: float
                    description: "Weighted MCDM score"
                  breakdown:
                    type: object
                    properties:
                      emotion_score:
                        type: integer
                      activity_score:
                        type: integer
                      weather_score:
                        type: integer
            parameters:
              type: object
              properties:
                emotion:
                  $ref: '#/components/schemas/Parameter'
                activity:
                  $ref: '#/components/schemas/Parameter'
                weather:
                  $ref: '#/components/schemas/Parameter'
            weights:
              type: object
              properties:
                emotion:
                  type: number
                  example: 0.40
                activity:
                  type: number
                  example: 0.35
                weather:
                  type: number
                  example: 0.25

    OutfitRecommendationRequest:
      type: object
      required: [emotion_id]
      properties:
        emotion_id:
          type: integer
        activity_id:
          type: integer
        weather_id:
          type: integer
        wardrobe_item_ids:
          type: array
          items:
            type: integer
        base_item_id:
          type: integer
          description: "Start with this item in the outfit"
        include_categories:
          type: array
          items:
            type: integer
          description: "Categories to include in outfit"

    OutfitRecommendationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Outfit recommendation generated successfully."
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            outfit:
              type: array
              items:
                type: object
                properties:
                  category:
                    type: string
                    example: "Tops"
                  item:
                    $ref: '#/components/schemas/Item'
                  score:
                    type: number
            total_score:
              type: number
              format: float
            parameters:
              type: object
              properties:
                emotion:
                  $ref: '#/components/schemas/Parameter'
                activity:
                  $ref: '#/components/schemas/Parameter'
                weather:
                  $ref: '#/components/schemas/Parameter'

    # ========== ANALYTICS (NEW in v2) ==========
    AnalyticsCoverageResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Coverage statistics retrieved."
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            total_items:
              type: integer
              example: 297
            scored_items:
              type: integer
              example: 297
            coverage_percent:
              type: number
              format: float
              example: 100.0
            by_category:
              type: array
              items:
                type: object
                properties:
                  category_id:
                    type: integer
                  category_name:
                    type: string
                  total:
                    type: integer
                  scored:
                    type: integer
                  coverage_percent:
                    type: number
            by_parameter_type:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: integer
                  type_name:
                    type: string
                  parameters:
                    type: integer
                  scores:
                    type: integer

    AnalyticsPatternsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Patterns analysis retrieved."
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            score_distribution:
              type: array
              items:
                type: object
                properties:
                  score:
                    type: integer
                  count:
                    type: integer
            top_scored_items:
              type: array
              items:
                type: object
                properties:
                  item:
                    $ref: '#/components/schemas/Item'
                  average_score:
                    type: number
            parameter_correlations:
              type: array
              items:
                type: object
                properties:
                  parameter_1:
                    type: string
                  parameter_2:
                    type: string
                  correlation:
                    type: number

    # ========== BRAND ==========
    Brand:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Zara"
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    BrandInput:
      type: object
      required: [name]
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string

    BrandsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Brand'

    BrandResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Brand'

    # ========== PAGE ==========
    Page:
      type: object
      properties:
        id:
          type: integer
          example: 1
        slug:
          type: string
          example: "terms-of-service"
        title:
          type: string
          example: "Terms of Service"
        content:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    PageInput:
      type: object
      required: [slug, title, content]
      properties:
        id:
          type: integer
        slug:
          type: string
        title:
          type: string
        content:
          type: string

    PagesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/Page'

    PageResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Page'

    # ========== SIZE STANDARD ==========
    SizeStandard:
      type: object
      properties:
        id:
          type: integer
          example: 1
        region:
          type: string
          example: "EU"
        sizes:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    SizeStandardsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        code:
          type: integer
          example: 200
        data:
          type: array
          items:
            $ref: '#/components/schemas/SizeStandard'

    # ========== IMPORT ==========
    ImportResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Import completed successfully."
        code:
          type: integer
          example: 200
        data:
          type: object
          properties:
            imported:
              type: integer
              example: 100
            skipped:
              type: integer
              example: 5
            errors:
              type: array
              items:
                type: string
