# Backend API

`apps/backend` - новое backend API на Symfony 7.3. Оно выступает единым хранилищем данных и публичным API для клиентских приложений.

## Где смотреть код

| Зона | Путь | Что внутри |
| --- | --- | --- |
| Контроллеры | `apps/backend/src/Controller` | HTTP-эндпоинты, маршруты, security-атрибуты |
| Сущности | `apps/backend/src/Entity` | Doctrine ORM mapping, serializer groups |
| Репозитории | `apps/backend/src/Repository` | QueryBuilder, фильтры, поиск |
| Сервисы | `apps/backend/src/Service` | бизнес-логика, интеграции, общие helpers |
| Команды | `apps/backend/src/Command` | консольные sync/import задачи |
| Конфиг | `apps/backend/config` | security, routes, Nelmio/Swagger, Doctrine |

## Основные разделы документации

- [DDD-обзор и бизнес-сущности](./backend-ddd.md) - контексты предметной области, связь сущностей с контроллерами, сервисами и командами.
- [Бизнес-сценарии (use cases)](./backend-scenarios/index.md) - отдельные статьи по ключевым потокам: JWT, pcode, расписание, запись, синхронизация, фиды.
- [CRUD для контентных сущностей](./backend-content-crud.md) - подробный разбор свежей задачи: контроллеры, пагинация, `CrudResponder`, `ContentRepositoryFilter`, sync services.
- [API и Swagger](../api-routes.md) - список HTTP-методов и где открыть Swagger.
- [Потоки данных](../flows.md) - запуск, синхронизация, авторизация, расписание.
- [Модели данных](../data-model.md) - ER-схемы и ключевые сущности.

## Архитектурный стиль backend

Для новых backend-задач стоит придерживаться таких правил:

- контроллеры должны быть тонкими и маршрутизировать запрос к сервисам/репозиториям;
- фильтрация списков должна жить в repository через `QueryBuilder`;
- пагинация должна использовать `Pagerfanta`, если список отдаётся наружу;
- write-поля должны контролироваться serializer groups (`*:write`);
- read-поля должны контролироваться serializer groups (`*:read`);
- admin-only операции должны быть закрыты через `#[IsGranted('ROLE_ADMIN')]`;
- sync/import из внешних источников не нужно смешивать с HTTP CRUD.

## Быстрая проверка backend

```bash
php bin/console cache:warmup --env=dev
php bin/console debug:router --env=dev
```

Публичный smoke-test списка:

```bash
curl 'http://localhost:8081/news/list?page=1&perPage=2'
```

Swagger UI:

```text
http://localhost:8081/docs
```

## Стек

- PHP `>=8.2`, контейнер `php84`.
- Symfony 7.3.
- Doctrine ORM 3, DBAL 4, migrations.
- PostgreSQL как основная БД.
- Дополнительные подключения к Bitrix MySQL и базе cabinet.
- Redis через `predis/predis`.
- JWT-аутентификация через `lexik/jwt-authentication-bundle`.
- OpenAPI-аннотации и `nelmio/api-doc-bundle`.
- Symfony Messenger/Scheduler для фоновой логики.

## Основные директории

- `src/Controller` - API-контроллеры.
- `src/Dto` - DTO для входных данных.
- `src/Entity` - Doctrine entities.
- `src/Repository` - запросы к БД.
- `src/Service` - бизнес-логика и интеграции.
- `src/Command` - CLI-команды импорта и синхронизации.
- `src/Message` и `src/MessageHandler` - асинхронные задачи.
- `migrations` - миграции БД.

## Точки входа

nginx направляет `api.sovamed.ru` в `apps/backend/public/index.php`, далее запросы обрабатываются Symfony router. Роуты объявлены PHP attributes в контроллерах.

Примеры групп контроллеров:

- `UserController` - логин, JWT, профиль пользователя, регистрация.
- `SpecialistController` - врачи и расписание.
- `PriceListController` и `PriceDepartmentController` - цены и категории.
- `ReviewController` - отзывы.
- `FilialController`, `DepartmentController`, `MedicalCenterController` - справочники клиник.
- `InfoclinicaController`, `CalltouchController` - интеграции.

## Авторизация

Security настроен как stateless API с JWT. Provider берет пользователя из `App\Entity\User` по email.

Для защищенных методов используются `#[IsGranted('ROLE_USER')]` и роли Symfony Security.

## Полезные команды

Установка зависимостей:

```bash
docker exec -it php84 composer install
```

Миграции:

```bash
docker exec -it php84 php bin/console doctrine:migrations:migrate
```

Очистка кеша:

```bash
docker exec -it php84 php bin/console cache:clear
```

Генерация swagger-файла, если установлены зависимости:

```bash
docker exec -it php84 composer generate-swagger
```

Запуск тестов:

```bash
docker exec -it php84 composer phpunit
```

## Служебные команды

В `src/Command` есть команды загрузки врачей, филиалов, новостей, услуг, цен, отзывов и кеша расписания. Названия Symfony-команд лучше смотреть через:

```bash
docker exec -it php84 php bin/console list app
```