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,67 @@
+---
+title: Создание лида Calltouch (Backend)
+---
+
+# Сценарий 4.2: Создание лида **Calltouch**
+
+## Бизнес-цель
+
+Маркетинг фиксирует обращения пользователей как **лиды** в системе **Calltouch** для сквозной аналитики и колл-центра.
+
+## Точки входа
+
+| Тип | Метод + URL | Класс |
+| --- | --- | --- |
+| HTTP | `POST /calltouch/create-lead` | `CalltouchController::createLead` |
+
+**Ограничение доступа:** `#[IsGranted('ROLE_ADMIN')]` на уровне класса контроллера — вызов только для административной роли API.
+
+## Реализация HTTP vs клиент
+
+1. Тело (form/json) мапится в `CalltouchCreateRequestDto`, проходит `Validator`.
+2. **Фактический вызов** `CalltouchClientService::requestCreate($dto)` в коде **закомментирован**; ответ клиента возвращён не будет.
+3. Контроллер отдаёт `200` с полем `request` (сырые данные из `$request->request->all()`).
+
+То есть **интеграция подготовлена, но в текущей ветке кода не активна** до раскомментирования строки.
+
+## Как устроен `CalltouchClientService` (целевое поведение)
+
+1. `configureHeaders($dto->regionId)` выбирает пару `siteId` + токен из строки ENV, разобранной в конструкторе (`param` формат `region:siteId:token,...`).
+2. Формируется `POST` на путь **`/lead-service/v1/api/request/create`** заголовками `Access-Token`, `SiteId`.
+3. Тело: `json_encode(['requests' => $dto->toArray()])`.
+4. Возвращается `data` из JSON-ответа Calltouch.
+
+## Mermaid (фактическое поведение в коде)
+
+```mermaid
+sequenceDiagram
+    participant A as Админ-клиент
+    participant CC as CalltouchController
+    participant V as Validator
+    A->>CC: POST /calltouch/create-lead
+    CC->>V: validate(CalltouchCreateRequestDto)
+    CC-->>A: 200 JSON (поле request)
+```
+
+После раскомментирования `CalltouchClientService::requestCreate` к схеме добавятся шаги HTTP `POST` к API Calltouch с заголовками `Access-Token` и `SiteId`.
+
+## Внешние зависимости
+
+| Система | Статус |
+| --- | --- |
+| Calltouch API | клиент реализован, HTTP в контроллере отключён |
+| PostgreSQL | не используется в сценарии лида напрямую |
+
+## Обработка ошибок и edge cases
+
+- **Нет конфигурации региона** — `configureHeaders` бросает `InvalidArgumentException` (на будущее при включении клиента).
+- **Опечатка в конструкторе** `CalltouchClientService`: два присваивания `$this->baseUrl` подряд — стоит перепроверить при включении интеграции.
+
+## Ссылки на классы
+
+- `apps/backend/src/Controller/CalltouchController.php`
+- `apps/backend/src/Service/Client/CalltouchClientService.php`
+- `apps/backend/src/Dto/CalltouchCreateRequestDto.php`
+- `apps/backend/src/Service/Client/Interfaces/CalltouchClientServiceInterface.php`
+
+См. [backend-ddd.md](../backend-ddd.md).