paper-racing-gpi/API-DOCUMENTATION.md

Racing A* Solver - API Documentation

Микросервис для решения задачи "Гонки на бумаге" с использованием алгоритма A*.

Запуск сервиса

# Сборка и запуск
./run-webservice.sh

# Или напрямую через dotnet
dotnet run --project racing-webservice.csproj

# Запуск на другом порту
PORT=8080 dotnet run --project racing-webservice.csproj

По умолчанию сервис запускается на http://localhost:5000

API Endpoints

1. GET / - Информация об API

Возвращает информацию о сервисе и доступных endpoints.

Request:

curl http://localhost:5000/

Response:

{
  "service": "Paper Racing A* Solver",
  "version": "1.0.0",
  "endpoints": {
    "health": "GET /health",
    "solve": "POST /solve",
    "info": "GET /"
  },
  "documentation": "POST /solve with JSON body containing 'map' field (2D array of integers)"
}

2. GET /health - Health Check

Проверка работоспособности сервиса.

Request:

curl http://localhost:5000/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-10-20T12:00:00Z"
}

3. POST /solve - Решение задачи

Основной endpoint для решения карты гонок.

Request:

curl -X POST http://localhost:5000/solve \
  -H "Content-Type: application/json" \
  -d @maps/simple-test.json

Request Body:

{
  "map": [
    [0, 0, 0, 0, 0],
    [0, 1, 1, 1, 0],
    [0, 0, 4, 0, 0],
    [0, 1, 1, 1, 0],
    [5, 0, 0, 0, 0]
  ],
  "maxIterations": 5000000,
  "timeoutSeconds": 60
}

Формат карты:

• 0 - дорога (первая ячейка дороги - старт по умолчанию)
• 1 - препятствие (камень)
• 2 - снег (ограниченное ускорение ±1)
• 3 - лёд (нельзя менять ускорение)
• 4 - чекпоинт (нужно посетить все)
• 5 - старт (приоритетная стартовая позиция)

Response (успех):

{
  "success": true,
  "solution": [
    [0, 0],
    [1, 1],
    [1, 0],
    [0, -1],
    ...
  ],
  "statistics": {
    "steps": 15,
    "checkpoints": 1,
    "iterations": 1234,
    "computeTimeSeconds": 0.52,
    "maxSpeed": 6
  }
}

Response (ошибка):

{
  "success": false,
  "error": "No solution found within the iteration limit",
  "solution": null,
  "statistics": null
}

Формат решения: Массив ускорений [ax, ay] для каждого шага:

• ax - ускорение по оси X
• ay - ускорение по оси Y (инвертировано для JSON формата)

Примеры использования

Python

import requests
import json

# Загружаем карту
with open('maps/simple-test.json', 'r') as f:
    map_data = json.load(f)

# Отправляем запрос
response = requests.post(
    'http://localhost:5000/solve',
    json=map_data
)

result = response.json()

if result['success']:
    print(f"✓ Решение найдено!")
    print(f"  Шагов: {result['statistics']['steps']}")
    print(f"  Время: {result['statistics']['computeTimeSeconds']:.2f}s")
    
    # Сохраняем решение
    with open('solution.json', 'w') as f:
        json.dump({'solution': result['solution']}, f, indent=2)
else:
    print(f"✗ Ошибка: {result['error']}")

JavaScript/Node.js

const fs = require('fs');
const fetch = require('node-fetch');

async function solveMap(mapFile) {
    // Читаем карту
    const mapData = JSON.parse(fs.readFileSync(mapFile, 'utf8'));
    
    // Отправляем запрос
    const response = await fetch('http://localhost:5000/solve', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(mapData)
    });
    
    const result = await response.json();
    
    if (result.success) {
        console.log('✓ Решение найдено!');
        console.log(`  Шагов: ${result.statistics.steps}`);
        console.log(`  Время: ${result.statistics.computeTimeSeconds.toFixed(2)}s`);
        
        // Сохраняем решение
        fs.writeFileSync('solution.json', 
            JSON.stringify({ solution: result.solution }, null, 2));
    } else {
        console.log(`✗ Ошибка: ${result.error}`);
    }
}

solveMap('maps/simple-test.json');

cURL

# Решить простую карту
curl -X POST http://localhost:5000/solve \
  -H "Content-Type: application/json" \
  -d @maps/simple-test.json \
  | jq '.'

# Решить карту с кастомными параметрами
curl -X POST http://localhost:5000/solve \
  -H "Content-Type: application/json" \
  -d '{
    "map": [[0,4,0],[5,0,0],[0,0,0]],
    "maxIterations": 1000000
  }' \
  | jq '.'

# Сохранить решение в файл
curl -X POST http://localhost:5000/solve \
  -H "Content-Type: application/json" \
  -d @maps/racing-map-15x15.json \
  | jq '.solution | {solution: .}' > solution.json

Docker Support (опционально)

Создайте Dockerfile:

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /app
COPY . .
RUN dotnet publish racing-webservice.csproj -c Release -o out

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app/out .
ENV PORT=5000
EXPOSE 5000
ENTRYPOINT ["dotnet", "racing-webservice.dll"]

Запуск в Docker:

docker build -t racing-solver .
docker run -p 5000:5000 racing-solver

Производительность

• Простые карты (до 5 чекпоинтов): < 1 секунда
• Средние карты (5-15 чекпоинтов): 1-10 секунд
• Сложные карты (15+ чекпоинтов): 10-120 секунд

Рекомендуется устанавливать maxIterations в зависимости от сложности карты.

Ограничения

• Максимальный размер карты: 200x200 (ограничено памятью)
• Максимальное количество чекпоинтов: ~100 (зависит от сложности)
• Максимальное время выполнения: зависит от параметра maxIterations

Устранение неполадок

Сервис не запускается

# Проверьте, свободен ли порт
netstat -tuln | grep 5000

# Используйте другой порт
PORT=8080 ./run-webservice.sh

Решение не найдено

• Увеличьте maxIterations
• Проверьте, что все чекпоинты достижимы
• Упростите карту (уберите препятствия, лёд, снег)

Медленная работа

• Уменьшите количество чекпоинтов
• Уменьшите размер карты
• Оптимизируйте расположение чекпоинтов (по порядку)