openapi: 3.0.3
info:
  title: Managed Tenant Onboarding Wizard UI (v2) (Internal)
  version: 1.0.0
  description: >
    Conceptual/internal API contract for onboarding sessions, onboarding evidence,
    and starting onboarding tasks (OperationRun-backed).

servers:
  - url: https://example.invalid

paths:
  /tenants/{tenantId}/onboarding/session:
    get:
      summary: Get current onboarding session (or null)
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingSessionResponse'
    post:
      summary: Create (or resume) onboarding session
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingSession'

  /tenants/{tenantId}/onboarding/session/{sessionId}:
    patch:
      summary: Update onboarding session (step, assignment, handoff)
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOnboardingSessionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingSession'

  /tenants/{tenantId}/onboarding/tasks:
    get:
      summary: List onboarding tasks and latest status
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnboardingTaskSummary'

  /tenants/{tenantId}/onboarding/tasks/{taskType}/runs:
    post:
      summary: Start onboarding task (OperationRun-backed)
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/TaskType'
      responses:
        '201':
          description: Run created (or reused)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationRunLink'
        '409':
          description: Blocked by concurrency guard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /tenants/{tenantId}/onboarding/evidence:
    get:
      summary: List onboarding evidence
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - name: taskType
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnboardingEvidence'

components:
  parameters:
    TenantId:
      name: tenantId
      in: path
      required: true
      schema:
        type: integer
    SessionId:
      name: sessionId
      in: path
      required: true
      schema:
        type: integer
    TaskType:
      name: taskType
      in: path
      required: true
      schema:
        type: string

  schemas:
    OnboardingSessionResponse:
      type: object
      required: [session]
      properties:
        session:
          oneOf:
            - $ref: '#/components/schemas/OnboardingSession'
            - type: 'null'

    OnboardingSession:
      type: object
      required: [id, tenant_id, status, current_step]
      properties:
        id:
          type: integer
        tenant_id:
          type: integer
        provider_connection_id:
          type: integer
          nullable: true
        status:
          type: string
          enum: [draft, in_progress, completed, abandoned]
        current_step:
          type: integer
          minimum: 1
          maximum: 5
        assigned_to_user_id:
          type: integer
          nullable: true
        locked_by_user_id:
          type: integer
          nullable: true
        locked_until:
          type: string
          format: date-time
          nullable: true

    UpdateOnboardingSessionRequest:
      type: object
      properties:
        current_step:
          type: integer
          minimum: 1
          maximum: 5
        assigned_to_user_id:
          type: integer
          nullable: true
        takeover:
          type: boolean
          nullable: true

    OnboardingTaskSummary:
      type: object
      required: [task_type, status]
      properties:
        task_type:
          type: string
        status:
          type: string
          enum: [ok, warn, fail, unknown]
        reason_code:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        last_run_id:
          type: integer
          nullable: true

    OnboardingEvidence:
      type: object
      required: [id, tenant_id, task_type, status, recorded_at]
      properties:
        id:
          type: integer
        tenant_id:
          type: integer
        onboarding_session_id:
          type: integer
          nullable: true
        provider_connection_id:
          type: integer
          nullable: true
        task_type:
          type: string
        status:
          type: string
          enum: [ok, warn, fail, unknown]
        reason_code:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        payload:
          type: object
          additionalProperties: true
        operation_run_id:
          type: integer
          nullable: true
        recorded_at:
          type: string
          format: date-time

    OperationRunLink:
      type: object
      required: [run_id, url]
      properties:
        run_id:
          type: integer
        url:
          type: string

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string