таски готовы

specs/020-task-reports-design/contracts/reports-api.openapi.yaml

@@ -0,0 +1,272 @@
+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]