Формирование пакета исполнительной документации

Урок 3 · Монтаж и пусконаладка контроллера · 10 мин · theory

Секция 1. Введение в исполнительную документацию (ИД)

Исполнительная документация (ИД), также известная как "as-built documentation", представляет собой полный комплект документов, который с максимальной точностью отражает фактическое исполнение проектных решений после завершения всех монтажных и пусконаладочных работ. В отличие от проектной документации, которая описывает, как система должна быть построена, исполнительная документация фиксирует, как она построена в реальности, со всеми изменениями, внесенными в ходе работ.

Роль ИД в жизненном цикле объекта автоматизации невозможно переоценить. Это не просто формальность или набор бумаг для архива, а критически важный инструмент для всех последующих этапов эксплуатации системы.

Важность ИД для эксплуатации и модернизации

Представьте, что вы являетесь инженером службы эксплуатации и через два года после сдачи объекта получаете заявку: "Перестала работать подсветка на кухне". Без исполнительной документации ваши действия превращаются в трудоемкий квест:

Какое реле контроллера управляет этой группой света?
На каком автоматическом выключателе в щите она "сидит"?
К какому входу контроллера подключен настенный выключатель?
Используется ли в сценарии датчик движения и какова его логика?

Поиск ответов на эти вопросы без ИД потребует часов, а возможно, и дней работы, включая вскрытие щита, "прозвонку" кабелей и анализ десятков строк кода в сценариях Node-RED. При наличии качественной ИД, включающей схемы подключений, кабельный журнал и описание сценариев, решение этой проблемы занимает минуты.

Ключевые преимущества наличия ИД:

Техническое обслуживание: Плановые проверки, замена компонентов (датчиков, реле) и диагностика производятся быстро и эффективно.

Поиск неисправностей: Время локализации и устранения неисправности сокращается в разы, что напрямую влияет на стоимость владения системой для заказчика.

Модернизация: При необходимости расширения системы (добавление новых функций, устройств) новый интегратор может быстро разобраться в существующей архитектуре и внести изменения, не нарушая работу старых компонентов.

Передача знаний: Если объект передается на обслуживание другой компании или внутреннему персоналу заказчика, ИД становится основным источником информации о системе.

Юридические и договорные аспекты

С юридической точки зрения, исполнительная документация является неотъемлемой частью результата выполненных работ. В большинстве договоров на создание систем автоматизации есть пункт о передаче полного комплекта ИД как обязательном условии для финальной оплаты и подписания акта приема-передачи.

> ℹ️ Информация: Отсутствие или некомплектность ИД может быть расценено заказчиком (и судом) как неполное исполнение обязательств по договору, что дает ему право задержать оплату или потребовать компенсацию.

Подготовленный пакет ИД — это ваше доказательство того, что работы выполнены в полном объеме и в соответствии с высокими профессиональными стандартами.

Риски и последствия отсутствия ИД

Для инсталлятора:

Репутационные потери: Сдача объекта без документации воспринимается как признак непрофессионализма.
Увеличение нагрузки на техподдержку: Заказчик будет обращаться к вам с каждым элементарным вопросом, который мог бы решить самостоятельно при наличии ИД. Это отнимает ваше время от новых проектов.
Сложности с гарантийным обслуживанием: Без точной картины системы сложно определить, является ли неисправность гарантийным случаем или результатом неправильной эксплуатации.
Юридические и финансовые риски: Удержание финального платежа, судебные иски.

Для заказчика:

"Черный ящик": Система становится непонятной и непредсказуемой. Заказчик полностью зависит от одного инсталлятора.
Высокая стоимость владения: Любое обслуживание или ремонт становятся дороже из-за необходимости проводить "реверс-инжиниринг" системы.
Проблемы при продаже недвижимости: Наличие «умного дома» без документации может не повысить, а наоборот, снизить привлекательность объекта для покупателя, который опасается столкнуться с непредсказуемой и необслуживаемой системой.

Качественно подготовленная исполнительная документация — это инвестиция в долгосрочные отношения с клиентом и в репутацию вашей компании.

---

Секция 2. Структура и состав пакета ИД

Для обеспечения полноты и унификации данных, пакет исполнительной документации должен иметь стандартизированную структуру и состав. Это упрощает навигацию по документам как для вашей команды, так и для службы эксплуатации заказчика.

> 💡 Подсказка: Создайте шаблонную структуру папок для ИД и используйте её на всех объектах. Это позволит стандартизировать процесс, сэкономить время и гарантировать, что ни один важный документ не будет упущен.

Полный перечень обязательных компонентов

Пакет ИД должен включать в себя как цифровые данные о конфигурации системы, так и традиционную проектную документацию, отражающую фактическое состояние.

📋 Ключевые понятия: Состав пакета ИД

01_Резервные_копии:

* Полный бэкап системы контроллера HI: Файл `.tar.gz`, созданный, как было рассмотрено в уроке `COURSE-03-M08-L02`. Это "цифровой слепок" всей системы.

* Экспорт сценариев Node-RED: Файл `flows.json`, содержащий все потоки, субпотоки и узлы конфигурации.

02_Схемы_и_планы:

* Принципиальная электрическая схема щита автоматизации (Э3): Схема, показывающая все внутренние соединения в щите.

Схемы внешних подключений (Э4): Детальные схемы подключения оконечных устройств (датчиков, приводов, светильников) к клеммам контроллера. Как мы изучали в модуле по стандартам схем, они могут быть представлены в формате `WIRING-.`

* План расположения оборудования и прокладки кабельных трасс (Э5): Планы этажей с нанесенными УГО оборудования и линиями кабелей.

03_Журналы_и_таблицы:

* Кабельный журнал (КЖ): Таблица со всеми кабелями на объекте с указанием маркировки, типа, длины, начальной и конечной точек подключения.

* Карта сети (IP-адреса): Таблица со всеми сетевыми устройствами системы (контроллеры, шлюзы, панели), их MAC- и IP-адресами, логинами и паролями.

* Карта шин данных: Таблицы адресов для всех используемых шин (Modbus Slave ID, DALI short addresses, KNX physical addresses).

* Таблица учетных данных: Документ, содержащий все логины и пароли для доступа к системе (SSH, Node-RED, веб-интерфейсы и т.д.). Этот документ должен передаваться под роспись и с соблюдением мер безопасности.

04_Проекты_смежных_систем:

* Файл проекта KNX (`.knxproj`), если используется интеграция.

* Конфигурационные файлы для шлюзов DALI, другого оборудования.

05_Системная_информация:

* Текстовый файл с отчетом о конфигурации контроллера (версия ОС, сетевые настройки, список служб), который мы научимся создавать в следующей секции.

06_Документация_оборудования:

* PDF-файлы с инструкциями (datasheets) на все установленное оборудование (контроллер, датчики, приводы).

07_Акты_и_протоколы:

* Скан-копии подписанных актов скрытых работ (если были).

* Протоколы испытаний и измерений (например, сопротивление изоляции).

* Финальный акт приема-передачи работ.

Форматы хранения данных

Выбор правильного формата для каждого документа обеспечивает его долговечность и доступность.

| Тип документа | Рекомендуемый формат | Примечание |

| ------------------------------ | ----------------------------------------------------- | --------------------------------------------------------------------------- |

| Резервная копия системы | `.tar.gz` | Стандартный архив Linux, сохраняет структуру и права доступа. |

| Сценарии Node-RED | `.json` | Текстовый формат, легко читается и подходит для систем контроля версий. |

| Схемы и планы | `.pdf` (для передачи), `.dwg`/`.vsdx` (исходники) | PDF — универсальный формат для просмотра, исходники нужны для правок. |

| Таблицы и журналы | `.xlsx` (для передачи), `.csv` (для автоматизации) | Excel удобен для чтения, CSV — для импорта в другие системы. |

| Системная информация, скрипты | `.txt`, `.sh` | Простые текстовые форматы, кроссплатформенные и надежные. |

| Учетные данные | `.kdbx` (KeePass), зашифрованный `.txt` или `.pdf` | Никогда не храните пароли в открытом виде! Используйте менеджеры паролей. |

| Документация на оборудование | `.pdf` | Общепринятый стандарт от производителей. |

Создание такого структурированного архива на начальном этапе проекта и его последовательное наполнение в ходе работ — залог быстрой и безболезненной сдачи объекта.

---

Секция 3. Практика: Автоматизация сбора системной информации

Ручной сбор данных о конфигурации контроллера — трудоемкий и чреватый ошибками процесс. Так как контроллер HI работает под управлением ОС Linux (Debian), мы можем использовать всю мощь командной строки для автоматизации этой задачи. Создадим простой bash-скрипт, который соберет ключевую системную информацию и сохранит ее в единый текстовый файл.

Использование команд Linux для сбора информации

Прежде чем писать скрипт, рассмотрим основные команды, которые нам понадобятся. Вы можете выполнить их, подключившись к контроллеру по SSH.

`date`: Показать текущую дату и время (важно для фиксации момента создания отчета).
`uname -a`: Показать информацию о ядре Linux и архитектуре системы.
`cat /etc/os-release`: Показать информацию о версии дистрибутива Debian.
`uptime`: Показать время непрерывной работы системы и среднюю нагрузку (Load Average).
`ip a`: Показать конфигурацию всех сетевых интерфейсов (IP-адреса, MAC-адреса).
`ip r`: Показать таблицу маршрутизации.
`arp -n`: Показать ARP-таблицу (соответствие IP- и MAC-адресов в локальной сети).
`df -h`: Показать использование дискового пространства.
`systemctl status hi-core.service`: Проверить статус основной службы контроллера.

Написание bash-скрипта для сбора данных

Теперь объединим эти команды в один скрипт. Создайте на своем компьютере файл с именем `generate_report.sh`.

#!/bin/bash
#
# Скрипт для автоматического сбора системной информации
# с контроллера HI.
# Версия 1.0
#

# Вывод заголовка и временной метки
echo "=========================================================="
echo "      ОТЧЕТ О КОНФИГУРАЦИИ СИСТЕМЫ КОНТРОЛЛЕРА HI"
echo "=========================================================="
echo "Дата создания отчета: $(date)"
echo ""

# Информация о системе и версии ПО
echo "=== 1. ИНФОРМАЦИЯ О СИСТЕМЕ ==="
echo "--- Версия ядра Linux ---"
uname -a
echo ""
echo "--- Версия дистрибутива ---"
cat /etc/os-release
echo ""

# Время работы и нагрузка
echo "=== 2. ВРЕМЯ РАБОТЫ И НАГРУЗКА (UPTIME) ==="
uptime
echo ""

# Сетевая конфигурация
echo "=== 3. СЕТЕВАЯ КОНФИГУРАЦИЯ ==="
echo "--- Конфигурация интерфейсов (ip a) ---"
ip a
echo ""
echo "--- Таблица маршрутизации (ip r) ---"
ip r
echo ""
echo "--- ARP-таблица (arp -n) ---"
arp -n
echo ""

# Использование диска
echo "=== 4. ИСПОЛЬЗОВАНИЕ ДИСКОВОГО ПРОСТРАНСТВА ==="
df -h
echo ""

# Статус ключевой службы
echo "=== 5. СТАТУС СЛУЖБЫ HI-CORE ==="
systemctl status hi-core.service
echo ""

echo "=========================================================="
echo "               Конец отчета"
echo "=========================================================="

Выполнение скрипта и сохранение отчета

Сохраните скрипт `generate_report.sh` на вашем рабочем компьютере.

Откройте терминал (на Windows можно использовать PowerShell или WSL).

Выполните следующую команду, заменив `user` и `controller_ip` на ваши данные для доступа по SSH:

ssh user@controller_ip 'bash -s' < generate_report.sh > HI-Core_sysinfo_$(date +%Y-%m-%d).txt

Разберем команду:

`ssh user@controller_ip`: Подключается к контроллеру.
`'bash -s'`: Запускает на удаленной машине интерпретатор bash, который будет читать команды со стандартного ввода.
`< generate_report.sh`: Перенаправляет содержимое нашего локального файла `generate_report.sh` на стандартный ввод команды `ssh`, тем самым передавая его для выполнения на контроллер.
`> HI-Core_sysinfo_....txt`: Перенаправляет весь вывод (результат работы скрипта) в новый файл на вашем локальном компьютере. Имя файла будет содержать текущую дату.

В результате у вас появится готовый текстовый файл `HI-Core_sysinfo_2024-11-15.txt`, который можно приложить к пакету ИД.

Мониторинг системной информации через MQTT

Для постоянного мониторинга состояния контроллера можно отправлять избранные системные параметры в MQTT-брокер. Это реализуется в Node-RED.

Пример потока: Узел `Inject` раз в 5 минут запускает узел `Exec`, который выполняет команду, а результат форматируется в JSON и отправляется в MQTT.

Узел `Exec`: Выполняет команду `uptime | awk '{print $10}' | sed 's/,//'`. Эта цепочка извлекает только значение средней нагрузки за 1 минуту.
Узел `Function`: Формирует сообщение по контракту.

// Получаем сырой вывод E.g. "0.15"
let load_avg = parseFloat(msg.payload);

if (!isNaN(load_avg)) {
    // Формируем сообщение по стандартному контракту
    msg.payload = {
        value: load_avg,
        source: "hi-core-main/system/load_avg_1m",
        ts: Date.now()
    };

    // Устанавливаем топик для публикации
    msg.topic = "telemetry/controllers/main/load_average";

    return msg;
}

return null; // Игнорируем, если что-то пошло не так

Узел `mqtt out`: Публикует данные в топик `telemetry/controllers/main/load_average`.

Теперь вы можете подписаться на этот топик в любой системе мониторинга и отслеживать нагрузку на контроллер в реальном времени.

---

Секция 4. Версионирование и хранение документации

Создание пакета ИД — это только половина дела. Не менее важно обеспечить его надежное хранение, контролировать изменения и предоставить удобный доступ для всех уполномоченных лиц.

> ⚠️ Внимание: Никогда не храните единственный экземпляр ИД на локальном компьютере. Риск потери данных из-за сбоя жесткого диска, кражи ноутбука или вирусной атаки слишком высок. Всегда используйте облачное хранилище с функцией резервного копирования.

Важность системы контроля версий

Проект автоматизации — это живой организм. Даже после сдачи объекта могут вноситься изменения: заказчик попросил изменить логику освещения, был заменен вышедший из строя датчик, обновлялась прошивка контроллера. Каждое такое изменение должно быть отражено в ИД.

Версионирование — это практика присвоения уникальных версий файлам или всему пакету документации при внесении изменений. Это позволяет:

Отслеживать историю изменений: кто, когда и что поменял.
Иметь возможность "откатиться" к предыдущей стабильной версии в случае проблем.
Избежать путаницы, когда у разных людей находятся разные версии одного и того же документа.

Для текстовых файлов (скрипты, `flows.json`) идеальным инструментом является система контроля версий Git. Для всего пакета документов используется более простой метод — версионирование имени архива.

Стандарты именования файлов и архивов

Четкая система именования — основа порядка. Рекомендуется следующий формат для финального архива ИД:

`[ИмяПроекта]_[ТипДокументации]_[v<Версия>]_[ГГГГ-ММ-ДД].zip`

Пример: `Коттедж_Николина_Гора_ИД_v1.0_2024-11-15.zip`

`Коттедж_Николина_Гора`: Понятное имя проекта.
`ИД`: Тип документации (Исполнительная Документация).
`v1.0`: Номер версии.

* `v1.0` — первая версия, сдаваемая заказчику.

* `v1.1` — незначительное изменение (например, поправка в схеме).

* `v2.0` — крупное изменение (например, добавлена автоматизация нового этажа).

`2024-11-15`: Дата создания версии.

Такое имя файла само по себе является информативным и позволяет легко сортировать и находить нужную версию.

Надежные методы хранения

Облачные сервисы (Google Drive, Яндекс.Диск, Dropbox):

* Преимущества: Доступ из любой точки мира, автоматическая синхронизация, история версий файлов, возможность совместного доступа.

* Рекомендации:

* Создайте общую папку для всех проектов компании.

* Для каждого объекта создайте отдельную папку.

* Настройте права доступа:

* Инженеры проекта: полный доступ (чтение/запись).

* Менеджер проекта: полный доступ.

* Заказчик/Служба эксплуатации: доступ только на чтение (Share -> View only). Это предотвратит случайное удаление или изменение документов.

Корпоративный NAS (Network-Attached Storage):

* Преимущества: Полный контроль над данными, высокая скорость доступа в локальной сети.

* Недостатки: Требует первоначальных вложений в оборудование и настройки. Необходимо самостоятельно организовывать резервное копирование (например, на другой NAS или в облако).

Передача физической копии

Несмотря на удобство облачных хранилищ, передача заказчику физической копии ИД на брендированном USB-накопителе является хорошим тоном и важным элементом ритуала сдачи объекта.

Накопитель должен содержать финальную, подписанную версию архива ИД.
Это создает у заказчика ощущение завершенности и материальности полученного продукта.
Это также является дополнительной резервной копией, хранящейся непосредственно на объекте.

Организация надежного хранения ИД — это признак зрелости и профессионализма компании-интегратора.

---

Секция 5. Процедура передачи объекта и документации

Финальный этап проекта — это формальная сдача-приемка объекта и передача полного пакета исполнительной документации заказчику или его представителю (эксплуатирующей организации). Этот процесс должен быть четко структурирован и задокументирован.

> 🔗 Связанный материал: Детальная процедура восстановления системы из резервной копии подробно рассмотрена в уроке `COURSE-03-M08-L03`. Обязательно продемонстрируйте этот процесс заказчику на практике, используя созданный вами бэкап.

Пошаговый чек-лист для процедуры сдачи-приемки

Процедура проводится в формате встречи на объекте с участием всех заинтересованных сторон.

[ ] Проверка объемов работ: Совместно с заказчиком пройти по всем помещениям и убедиться, что все запланированные функции реализованы и работают корректно.

[ ] Демонстрация работы системы: Показать работу всех ключевых сценариев автоматизации (климат, освещение, безопасность) с различных интерфейсов управления (настенные панели, мобильное приложение).

[ ] Презентация исполнительной документации:

* Показать структуру папок в облачном хранилище.

* Кратко объяснить назначение каждого основного документа (схемы, бэкап, IP-карта).

* Убедиться, что заказчик получил ссылку для доступа (только на чтение).

[ ] Инструктаж по базовой эксплуатации:

* Объяснить, как пользоваться основными функциями системы.

* Показать, где находится основное оборудование (щит автоматизации) и что означают статус-индикаторы контроллера.

[ ] Демонстрация процедуры восстановления:

* Объяснить важность резервных копий.

* Показать (хотя бы на словах, а лучше на практике, если есть тестовый стенд) процесс восстановления сценариев Node-RED из `.json`-файла и полного восстановления системы из `.tar.gz`-архива. Это вселяет в заказчика уверенность, что система обслуживаема.

[ ] Передача учетных данных: Вручить заказчику запечатанный конверт или файл из менеджера паролей с таблицей учетных данных для доступа к системе. Получить его подпись, подтверждающую получение.

[ ] Передача физической копии ИД: Вручить брендированный USB-накопитель с финальным архивом.

[ ] Подписание акта приема-передачи:

* После того как заказчик убедился в работоспособности системы и получил всю документацию, подписывается Акт приема-передачи выполненных работ.

* Этот документ юридически фиксирует завершение проекта, передачу ответственности за эксплуатацию заказчику и начало гарантийного периода.

Инструктаж для заказчика

Ключ к успешному инструктажу — говорить на языке заказчика, а не инженера. Избегайте узкоспециализированных терминов. Фокусируйтесь на том, что система делает и как этим управлять, а не на том, как она устроена внутри.

Покажите ему, где в ИД найти ответы на самые частые вопросы:

"Вот план, на котором видно, где какой датчик."
"Вот таблица, где написано, какой автомат за какую розетку отвечает."
"Вот инструкция, как перезагрузить контроллер, если что-то зависнет."

Подписание акта приема-передачи

Акт должен содержать как минимум следующую информацию:

Наименования и реквизиты сторон (исполнитель и заказчик).
Ссылка на номер и дату основного договора.
Формулировка вроде: "Исполнитель сдал, а Заказчик принял работы по монтажу и пусконаладке системы автоматизации... Работы выполнены в полном объеме, в установленные сроки и с надлежащим качеством. Претензий по объему и качеству работ Заказчик не имеет."
Важный пункт: "Вместе с результатами работ Исполнитель передал, а Заказчик принял полный комплект исполнительной и эксплуатационной документации согласно приложению №1 к данному Акту."

Подписание этого документа является формальным завершением вашей работы в рамках проекта и переходом к этапу гарантийного сопровождения.

---

Секция 6. Итоги и ключевые выводы

В этом уроке мы детально рассмотрели один из важнейших финальных этапов любого проекта автоматизации — формирование и передачу исполнительной документации. Качественная ИД — это маркер профессионализма и зрелости компании-интегратора.

Исполнительная документация — это не опция, а обязательный элемент профессиональной инсталляции. Она служит фундаментом для эффективной эксплуатации, быстрого поиска неисправностей и будущих модернизаций системы. Отказ от подготовки ИД — это прямой путь к репутационным потерям и созданию проблем как для себя, так и для клиента. Качественная ИД — это ваше конкурентное преимущество и залог долгосрочных отношений с клиентом. Заказчик, получивший понятную и полную документацию, чувствует себя уверенно и с большей вероятностью порекомендует вас другим или обратится снова для расширения системы. Он видит, что получил не "черный ящик", а прозрачный и обслуживаемый продукт. Автоматизация и стандартизация процесса сбора ИД значительно повышает эффективность работы инженера. Использование скриптов для сбора системной информации и шаблонной структуры папок экономит десятки часов рабочего времени в год и минимизирует риск человеческой ошибки.

Давайте еще раз резюмируем состав полного пакета ИД:

Цифровой слепок: Полный бэкап системы и экспорт сценариев.
Визуализация: Электрические схемы, планы расположения.
Систематизация: Кабельные журналы, карты IP-адресов и шин данных.
Безопасность: Защищенная таблица учетных данных.
Контекст: Проекты смежных систем и инструкции на оборудование.
Юридическая основа: Подписанные акты.

Процедура передачи документации, включая демонстрацию работы системы и инструктаж — это финальный аккорд проекта, который закрепляет положительное впечатление о вашей работе.

Что дальше

Вы освоили все ключевые этапы монтажа и пусконаладки контроллера HI, от первого включения до финальной передачи объекта заказчику. Этот модуль завершает курс для инсталляторов. Теперь вы готовы применить полученные знания на практике и перейти к подготовке к сертификационному экзамену уровня Installer (CERT-INSTALLER), который подтвердит вашу квалификацию.