# 🏛️ Архитектура Жнеца V4: "Магистр" (ТЗ и План Работ)

**Дата:** 02.05.2026
**Автор:** Gemini CLI (на базе глубокого анализа ошибок и логики Аристотеля)
**Цель:** 100% автономный сбор критически важных юридических документов (Информационные сообщения, Обращения, Договоры) с портала ГИС ЖКХ.

## 🔬 Анализ ошибок предыдущих версий
1. **Слепота к фреймам:** ГИС ЖКХ активно использует iframe и подгрузку контента через Angular. Обычные селекторы не срабатывали.
2. **Stale Element Reference:** При возврате из карточки документа назад в список (через кнопку "Назад"), Angular полностью перерисовывает страницу. Сохраненные ранее в памяти скрипта ссылки на документы уничтожались. Скрипт кликал "в пустоту" и падал.
3. **Отсутствие четкой последовательности:** Агент пытался быть "умным" и угадывать состояние, что приводило к хаотичным прыжкам между разделами.
4. **Игнорирование конкретных указаний пользователя:** Неумение распознать кнопку входа (когда куки живы) и неспособность пройти по четко заданным разделам.

## 🏗️ Новая Архитектура: Жесткий Маршрутизатор
Вместо того чтобы "угадывать" состояние страницы, робот будет работать как **Машина Состояний (FSM)** с четким линейным планом.

### Фаза 0: Авторизация и Инициализация
- Открываем `dom.gosuslugi.ru`.
- **Проверка входа:** 
  - Ищем кнопку "Выйти" или ФИО пользователя. Если есть -> Идем к Фазе 1.
  - Ищем кнопку "Личный кабинет" или "Войти". Если есть -> Кликаем, ждем загрузки, проверяем вход.
  - Если ничего не понятно -> Пишем в Телеграм: "Нужен логин руками", ждем 60 секунд.

### Фаза 1: Информационные сообщения (Уведомления)
*Юридически значимые оповещения.*
1. Переход в раздел уведомлений.
2. Ожидание полной загрузки таблицы.
3. Скриншот всего экрана (для фиксации дат).
4. Поиск и скачивание всех прикрепленных файлов (документы, PDF, ZIP).
5. Проверка пагинации -> если есть "Следующая", кликаем, скриншотим, скачиваем.

### Фаза 2: Обращения и ответы на них
*Переписка с госорганами и УК.*
1. Переход в раздел обращений.
2. Скриншот списка.
3. Получение количества обращений на текущей странице.
4. Цикл `for i in range(count)`:
   - Находим список заново (защита от Stale Element).
   - Кликаем на `i`-тое обращение.
   - Скриншот карточки обращения.
   - Поиск и скачивание всех прикрепленных файлов.
   - Возврат назад (клик по "хлебным крошкам" или `page.go_back()`).
   - Ожидание прогрузки списка.
5. Обработка пагинации.

### Фаза 3: Информация о договорах по дому
1. Переход в раздел договоров.
2. Нажатие кнопки "Найти" -> ожидание таблицы.
3. Цикл `for i in range(count)` (Аналогично Фазе 2):
   - Заново ищем все ссылки "Договор...".
   - Кликаем `i`-тую ссылку.
   - Скриншот карточки.
   - Поиск всех кнопок скачивания во всех фреймах.
   - Загрузка в NAS (`gis_archive/contracts/[ИМЯ]/`).
   - Генерация MD-отчета в Obsidian.
   - Возврат назад, ожидание таблицы.

## 🛡️ Модуль Защиты и Отчетности
- **Playwright Persistent Context:** Куки сохраняются.
- **Smart Waiters:** Использование `wait_for_load_state("networkidle")` и случайных пауз (3-7 сек) для имитации человека.
- **Telegram Logging:** Отчет о начале каждой фазы, о скачивании каждого файла, о завершении миссии.