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