Skip to content

# TASK_PHASE_GOVERNANCE_MIGRATION_NEXTJS.md

## Міграція Agent Governance Engine в Next.js (apps/web)

Objective: Перенести всі Governance компоненти з `src/` (Vite) в `apps/web/` (Next.js) для деплою на DAARION.space.

Date: 2025-11-30
Status: In Progress

## 1. Контекст

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

- `src/` (Vite/React) — містить нові Governance компоненти, але не задеплоєний
- `apps/web/` (Next.js) — продакшн на DAARION.space, старий код

### Ціль

- Єдиний продакшн frontend = `apps/web` (Next.js)
- `src/` = полігон для прототипування

## 2. Файли для міграції

### 2.1 Types (src/ → apps/web/)

Source | Target
--- | ---
`src/types/governance.ts` | `apps/web/src/lib/types/governance.ts`
`src/types/ontology.ts` | `apps/web/src/lib/types/ontology.ts`

### 2.2 API Clients

Source | Target
--- | ---
`src/api/governance.ts` | `apps/web/src/lib/api/governance.ts`
`src/api/audit.ts` | `apps/web/src/lib/api/audit.ts`
`src/api/incidents.ts` | `apps/web/src/lib/api/incidents.ts`
`src/api/dais.ts` | `apps/web/src/lib/api/dais.ts`
`src/api/assignments.ts` | `apps/web/src/lib/api/assignments.ts`

### 2.3 Components

Source | Target
--- | ---
`src/features/governance/components/GovernanceLevelBadge.tsx` | `apps/web/src/components/governance/GovernanceLevelBadge.tsx`
`src/features/governance/components/CityGovernancePanel.tsx` | `apps/web/src/components/governance/CityGovernancePanel.tsx`
`src/features/governance/components/DistrictGovernancePanel.tsx` | `apps/web/src/components/governance/DistrictGovernancePanel.tsx`
`src/features/governance/components/MicroDAOGovernancePanel.tsx` | `apps/web/src/components/governance/MicroDAOGovernancePanel.tsx`
`src/features/governance/components/AuditDashboard.tsx` | `apps/web/src/components/governance/AuditDashboard.tsx`
`src/features/governance/components/IncidentsList.tsx` | `apps/web/src/components/governance/IncidentsList.tsx`
`src/features/governance/components/ReportButton.tsx` | `apps/web/src/components/governance/ReportButton.tsx`

### 2.4 Pages (Next.js App Router)

Route | File | Description
--- | --- | ---
`/governance` | `apps/web/src/app/governance/page.tsx` | City Governance (REPLACE old MicroDAO voting)
`/governance/district/[id]` | `apps/web/src/app/governance/district/[id]/page.tsx` | District Governance
`/governance/microdao/[id]` | `apps/web/src/app/governance/microdao/[id]/page.tsx` | MicroDAO Governance
`/audit` | `apps/web/src/app/audit/page.tsx` | Audit Dashboard
`/incidents` | `apps/web/src/app/incidents/page.tsx` | Incidents List

## 3. Адаптація для Next.js

### 3.1 Import paths

    // Vite (src/)
    import { api } from '../../../api/governance'

    // Next.js (apps/web/)
    import { governanceApi } from '@/lib/api/governance'

### 3.2 React Query → fetch

- Next.js App Router використовує Server Components
- Замість `useQuery` — використовуємо `async/await` в server components
- Client components позначаємо `'use client'`

### 3.3 Routing

    // Vite (react-router-dom)
    import { useParams, useNavigate } from 'react-router-dom'

    // Next.js
    import { useParams } from 'next/navigation'
    import Link from 'next/link'

## 4. Checklist

### Phase 1: Types & API

- [ ] Створити `apps/web/src/lib/types/governance.ts`
- [ ] Створити `apps/web/src/lib/types/ontology.ts`
- [ ] Створити `apps/web/src/lib/api/governance.ts`
- [ ] Створити `apps/web/src/lib/api/audit.ts`
- [ ] Створити `apps/web/src/lib/api/incidents.ts`

### Phase 2: Components

- [ ] Мігрувати `GovernanceLevelBadge`
- [ ] Мігрувати `ReportButton`
- [ ] Мігрувати `CityGovernancePanel`
- [ ] Мігрувати `DistrictGovernancePanel`
- [ ] Мігрувати `MicroDAOGovernancePanel`
- [ ] Мігрувати `AuditDashboard`
- [ ] Мігрувати `IncidentsList`

### Phase 3: Pages

- [ ] Замінити `/governance/page.tsx` на новий City Governance
- [ ] Створити `/governance/district/[id]/page.tsx`
- [ ] Створити `/governance/microdao/[id]/page.tsx`
- [ ] Створити `/audit/page.tsx`
- [ ] Створити `/incidents/page.tsx`

### Phase 4: Integration

- [ ] Додати GovernanceLevelBadge в Agent Dashboard
- [ ] Додати ReportButton в City Rooms
- [ ] Оновити Navigation з посиланнями на Audit/Incidents

### Phase 5: Deploy

- [ ] Commit & Push
- [ ] Rebuild Docker image
- [ ] Deploy to NODE1
- [ ] Test on DAARION.space

## 5. API Endpoints (backend)

Governance Engine API вже готовий:

    POST /api/v1/governance/agent/promote
    POST /api/v1/governance/agent/demote
    POST /api/v1/governance/agent/revoke
    POST /api/v1/governance/agent/suspend
    POST /api/v1/governance/agent/reinstate
    GET  /api/v1/governance/agent/:id/roles
    GET  /api/v1/governance/agent/:id/permissions
    POST /api/v1/governance/check
    GET  /api/v1/governance/agents/city
    GET  /api/v1/governance/agents/district-leads
    GET  /api/v1/governance/agents/by-level/:level

    GET  /api/v1/audit/events
    GET  /api/v1/audit/events/:id
    GET  /api/v1/audit/actor/:actorId
    GET  /api/v1/audit/target/:targetId
    GET  /api/v1/audit/stats

    POST /api/v1/incidents
    GET  /api/v1/incidents
    GET  /api/v1/incidents/:id
    PUT  /api/v1/incidents/:id
    POST /api/v1/incidents/:id/assign
    POST /api/v1/incidents/:id/escalate
    POST /api/v1/incidents/:id/resolve
    POST /api/v1/incidents/:id/close
    POST /api/v1/incidents/:id/comment

## 6. Результат

Після виконання цього таску:

✅ `/governance` на DAARION.space показує City Governance Panel
✅ `/audit` показує Audit Dashboard
✅ `/incidents` показує Incidents List
✅ Agent Dashboard містить GovernanceLevelBadge
✅ City Rooms мають ReportButton
✅ Старий MicroDAO voting видалено/замінено

Next: Execute migration step by step