Журнал действий

Журнал отвечает на вопросы «кто, когда, что делал и чем это кончилось». Что именно поменялось в данных — в Истории правок.

Возможности

• Входы (удачные и неудачные), выходы, смена пароля, действия с пользователями.
• Все запросы на изменение данных: правки сети и карточек, групповые правки, импорт, справочники, журналы, расчёты, сохранение расчётов, выгрузки.
• Выдача ключей для внешних программ, ключей встраивания, подписки вебхуков, вызовы инструментов MCP и запросы к ИИ.
• Для каждой записи — время, пользователь, город, действие, адрес запроса, код ответа, длительность в миллисекундах и IP-адрес.
• Отбор по пользователю, действию, городу и датам, поиск по части адреса, логина, IP или подробностей, «Только ошибки». «В Excel (CSV)» выгружает всё, что попало под отбор.

Как это работает

Что пишется. Сервер записывает запрос после ответа, отдельной задачей — запись в журнал не задерживает работу, а её ошибка не ломает запрос (уходит только в лог приложения). Действие определяется по адресу запроса:

Действие	Что попадает
Вход, Неудачный вход, Выход	вход пишется с логином, без пароля
Смена пароля, Управление пользователями	/auth/password, /admin/users
Правка сети, Отмена / повтор	топология, разрез, разворот, слияние, отмена и повтор
Правка свойств, Групповая правка, Шаблоны карточек	карточки, оборудование, групповые установщики
Импорт, Справочники, Журналы	загрузка файлов, словари, журналы ТУ, ПТС, нарядов и отключений
Расчёт, Сохранение расчёта	запуск расчёта, удаление расчёта, направления пьезометра
Выгрузка	Excel, Word, скачивание файлов — в том числе запросом GET
Изменение данных, Прочее действие	остальные PUT, PATCH, DELETE и POST
Запрос к ИИ	вызовы помощника с числом токенов
ИИ-клиент (MCP), Токен ИИ-клиента, Ключ API v2, Ключ ArcGIS	вызовы инструментов MCP и выдача ключей — со сроком и подробностями
Ключ встраивания выдан / отозван, Вебхук создан / изменён / удалён, Новый секрет вебхука, Повтор доставки вебхука	настройка интеграций администратором
Соцобъекты из потребителей, из файла, из OSM; Правка соцобъекта; Удаление соцобъектов	слой социальных объектов

Не пишутся: чтение (GET, кроме выгрузок), проверки входа и /auth/me, присутствие на живой карте, предпросмотры (dry_run), калькуляторы и анализ без записи, разбор файла перед импортом, выборка по условиям, показания шлюза SCADA.

В адресе запроса значения параметров token, access_token, password, key заменяются на ***.

Где хранится. Таблица activity_log базы пользователей (UsersDB) — одна на все города; в столбце «Город» — город запроса. Список «Город» появляется в окне, если в журнале больше одного города.

«Только ошибки» — записи с кодом ответа 400 и выше: отказ в праве (403), неверные данные (422), конфликт (409), сбой сервера (500).

Сколько хранится. Раз в сутки сервер удаляет записи старше ACTIVITY_LOG_DAYS дней (по умолчанию 730, не меньше 30).

Выгрузка. Файл журнал-действий-ГГГГ-ММ-ДД.csv в UTF-8 с BOM, разделитель «;» — открывается в Excel двойным щелчком. Столбцы: Время, Пользователь, Город, Действие, Метод, Адрес, Статус, мс, IP, Подробности. В файл попадает не больше 50 000 строк, новые первыми; об обрезке файл не сообщает — сужайте отбор по датам. Ячейка, которая начинается с =, +, - или @ (например, набранный при неудачном входе «логин» =HYPERLINK(…)), выгружается с апострофом впереди — Excel покажет её текстом и не выполнит как формулу.

Одна строка на действие. Выдачу ключей, вызовы MCP, настройку вебхуков, ключей встраивания и социальных объектов разделы пишут сами — с подробностями (срок ключа, инструмент, число объектов); общей строки «Прочее действие» к ним нет. Проверка вебхука («Проверить») пишется общей строкой «Прочее действие».

Что нужно для работы

• Права: «Просмотр журнала действий» (audit_view). Оно есть у роли «Администратор»; другой роли его можно выдать в «Правах» пользователя.
• База: таблица activity_log в UsersDB. Нет таблицы — «Журнал действий недоступен (нет таблицы activity_log в UsersDB?)».
• Сервер: ACTIVITY_LOG_ENABLED не выключен (по умолчанию true).

Шаги

1. Откройте «Инструменты» и наберите в поиске «Журнал действий» — пункт выделен рамкой.

   

2. Нажмите пункт — откроется окно.

   

3. «Только ошибки» оставляет запросы, которые закончились ошибкой (статус 4xx/5xx), — так ищут, у кого и что не получилось. Отбор по пользователю (логин из списка), действию, городу, датам и поиск по части логина, адреса или IP работают вместе; «В Excel (CSV)» выгружает отобранное — до 50 000 строк.

   

Примеры

Сколько ошибок. На стенде с копией Алматы (almatygid_copy) в журнале 1 837 записей, из них 159 — с ошибкой. Чаще всего: 422 у прочих действий (31) и у журналов (31) — сервер отклонил неверные данные формы; 409 у отмены (11) — отменять было нечего или объект уже изменили.

У кого не получилось войти. Действие «Неудачный вход», даты — за неделю. В столбце «Пользователь» — логин, который набрали при входе (он может быть и несуществующим), в IP — откуда пытались.

Если не получается

• Журнал пуст при отборе по пользователю — выбирайте логин из списка: отбор по пользователю ищет точное совпадение; поиск по части логина — в поле поиска.

Для администратора

• В журнале лежат логины и IP-адреса — это персональные данные. Журнал открыт только с правом «Просмотр журнала действий»; маскирование персональных данных (право pii_view) к журналу не применяется.
• Журнал общий для всех городов. Пользователь, которому открыты не все города (список городов в его карточке), видит только записи своих городов — и в списке, и в выгрузке; записи без города ему не показываются.
• Подробности (details) пишут сами разделы: выдача ключей — срок, вызовы ИИ — модель и токены, вызовы MCP — инструмент.
• Переменные: ACTIVITY_LOG_ENABLED (true), ACTIVITY_LOG_DAYS (730). IP за nginx берётся из X-Real-IP или первого адреса X-Forwarded-For.

Для разработчика

• Запись: activity.py — ActivityMiddleware (чистый ASGI), classify (правила _RULES, исключения _SKIP, _READONLY_POST, _SELF_LOGGED — адреса, которые пишут сами роутеры), ACTION_LABELS, явная запись activity.write (вход, ключи, MCP, ИИ, встраивание, вебхуки, социальные объекты). Новый код действия без подписи ловит тест test_every_written_action_has_label.
• Чтение: GET /api/v1/activity-log (username, action, city, date_from, date_to, q, failed, page, page_size до 500), GET /api/v1/activity-log.csv — routers/activity_log.py.
• Веб: components/ActivityLogDialog.vue.
• Тесты: tests/test_activity.py, tests/test_activity_log_scope.py (города, CSV); e2e — e2e/functions/admin.spec.ts.