openapi: 3.0.3
info:
  title: Numerology Platform Public API
  version: 1.0.0
  description: |
    Публичная документация для клиентов платформы (astro/numerology/ai).
    Все запросы выполняются с заголовком x-api-key.
servers:
  - url: https://platform.mgcm8.com
security:
  - ApiKeyAuth: []
paths:
  /v1/compute:
    post:
      tags: [Public API]
      summary: Синхронный расчет модулей
      description: Возвращает результат сразу. Подходит для realtime-сценариев.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComputeRequest'
            examples:
              numerology_full:
                summary: Полный нумерологический профиль
                value:
                  subject:
                    date: '1990-05-15'
                    time: '12:00:00'
                    timezone: Europe/Moscow
                  locale: ru
                  modules: [numerology.full]
              astrology_natal:
                summary: Натальная карта
                value:
                  subject:
                    date: '1990-05-15'
                    time: '12:00:00'
                    timezone: Europe/Moscow
                    lat: 55.7558
                    lon: 37.6176
                  locale: ru
                  modules: [astrology.natal]
              ai_description:
                summary: AI-описание профиля
                value:
                  subject:
                    date: '1990-05-15'
                    time: '12:00:00'
                    timezone: Europe/Moscow
                  locale: ru
                  modules: [ai.description]
                  ai:
                    stream: false
      responses:
        '200':
          description: Успешный расчет
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputeResponse'
        '400':
          description: Ошибка валидации payload
        '401':
          description: Не передан или неверный x-api-key
        '429':
          description: Превышен rate limit
        '500':
          description: Внутренняя ошибка выполнения
  /v1/jobs:
    post:
      tags: [Public API]
      summary: Создать асинхронную задачу
      description: Подходит для длительных расчетов. Результат забирается через /v1/jobs/{id}.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComputeRequest'
      responses:
        '202':
          description: Задача поставлена в очередь
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: job_1771189880000_abcdef12
                  status:
                    type: string
                    example: queued
                  queue:
                    type: string
                    example: ai
        '400':
          description: Ошибка валидации payload
        '401':
          description: Не передан или неверный x-api-key
        '429':
          description: Превышен rate limit
  /v1/jobs/{id}:
    get:
      tags: [Public API]
      summary: Получить статус асинхронной задачи
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Текущее состояние задачи
        '401':
          description: Не передан или неверный x-api-key
        '404':
          description: Задача не найдена
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    Subject:
      type: object
      required: [date]
      properties:
        date:
          type: string
          example: '1990-05-15'
        time:
          type: string
          example: '12:00:00'
        timezone:
          type: string
          example: Europe/Moscow
        lat:
          type: number
          example: 55.7558
        lon:
          type: number
          example: 37.6176
        birthDate:
          type: string
          example: '1990-05-15T12:00:00Z'
        transitDate:
          type: string
          example: '2026-02-20'
    AiOptions:
      type: object
      properties:
        provider:
          type: string
          example: openrouter
        model:
          type: string
          example: openai/gpt-4o-mini
        stream:
          type: boolean
          default: false
        fallback:
          type: object
          properties:
            provider:
              type: string
            model:
              type: string
        module_overrides:
          type: object
          additionalProperties:
            type: object
            properties:
              provider:
                type: string
              model:
                type: string
    ComputeRequest:
      type: object
      required: [subject, modules]
      properties:
        subject:
          $ref: '#/components/schemas/Subject'
        locale:
          type: string
          example: ru
        modules:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - numerology.matrix
              - numerology.age
              - numerology.graph
              - numerology.short-description
              - numerology.local-characteristic
              - numerology.psychotype
              - numerology.ideality
              - numerology.personal-year
              - numerology.personal-year-description
              - numerology.life-path
              - numerology.days-until-birthday
              - numerology.next-birthday
              - numerology.compatibility
              - numerology.union
              - numerology.graph-insights
              - numerology.twins
              - numerology.full
              - astrology.natal
              - astrology.transit
              - astrology.daily
              - astrology.yearly
              - ai.description
              - ai.card
              - ai.graph
        astro:
          type: object
          properties:
            houseSystem:
              type: string
              example: placidus
        transit:
          type: object
          properties:
            date:
              type: string
              example: '2026-02-20'
            time:
              type: string
              example: '09:00:00'
        partner:
          type: object
          properties:
            date:
              type: string
              example: '1991-04-01'
            birthDate:
              type: string
              example: '1991-04-01T00:00:00Z'
        ai:
          $ref: '#/components/schemas/AiOptions'
    ComputeResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        modules:
          type: array
          items:
            type: string
        result:
          type: object
          additionalProperties:
            type: object