microdao-daarion/docs/tasks/ASSETS_PROXY_MANUAL_TEST_PLAN.md

Manual Test Plan — Assets Proxy Debugging

Контекст

Після виправлення HEAD методу в city-service, логотипи та банери все ще не відображаються на фронті. Потрібно перевірити:

1. Які URL генерує фронт
2. Що реально повертає Next.js route
3. Чи web-сервіс оновлений до останнього коду

Крок 1: Перевірка реальних запитів в браузері

1.1 Відкрити DevTools

1. Відкрити https://daarion.space/microdao у браузері
2. Відкрити DevTools (F12 або Cmd+Option+I)
3. Перейти на вкладку Network
4. Фільтр: Img (або All + фільтр за назвою банера/логотипа)

1.2 Знайти "биті" зображення

1. Знайти запити до зображень, які не завантажились (червоний статус або placeholder)
2. Клікнути по одному з них
3. Перевірити:
   • Request URL (повний шлях)
   • Status (200/404/500/...)
   • Response headers → Content-Type, Content-Length

1.3 Аналіз URL

Якщо URL виглядає як /_next/image?url=...

→ Використовується Next <Image> з оптимізацією

Рішення:

• Або виставити unoptimized на компоненті
• Або налаштувати next.config.ts (domains) та переконатися, що url вказує на /api/city/assets/proxy/...

Якщо URL виглядає як /api/city/assets/proxy/...

→ Це правильний шлях через proxy

Далі:

1. Відкрити цей URL у новій вкладці браузера
2. Перевірити:
   • Якщо картинка відкривається → проблема в Next <Image> / верстці
   • Якщо не відкривається (404/500 або HTML-сторінка) → проблема в шляху або в проміжному Next route

Крок 2: Перевірка оновлення web-сервісу

2.1 Перебудувати web-сервіс

На сервері (там де docker-compose):

cd /opt/microdao-daarion
git pull
docker compose -f docker-compose.web.yml build web
docker compose -f docker-compose.web.yml up -d --no-deps web

2.2 Hard refresh в браузері

Після перебудови:

1. Відкрити https://daarion.space/microdao
2. Зробити hard refresh:
   • Windows/Linux: Ctrl+Shift+R
   • Mac: Cmd+Shift+R

Крок 3: Перевірка шляху в proxy

3.1 Скопіювати точний path

З Network tab в DevTools:

1. Знайти запит до /api/city/assets/proxy/...
2. Скопіювати точний path після /api/city/assets/proxy/

Наприклад: microdao/banner/xyz.png

3.2 Перевірка через city-service

На сервері (там де city-service):

# Перевірка через city-service (внутрішній Docker network)
docker exec daarion-city-service curl -i "http://localhost:7001/city/assets/proxy/microdao/banner/xyz.png"

3.3 Перевірка напряму у MinIO

# Перевірка напряму у MinIO (якщо є NGINX/MinIO url)
curl -I "https://assets.daarion.space/daarion-assets/microdao/banner/xyz.png"

3.4 Аналіз результатів

• Якщо другий запит (на MinIO) 200, а перший ні → проблема в:
  • normalizeAssetUrl неправильно обрізає/додає daarion-assets/
  • Next route/NGINX "з'їдає" частину шляху

Примітка: Банери часто лежать в іншому префіксі, ніж логотипи, тому:

• Для логотипів normalizeAssetUrl може працювати (структура шляху співпала)
• Для банерів — ні (інший префікс, додатковий каталог, інший формат збереження в БД)

Крок 4: Перевірка логів

4.1 Логи city-service

docker logs daarion-city-service | grep "assets/proxy"

Перевірити:

• Чи є запити на /city/assets/proxy/...
• Який статус (200/404/500)
• Чи є помилки

4.2 Логи web-сервісу

docker logs daarion-web | grep -E "assets|proxy|image"

Перевірити:

• Чи є запити на /api/city/assets/proxy/...
• Чи є помилки в Next.js route

Крок 5: Перевірка normalizeAssetUrl

5.1 Перевірка вхідних даних з БД

# Отримати URL з БД для конкретного MicroDAO
curl -s "https://daarion.space/api/city/microdao/daarion" | jq '{logo_url, banner_url}'

5.2 Перевірка нормалізації

В браузері (Console в DevTools):

// Тест normalizeAssetUrl
const testUrl = "https://assets.daarion.space/daarion-assets/microdao/logo/2025/12/02/abc123.png";
// Очікуваний результат: "/api/city/assets/proxy/microdao/logo/2025/12/02/abc123.png"

Очікувані результати

✅ Успішний сценарій

1. Network tab:

   • URL: /api/city/assets/proxy/microdao/logo/2025/12/02/abc123.png
   • Status: 200 OK
   • Content-Type: image/png
   • Зображення відображається

2. Логи city-service:

   INFO: "GET /city/assets/proxy/microdao/logo/2025/12/02/abc123.png HTTP/1.1" 200 OK
   

3. Прямий доступ до URL:

   • Відкривається зображення в новій вкладці

❌ Проблемні сценарії

Сценарій 1: 404 Not Found

Симптоми:

• Status: 404
• Response: Asset not found

Можливі причини:

• Файл не існує в MinIO
• Неправильний path (зайвий/відсутній префікс daarion-assets/)
• Неправильна нормалізація URL

Рішення:

• Перевірити чи файл існує в MinIO
• Перевірити normalizeAssetUrl контракт
• Перевірити шлях в БД

Сценарій 2: 405 Method Not Allowed

Симптоми:

• Status: 405
• Response: Method Not Allowed

Можливі причини:

• HEAD метод не підтримується (має бути виправлено)
• Next.js route не має HEAD handler

Рішення:

• Перевірити чи city-service має оновлений код
• Перевірити чи Next.js route має HEAD handler

Сценарій 3: 500 Internal Server Error

Симптоми:

• Status: 500
• Response: Internal Server Error

Можливі причини:

• Помилка в city-service при доступі до MinIO
• Неправильні ENV змінні (MINIO_ENDPOINT, MINIO_ACCESS_KEY, тощо)

Рішення:

• Перевірити логи city-service
• Перевірити ENV змінні в docker-compose

Сценарій 4: Зображення не відображається, але статус 200

Симптоми:

• Status: 200 OK
• Content-Type правильний
• Але зображення не відображається

Можливі причини:

• Next <Image> з оптимізацією блокує
• CSS/верстка приховує зображення
• CORS проблема

Рішення:

• Перевірити чи використовується <img> або <Image>
• Перевірити CSS стилі
• Перевірити CORS headers

Чек-лист для швидкої перевірки

• Web-сервіс перебудовано з останнім кодом
• Hard refresh в браузері виконано
• Network tab показує запити на /api/city/assets/proxy/...
• Статус запитів: 200 OK
• Content-Type: image/png або image/jpeg
• Прямий доступ до URL відкриває зображення
• Логи city-service показують успішні запити
• normalizeAssetUrl правильно конвертує URL з БД

Наступні кроки після тестування

1. Зафіксувати результати тестування
2. Якщо є проблеми — зібрати:
   • Точні URL з Network tab
   • Логи city-service та web-сервісу
   • Приклади URL з БД
3. Передати інформацію для подальшого виправлення