sova-bootstrap
137 lines
6.1 KiB
Markdown
137 lines
6.1 KiB
Markdown
# 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
|
||
```
|