openapi: 3.0.3
info:
  title: Unified Task Reports API
  version: 1.0.0
  description: API contract for consolidated task reports across task types.

servers:
  - url: /api

paths:
  /reports:
    get:
      summary: List unified task reports
      description: Returns paginated normalized reports with filtering and sorting.
      operationId: listReports
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: page_size
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - in: query
          name: task_types
          description: Comma-separated values
          schema:
            type: string
            example: migration,backup
        - in: query
          name: statuses
          description: Comma-separated values
          schema:
            type: string
            example: failed,in_progress
        - in: query
          name: time_from
          schema:
            type: string
            format: date-time
        - in: query
          name: time_to
          schema:
            type: string
            format: date-time
        - in: query
          name: search
          schema:
            type: string
            maxLength: 200
        - in: query
          name: sort_by
          schema:
            type: string
            enum: [updated_at, status, task_type]
            default: updated_at
        - in: query
          name: sort_order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Paginated unified reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportCollection'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden

  /reports/{report_id}:
    get:
      summary: Get report detail
      description: Returns one normalized report with optional diagnostics and next actions.
      operationId: getReportDetail
      parameters:
        - in: path
          name: report_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Report detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportDetailView'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Report not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    TaskType:
      type: string
      enum:
        - llm_verification
        - backup
        - migration
        - documentation
        - unknown

    ReportStatus:
      type: string
      enum:
        - success
        - failed
        - in_progress
        - partial

    ReportSourceRef:
      type: object
      additionalProperties: true
      description: Optional pointers to related domain objects (dashboard/dataset/environment).

    ErrorContext:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        next_actions:
          type: array
          items:
            type: string
      required: [message]

    TaskReport:
      type: object
      properties:
        report_id:
          type: string
        task_id:
          type: string
        task_type:
          $ref: '#/components/schemas/TaskType'
        status:
          $ref: '#/components/schemas/ReportStatus'
        started_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
        summary:
          type: string
        details:
          type: object
          nullable: true
          additionalProperties: true
        error_context:
          $ref: '#/components/schemas/ErrorContext'
        source_ref:
          $ref: '#/components/schemas/ReportSourceRef'
      required:
        - report_id
        - task_id
        - task_type
        - status
        - updated_at
        - summary

    ReportQueryEcho:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        task_types:
          type: array
          items:
            $ref: '#/components/schemas/TaskType'
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/ReportStatus'
        time_from:
          type: string
          format: date-time
          nullable: true
        time_to:
          type: string
          format: date-time
          nullable: true
        search:
          type: string
          nullable: true
        sort_by:
          type: string
          enum: [updated_at, status, task_type]
        sort_order:
          type: string
          enum: [asc, desc]
      required: [page, page_size, sort_by, sort_order]

    ReportCollection:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TaskReport'
        total:
          type: integer
          minimum: 0
        page:
          type: integer
          minimum: 1
        page_size:
          type: integer
          minimum: 1
        has_next:
          type: boolean
        applied_filters:
          $ref: '#/components/schemas/ReportQueryEcho'
      required: [items, total, page, page_size, has_next, applied_filters]

    ReportDetailView:
      type: object
      properties:
        report:
          $ref: '#/components/schemas/TaskReport'
        timeline:
          type: array
          items:
            type: object
            additionalProperties: true
        diagnostics:
          type: object
          nullable: true
          additionalProperties: true
        next_actions:
          type: array
          items:
            type: string
      required: [report]

    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string
      required: [detail]