openapi: 3.1.0
info:
  title: addrkit
  version: "1.0.0"
  description: >
    Детерминированный сервис нормализации и поиска адресов. Ответ всегда
    берётся из реестра; LLM не участвует в пути корректности.
servers:
  - url: http://localhost:6171
paths:
  /v1/resolve:
    post:
      summary: Разобрать и сопоставить адрес
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
                  example: "2-я Станционная улица 1/1 стр."
      responses:
        "200":
          description: Результат сопоставления
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResolveResult"
        "400":
          description: Некорректный запрос
  /v1/outages:
    post:
      summary: Отключения по адресу (после строгого сопоставления дома)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address]
              properties:
                address:
                  type: string
      responses:
        "200":
          description: Канонический адрес и отключения
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutagesResult"
  /v1/healthz:
    get:
      summary: Живость
      responses:
        "200": { description: ok }
  /v1/readyz:
    get:
      summary: Готовность (индекс загружен)
      responses:
        "200": { description: ready }
        "503": { description: not ready }
  /v1/version:
    get:
      summary: Версия данных
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data_version: { type: string }
components:
  schemas:
    Status:
      type: string
      enum: [found, partial, ambiguous, not_found, portal_timeout, infra_error]
    Candidate:
      type: object
      properties:
        address: { type: string }
        district: { type: string }
        house: { type: string }
        score: { type: number, format: double }
    ResolveResult:
      type: object
      required: [status, confidence]
      properties:
        status: { $ref: "#/components/schemas/Status" }
        address: { type: string }
        district: { type: string }
        confidence: { type: number, format: double }
        candidates:
          type: array
          items: { $ref: "#/components/schemas/Candidate" }
        data_version: { type: string }
    Outage:
      type: object
      properties:
        type: { type: string }
        system: { type: string }
        address: { type: string }
        start_date: { type: string }
        end_date: { type: string }
        action: { type: string }
    OutagesResult:
      type: object
      properties:
        status: { $ref: "#/components/schemas/Status" }
        address: { type: string }
        district: { type: string }
        outages:
          type: array
          items: { $ref: "#/components/schemas/Outage" }
        as_of: { type: string }
        data_version: { type: string }