Skip to content

# TASK_PHASE_GOVERNANCE_BACKEND_API

Status: 🔄 In Progress
Created: 2024-11-30
Goal: Додати Governance, Audit, Incidents API endpoints до `city-service` (FastAPI)

## 📋 Контекст

Frontend UI для Governance Engine вже задеплоєний на `daarion.space`, але API endpoints повертають 404 бо `city-service` не має цих маршрутів.

Проблема:

    curl http://localhost:7001/api/v1/governance/agents/city
    # → {"detail":"Not Found"}

Рішення: Додати governance endpoints безпосередньо в `city-service` (FastAPI), використовуючи вже існуючі таблиці БД.

## 📁 Нові файли в city-service

    services/city-service/
    ├── repo_governance.py      # Repository для governance/audit/incidents
    ├── routes_governance.py    # FastAPI router для /api/v1/governance/*
    ├── routes_audit.py         # FastAPI router для /api/v1/audit/*
    ├── routes_incidents.py     # FastAPI router для /api/v1/incidents/*
    └── main.py                 # Оновити для підключення нових роутів

## 🎯 API Endpoints

### Governance (`/api/v1/governance`)

Method | Endpoint | Description
--- | --- | ---
GET | `/agents/city` | City Governance Agents (DAARWIZZ, DARIO, DARIA)
GET | `/agents/district/{id}` | District Lead Agent + core-team
GET | `/agents/microdao/{id}` | MicroDAO Orchestrator + workers
GET | `/agents/by-level/{level}` | Agents filtered by gov_level
GET | `/agent/{id}/roles` | Agent roles and permissions
POST | `/agent/promote` | Promote agent to higher level
POST | `/agent/demote` | Demote agent
POST | `/agent/revoke` | Revoke agent (soft/hard)
POST | `/agent/suspend` | Suspend agent temporarily
POST | `/agent/reinstate` | Reinstate suspended agent
POST | `/check` | Check permission for action

### Audit (`/api/v1/audit`)

Method | Endpoint | Description
--- | --- | ---
GET | `/events` | List audit events with filters
GET | `/events/{id}` | Single event details
GET | `/actor/{actorId}` | Events by actor
GET | `/target/{targetId}` | Events by target
GET | `/stats` | Audit statistics

### Incidents (`/api/v1/incidents`)

Method | Endpoint | Description
--- | --- | ---
GET | `/` | List incidents with filters
GET | `/{id}` | Single incident details
POST | `/` | Create incident
POST | `/{id}/assign` | Assign incident
POST | `/{id}/escalate` | Escalate incident
POST | `/{id}/resolve` | Resolve incident
POST | `/{id}/close` | Close incident
POST | `/{id}/comment` | Add comment
GET | `/{id}/history` | Incident history

## 🗄️ Database Tables (вже існують)

- `agents` (з полями `gov_level`, `status`, `revoked_at`, `revoked_by`)
- `agent_assignments`
- `event_outbox` (actor_id, target_id, scope)
- `incidents`
- `incident_history`
- `permissions`
- `agent_revocations`
- `dais_keys`

## ✅ Checklist

- [ ] Create `repo_governance.py`
- [ ] Create `routes_governance.py`
- [ ] Create `routes_audit.py`
- [ ] Create `routes_incidents.py`
- [ ] Update `main.py` to include new routers
- [ ] Test locally
- [ ] Deploy to NODE1
- [ ] Verify on daarion.space

## 🚀 Deployment

    # On NODE1
    cd /opt/microdao-daarion
    git pull
    docker build -t daarion-city-service services/city-service/
    docker stop daarion-city-service && docker rm daarion-city-service
    docker run -d --name daarion-city-service --network dagi-network ...