feat: migrate to VitePress from monorepo docs, add test-contour section

2026-05-28 12:29:31 +03:00
parent e90dfe1bd4
commit e3e438df68
76 changed files with 11998 additions and 60 deletions
@@ -0,0 +1,136 @@
+# 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
+```