openapi: 3.1.0
info:
  title: User Profile Dashboard Filter API
  version: "1.0.0"
  description: >
    API contract for user profile dashboard filtering with Superset account lookup
    by selected environment and default "my dashboards" behavior on the main dashboards page.
servers:
  - url: /api

security:
  - bearerAuth: []

paths:
  /profile/preferences:
    get:
      summary: Get current user's dashboard filter preferences
      operationId: getMyDashboardPreferences
      tags: [profile]
      responses:
        "200":
          description: Preference payload for authenticated user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProfilePreferenceResponse"
        "401":
          description: Unauthorized
    patch:
      summary: Update current user's dashboard filter preferences
      operationId: updateMyDashboardPreferences
      tags: [profile]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProfilePreferenceUpdateRequest"
            examples:
              enableFilter:
                value:
                  superset_username: "john_doe"
                  show_only_my_dashboards: true
              disableFilter:
                value:
                  superset_username: "john_doe"
                  show_only_my_dashboards: false
      responses:
        "200":
          description: Preference saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProfilePreferenceResponse"
        "401":
          description: Unauthorized
        "422":
          description: Validation failed

  /profile/superset-accounts:
    get:
      summary: Lookup Superset accounts in selected environment for profile binding
      operationId: lookupSupersetAccounts
      tags: [profile, lookup]
      parameters:
        - name: environment_id
          in: query
          required: true
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: page_index
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: sort_column
          in: query
          required: false
          schema:
            type: string
            enum: [username, first_name, last_name, email]
            default: username
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        "200":
          description: Lookup result (success or degraded with warning)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupersetAccountLookupResponse"
              examples:
                success:
                  value:
                    status: success
                    environment_id: dev
                    page_index: 0
                    page_size: 20
                    total: 2
                    items:
                      - environment_id: dev
                        username: john_doe
                        display_name: John Doe
                        email: john@example.local
                        is_active: true
                      - environment_id: dev
                        username: jane_admin
                        display_name: Jane Admin
                        email: jane@example.local
                        is_active: true
                degraded:
                  value:
                    status: degraded
                    environment_id: dev
                    page_index: 0
                    page_size: 20
                    total: 0
                    warning: Cannot load Superset accounts for this environment right now. You can enter username manually.
                    items: []
        "401":
          description: Unauthorized
        "404":
          description: Environment not found

  /dashboards:
    get:
      summary: Get dashboards list with optional profile-default filtering context
      operationId: getDashboards
      tags: [dashboards]
      parameters:
        - name: env_id
          in: query
          required: true
          schema:
            type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: page_context
          in: query
          required: false
          schema:
            type: string
            enum: [dashboards_main, other]
            default: dashboards_main
        - name: apply_profile_default
          in: query
          required: false
          schema:
            type: boolean
            default: true
        - name: override_show_all
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: filter_title
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: filter_git_status
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: filter_llm_status
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: filter_changed_on
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: filter_actor
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Dashboards page with effective profile filter metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DashboardsResponse"
        "400":
          description: Invalid pagination or query parameters
        "401":
          description: Unauthorized
        "404":
          description: Environment not found
        "503":
          description: Superset backend unavailable

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ProfilePreference:
      type: object
      required:
        - user_id
        - show_only_my_dashboards
        - created_at
        - updated_at
      properties:
        user_id:
          type: string
        superset_username:
          type: string
          nullable: true
        superset_username_normalized:
          type: string
          nullable: true
        show_only_my_dashboards:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ProfilePreferenceUpdateRequest:
      type: object
      required:
        - show_only_my_dashboards
      properties:
        superset_username:
          type: string
          nullable: true
        show_only_my_dashboards:
          type: boolean

    ProfilePreferenceResponse:
      type: object
      required:
        - status
        - preference
      properties:
        status:
          type: string
          enum: [success, error]
        message:
          type: string
        validation_errors:
          type: array
          items:
            type: string
        preference:
          $ref: "#/components/schemas/ProfilePreference"

    SupersetAccountCandidate:
      type: object
      required:
        - environment_id
        - username
      properties:
        environment_id:
          type: string
        username:
          type: string
        display_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        is_active:
          type: boolean
          nullable: true

    SupersetAccountLookupResponse:
      type: object
      required:
        - status
        - environment_id
        - page_index
        - page_size
        - total
        - items
      properties:
        status:
          type: string
          enum: [success, degraded]
        environment_id:
          type: string
        page_index:
          type: integer
          minimum: 0
        page_size:
          type: integer
          minimum: 1
          maximum: 100
        total:
          type: integer
          minimum: 0
        warning:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/SupersetAccountCandidate"

    GitStatus:
      type: object
      properties:
        branch:
          type: string
          nullable: true
        sync_status:
          type: string
          enum: [OK, DIFF, NO_REPO, ERROR]
          nullable: true
        has_repo:
          type: boolean
          nullable: true
        has_changes_for_commit:
          type: boolean
          nullable: true

    LastTask:
      type: object
      properties:
        task_id:
          type: string
          nullable: true
        status:
          type: string
          enum: [PENDING, RUNNING, SUCCESS, FAILED, ERROR, AWAITING_INPUT, WAITING_INPUT, AWAITING_MAPPING]
          nullable: true
        validation_status:
          type: string
          enum: [PASS, FAIL, WARN, UNKNOWN]
          nullable: true

    DashboardItem:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: integer
        title:
          type: string
        slug:
          type: string
          nullable: true
        last_modified:
          type: string
          nullable: true
        created_by:
          type: string
          nullable: true
        modified_by:
          type: string
          nullable: true
        owners:
          type: array
          items:
            type: string
        git_status:
          $ref: "#/components/schemas/GitStatus"
        last_task:
          $ref: "#/components/schemas/LastTask"

    EffectiveProfileFilter:
      type: object
      required:
        - applied
        - source_page
        - override_show_all
      properties:
        applied:
          type: boolean
        source_page:
          type: string
          enum: [dashboards_main, other]
        override_show_all:
          type: boolean
        username:
          type: string
          nullable: true
        match_logic:
          type: string
          enum: [owners_or_modified_by]

    DashboardsResponse:
      type: object
      required:
        - dashboards
        - total
        - page
        - page_size
        - total_pages
      properties:
        dashboards:
          type: array
          items:
            $ref: "#/components/schemas/DashboardItem"
        total:
          type: integer
          minimum: 0
        page:
          type: integer
          minimum: 1
        page_size:
          type: integer
          minimum: 1
        total_pages:
          type: integer
          minimum: 1
        effective_profile_filter:
          $ref: "#/components/schemas/EffectiveProfileFilter"