Энергетический цифровой двойник деревни

Проект представляет собой веб-симулятор "цифрового двойника" распределённой энергетической системы небольшой деревни. Он строит процедурно сгенерированную геометрию (в стиле Watabou Village Generator), накладывает на неё автогенерируемую сеть источников, линий и трансформаторов, обеспечивает интерактивный редактор и непрерывную симуляцию нагрузок и потоков с визуальными индикаторами перегрузок, просадок и питания домов.

1. Архитектура

• Стек: чистый клиент на Canvas/SVG, FastAPI на бэкенде, контексты и чистая архитектура.
• Обмен данными: клиент хранит только UI-состояние, получает географические и сетевые снепшоты по HTTP/WS и отправляет команды редактирования; сервер генерирует геометрию, строит сеть, принимает команды, запускает тик-симуляции и пушит обновления WebSocket.
• Контекст power_grid: отдельные доменные сущности (Source, Transformer, Pole, Consumer, Line), доменные сервисы (включая радиальный линейный решатель), use-case-обёртки, инфраструктура (ID, repository для grid → легко заменить), и тонкий API-слой FastAPI.
• Потоки: генерация geo-снепшота по seed/tags → построение сети → симуляционный цикл (SimulateTick + solver → обновление WS) → команды редактирования и мгновенный отклик.
• Транспорт: REST для создания/запроса/симуляции и WebSocket /v1/power-grid/grids/{grid_id}/ws, который пушит обновлённые снепшоты, принимает команды (set_line_status, trigger_fault, clear_faults) и позволяет реализовать live-интерфейс.
• Клиент: Canvas-компонент накладывает узлы/линии из снепшота и предлагает control panel для создания сетей, запуска тиков, генерации аварий, изменения свойств узлов и управление статусами линий через REST/WS.

2. Подходы и принципы

• Чистая архитектура и DDD: домен не знает о FastAPI/WS/JSON/Canvas, use cases — единственная входная точка для изменений, API — thin layer, инфраструктура можно заменить без правок домена.
• Процедурная генерация: геометрия рассматривается как упрощённый GIS-слой; дороги формируют каркас трасс ЛЭП, дома — потребителей.
• Энергосеть как граф: узлы и линии имеют editable props, вычисляемый state и статус; линии и узлы могут быть онлайн/офлайн/аварийными, что формирует основу для будущей физики.
• LinDistFlow и радиальная модель: пока считается только активная мощность, строится радиальное дерево и выполняются backward/forward sweep; в будущих итерациях можно добавить Q, фазы, секционирование и аварийную логику.
• Интерактивный цифровой двойник: редактирование происходит через команды, расчёт состояния — на сервере. Это позволяет избегать рассинхронизации и открывает путь к многопользовательским сценариям.

3. Требования

Функциональные

1. Генерация карты деревни по seed и тегам.
2. Автопостроение сети: HV фидеры вдоль major дорог, LV ветки по minor дорогам, ТП между HV/LV, сервисные линии к домам.
3. Каждый дом имеет базовое потребление, профиль и cosφ.
4. Клиентская интеракция: выделение, редактирование props, добавление/удаление узлов и линий.
5. Управление симуляцией: старт/пауза/шаг, пересчёт потоков/напряжений.
6. Визуальная индикация нагрузки и статуса: цвет/толщина линий, оверлеи по overload_ratio, маркеры питания домов.
7. Live-обновления через WebSocket.

Нефункциональные

1. Расширяемость физики без переписывания UI/API.
2. Детерминированность при фиксированном seed.
3. Стабильная сериализация снепшотов (версионирование).
4. Производительность: 1–2k домов/наблюдаемый цикл в реальном времени.
5. Изолированность контекстов для будущих подсистем (water_supply, telecom и т.д.).

4. Важные напоминания

• Строим каркас twin-системы, а не простую «игру про проводочки»; домен и слоя — страховка будущего.
• Текущая физика упрощённая. Не стоит говорить о ней как о промышленной модели — Q, фазы, секционирование, аварии и оптимация будут добавлены позже, но архитектура уже это допускает.

5. Следующие шаги (в рамках текущей дорожной карты)

1. Ввести секционирование и аварийные статусы линий (online/open/faulted), чтобы solver работал только по online и выявлял острова с island_id.
2. Добавить профили нагрузки (residential/commercial/industrial/nightlife) и cosφ: P вычисляется по профилю и шуму, Q получается из cosφ, а перегрузки считаются по полной мощности S.
3. Обновить интерфейс: рисование открытых/аварийных линий, показ статуса/потоков/island_id, редактирование профиля и cosφ, а также статуса линии.

Эти дополнения приближают поведение к SCADA/Distribution-digital-twin уровню и сохраняют упрощённость MVP-физики.