microdao-daarion/docs/tasks/ASSETS_PROXY_DEBUG_REPORT.md

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:

Router prefix: /city
Router routes: ['/city/assets/proxy/{path:path}', '/city/assets/upload']

4. ✅ Перевірка ENV змінних

ENV в docker-compose.city-space.yml:

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:

   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:

   # Конвертується в: /api/city/assets/proxy/microdao/logo/2025/12/02/...
   

3. Proxy endpoint:

   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. Перевірка на сервері

# Перевірити логи 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. Перевірка компонентів

# Знайти всі місця де використовується 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. Документація створена. Система готова до використання.