paper-racing-gpi/WEBSERVICE-README.md

Racing A* Web Service

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

Быстрый старт

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

# Используя скрипт (рекомендуется)
./run-webservice.sh

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

# На другом порту
PORT=8080 ./run-webservice.sh

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

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

curl http://localhost:5000/health

3. Решение карты

# Используя готовую карту
curl -X POST http://localhost:5000/solve \
  -H "Content-Type: application/json" \
  -d @maps/simple-test.json

# Или создайте свою карту
curl -X POST http://localhost:5000/solve \
  -H "Content-Type: application/json" \
  -d '{
    "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]
    ]
  }'

API Endpoints

GET /

Информация о сервисе и доступных endpoints

GET /health

Health check endpoint для мониторинга

POST /solve

Основной endpoint - решение карты гонок

Request Body:

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

Response (успех):

{
  "success": true,
  "solution": [[0, 0], [1, 1], [1, 0], ...],
  "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
}

Формат карты

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

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

Bash/cURL

# Тестовый скрипт
./test-api.sh

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

Python

# Используя готовый клиент
./example-client.py maps/simple-test.json solution.json

# Или импортируйте в свой код
python3 example-client.py maps/racing-map-15x15.json my-solution.json

import requests
import json

# Решение карты
with open('maps/simple-test.json') 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"✓ Найдено решение за {result['statistics']['steps']} шагов")
    with open('solution.json', 'w') as f:
        json.dump({'solution': result['solution']}, f, indent=2)

JavaScript/Node.js

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

async function solveMap() {
    const mapData = JSON.parse(fs.readFileSync('maps/simple-test.json'));
    
    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(`✓ Solution found: ${result.statistics.steps} steps`);
        fs.writeFileSync('solution.json', 
            JSON.stringify({ solution: result.solution }, null, 2));
    }
}

solveMap();

Архитектура

racing/
├── ProgramAStar.cs          # Ядро A* алгоритма
├── ProgramWebService.cs     # Web API
├── racing-webservice.csproj # Конфигурация проекта
├── run-webservice.sh        # Скрипт запуска
├── test-api.sh              # Тестирование API
└── example-client.py        # Пример Python клиента

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

Сложность	Чекпоинты	Примерное время
Простая	1-5	< 1 сек
Средняя	5-15	1-10 сек
Сложная	15-40	10-120 сек

Конфигурация

Переменные окружения

• PORT - порт для запуска сервиса (по умолчанию: 5000)

PORT=8080 dotnet run --project racing-webservice.csproj

Параметры запроса

• maxIterations - максимальное количество итераций A* (по умолчанию: 5000000)
• timeoutSeconds - таймаут выполнения в секундах (опционально)

Мониторинг

# Health check
curl http://localhost:5000/health

# С использованием watch для мониторинга
watch -n 1 'curl -s http://localhost:5000/health | jq .'

Troubleshooting

Порт уже занят

# Проверьте, что использует порт 5000
netstat -tuln | grep 5000

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

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

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

Сервис не отвечает

# Проверьте, что сервис запущен
ps aux | grep racing-webservice

# Перезапустите сервис
./run-webservice.sh

Полная документация

См. API-DOCUMENTATION.md для подробной документации API.

Лицензия

См. основной README.md