REST API Contract A0Service

Обзор

REST API контракт для системы A0Service, сгенерированный из Delphi Type Library (A0Service_TLB.pas). Контракт реализован в формате OpenAPI 3.0.3 и предоставляет полную спецификацию интерфейсов системы.

Структура

Контракт организован в split структуру для лучшей поддерживаемости:

split/
  openapi.yaml           # Основной OpenAPI файл с путями и безопасностью
  paths/                  # Определения эндпоинтов
    auth_login.yaml
    auth_logout.yaml
    auth_refresh.yaml
    health.yaml
    metrics_node.yaml
    metrics_haproxy.yaml
    status.yaml
    estimate_*.yaml
    implement_*.yaml
  components/
    schemas/              # Модели данных
      LoginRequest.yaml
      LoginResponse.yaml
      LogoutResponse.yaml
      NodePoolMetrics.yaml
      NodeLoadStatus.yaml
      THAProxyAgentMetrics.yaml
      IA0*.yaml            # Модели объектов A0
      E*.yaml             # Перечисления
    parameters/           # Переиспользуемые параметры
    examples/             # Примеры ответов
  reports/                # Отчеты сравнения и анализа
    dto_contract_comparison.md

Сборка из Split структуры

Для сборки полного OpenAPI контракта из split структуры:

# Использование swagger-codegen 
swagger-codegen generate -i split/openapi.yaml -l openapi -o ./generated

# Использование openapi-generator
openapi-generator-cli generate -i split/openapi.yaml -g openapi -o ./generated

# Использование @redocly/cli
npx @redocly/cli bundle split/openapi.yaml --output openapi.yaml



# Использование @redocly/cli для созданий файла документации 
npx @redocly/cli build-docs split/openapi.yaml --output openapi.yaml

Файл `split/openapi.yaml` автоматически ссылается на все файлы путей и схем с помощью синтаксиса `$ref`, поэтому для генерации достаточно основного файла.

## Основные объекты

- **IA0Complex** - A0 Complex с заголовком, идентификатором, итогами и деревом
- **IA0Proj** - A0 Project с полной информацией о проекте
- **IA0OS** - Объектная смета с деталями на уровне объекта
- **IA0LS** - Локальная смета со строками (выровнена с DTO)
- **IA0Act** - Акт со строками (выровнен с DTO)

## Аутентификация

API использует JWT Bearer токен аутентификацию:

- `POST /auth/login` - Вход с учетными данными
- `POST /auth/logout` - Выход и инвалидация токена
- `POST /auth/refresh` - Обновление access токена

**Формат LoginResponse (выровнен с DTO):**
```json
{
  "accessToken": "...",
  "refreshToken": "...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Эндпоинты мониторинга

• GET /health - Базовая проверка здоровья
• GET /health/ready - Проверка готовности
• GET /health/live - Проверка жизнеспособности
• GET /metrics/node - Детальные метрики ноды (NodePoolMetrics)
• GET /metrics/haproxy - Метрики HAProxy (THAProxyAgentMetrics)
• GET /status - Детальный статус сервиса

Модели данных

Модели аутентификации

• LoginRequest - { login, password }
• LoginResponse - { accessToken, refreshToken, expiresIn, tokenType }
• LogoutResponse - { success, message }

Модели метрик

• NodePoolMetrics - Детальные метрики ноды с CPU, RAM, инстансами, оценкой нагрузки
• NodeLoadStatus - Перечисление: ready | drain | down
• THAProxyAgentMetrics - { weight, status }

Бизнес-объекты A0

Все объекты A0 следуют единым паттернам:

• ID объекты с иерархическим наследованием
• Title объекты с метаданными бизнес-операций
• Tree структуры для иерархических данных
• Totals для финансовых итогов
• Strings коллекции для строковых элементов

Особенности реализации

• ReadOnly флаги: Свойства помечены как readOnly на основе анализа Set_ методов в оригинальных Delphi интерфейсах
• Преобразование типов: Правильное маппинг Delphi в OpenAPI типы (Currency->double, TGUID->uuid, WideString->string)
• Упрощенное наследование: Сложные иерархии интерфейсов уплощены для REST API
• Русские описания: Все схемы и свойства содержат русские описания
• Массивы вместо коллекций: Интерфейсные коллекции представлены как массивы для удобства REST API
• Split структура: Модульная организация для поддерживаемости
• Выравнивание с DTO: Ключевые модели выровнены с реальными Delphi DTO реализациями

Файлы

• split/openapi.yaml - Основной файл OpenAPI 3.0.3
• split/paths/*.yaml - Определения эндпоинтов
• split/components/schemas/*.yaml - Схемы моделей данных
• split/reports/dto_contract_comparison.md - Отчет сравнения DTO и контракта
• A0Service_TLB.pas - Исходная Delphi Type Library
• README.md - Эта документация

Использование

Контракт может использоваться для:

• Генерации клиентских библиотек
• Валидации запросов/ответов
• Документации API
• Тестирования сервиса
• Разработки через контракт (contract-first)

Версия

OpenAPI: 3.0.3
Последнее обновление: 2026-04-22

Примечания

• Этот репозиторий использует split структуру. Все изменения должны делаться в директории split/.
• Корневой файл openapi.yaml существует, но не должен изменяться без явного запроса.
• Выравнивание с DTO выполнено для ключевых моделей (LoginResponse, NodePoolMetrics, IA0LS, IA0Act).
• Устаревший эндпоинт /metrics удален в пользу /metrics/node и /metrics/haproxy.