add web-service

WEBSERVICE-README.md

@@ -0,0 +1,253 @@
+# 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)
+