# TASK_PHASE_DISTRICT_PORTALS_v1

Version: 1.0
Status: Ready
Priority: High (City → District → MicroDAO контур)

---

# 1. МЕТА

Зробити **District-и повноцінними "порталами платформ"** у DAARION.city:

- окремі сторінки District-ів (SOUL, GREENFOOD, ENERGYUNION),
- прив'язка до існуючих District-протоколів,
- інтеграція з Rooms, Matrix, Presence, Chat Widget,
- відображення MicroDAO всередині District-а.

Результат:
користувач, заходячи на DAARION.space, може:

- потрапити в місто (/city),
- з міста — в District-портал (/soul, /greenfood, /energy-union),
- з District — у відповідні MicroDAO / кімнати / агентів.

---

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

Уже є:

- Foundation-документи:
  - `GREENFOOD_District_Protocol_v1.md`
  - `ENERGYUNION_District_Protocol_v1.md`
  - `SOUL_District_Protocol_v1.md`
  - `District_Interface_Architecture_v1.md`
- Таблиця `microdaos` з полем `dao_type = 'district'` (SOUL, GREENFOOD, ENERGYUNION).
- Rooms Layer:
  - District rooms для:
    - SOUL (soul-lobby, soul-events, soul-masters, ...)
    - GREENFOOD (greenfood-lobby, ... )
    - ENERGYUNION (energyunion-lobby, energyunion-compute, ...)
- Matrix + Chat:
  - `rooms.matrix_room_id` заповнено,
  - Chat API працює,
  - Presence API працює.
- Frontend:
  - City Layer /city, /city/{slug}
  - Agents, Nodes, MicroDAO базові сторінки

---

# 3. SCOPE

1. Backend District API:
   - `GET /api/v1/districts`
   - `GET /api/v1/districts/{slug}`
2. Frontend routing:
   - `/districts` (список всіх District-ів)
   - `/districts/[slug]` (універсальний портал)
   - короткі alias-роути:
     - `/soul` → SOUL District
     - `/greenfood` → GREENFOOD District
     - `/energy-union` → ENERGYUNION District
3. UI District-порталу:
   - header (назва, опис, тип, lead agent),
   - District rooms (список кімнат + переходи),
   - host agents (lead/core team) + presence,
   - chat widget (District lobby room),
   - список MicroDAO всередині District-а.
4. Інтеграція з City Layer:
   - посилання з City → District.

---

# 4. МОДУЛЬ 1 — BACKEND: DISTRICT API (CITY-SERVICE)

## 4.1. `GET /api/v1/districts`

Повертає список всіх District-ів.

Приблизний вихід:

```json
[
  {
    "id": "uuid",
    "slug": "soul",
    "name": "SOUL Retreat District",
    "description": "Wellness / Retreat / Metahuman",
    "dao_type": "district",
    "lead_agent": {
      "id": "agent_id_soul",
      "name": "SOUL"
    },
    "rooms": [
      {
        "id": "uuid",
        "slug": "soul-lobby",
        "name": "SOUL Lobby"
      }
    ],
    "microdaos_count": 0
  },
  {
    "id": "uuid",
    "slug": "greenfood",
    "name": "GREENFOOD District",
    "description": "ERP / Supply Chains / Food",
    "dao_type": "district",
    "lead_agent": {
      "id": "agent_id_greenfood",
      "name": "ERP GREENFOOD"
    },
    "rooms": [ ... ],
    "microdaos_count": 0
  },
  {
    "id": "uuid",
    "slug": "energy-union",
    "name": "Energy Union District",
    "description": "DePIN / Energy / Compute",
    "dao_type": "district",
    "lead_agent": {
      "id": "agent_id_helion",
      "name": "Helion"
    },
    "rooms": [ ... ],
    "microdaos_count": 0
  }
]
```

Логіка:

- брати записи з `microdaos` де `dao_type = 'district'`;
- підвантажити lead-agent (згідно District-протоколів);
- підтягнути ключові кімнати (lobby тощо) через `rooms` та `district_id` / зв'язки.

## 4.2. `GET /api/v1/districts/{slug}`

Подробиці District-а.

Приблизний вихід:

```json
{
  "id": "uuid",
  "slug": "soul",
  "name": "SOUL Retreat District",
  "description": "Wellness / Retreat / Metahuman District",
  "dao_type": "district",
  "lead_agent": {
    "id": "agent_id_soul",
    "name": "SOUL",
    "dais_id": "dais_soul"
  },
  "core_team": [
    {
      "id": "agent_spirit",
      "name": "Spirit",
      "role": "Guidance"
    },
    {
      "id": "agent_logic",
      "name": "Logic",
      "role": "Information"
    }
  ],
  "rooms": [
    {
      "id": "room_id_lobby",
      "slug": "soul-lobby",
      "name": "SOUL Lobby",
      "matrix_room_id": "!room:matrix..."
    },
    {
      "id": "room_id_events",
      "slug": "soul-events",
      "name": "Events"
    }
  ],
  "microdaos": [
    {
      "id": "microdao_id_1",
      "slug": "soul-hub-1",
      "name": "Retreat Hub #1"
    }
  ]
}
```

Якщо District не знайдено → 404.

---

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

У `apps/web/src/lib/api/districts.ts`:

```ts
export type DistrictSummary = {
  id: string;
  slug: string;
  name: string;
  description: string;
  daoType: "district";
  leadAgent: {
    id: string;
    name: string;
  };
  rooms: {
    id: string;
    slug: string;
    name: string;
  }[];
  microdaosCount: number;
};

export type DistrictDetail = {
  id: string;
  slug: string;
  name: string;
  description: string;
  daoType: "district";
  leadAgent: {
    id: string;
    name: string;
    daisId?: string;
  };
  coreTeam: {
    id: string;
    name: string;
    role: string;
  }[];
  rooms: {
    id: string;
    slug: string;
    name: string;
    matrixRoomId?: string;
  }[];
  microdaos: {
    id: string;
    slug: string;
    name: string;
  }[];
};

export async function getDistricts(): Promise<DistrictSummary[]> { ... }

export async function getDistrictBySlug(slug: string): Promise<DistrictDetail> { ... }
```

---

# 6. МОДУЛЬ 3 — ROUTING

## 6.1. `/districts` (список)

Файл: `apps/web/src/app/districts/page.tsx`

Повинен:

- завантажити `getDistricts()`;
- показати карточки District-ів:
  - SOUL
  - GREENFOOD
  - ENERGY UNION
- кожна картка:
  - назва
  - опис
  - lead agent (ім'я + presence)
  - кнопка/посилання "Перейти до District".

## 6.2. `/districts/[slug]` (портал District-а)

Файл: `apps/web/src/app/districts/[slug]/page.tsx`

Логіка:

- прочитати `params.slug`;
- викликати `getDistrictBySlug(slug)`;
- якщо 404 → `notFound()`.

---

# 7. МОДУЛЬ 4 — UI DISTRICT-ПОРТАЛУ

Структура сторінки `/districts/[slug]`:

## 7.1. Header

- Назва District-а (`name`)
- Опис (`description`)
- Badge: "District"
- Breadcrumb:
  - `City / Districts / {DistrictName}`

## 7.2. Lead Agent + Core Team

Секція "District Agents":

- Lead Agent:
  - аватар,
  - ім'я (SOUL / GREENFOOD / Helion),
  - PresenceDot (online/offline/away),
  - кнопка "Кабінет агента".

- Core Team (якщо є):
  - список агентів (Spirit, Logic, Energia тощо),
  - ролі (Guidance, Information, Energy, Scheduler...),
  - presence.

## 7.3. Rooms

Секція "District Rooms":

- список кімнат District-а:
  - назва,
  - опис (якщо є),
  - scope tag (lobby / events / labs / providers / compute / guidance / etc.),
  - кнопка "Відкрити кімнату" → `/city/{slug}` або окремий `/rooms/{slug}`, залежно від моделі.
- Для lobby-кімнати:
  - окремий акцент: "Головний портал District-а".

(Якщо кімнати реалізовані як `rooms.scope = 'district'`, на UI використовувати їх метадані з БД.)

## 7.4. MicroDAO

Секція "MicroDAO цього District-а":

- таблиця/карточки:
  - назва MicroDAO,
  - тип (якщо є),
  - кнопка "Відкрити MicroDAO" → `/microdao/{slug}`.

## 7.5. Chat (District Lobby)

- Внизу чи праворуч: Chat Widget, прив'язаний до **District Lobby Room**:
  - отримати lobby room з `rooms` (наприклад, slug `soul-lobby`, `greenfood-lobby`, `energyunion-lobby`);
  - чат працює через `/api/v1/chat/rooms/{room_id}`.
- Неавторизованим показувати "Увійти, щоб писати".

---

# 8. МОДУЛЬ 5 — SHORTCUT ROUTES

Щоб було зручно заходити на платформи:

- `/soul` → редірект або пряма сторінка, що використовує `getDistrictBySlug("soul")`.
- `/greenfood` → `getDistrictBySlug("greenfood")`.
- `/energy-union` → `getDistrictBySlug("energy-union")`.

Реалізація:

- створити файли:
  - `apps/web/src/app/soul/page.tsx`
  - `apps/web/src/app/greenfood/page.tsx`
  - `apps/web/src/app/energy-union/page.tsx`

Які просто рендерять той самий компонент, що й `/districts/[slug]`, з фіксованим `slug`.

---

# 9. ІНТЕГРАЦІЯ З CITY LAYER

На сторінці `/city` або в City Square:

- для портальних точок (District Portals):
  - додати кнопки/картки:
    - "SOUL Retreat District"
    - "GREENFOOD District"
    - "Energy Union District"
  - клік → переходить на:
    - `/soul`
    - `/greenfood`
    - `/energy-union`

---

# 10. SMOKE-ТЕСТИ

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

1. `/districts`:
   - показує 3 District-и (SOUL, GREENFOOD, ENERGYUNION).

2. `/districts/soul`:
   - рендериться без помилок,
   - видно SOUL як lead agent + presence,
   - видно Spirit/Logic (як core team, якщо додані),
   - видно список rooms (soul-lobby, soul-events, soul-guidance...),
   - чат-простір для lobby.

3. `/districts/greenfood`:
   - рендериться,
   - видно ERP GREENFOOD agent,
   - rooms згідно GREENFOOD_District_Protocol,
   - microDAO (якщо є) у списку.

4. `/districts/energy-union`:
   - рендериться,
   - видно Helion, Energia,
   - rooms (lobby, compute, providers, labs...),
   - чат-простір.

5. `/soul`, `/greenfood`, `/energy-union`:
   - відкривають відповідні портали District-ів.

6. City → District:
   - з City UI є лінки, які ведуть на District Portals.

---

# 11. ФІНАЛЬНИЙ ЗВІТ

Після виконання:

Створити файл:

`docs/debug/district_portals_report_<DATE>.md`

І включити в нього:

- список District-ів з `/api/v1/districts`,
- приклади `GET /api/v1/districts/{slug}`,
- скрін/опис `/districts`, `/districts/soul`, `/districts/greenfood`, `/districts/energy-union`,
- підтвердження, що `/soul`, `/greenfood`, `/energy-union` працюють.

---

# 12. PROMPT ДЛЯ CURSOR

```text
Виконай TASK_PHASE_DISTRICT_PORTALS_v1.md.

Фокус:
1) Backend: /api/v1/districts, /api/v1/districts/{slug}
2) Frontend: /districts, /districts/[slug], /soul, /greenfood, /energy-union
3) District UI: lead agent, core team, rooms, microDAO list, chat (lobby room)
4) Інтеграція з City Layer (/city → District Portals)

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

---

**Target Date**: Immediate
**Priority**: High
**Dependencies**: City Layer complete, Matrix rooms synced