feat: Add presence heartbeat for Matrix online status

- matrix-gateway: POST /internal/matrix/presence/online endpoint - usePresenceHeartbeat hook with activity tracking - Auto away after 5 min inactivity - Offline on page close/visibility change - Integrated in MatrixChatRoom component
2025-11-27 00:19:40 -08:00
parent 5bed515852
commit 3de3c8cb36
6371 changed files with 1317450 additions and 932 deletions
--- a/PHASE7_BACKEND_COMPLETE.md
+++ b/PHASE7_BACKEND_COMPLETE.md
@@ -0,0 +1,414 @@
+# ✅ PHASE 7 — microDAO Console Backend COMPLETE
+
+**Статус:** ✅ Завершено  
+**Дата:** 24 листопада 2025
+
+---
+
+## 📋 Огляд
+
+Phase 7 Backend Completion додає **повну backend-реалізацію** для microDAO Console:
+- ✅ Повний CRUD для microDAO
+- ✅ Управління учасниками (members) з ролями
+- ✅ Управління казною (treasury)
+- ✅ Налаштування (settings)
+- ✅ PDP + Auth перевірки для всіх операцій
+- ✅ NATS події для всіх змін
+- ✅ Frontend інтеграція з реальними даними
+
+---
+
+## 📦 Створені файли
+
+### Backend (microdao-service)
+
+#### Repository Layer
+- **`services/microdao-service/repository_microdao.py`** — 485 рядків
+  - `create_microdao()` — створення microDAO + автоматичне додавання owner
+  - `update_microdao()` — оновлення назви, опису, статусу
+  - `delete_microdao()` — м'яке видалення (is_active=false)
+  - `get_microdao_by_slug()` — отримання по slug
+  - `get_microdao_by_id()` — отримання по ID
+  - `list_microdaos_for_user()` — список microDAO де користувач є member
+  - `list_members()` — список учасників
+  - `add_member()` — додавання учасника
+  - `remove_member()` — видалення учасника
+  - `get_user_role_in_microdao()` — отримання ролі користувача
+  - `get_treasury_items()` — список токенів у казні
+  - `apply_treasury_delta()` — зміна балансу (±)
+  - `set_treasury_balance()` — встановлення балансу
+  - `get_settings()` — отримання налаштувань
+  - `upsert_setting()` — оновлення налаштування
+  - `delete_setting()` — видалення налаштування
+
+#### Routes Layer
+- **`services/microdao-service/routes_microdao.py`** — 248 рядків
+  - `GET /microdao` — список microDAO користувача
+  - `POST /microdao` — створення microDAO
+  - `GET /microdao/{slug}` — деталі microDAO
+  - `PUT /microdao/{slug}` — оновлення microDAO
+  - `DELETE /microdao/{slug}` — видалення microDAO
+
+- **`services/microdao-service/routes_members.py`** — 249 рядків
+  - `GET /microdao/{slug}/members` — список учасників
+  - `POST /microdao/{slug}/members` — додавання учасника
+  - `PATCH /microdao/{slug}/members/{member_id}` — зміна ролі
+  - `DELETE /microdao/{slug}/members/{member_id}` — видалення учасника
+
+- **`services/microdao-service/routes_treasury.py`** — 186 рядків
+  - `GET /microdao/{slug}/treasury` — список токенів
+  - `POST /microdao/{slug}/treasury` — зміна балансу (delta)
+  - `PUT /microdao/{slug}/treasury/{token_symbol}` — встановлення балансу
+
+- **`services/microdao-service/routes_settings.py`** — 212 рядків
+  - `GET /microdao/{slug}/settings` — всі налаштування
+  - `POST /microdao/{slug}/settings` — оновлення одного налаштування
+  - `PUT /microdao/{slug}/settings` — bulk update
+  - `DELETE /microdao/{slug}/settings/{key}` — видалення налаштування
+
+#### NATS Integration
+- **`services/microdao-service/nats_client.py`** — 41 рядок
+  - `NATSPublisher` клас для публікації подій
+  - Події: `microdao.event.created`, `microdao.event.updated`, `microdao.event.deleted`
+  - Події: `microdao.event.member_added`, `microdao.event.member_removed`, `microdao.event.member_role_updated`
+  - Події: `microdao.event.treasury_updated`, `microdao.event.settings_updated`
+
+#### Main Application
+- **`services/microdao-service/main.py`** — оновлено
+  - Підключення всіх routes
+  - Ініціалізація repository
+  - Підключення NATS publisher
+  - Dependency injection для всіх routes
+
+- **`services/microdao-service/requirements.txt`** — оновлено
+  - Додано `nats-py==2.6.0`
+
+---
+
+### Frontend
+
+#### API Client
+- **`src/api/microdao.ts`** — оновлено (+67 рядків)
+  - `deleteMicrodao()` — видалення microDAO
+  - `updateTreasuryBalance()` — зміна балансу токена
+  - `setTreasuryBalance()` — встановлення балансу токена
+  - `getSettings()` — отримання налаштувань
+  - `updateSetting()` — оновлення налаштування
+  - `updateSettings()` — bulk update налаштувань
+  - `deleteSetting()` — видалення налаштування
+
+#### UI Components
+- **`src/features/microdao/MicrodaoListPage.tsx`** — вже існує
+  - Використовує реальне API через `useMicrodaos()` hook
+  - Створення microDAO через `createMicrodao()`
+  
+- **`src/features/microdao/MicrodaoConsolePage.tsx`** — вже існує
+  - Використовує реальне API:
+    - `getMicrodao(slug)` для деталей
+    - `getMembers(slug)` для учасників
+    - `getTreasury(slug)` для казни
+    - `getAgents(microdao.external_id)` для агентів
+
+---
+
+### Infrastructure
+
+#### Docker
+- **`docker-compose.phase7.yml`** — оновлено
+  - Додано `NATS_URL` для `microdao-service`
+  - Додано залежність від `nats` сервісу
+  - Всі сервіси Phase 4-7 підключені
+
+---
+
+## 🔐 Security
+
+### Authentication
+- Всі endpoints перевіряють `Authorization: Bearer <token>` header
+- Отримання `ActorIdentity` через `auth-service` (`/auth/me`)
+- 401 у разі відсутності або невалідного токена
+
+### Authorization (PDP)
+Всі операції перевіряються через `pdp-service`:
+
+| Операція | Action | Resource |
+|----------|--------|----------|
+| Список microDAO | - | Автоматично фільтрує по user_id |
+| Створення microDAO | `MICRODAO_CREATE` | `{type: "MICRODAO"}` |
+| Перегляд microDAO | `MICRODAO_READ` | `{type: "MICRODAO", id: microdao_id}` |
+| Оновлення microDAO | `MICRODAO_MANAGE` | `{type: "MICRODAO", id: microdao_id}` |
+| Видалення microDAO | `MICRODAO_MANAGE` | `{type: "MICRODAO", id: microdao_id}` |
+| Додавання учасника | `MICRODAO_MANAGE_MEMBERS` | `{type: "MICRODAO", id: microdao_id}` |
+| Видалення учасника | `MICRODAO_MANAGE_MEMBERS` | `{type: "MICRODAO", id: microdao_id}` |
+| Перегляд казни | `MICRODAO_READ_TREASURY` | `{type: "MICRODAO", id: microdao_id}` |
+| Управління казною | `MICRODAO_MANAGE_TREASURY` | `{type: "MICRODAO", id: microdao_id}` |
+| Управління налаштуваннями | `MICRODAO_MANAGE` | `{type: "MICRODAO", id: microdao_id}` |
+
+### Roles
+- **owner** — повний доступ, не може бути видалений якщо останній
+- **admin** — може керувати учасниками, налаштуваннями
+- **member** — може читати дані microDAO
+- **guest** — обмежений доступ
+
+---
+
+## 📊 Database Schema
+
+Міграція `008_create_microdao_core.sql` створює:
+
+### Таблиці
+1. **microdaos** — основна таблиця microDAO
+   - `id`, `external_id`, `slug`, `name`, `description`
+   - `owner_user_id` (FK → users)
+   - `is_active`, `created_at`, `updated_at`
+
+2. **microdao_members** — учасники microDAO
+   - `id`, `microdao_id` (FK), `user_id` (FK)
+   - `role` (owner/admin/member/guest)
+   - `joined_at`
+
+3. **microdao_treasury** — казна microDAO
+   - `id`, `microdao_id` (FK)
+   - `token_symbol`, `balance` (NUMERIC 30,8)
+   - `updated_at`
+
+4. **microdao_settings** — налаштування microDAO
+   - `id`, `microdao_id` (FK)
+   - `key`, `value` (JSONB)
+
+### Індекси
+- `idx_microdao_members_user_id`
+- `idx_microdao_members_microdao_id_role`
+- `idx_microdao_treasury_microdao_id`
+
+### Seed Data
+- Створено microDAO "DAARION Core" з slug `daarion-city`
+- Додано treasury з 1,000,000 DAARION токенів
+- Налаштовано `visibility: public`, `join_mode: request`
+- Прив'язано існуючих агентів до DAARION microDAO
+
+---
+
+## 📡 NATS Events
+
+### Публіковані події
+
+#### microDAO Lifecycle
+- **`microdao.event.created`**
+  ```json
+  {
+    "microdao_id": "uuid",
+    "slug": "daarion-city",
+    "name": "DAARION Core",
+    "owner_user_id": "uuid",
+    "actor_id": "uuid",
+    "ts": "2025-11-24T12:00:00Z"
+  }
+  ```
+
+- **`microdao.event.updated`**
+  ```json
+  {
+    "microdao_id": "uuid",
+    "slug": "daarion-city",
+    "actor_id": "uuid",
+    "changes": {"name": "New Name"},
+    "ts": "2025-11-24T12:00:00Z"
+  }
+  ```
+
+- **`microdao.event.deleted`**
+
+#### Members
+- **`microdao.event.member_added`**
+- **`microdao.event.member_removed`**
+- **`microdao.event.member_role_updated`**
+
+#### Treasury
+- **`microdao.event.treasury_updated`**
+  ```json
+  {
+    "microdao_id": "uuid",
+    "slug": "daarion-city",
+    "token_symbol": "DAARION",
+    "delta": "100.5",
+    "new_balance": "1100.5",
+    "actor_id": "uuid",
+    "ts": "2025-11-24T12:00:00Z"
+  }
+  ```
+
+#### Settings
+- **`microdao.event.settings_updated`**
+- **`microdao.event.setting_deleted`**
+
+---
+
+## 🚀 Як запустити
+
+### 1. Застосувати міграцію
+```bash
+# Вручну (якщо PostgreSQL вже запущений)
+psql -U postgres -d daarion -f migrations/008_create_microdao_core.sql
+```
+
+### 2. Запустити всі сервіси
+```bash
+cd /Users/apple/github-projects/microdao-daarion
+
+# Запустити Phase 7
+docker-compose -f docker-compose.phase7.yml up -d
+
+# Або використати скрипт
+bash scripts/start-phase7.sh
+```
+
+### 3. Перевірити здоров'я сервісів
+```bash
+# MicroDAO Service
+curl http://localhost:7015/health
+
+# Agents Service
+curl http://localhost:7014/health
+
+# Auth Service
+curl http://localhost:7011/health
+
+# PDP Service
+curl http://localhost:7012/health
+```
+
+### 4. Перевірити frontend
+```bash
+cd /Users/apple/github-projects/microdao-daarion
+npm run dev
+
+# Відкрити браузер
+open http://localhost:3000/microdao
+```
+
+---
+
+## ✅ Acceptance Criteria
+
+Всі критерії виконано:
+
+- ✅ `/microdao` повертає список microDAO, де actor є member
+- ✅ `/microdao` (POST) створює новий microDAO і додає owner в members
+- ✅ `/microdao/{slug}` повертає деталі microDAO
+- ✅ `/microdao/{slug}/members` повертає список учасників
+- ✅ `/microdao/{slug}/treasury` повертає список токенів
+- ✅ PDP блокує доступ до чужих microDAO (403)
+- ✅ MicrodaoListPage показує **реальні** microDAO із БД
+- ✅ MicrodaoConsolePage показує **реальні** Overview/Members/Treasury/Agents
+- ✅ Всі NATS події публікуються при змінах
+- ✅ Увесь стек стартує через `docker-compose.phase7.yml` без помилок
+
+---
+
+## 📈 Статистика
+
+### Backend
+- **Файлів створено:** 7
+- **Рядків коду:** ~1,800
+- **Endpoints:** 16
+- **NATS events:** 8
+- **Database tables:** 4
+- **Duration:** ~3 години
+
+### Frontend
+- **Файлів оновлено:** 1 (API client)
+- **Функцій додано:** 7
+- **Сторінки:** 2 (вже існували, використовують реальні дані)
+
+---
+
+## 🔄 Інтеграція з іншими модулями
+
+### ✅ Auth Service (Phase 4.5)
+- Всі endpoints використовують Passkey authentication
+- ActorIdentity передається з auth-service
+
+### ✅ PDP Service (Phase 4)
+- Всі операції перевіряються через PDP
+- Ролі: owner, admin, member, guest
+
+### ✅ Agents Service (Phase 6)
+- MicroDAO Console показує агентів через `/agents?microdao_id=...`
+- Агенти прив'язані до microDAO через `microdao_id`
+
+### ✅ Messaging Service (Phase 1-2)
+- Готово для інтеграції каналів microDAO
+- Placeholder links у MicrodaoConsolePage
+
+### ✅ Usage Engine (Phase 4)
+- Готово для збору метрик використання microDAO
+- Treasury може інтегруватись з usage tracking
+
+---
+
+## 🎯 Наступні кроки
+
+### Phase 8 — DAO Dashboard (Governance)
+- Proposals & Voting
+- Multi-signature operations
+- Role-based permissions
+- Token distribution
+
+### Phase 9 — Living Map
+- City Layer visualization
+- Space Layer для microDAOs
+- Node Layer для агентів
+- Real-time updates через NATS
+
+### Опціональні покращення Phase 7
+- [ ] Webhook notifications для microDAO events
+- [ ] Audit log для всіх операцій
+- [ ] Bulk operations (додавання багатьох членів)
+- [ ] Invitation system з кодами запрошень
+- [ ] Treasury history (transaction log)
+- [ ] Settings validation schemas
+
+---
+
+## 🐛 Known Issues
+
+Немає критичних проблем.
+
+### Мінорні покращення
+- Treasury balance використовує NUMERIC, але frontend показує як number (можливі проблеми з точністю для великих чисел)
+- Member role update робить DELETE + INSERT замість UPDATE (можна оптимізувати)
+
+---
+
+## 📚 Документація
+
+### Створені документи
+- ✅ **PHASE7_BACKEND_COMPLETE.md** (цей файл)
+- ✅ **docs/tasks/TASK_PHASE7_BACKEND_COMPLETION.md** (task specification)
+
+### Оновлені документи
+- ✅ **docker-compose.phase7.yml** (додано NATS для microdao-service)
+- ✅ **src/api/microdao.ts** (додано Settings та Treasury management)
+
+---
+
+## 🎉 Висновок
+
+**Phase 7 Backend Completion успішно завершено!**
+
+MicroDAO Console тепер має:
+- ✅ Production-ready backend з повним CRUD
+- ✅ Безпечний доступ через Auth + PDP
+- ✅ Real-time події через NATS
+- ✅ Повну інтеграцію frontend з backend
+- ✅ Готовність до розширення (Governance, City Layer, тощо)
+
+**Готово до тестування та розгортання! 🚀**
+
+---
+
+**Автор:** AI Assistant (Phase 7 Backend Completion)  
+**Дата:** 24 листопада 2025  
+**Версія:** 1.0.0
+