MicroDAO & Agent Consistency Cleanup (Task 037A)¶

Дата: 29 листопада 2025
Статус: Реалізовано (інструменти готові)

Цей документ описує процедуру очистки та вирівнювання даних між агентами, MicroDAO та Citizens Layer.

1. Проблематика¶

У системі накопичилися: * Агенти без привʼязки до MicroDAO (orphans). * Публічні агенти без public_slug або node_id. * MicroDAO без кімнат або без primary кімнати. * Це призводить до некоректного відображення у /citizens, /microdao та /nodes.

2. Інструменти аудиту¶

SQL Аудит (`db/sql/037_microdao_agent_audit.sql`)¶

Цей SQL-файл містить запити для ручної перевірки стану бази даних: * Пошук публічних агентів без membership. * Пошук агентів без node_id. * Пошук MicroDAO без кімнат. * Пошук MicroDAO з дубльованими primary-кімнатами.

Запуск (приклад):

cat db/sql/037_microdao_agent_audit.sql | docker exec -i dagi-postgres psql -U postgres -d daarion

Автоматичний скрипт (`services/city-service/tools/fix_microdao_agent_consistency.py`)¶

Скрипт для автоматичного виправлення типових помилок.

Що він робить: 1. Агенти: * Якщо public_slug відсутній → встановлює public_slug = id. * Логує агентів без node_id та MicroDAO membership. 2. MicroDAO: * Перевіряє наявність кімнат. * Якщо є кімнати, але немає primary → призначає кімнату з найменшим sort_order як primary. * Якщо є кілька primary → залишає одну, інші робить team.

Запуск: 1. Зайти в контейнер city-service (або локально з налаштованим venv). 2. Запустити в режимі Dry Run (тільки логування): bash python tools/fix_microdao_agent_consistency.py 3. Застосувати зміни: bash python tools/fix_microdao_agent_consistency.py --apply

3. Зміни в API (Citizens Layer)¶

Впроваджено суворішу фільтрацію для публічних громадян (/public/citizens): * Агент повинен мати is_public = true. * public_slug не NULL. * node_id не NULL. * Має хоча б одне MicroDAO membership (EXISTS (SELECT 1 FROM microdao_agents ...)).

Це гарантує, що "сміттєві" тестові агенти не потрапляють у публічні списки.

Також API тепер повертає розширену інформацію: * home_microdao_slug, home_microdao_name * primary_city_room (об'єкт з деталями кімнати)

4. Рекомендації для Operations¶

Регулярно запускати audit.sql для моніторингу здоров'я даних.
При створенні нових агентів вручну через SQL — обов'язково додавати їх у microdao_agents та прописувати node_id.
При створенні MicroDAO — обов'язково створювати хоча б одну кімнату і робити її primary.