Исполнительная документация: что передать заказчику

Урок 5 · Введение в протоколы автоматизации · 30 мин · theory

Введение: Роль и ценность исполнительной документации

> 💡 Подсказка: Рассматривайте подготовку документации не как затраты, а как инвестицию. Хорошо документированный проект — ваше лучшее портфолио и защита от необоснованных претензий в будущем.

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

Цели подготовки ИД можно свести к трем ключевым задачам:

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

Упрощение будущего обслуживания и модернизации. Любая система со временем требует обслуживания, диагностики неисправностей или расширения функционала. Без подробной технической документации любая такая задача превращается в сложный и дорогостоящий квест по "реверс-инжинирингу" собственного или чужого проекта. Качественная ИД позволяет любому квалифицированному инженеру (включая вас самих спустя год) быстро разобраться в архитектуре системы. Это основа долгосрочного жизненного цикла проекта.

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

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

Пакет 'As-Built' (Как построено) — это техническая изнанка проекта, предназначенная для инженеров службы эксплуатации, сторонних подрядчиков или для вас самих в будущем. Он содержит исчерпывающую информацию об архитектуре, подключениях, настройках и логике системы.
Пакет 'User Manual' (Руководство пользователя) — это набор инструкций для конечного пользователя (владельца дома, администратора офиса). Он написан простым языком, сфокусирован на пользовательских сценариях и не содержит сложной технической информации.

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

---

Пакет инженера 'As-Built': Техническая изнанка проекта

> ⚠️ Внимание: Никогда не передавайте заказчику исходные файлы проектов (например, `.esf` для ETS или исходники для iRidium) без отдельного пункта в договоре. Как правило, передаются только резервные копии для восстановления и скомпилированные версии.

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

📋 Ключевые понятия: Состав пакета 'As-Built':

### Финальные электрические схемы и схемы подключений

Это не те предварительные чертежи, что были в начале проекта, а скорректированные по факту монтажа схемы. Они должны включать:

* Однолинейную схему главного электрощита с указанием номиналов всех автоматов, УЗО, дифавтоматов.

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

* Актуализированные ASCII-схемы подключений (согласно стандарту `WIRING-XXXX-XXX`), которые мы рассматривали в курсе по протоколам, с точным указанием, какой датчик к какой клемме контроллера подключен.

* Все маркировки на схемах должны совпадать с физическими маркировками на клеммах и проводах в щите.

### Актуализированный кабельный журнал

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

* Маркировка: Уникальный идентификатор кабеля (например, `KL-047`).

* Источник: Откуда кабель идет (например, `ЩА.RL-05`).

* Назначение: Куда кабель приходит (например, `Светильник.Гостиная.Зона1`).

* Тип кабеля: Марка и сечение (например, `ВВГнг(А)-LS 3х1.5`).

* Фактическая длина: Длина, измеренная после прокладки.

### Сетевая карта объекта

В современной системе автоматизации десятки устройств общаются по IP. Сетевая карта объекта — это единая таблица, где сведены все сетевые реквизиты.

* Обязательно используйте статические IP-адреса для всего стационарного оборудования! Это предотвратит хаос после перезагрузки роутера.

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

| Контроллер HI-Core | `CTRL-MAIN` | `DC:A6:32:01:23:45` | `192.168.1.10` | `10` (IoT) | Главный контроллер |

### Карта протоколов

Это ваш "словарь" для общения с системой. Карта протоколов документирует все используемые в проекте адреса, топики и регистры.

* MQTT: Таблица всех топиков, используемых для управления (`/set`) и телеметрии (`/state`).

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

* Modbus: Таблица устройств на шине RS-485 и используемых регистров.

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

### Резервные копии конфигураций

Резервное копирование конфигураций — это страховка на случай сбоя контроллера или человеческой ошибки. Необходимо сохранить и передать заказчику:

* Node-RED: Файлы `flows.json`, `flows_cred.json`, `settings.js`. Обычно они находятся в директории `~/.node-red/`. Это сердце всей логики автоматизации.

# Пример команды для создания архива конфигурации Node-RED tar -czvf nodered_backup_$(date +%F).tar.gz ~/.node-red/flows.json ~/.node-red/flows_cred.json ~/.node-red/settings.js

* Конфигурация контроллера HI-Core (Debian-based): Критически важно сохранить содержимое директории `/etc/`, где хранятся сетевые настройки, конфигурации системных сервисов и т.д. В нашей платформе ключевые конфигурации оборудования (Modbus-устройств, MQTT-каналов) лежат в `/etc/wb-configs.d/`.

# Архивирование ключевых конфигураций контроллера tar -czvf hicore_config_$(date +%F).tar.gz /etc/network/interfaces /etc/wb-configs.d/

* Другие системы: Проекты визуализации (например, скомпилированный проект для iRidium Viewer), конфигурации VoIP-шлюзов, сетевого оборудования.

Весь этот пакет данных формирует полное техническое досье объекта.

---

Пакет пользователя: Руководства для комфортной эксплуатации

> 🔗 Связанный материал: Принципы проектирования интуитивных интерфейсов, которые лягут в основу скриншотов для руководств, мы подробно разбирали в курсе по визуализации `COURSE-04`, модуль 'UX/UI для умного дома' (`COURSE-04-M02`).

Если пакет 'As-Built' написан инженерами для инженеров, то пакет 'User Manual' создается для людей, которые будут жить или работать на объекте. Его главная цель — сделать взаимодействие с умной системой простым, понятным и комфортным. Технический жаргон здесь недопустим.

Структура руководства пользователя

Хорошее руководство должно иметь четкую и логичную структуру, отвечающую на вопросы пользователя в порядке их возникновения.

«Быстрый старт» (Quick Start Guide): Одностраничная памятка с самым необходимым. Как включить/выключить весь свет, как изменить температуру в основной комнате, как запустить сценарий «Я ушел». Это то, что вешают на холодильник.

Описание сценариев автоматизации: Раздел, объясняющий, как работает система.

* Язык изложения: Пишите не про функции, а про выгоды и задачи. Вместо "Система использует датчик освещенности для управления реле RL-07 по алгоритму ПИД-регулирования", напишите "Вечером свет на террасе включится автоматически. Его яркость будет плавно подстраиваться, чтобы создать уютную атмосферу и сэкономить электроэнергию".

* Структура описания: Для каждого сценария («Климат-контроль», «Защита от протечек», «Управление шторами») опишите:

Что он делает?* (Цель).

Как он работает?* (Простое описание логики).

Как им управлять?* (Конкретные шаги в приложении или с помощью выключателей).

«Что делать, если…» (FAQ & Troubleshooting): Самый важный раздел для снижения количества звонков в вашу техподдержку.

...пропал интернет?* (Работают ли локальные выключатели и сценарии).

...нужно перезагрузить главный контроллер?* (Фото щита с подписанным автоматом и пошаговая инструкция: выключить на 10 секунд, затем включить).

...свет не реагирует на выключатель?* (Проверить автомат, проверить, не включен ли режим "Не беспокоить").

...в приложении отображается ошибка?* (Сделать скриншот и отправить в поддержку).

Контакты поддержки: Четко указанные телефон, e-mail и/или мессенджер для связи с вашей компанией. Укажите время работы техподдержки.

Практический пример: Quick Start Guide

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

Быстрый старт: Гостиная

| Действие | Как сделать |

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

| Включить/выключить весь свет | Двойное нажатие на любую клавишу выключателя у входа в гостиную. |

| Изменить яркость основного света | Нажать и удерживать верхнюю правую клавишу выключателя у входа. Яркость будет меняться циклически. |

| Изменить температуру в комнате | 1. Откройте приложение на телефоне или панели в стене.
2. Перейдите в раздел "Гостиная".
3. Используйте слайдер "Температура", чтобы выставить желаемое значение. |

| Сценарий "Кино" | 1. В приложении нажмите кнопку "Сценарии".
2. Выберите "Кино".
(Свет плавно погаснет, шторы закроются, температура установится на 22°C). |

Использование скриншотов из реального интерфейса визуализации (например, iRidium) в этих руководствах многократно повышает их наглядность и понятность для пользователя.

---

Форматы и хранение: Организация доступа к документации

> 💡 Подсказка: Для резервных копий используйте именование файлов с указанием даты, например: `HICORE_backup_2024-10-26.zip`. Это поможет избежать путаницы при восстановлении.

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

Цифровой vs. Бумажный формат

Еще 10-15 лет назад стандартом была толстая папка с распечатанными схемами. Сегодня основной формат — цифровой, но бумажная копия для самых важных документов остается полезной.

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

| Цифровой | Легко копировать, передавать, хранить. Удобный поиск. Не занимает физическое место. Легко обновлять. | Требует устройства для просмотра. Риск потери данных при сбое носителя. Может быть случайно удален. | Основной формат. Использовать облачные сервисы для хранения. |

| Бумажный | Не требует энергии для доступа. Надежен. Удобен для быстрых пометок во время работы в щите. | Сложно обновлять. Занимает место. Со временем изнашивается. Невозможность поиска по тексту. | Вспомогательный формат. Распечатать "Паспорт объекта", Quick Start Guide и однолинейную схему щита. |

Организация облачного хранения документации

Лучшая практика — создать для объекта папку в облачном сервисе (Google Drive, Яндекс.Диск, Dropbox), предоставить заказчику доступ (с правами просмотра) и передать ему права владельца после окончательного расчета.

Рекомендованная структура папок:

[Название Объекта, например, "Коттедж_Иваново"]
├── 01_User_Manuals/
│   ├── Quick_Start_Guide.pdf
│   └── Full_User_Manual.pdf
│
├── 02_As_Built_Documentation/
│   ├── 01_Schematics/
│   │   ├── Electrical_Scheme_Final.pdf
│   │   └── Wiring_ASCII_Schemes.txt
│   ├── 02_Cabel_Journal/
│   │   └── Cabel_Journal_Final.xlsx
│   ├── 03_Network_And_Protocols/
│   │   ├── IP_Map.xlsx
│   │   └── Protocols_Map.xlsx
│   └── 04_Device_Passports/
│       ├── Controller_HI-Core_passport.pdf
│       └── DALI_Gateway_manual.pdf
│
├── 03_Backups/
│   ├── NodeRED_backup_2024-10-26.tar.gz
│   └── HICORE_config_2024-10-26.tar.gz
│
└── Object_Passport.pdf

Практические шаги

Создайте «Паспорт объекта»: Это единый PDF-документ на 1-2 страницы, содержащий самую важную сводную информацию:

* Адрес объекта.

* Ваши контактные данные для поддержки.

* Ссылка на папку в облачном хранилище.

* Основные (не-администраторские!) логины и пароли для пользовательских интерфейсов.

* Дата сдачи объекта.

Разместите QR-код в щите: Распечатайте на самоклеящейся бумаге QR-код, содержащий прямую ссылку на облачную папку с документацией. Наклейте его на внутреннюю сторону дверцы главного электрощита. Любой техник, пришедший на объект, сможет за секунду получить доступ ко всей необходимой информации, просто навёв камеру телефона. Это производит неизгладимое впечатление профессионализма.

---

Итоги: Чек-лист и процедура подписания актов

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

Подготовка и передача исполнительной документации — финальный аккорд проекта, после которого следует формальная процедура сдачи-приемки. Она закрепляет окончание работ и переход ответственности.

Кратко повторим состав двух обязательных пакетов документации:

Инженерный пакет 'As-Built': Схемы, кабельный журнал, сетевая карта, карта протоколов, резервные копии конфигураций. Все это — технический ДНК системы.
Пользовательский пакет 'User Manual': Понятные руководства, Quick Start Guide, раздел "Что делать, если...", контакты поддержки. Все это — ключ к комфортной эксплуатации.

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

Перед тем как вызывать заказчика для подписания документов, убедитесь, что все пункты выполнены:

[ ] Система полностью протестирована согласно ранее составленному тест-плану.

[ ] Все выявленные замечания устранены.

[ ] Пакет документации 'As-Built' полностью укомплектован и загружен в облачное хранилище.

[ ] Пакет документации 'User Manual' укомплектован, распечатан Quick Start Guide.

[ ] QR-код со ссылкой на документацию размещен в электрощите.

[ ] Подготовлен бланк Акта приема-передачи работ.

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

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

Акт приема-передачи — это главный юридический документ, завершающий проект. Его подписание означает, что:

Заказчик подтверждает, что работы выполнены в полном объеме и соответствуют договору.
Система автоматизации передана в эксплуатацию заказчику.
Ответственность за дальнейшую эксплуатацию, включая возможные повреждения оборудования из-за неправильного использования, переходит к заказчику.
Начинается отсчет гарантийного периода на выполненные работы и поставленное оборудование.

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

Что дальше

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