docs: add compose + node dashboard tasks

2025-11-30 06:51:46 -08:00
parent 7ff426f975
commit 9d6428c6ee
2 changed files with 213 additions and 0 deletions
--- a/docs/tasks/TASK_PHASE_NODE_DASHBOARD_API_MVP.md
+++ b/docs/tasks/TASK_PHASE_NODE_DASHBOARD_API_MVP.md
@@ -0,0 +1,115 @@
+# TASK PHASE — NODE DASHBOARD API (MVP)
+
+Version: 1.0  
+Target: NODE1 (city-service + daarion-web)
+
+---
+
+## 1. Мета
+
+Замість 404-заглушки для `/api/node/dashboard` зробити мінімальний Node Dashboard API, який:
+
+- повертає базову інформацію про ноду (status, tags, agents_online, uptime);
+- не ламає сторінку ноди, навіть якщо метрик поки немає;
+- має чітку структуру для подальшого розширення (Prometheus, NATS events, тощо).
+
+---
+
+## 2. Поточний стан
+
+- `/nodes` і `/nodes/:nodeId` вже працюють через `/public/nodes`.
+- На сторінці `nodes/[nodeId]` фронт робить запит на `/api/node/dashboard`, отримує 404 та показує банер (graceful degradation).
+- бекенд не має відповідного endpoint’а.
+
+---
+
+## 3. Завдання для backend (city-service)
+
+### 3.1. Створити Node Dashboard endpoint
+
+1. Додати новий роутер, наприклад `routes_node_dashboard.py`, або розширити існуючий `routes_city`.
+2. Маршрут:
+   ```
+   GET /api/v1/nodes/{node_id}/dashboard
+   ```
+3. Реалізація:
+   ```python
+   @router.get("/api/v1/nodes/{node_id}/dashboard")
+   async def get_node_dashboard(node_id: str):
+       node = await repo_city.get_node_by_id(node_id)
+       if not node:
+           raise HTTPException(status_code=404, detail="Node not found")
+
+       return {
+           "node_id": node["node_id"],
+           "name": node["name"],
+           "kind": node.get("kind"),
+           "status": node.get("status", "unknown"),
+           "tags": node.get("roles", []),
+           "agents_total": node.get("agents_total", 0),
+           "agents_online": node.get("agents_online", 0),
+           "uptime": None,                 # placeholder
+           "metrics_available": False      # флаг, що метрик ще немає
+       }
+   ```
+4. Під’єднати роутер у `main.py`.
+
+### 3.2. Legacy-роут (опційно)
+
+Якщо фронт все ще звертається до `/api/node/dashboard?nodeId=...`, додати невеликий alias:
+```python
+@router.get("/api/node/dashboard")
+async def get_node_dashboard_legacy(node_id: str):
+    return await get_node_dashboard(node_id)
+```
+
+### 3.3. Repo / модель
+
+Перевірити, що `repo_city.get_node_by_id` повертає словник з потрібними полями (node_id, name, roles, status, agents_total, agents_online).
+
+---
+
+## 4. Завдання для frontend (apps/web)
+
+1. В `apps/web/src/lib/api/nodes.ts` (або аналогічному файлі):
+   ```ts
+   export async function getNodeDashboard(nodeId: string) {
+     return api.get(`/api/nodes/${encodeURIComponent(nodeId)}/dashboard`);
+   }
+   ```
+2. В `nodes/[nodeId]/page.tsx`:
+   - використовувати новий API;
+   - якщо `metrics_available === false`, показувати банер “детальний дашборд у розробці”, але рендерити базову інформацію;
+   - якщо відповідь 404 → fallback до вже наявної логіки (профіль з `/public/nodes`).
+
+---
+
+## 5. Перевірки
+
+1. `GET https://daarion.space/api/nodes/node-1-hetzner-gex44/dashboard`
+   ```json
+   {
+     "node_id": "node-1-hetzner-gex44",
+     "name": "...",
+     "status": "online",
+     "tags": ["core","gateway",...],
+     "agents_total": 9,
+     "agents_online": 1,
+     "uptime": null,
+     "metrics_available": false
+   }
+   ```
+2. UI `https://daarion.space/nodes/node-1-hetzner-gex44`:
+   - сторінка відкривається без помилок;
+   - зверху банер (поки API повертає `metrics_available=false`);
+   - базова інформація про ноду видно.
+3. У логах Next.js немає помилок “Failed to fetch node dashboard”.
+
+---
+
+## 6. Подальші кроки (out of scope)
+
+- Коли з’являться реальні метрики (Prometheus, Agent runtime), заповнити поля `uptime`, `metrics_available=True`, додати масив графіків/alerts.
+- Додати історію подій ноди (restart, incident, deployment) через `event_outbox`.
+
+