paper-racing-gpi/WEBSERVICE-README.md

# Racing A* Web Service

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

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

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

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

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

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

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

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

```bash
curl http://localhost:5000/health
```

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

```bash
# Используя готовую карту
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:**
```json
{
  "map": [[0, 0, 4], [5, 0, 0], [0, 0, 0]],
  "maxIterations": 5000000,
  "timeoutSeconds": 60
}
```

**Response (успех):**
```json
{
  "success": true,
  "solution": [[0, 0], [1, 1], [1, 0], ...],
  "statistics": {
    "steps": 15,
    "checkpoints": 1,
    "iterations": 1234,
    "computeTimeSeconds": 0.52,
    "maxSpeed": 6
  }
}
```

**Response (ошибка):**
```json
{
  "success": false,
  "error": "No solution found within the iteration limit",
  "solution": null,
  "statistics": null
}
```

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

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

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

### Bash/cURL

```bash
# Тестовый скрипт
./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

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

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

```python
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

```javascript
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)

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

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

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

## Мониторинг

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

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

## Troubleshooting

### Порт уже занят
```bash
# Проверьте, что использует порт 5000
netstat -tuln | grep 5000

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

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

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

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

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

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

## Лицензия

См. основной [README.md](README.md)