Карта API та інтеграцій проєкту

Карта інтеграцій показує шлях, а не лише URL

Щоб зрозуміти інтеграцію, недостатньо перелічити endpoint-и. Потрібно простежити шлях від HTTP-запиту через обробник і бізнес-сервіс до бази даних, зовнішнього клієнта, черги або події, а потім знайти тест і конфігурацію, які підтверджують контракт.

`CODEBASE_INVENTORY.md` описує склад репозиторію, а `API_MAP.md` фіксує взаємозвʼязки між маршрутами, кодом, інтеграціями та середовищем.

Досліджуйте один критичний сценарій

1. Оберіть checkout, refund, підтримку або інший конкретний flow.
2. Знайдіть маршрут і контролер.
3. Пройдіть до сервісу та його залежностей.
4. Перевірте записи до БД, зовнішні клієнти, черги та події.
5. Знайдіть правила авторизації й середовищні змінні.
6. Зіставте шлях із тестами.
7. Занесіть лише підтверджені звʼязки та відкриті питання до API_MAP.md.

Структура `API_MAP.md`

# API_MAP.md

## Клієнтські маршрути
## API підтримки
## API адміністративної панелі
## Зовнішні інтеграції
## Відкриті питання

| Метод і шлях | Обробник | Авторизація | Інтеграції | Тести |
| --- | --- | --- | --- | --- |
| POST /api/... | ... | ... | ... | ... |

Інтеграційні докази

• контролер підтверджує існування маршруту;
• сервіс показує подальший напрям виконання;
• конфігурація виявляє залежності середовища;
• файл збірки підтверджує підключення бібліотеки;
• тест фіксує очікувану поведінку;
• коментар може бути підказкою, але не замінює кодову перевірку.

Карта живе разом із кодом

Після змін у маршрутах, сервісах або конфігурації переглядайте diff `API_MAP.md`. Документ має залишатися коротким, доказовим і синхронним із реалізацією, а не ставати одноразовою чернеткою.