193 lines
5.6 KiB
Markdown
193 lines
5.6 KiB
Markdown
# Racing A* Web Service - Сводка
|
||
|
||
## Что было сделано
|
||
|
||
Алгоритм A* из `ProgramAStar.cs` успешно обёрнут в микросервис на базе ASP.NET Core Web API.
|
||
|
||
## Созданные файлы
|
||
|
||
### 1. Основные файлы сервиса
|
||
- **`ProgramWebService.cs`** - Web API с endpoints для решения карт
|
||
- **`racing-webservice.csproj`** - конфигурация проекта веб-сервиса
|
||
- **`run-webservice.sh`** - скрипт для запуска сервиса
|
||
|
||
### 2. Документация
|
||
- **`WEBSERVICE-README.md`** - краткое руководство по использованию
|
||
- **`API-DOCUMENTATION.md`** - полная документация API с примерами
|
||
|
||
### 3. Примеры и тесты
|
||
- **`test-api.sh`** - bash скрипт для тестирования всех endpoints
|
||
- **`example-client.py`** - Python клиент для работы с API
|
||
|
||
## API Endpoints
|
||
|
||
| Method | Endpoint | Описание |
|
||
|--------|-----------|---------------------------------------------|
|
||
| GET | `/` | Информация о сервисе и доступных endpoints |
|
||
| GET | `/health` | Health check для мониторинга |
|
||
| POST | `/solve` | Решение карты гонок (основной endpoint) |
|
||
|
||
## Запуск
|
||
|
||
```bash
|
||
# Быстрый старт
|
||
./run-webservice.sh
|
||
|
||
# Проверка
|
||
curl http://localhost:5000/health
|
||
|
||
# Решение карты
|
||
curl -X POST http://localhost:5000/solve \
|
||
-H "Content-Type: application/json" \
|
||
-d @maps/simple-test.json
|
||
```
|
||
|
||
## Формат API
|
||
|
||
### Запрос (POST /solve)
|
||
```json
|
||
{
|
||
"map": [
|
||
[0, 0, 4],
|
||
[5, 0, 0],
|
||
[0, 0, 0]
|
||
],
|
||
"maxIterations": 5000000,
|
||
"timeoutSeconds": 60
|
||
}
|
||
```
|
||
|
||
### Ответ (успех)
|
||
```json
|
||
{
|
||
"success": true,
|
||
"solution": [[0, 0], [1, 1], ...],
|
||
"statistics": {
|
||
"steps": 15,
|
||
"checkpoints": 1,
|
||
"iterations": 1234,
|
||
"computeTimeSeconds": 0.52,
|
||
"maxSpeed": 6
|
||
}
|
||
}
|
||
```
|
||
|
||
### Ответ (ошибка)
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "No solution found within the iteration limit"
|
||
}
|
||
```
|
||
|
||
## Особенности реализации
|
||
|
||
1. **Переиспользование кода** - используется существующий класс `RaceTrack` из `ProgramAStar.cs`
|
||
2. **Minimal API** - современный подход .NET 8.0
|
||
3. **CORS** - настроен для кросс-доменных запросов
|
||
4. **Логирование** - вывод информации о запросах в консоль
|
||
5. **Обработка ошибок** - корректная обработка и возврат ошибок
|
||
|
||
## Тестирование
|
||
|
||
Сервис успешно протестирован:
|
||
|
||
✅ Health check endpoint работает
|
||
✅ Информационный endpoint отдаёт данные
|
||
✅ Решение простой карты (inline JSON) - успешно
|
||
✅ Решение карты из файла (simple-test.json) - успешно
|
||
|
||
### Результаты тестов
|
||
|
||
```json
|
||
// Health Check
|
||
{
|
||
"status": "healthy",
|
||
"version": "1.0.0",
|
||
"timestamp": "2025-10-20T18:04:18Z"
|
||
}
|
||
|
||
// Решение simple-test.json
|
||
{
|
||
"success": true,
|
||
"solution": [[0,0], [1,-2], [-1,1], [2,-1]],
|
||
"statistics": {
|
||
"steps": 4,
|
||
"checkpoints": 2,
|
||
"computeTimeSeconds": 0.0083
|
||
}
|
||
}
|
||
```
|
||
|
||
## Интеграция с существующим кодом
|
||
|
||
Микросервис **не изменяет** существующий код:
|
||
- `ProgramAStar.cs` остаётся без изменений
|
||
- `racing-astar.csproj` для CLI версии остаётся рабочим
|
||
- Все существующие скрипты (`run-astar.sh`, `run-all-tests.sh`) продолжают работать
|
||
|
||
## Клиенты
|
||
|
||
### Python
|
||
```python
|
||
import requests
|
||
response = requests.post('http://localhost:5000/solve', json=map_data)
|
||
result = response.json()
|
||
```
|
||
|
||
### JavaScript
|
||
```javascript
|
||
const response = await fetch('http://localhost:5000/solve', {
|
||
method: 'POST',
|
||
body: JSON.stringify(mapData)
|
||
});
|
||
const result = await response.json();
|
||
```
|
||
|
||
### cURL
|
||
```bash
|
||
curl -X POST http://localhost:5000/solve \
|
||
-H "Content-Type: application/json" \
|
||
-d @map.json
|
||
```
|
||
|
||
## Развёртывание
|
||
|
||
### Локально
|
||
```bash
|
||
./run-webservice.sh
|
||
```
|
||
|
||
### Docker (опционально)
|
||
```bash
|
||
docker build -t racing-solver .
|
||
docker run -p 5000:5000 racing-solver
|
||
```
|
||
|
||
### Cloud (Azure, AWS, GCP)
|
||
Проект готов к развёртыванию в облаке как стандартное ASP.NET Core приложение.
|
||
|
||
## Следующие шаги (опционально)
|
||
|
||
1. ✅ Базовый Web API - **готово**
|
||
2. Добавить аутентификацию (API keys)
|
||
3. Добавить rate limiting
|
||
4. Добавить кэширование решений
|
||
5. Добавить WebSocket для real-time обновлений
|
||
6. Добавить Swagger/OpenAPI документацию
|
||
7. Добавить Docker контейнеризацию
|
||
8. Настроить CI/CD
|
||
|
||
## Заключение
|
||
|
||
Микросервис готов к использованию! 🚀
|
||
|
||
- ✅ API работает корректно
|
||
- ✅ Документация создана
|
||
- ✅ Примеры клиентов подготовлены
|
||
- ✅ Тестовые скрипты работают
|
||
- ✅ Совместимость с существующим кодом сохранена
|
||
|
||
Используйте `./run-webservice.sh` для запуска!
|
||
|