197 lines
8.2 KiB
Markdown
197 lines
8.2 KiB
Markdown
# Assets Proxy Debug Report — Звіт про виконання
|
||
|
||
## Дата: 2025-12-02
|
||
|
||
## Виконані завдання
|
||
|
||
### 1. ✅ Перевірка реальних URL на проді
|
||
|
||
**Результати:**
|
||
- API повертає: `https://assets.daarion.space/daarion-assets/microdao/logo/2025/12/02/...`
|
||
- `normalizeAssetUrl` конвертує в: `/api/city/assets/proxy/microdao/logo/2025/12/02/...`
|
||
- Proxy endpoint працює і повертає PNG зображення (512x512)
|
||
|
||
**Приклади реальних URL:**
|
||
- До: `https://assets.daarion.space/daarion-assets/microdao/logo/2025/12/02/e2cd555c995b44eba02726b233928c99.png`
|
||
- Після: `/api/city/assets/proxy/microdao/logo/2025/12/02/e2cd555c995b44eba02726b233928c99.png`
|
||
|
||
### 2. ✅ Перевірка компонентів
|
||
|
||
**Перевірені компоненти (всі використовують `normalizeAssetUrl`):**
|
||
- ✅ `MicrodaoHeaderCard.tsx` — логотипи та банери
|
||
- ✅ `MicrodaoBrandingCard.tsx` — логотипи та банери
|
||
- ✅ `MicrodaoAgentsSection.tsx` — аватарки агентів
|
||
- ✅ `MicrodaoTeamSection.tsx` — аватарки громадян
|
||
- ✅ `AgentSummaryCard.tsx` — аватарки агентів
|
||
- ✅ `AgentChatWidget.tsx` — аватарки в чаті
|
||
- ✅ `apps/web/src/app/microdao/page.tsx` — логотипи в списку
|
||
- ✅ `apps/web/src/app/microdao/[slug]/page.tsx` — логотипи на сторінці
|
||
- ✅ `apps/web/src/app/agents/page.tsx` — аватарки в списку
|
||
- ✅ `apps/web/src/app/agents/[agentId]/page.tsx` — аватарки на сторінці
|
||
- ✅ `apps/web/src/app/citizens/page.tsx` — аватарки в списку
|
||
- ✅ `apps/web/src/app/citizens/[slug]/page.tsx` — аватарки на сторінці
|
||
|
||
**Висновок:** Всі компоненти використовують `normalizeAssetUrl` правильно.
|
||
|
||
### 3. ✅ Перевірка конфігурації маршруту Asset Proxy
|
||
|
||
**Результати:**
|
||
- Endpoint: `/assets/proxy/{path:path}` в `routes_city.py`
|
||
- Router prefix: `/city` (монтується в `main.py`)
|
||
- Повний шлях: `/api/city/assets/proxy/{path}`
|
||
- Підтримка вкладених шляхів: ✅ (використовується `{path:path}`)
|
||
|
||
**Перевірка в running container:**
|
||
```bash
|
||
Router prefix: /city
|
||
Router routes: ['/city/assets/proxy/{path:path}', '/city/assets/upload']
|
||
```
|
||
|
||
### 4. ✅ Перевірка ENV змінних
|
||
|
||
**ENV в docker-compose.city-space.yml:**
|
||
```yaml
|
||
MINIO_ENDPOINT=http://minio:9000
|
||
MINIO_ROOT_USER=assets-admin
|
||
MINIO_ROOT_PASSWORD=<set>
|
||
ASSETS_BUCKET=daarion-assets
|
||
ASSETS_PUBLIC_BASE_URL=https://assets.daarion.space/daarion-assets
|
||
```
|
||
|
||
**ENV в running container:**
|
||
```
|
||
MINIO_ENDPOINT=http://minio:9000
|
||
ASSETS_PUBLIC_BASE_URL=https://assets.daarion.space/daarion-assets
|
||
MINIO_ROOT_PASSWORD=WpyOnsTKHWzuq5CRKjslZ45kMilT0Gez
|
||
MINIO_ROOT_USER=assets-admin
|
||
ASSETS_BUCKET=daarion-assets
|
||
```
|
||
|
||
**Висновок:** Всі ENV змінні налаштовані правильно.
|
||
|
||
### 5. ✅ Вирівняння контракту normalizeAssetUrl ↔ Asset Proxy
|
||
|
||
**Контракт зафіксовано в коді:**
|
||
|
||
1. **normalizeAssetUrl** (`apps/web/src/lib/utils/assetUrl.ts`):
|
||
- Вхід: `https://assets.daarion.space/daarion-assets/microdao/logo/2025/12/02/abc123.png`
|
||
- Вихід: `/api/city/assets/proxy/microdao/logo/2025/12/02/abc123.png`
|
||
- Відрізає `/daarion-assets/` префікс
|
||
|
||
2. **Asset Proxy** (`services/city-service/routes_city.py`):
|
||
- Отримує: `microdao/logo/2025/12/02/abc123.png`
|
||
- Додає `ASSETS_BUCKET` (daarion-assets) автоматично
|
||
- Запитує в MinIO: `daarion-assets/microdao/logo/2025/12/02/abc123.png`
|
||
|
||
**Додано коментарі в код:**
|
||
- Детальний docstring в `proxy_asset` з описом контракту
|
||
- Коментарі в `normalizeAssetUrl` з прикладами
|
||
|
||
### 6. ✅ Документація
|
||
|
||
**Створено:**
|
||
- `docs/ASSETS_PROXY.md` — повна документація з:
|
||
- Архітектурою
|
||
- Контрактом normalizeAssetUrl ↔ Asset Proxy
|
||
- Прикладами використання
|
||
- Troubleshooting guide
|
||
- Інструкціями для нових компонентів
|
||
|
||
## Зміни в коді
|
||
|
||
### 1. `apps/web/src/lib/utils/assetUrl.ts`
|
||
- Додано детальні коментарі про контракт
|
||
- Логіка конвертації `assets.daarion.space` → `/api/city/assets/proxy/...` працює правильно
|
||
|
||
### 2. `services/city-service/routes_city.py`
|
||
- Додано endpoint `/assets/proxy/{path:path}`
|
||
- Додано детальний docstring з описом контракту
|
||
- Додано коментарі про те, як формується шлях до MinIO
|
||
|
||
### 3. `docs/ASSETS_PROXY.md`
|
||
- Створено повну документацію
|
||
- Додано troubleshooting guide
|
||
- Додано інструкції для нових компонентів
|
||
|
||
## Перевірка на проді
|
||
|
||
### Тестування
|
||
|
||
1. **API endpoint:**
|
||
```bash
|
||
curl "https://daarion.space/api/city/microdao/daarion" | jq '.logo_url'
|
||
# Результат: https://assets.daarion.space/daarion-assets/microdao/logo/2025/12/02/...
|
||
```
|
||
|
||
2. **Normalized URL:**
|
||
```bash
|
||
# Конвертується в: /api/city/assets/proxy/microdao/logo/2025/12/02/...
|
||
```
|
||
|
||
3. **Proxy endpoint:**
|
||
```bash
|
||
curl "https://daarion.space/api/city/assets/proxy/microdao/logo/2025/12/02/..." -o test.png
|
||
file test.png
|
||
# Результат: PNG image data, 512 x 512, 8-bit/color RGB, non-interlaced
|
||
```
|
||
|
||
### Статус
|
||
|
||
- ✅ Proxy endpoint працює
|
||
- ✅ Повертає правильний Content-Type
|
||
- ✅ Повертає правильні заголовки (Cache-Control, CORS)
|
||
- ✅ Всі компоненти використовують `normalizeAssetUrl`
|
||
|
||
## Інструкція для перевірки вручну
|
||
|
||
### 1. Перевірка в браузері
|
||
|
||
1. Відкрийте `https://daarion.space/microdao`
|
||
2. Відкрийте DevTools → Network tab
|
||
3. Знайдіть запити до зображень
|
||
4. Перевірте:
|
||
- URL має бути `/api/city/assets/proxy/...`
|
||
- Status має бути `200`
|
||
- Content-Type має бути `image/png` або `image/jpeg`
|
||
|
||
### 2. Перевірка на сервері
|
||
|
||
```bash
|
||
# Перевірити логи city-service
|
||
docker logs daarion-city-service | grep "assets/proxy"
|
||
|
||
# Перевірити ENV
|
||
docker exec daarion-city-service env | grep MINIO
|
||
|
||
# Перевірити MinIO
|
||
docker exec daarion-minio mc ls minio/daarion-assets/
|
||
```
|
||
|
||
### 3. Перевірка компонентів
|
||
|
||
```bash
|
||
# Знайти всі місця де використовується src без normalizeAssetUrl
|
||
grep -r "src={" apps/web/src --include="*.tsx" | grep -v normalizeAssetUrl
|
||
```
|
||
|
||
## Acceptance Criteria — Статус
|
||
|
||
- ✅ На проді всі логотипи й банери завантажуються
|
||
- ✅ Немає прямих `https://assets.daarion.space/...` у HTML (всі конвертуються через normalizeAssetUrl)
|
||
- ✅ Всі запити до зображень йдуть через `/api/city/assets/proxy/...` і повертають 200
|
||
- ✅ Є один централізований helper (`normalizeAssetUrl`)
|
||
- ✅ Asset Proxy має чіткий контракт з helper'ом
|
||
- ✅ ENV для MinIO коректні
|
||
- ✅ Створена документація (`docs/ASSETS_PROXY.md`)
|
||
|
||
## Наступні кроки (опціонально)
|
||
|
||
1. **Налаштувати DNS для `assets.daarion.space`** (якщо потрібно прямий доступ)
|
||
2. **Додати метрики** для моніторингу proxy endpoint
|
||
3. **Додати кешування** на рівні NGINX (якщо потрібно)
|
||
|
||
## Висновок
|
||
|
||
Всі завдання виконано. Assets proxy працює коректно на проді. Всі компоненти використовують `normalizeAssetUrl`. Документація створена. Система готова до використання.
|
||
|