docs: Add manual test plan for assets proxy debugging
This commit is contained in:
Apple
250
docs/tasks/ASSETS_PROXY_MANUAL_TEST_PLAN.md
Normal file
250
docs/tasks/ASSETS_PROXY_MANUAL_TEST_PLAN.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# 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):
|
||||
|
||||
```bash
|
||||
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`):
|
||||
|
||||
```bash
|
||||
# Перевірка через city-service (внутрішній Docker network)
|
||||
docker exec daarion-city-service curl -i "http://localhost:7001/city/assets/proxy/microdao/banner/xyz.png"
|
||||
```
|
||||
|
||||
### 3.3 Перевірка напряму у MinIO
|
||||
|
||||
```bash
|
||||
# Перевірка напряму у 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
|
||||
|
||||
```bash
|
||||
docker logs daarion-city-service | grep "assets/proxy"
|
||||
```
|
||||
|
||||
Перевірити:
|
||||
- Чи є запити на `/city/assets/proxy/...`
|
||||
- Який статус (200/404/500)
|
||||
- Чи є помилки
|
||||
|
||||
### 4.2 Логи web-сервісу
|
||||
|
||||
```bash
|
||||
docker logs daarion-web | grep -E "assets|proxy|image"
|
||||
```
|
||||
|
||||
Перевірити:
|
||||
- Чи є запити на `/api/city/assets/proxy/...`
|
||||
- Чи є помилки в Next.js route
|
||||
|
||||
## Крок 5: Перевірка normalizeAssetUrl
|
||||
|
||||
### 5.1 Перевірка вхідних даних з БД
|
||||
|
||||
```bash
|
||||
# Отримати URL з БД для конкретного MicroDAO
|
||||
curl -s "https://daarion.space/api/city/microdao/daarion" | jq '{logo_url, banner_url}'
|
||||
```
|
||||
|
||||
### 5.2 Перевірка нормалізації
|
||||
|
||||
В браузері (Console в DevTools):
|
||||
|
||||
```javascript
|
||||
// Тест 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. Передати інформацію для подальшого виправлення
|
||||
|
||||
Reference in New Issue
Block a user