openapi: 3.1.0
info:
  title: yuban-server business capability API
  version: 1.0.0
servers:
  - url: https://business-api.yuban.co
paths:
  /health:
    get:
      operationId: health
      responses:
        '200':
          description: Service is healthy
  /recording-transcription/jobs:
    post:
      operationId: createRecordingTranscriptionJob
      security:
        - bearerAuth: []
      parameters:
        - in: header
          name: Idempotency-Key
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecordingTranscriptionJob'
      responses:
        '202':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
  /recording-transcription/jobs/{jobId}:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      operationId: getRecordingTranscriptionJob
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current job state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
  /recording-transcription/jobs/{jobId}/cancel:
    parameters:
      - $ref: '#/components/parameters/JobId'
    post:
      operationId: cancelRecordingTranscriptionJob
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Job cancelled or already terminal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    JobId:
      in: path
      name: jobId
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    CreateRecordingTranscriptionJob:
      type: object
      required: [audioUrl]
      additionalProperties: false
      properties:
        audioUrl:
          type: string
          format: uri
        durationMs:
          type: integer
          minimum: 1
        roleType:
          type: integer
          enum: [0, 1]
          default: 1
        roleNum:
          type: integer
          minimum: 0
          maximum: 10
          default: 0
        requestId:
          type: string
          maxLength: 200
    JobResponse:
      type: object
      required: [success, job]
      properties:
        success:
          type: boolean
          const: true
        reused:
          type: boolean
        job:
          $ref: '#/components/schemas/Job'
    Job:
      type: object
      required: [id, status, stage, progress, createdAt, updatedAt, expiresAt]
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [queued, running, completed, failed, cancelled]
        stage:
          type: string
        progress:
          type: integer
          minimum: 0
          maximum: 100
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        heartbeatAt:
          type: [string, 'null']
          format: date-time
        expiresAt:
          type: string
          format: date-time
        result:
          $ref: '#/components/schemas/TranscriptionResult'
        error:
          $ref: '#/components/schemas/Error'
    TranscriptionResult:
      type: object
      required: [text, segments, charCount, sha256]
      properties:
        text:
          type: string
        segments:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
        charCount:
          type: integer
        sha256:
          type: string
          pattern: '^[0-9a-f]{64}$'
    Segment:
      type: object
      required: [text]
      properties:
        text:
          type: string
        startMs:
          type: [integer, 'null']
        endMs:
          type: [integer, 'null']
        speakerId:
          type: [string, 'null']
    Error:
      type: object
      required: [code, message, retryable]
      properties:
        code:
          type: string
        message:
          type: string
        retryable:
          type: boolean