microdao-daarion/docs/tasks/TASK_PHASE_CITY_ROOMS_ROUTING_v1.md

TASK_PHASE_CITY_ROOMS_ROUTING_v1

Version: 1.0 Status: Ready Priority: High (City Layer UX + Matrix Rooms)

---

1. МЕТА

Зробити так, щоб кожна City Room була доступною за URL:

• /city — огляд усіх кімнат
• /city/{slug} — сторінка конкретної кімнати

Сторінка кімнати має:

• завантажувати дані кімнати з backend (room meta + matrix_room_id),
• показувати присутніх агентів,
• інтегрувати чат (Matrix room),
• показувати presence агентів.

---

2. ВИХІДНІ ДАНІ

Вже є:

• Таблиця rooms з city-кімнатами (scope = 'city', 8+ кімнат).
• Поле slug або еквівалент (наприклад city-general, city-welcome тощо).
• matrix_room_id заповнене (Matrix sync завершений).
• Matrix Gateway та Chat API:
  • GET /api/v1/chat/rooms/{room_id}/messages
  • POST /api/v1/chat/rooms/{room_id}/messages
• Presence Layer:
  • GET /api/v1/agents/{agent_id}/presence
• Frontend:
  • базовий Chat Widget
  • компонент PresenceDot
  • карта /city вже існує (огляд кімнат).

---

3. SCOPE

1. Frontend routing для /city/{slug} (Next.js, App Router).
2. API-обгортка для завантаження City Room.
3. Сторінка кімнати:
   • назва, опис, тип кімнати;
   • список ключових агентів (host/moderators);
   • presence-індикатори;
   • чат-виджет, прив'язаний до room_id / matrix_room_id.
4. Обробка помилок:
   • 404, якщо кімната не існує;
   • fallback UI, якщо Matrix тимчасово недоступний.

---

4. МОДУЛЬ 1 — BACKEND (CITY-SERVICE) API (якщо ще немає)

Перевірити/додати в city-service:

4.1. GET /api/v1/city/rooms

Список всіх city-кімнат.

Вихід:

[
  {
    "id": "uuid",
    "slug": "city-general",
    "name": "General",
    "description": "Головна кімната міста",
    "scope": "city",
    "matrix_room_id": "!room:matrix.daarion.city",
    "host_agents": ["agent_id_1", "agent_id_2"]
  },
  ...
]

4.2. GET /api/v1/city/rooms/{slug}

Конкретна кімната за slug.

Вихід:

{
  "id": "uuid",
  "slug": "city-general",
  "name": "General",
  "description": "Головна кімната міста",
  "scope": "city",
  "matrix_room_id": "!room:matrix.daarion.city",
  "host_agents": [
    {
      "id": "agent_id_1",
      "name": "DARIO",
      "role": "host"
    }
  ]
}

Якщо кімнати немає → 404.

---

5. МОДУЛЬ 2 — FRONTEND API КЛІЄНТ

В apps/web/src/lib/api/city.ts (або створити новий):

export async function getCityRooms(): Promise<CityRoomSummary[]> { ... }

export async function getCityRoomBySlug(slug: string): Promise<CityRoomDetail> { ... }

Де CityRoomDetail містить як мінімум:

• id
• slug
• name
• description
• matrixRoomId
• hostAgents[]

---

6. МОДУЛЬ 3 — ROUTING: /city/{slug}

У apps/web/src/app/city/[slug]/page.tsx:

1. Прочитати params.slug.
2. Викликати getCityRoomBySlug(slug).
3. Якщо 404 → показати notFound() (Next.js).
4. Якщо інша помилка → показати error boundary / fallback.

---

7. МОДУЛЬ 4 — UI СТОРІНКИ КІМНАТИ

Макет сторінки /city/{slug}:

7.1. Верхня частина (header)

• Назва кімнати (room.name)
• Підназва / опис (room.description)
• Badge: City Room
• Breadcrumb: City / {room.name}

7.2. Блок "Host Agents"

Карточка(и) головних агентів кімнати:

• аватар
• ім'я
• роль (host/moderator)
• PresenceDot (online/away/offline)
• посилання "Перейти в кабінет агента"

Дані брати з host_agents.

7.3. Блок "Room Info" (опціонально)

• список тегів (public / governance / help / etc.)
• кількість учасників (якщо є)

7.4. Блок "Chat"

Використати Chat Widget, але прив'язати не до Agent/Node/MicroDAO, а до ROOM:

• якщо вже є універсальний <AgentChatWidget> з режимами entityType, можна:
  • додати entityType="room"
  • entityId = room.id
• якщо ні — створити CityRoomChatWidget, який:
  • бере room.id → /api/v1/chat/rooms/{room.id}/messages
  • дозволяє надсилати повідомлення в кімнату

Для неавторизованих:

• "Увійдіть, щоб писати у міську кімнату".

---

8. МОДУЛЬ 5 — ІНТЕГРАЦІЯ З /city

На сторінці /city:

• у списку/мапі кімнат:
  • додати посилання на /city/{slug}.
• клік по кімнаті → відкриває /city/{slug}.

---

9. ОБРОБКА ПОМИЛОК

1. Якщо /api/v1/city/rooms/{slug} повертає 404:

   • Next.js notFound() → стандартна 404-сторінка.

2. Якщо помилка backend (500):

   • показати повідомлення "Кімната тимчасово недоступна".

3. Якщо немає matrix_room_id:

   • показати банер "Matrix ще синхронізується, чат скоро з'явиться".

---

10. SMOKE-ТЕСТИ

Після завершення:

1. /city:

   • список/мапа містить 8+ кімнат.

2. /city/general:

   • сторінка відкривається;
   • видно назву, опис;
   • видно host-агентів (наприклад, DARIO/DARIA);
   • видно presence.

3. /city/welcome, /city/leadership-hall, /city/builders, /city/security, /city/announcements:

   • усі відкриваються без 404.

4. Chat:

   • у кімнаті /city/general можливо:
     • побачити історію повідомлень;
     • відправити нове повідомлення (як авторизований користувач).

---

11. FINISH-АРТЕФАКТ

Після виконання Cursor створює:

docs/debug/city_rooms_routing_report_<DATE>.md

Зі змістом:

• список slug'ів city-кімнат;
• приклади успішних HTTP-викликів:
  • GET /api/v1/city/rooms
  • GET /api/v1/city/rooms/{slug}
• скріншот або опис перевірки /city/{slug};
• підтвердження роботи чату в принаймні одній кімнаті.

---

12. PROMPT ДЛЯ CURSOR

Виконай TASK_PHASE_CITY_ROOMS_ROUTING_v1.md.

Фокус:
1) Backend: /api/v1/city/rooms, /api/v1/city/rooms/{slug} (якщо ще немає)
2) Frontend: Next.js routing /city/[slug]
3) UI: сторінка кімнати (host agents, presence, chat)
4) Інтеграція з існуючими чат/Matrix/PRESENCE шарами

Після завершення створи:
docs/debug/city_rooms_routing_report_<DATE>.md

---

Target Date: Immediate Priority: High Dependencies: Matrix integration complete, Chat API working