microdao-daarion/docs/tasks/TASK_PHASE_BRANDING_BANNERS_MVP.md

TASK_PHASE_BRANDING_BANNERS_MVP — Завершення підтримки логотипів та банерів

Контекст

Після виправлення proxy endpoint та нормалізації URL:

• ✅ Логотипи працюють: завантажуються через /api/city/assets/proxy/...
• ✅ Proxy endpoint працює: HEAD/GET методи підтримуються
• ⚠️ Банери: banner_url: null в БД (просто ще не завантажували)

Поточна ситуація:

• Технічна інфраструктура працює
• Потрібно перевірити повний upload flow для банерів
• Можливо додати fallback для відображення банера

---

Завдання

1. Перевірити upload-флоу для банера

Кроки:

1. Залогінитись на daarion.space

   • Відкрити сторінку MicroDAO (наприклад, /microdao/daarion)
   • Перейти до секції "Branding"

2. Завантажити банер:

   • Натиснути "Upload Banner"
   • Вибрати зображення (PNG/JPG, рекомендовано 1920x400 або подібне)
   • Дочекатись завершення завантаження (без помилок)

3. Перевірити в DevTools → Network:

   • Знайти запит на /api/assets/upload (або /api/city/assets/upload)
   • Статус: 200 OK
   • Відповідь містить processed_url або original_url з MinIO URL
   • Знайти запит на /api/microdao/{slug}/branding (PATCH)
   • Статус: 200 OK
   • Відповідь містить banner_url (не null)

4. Перевірити оновлення в БД:

   curl -s "https://daarion.space/api/city/microdao/daarion" | jq '{logo_url, banner_url}'
   

   • banner_url має бути заповнений (не null)
   • URL має бути формату: https://assets.daarion.space/daarion-assets/microdao/banner/...

5. Перевірити відображення:

   • Оновити сторінку MicroDAO
   • Банер має відображатись (не placeholder)
   • В DevTools → Network знайти запит на /api/city/assets/proxy/microdao/banner/...
   • Статус: 200 OK, Content-Type: image/png або image/jpeg

2. Гарантувати запис banner_url у БД

Перевірити:

1. Backend endpoint /api/microdao/{slug}/branding (PATCH):

   • Файл: apps/web/src/app/api/microdao/[slug]/branding/route.ts (або подібний)
   • Переконатись, що banner_url зберігається в БД
   • Перевірити валідацію URL

2. Backend endpoint /api/city/microdao/{slug}/branding (якщо є):

   • Файл: services/city-service/routes_city.py
   • Переконатись, що endpoint оновлює banner_url в таблиці microdaos

3. Database schema:

   • Переконатись, що microdaos.banner_url має тип text (після міграції 043_asset_urls_to_text.sql)
   • Перевірити, що поле може бути NULL (для старих записів)

3. Додати fallback при banner_url == null

Варіанти реалізації:

Варіант A: Використати логотип як банер

// apps/web/src/components/microdao/MicrodaoHeaderCard.tsx
const bannerUrl = normalizeAssetUrl(microdao.banner_url) || normalizeAssetUrl(microdao.logo_url);

Варіант B: Використати дефолтний банер

// apps/web/src/lib/utils/assetUrl.ts
export function normalizeAssetUrl(url: string | null | undefined, fallback?: string): string | null {
  if (!url) return fallback || null;
  // ... existing logic
}

// Usage:
const bannerUrl = normalizeAssetUrl(microdao.banner_url, '/assets/default-banner.png');

Варіант C: CSS gradient fallback

// Якщо banner_url == null, використати CSS gradient замість зображення
style={microdao.banner_url ? {
  backgroundImage: `url(${normalizeAssetUrl(microdao.banner_url)})`,
} : {
  background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
}}

Рекомендація: Варіант A (використати логотип) — найпростіший і найлогічніший.

4. Задокументувати "як правильно додавати логотип/банер до MicroDAO"

Створити документацію:

1. Файл: docs/BRANDING_ASSETS_GUIDE.md

2. Зміст:

   • Як завантажити логотип/банер через UI
   • Рекомендовані розміри:
     • Logo: 512x512px (квадратне)
     • Banner: 1920x400px (широке)
   • Підтримувані формати: PNG, JPG, WebP
   • Як працює proxy endpoint
   • Як працює normalizeAssetUrl
   • Troubleshooting (якщо зображення не відображається)

---

Acceptance Criteria

• Upload банера працює без помилок
• banner_url зберігається в БД після завантаження
• Банер відображається на сторінці MicroDAO після завантаження
• Proxy endpoint працює для банерів (/api/city/assets/proxy/microdao/banner/...)
• Додано fallback для banner_url == null (опціонально)
• Створено документацію по роботі з branding assets

---

Технічні деталі

Endpoints для перевірки

1. Upload asset:

   • POST /api/assets/upload (Next.js route)
   • Або POST /api/city/assets/upload (city-service)
   • Body: FormData з file та type (наприклад, microdao_banner)

2. Update branding:

   • PATCH /api/microdao/{slug}/branding
   • Body: { banner_url: "https://assets.daarion.space/..." }

3. Get MicroDAO:

   • GET /api/city/microdao/{slug}
   • Response: { logo_url: "...", banner_url: "..." }

Файли для перевірки/зміни

1. Frontend:

   • apps/web/src/components/microdao/MicrodaoBrandingCard.tsx — компонент завантаження
   • apps/web/src/components/microdao/MicrodaoHeaderCard.tsx — відображення банера
   • apps/web/src/app/microdao/[slug]/page.tsx — сторінка MicroDAO

2. Backend:

   • services/city-service/routes_city.py — endpoint /assets/upload та /microdao/{slug}/branding
   • apps/web/src/app/api/microdao/[slug]/branding/route.ts — Next.js API route (якщо є)

3. Database:

   • Таблиця microdaos з полями logo_url та banner_url (тип text)

---

Troubleshooting

Проблема: Банер не зберігається в БД

Перевірити:

1. Чи працює endpoint /api/microdao/{slug}/branding (PATCH)
2. Чи правильно передається banner_url в запиті
3. Чи є помилки в логах city-service

Проблема: Банер зберігається, але не відображається

Перевірити:

1. Чи використовується normalizeAssetUrl для банера
2. Чи працює proxy endpoint для шляху банера
3. Чи файл існує в MinIO за вказаним шляхом

Проблема: Upload не працює

Перевірити:

1. Чи працює endpoint /api/assets/upload
2. Чи правильно налаштовані ENV змінні для MinIO
3. Чи є помилки в логах city-service

---

Наступні кроки

1. Виконати перевірку upload-флоу для банера
2. Виправити виявлені проблеми (якщо є)
3. Додати fallback для banner_url == null (опціонально)
4. Створити документацію
5. Закомітити зміни