Шаг 5: Подготовка артефактов к сдаче (экспорт flow, документация, видео-демо)
Введение: цели и состав артефактов проекта
На протяжении этого финального модуля мы планомерно создавали комплексный сценарный слой для объекта автоматизации. Мы прошли путь от проектирования графа состояний до реализации конкретных штатных и аварийных сценариев, завершив самотестированием системы. Этот урок посвящен заключительному и критически важному этапу — подготовке и оформлению результатов вашей работы для сдачи.
Цель данного урока — научить вас формировать профессиональный пакет проектных артефактов. Артефакты — это материальные результаты вашей инженерной деятельности, которые позволяют другому специалисту понять, воспроизвести, проверить и в дальнейшем поддерживать разработанное вами решение. В контексте нашего финального проекта, вы должны подготовить три обязательных артефакта:
Важность этого этапа нельзя недооценивать. В реальной коммерческой практике проект никогда не заканчивается просто работающим кодом. Без качественной документации и чистого, понятного экспорта система становится «черным ящиком» — ее невозможно обслуживать, модифицировать или передавать другому инженеру. Потратив время на аккуратную подготовку артефактов, вы не просто выполняете учебное задание, а демонстрируете профессиональную зрелость и уважение к коллегам, которым, возможно, предстоит работать с вашим решением в будущем.
---
Экспорт Flow из Node-RED: стандарты и чистота кода
Основным артефактом вашего проекта является файл формата JSON, содержащий полную конфигурацию ваших потоков (flows). Прежде чем экспортировать проект, необходимо провести его «санитарную очистку», чтобы он был готов к передаче и развертыванию на другом контроллере.
Пошаговая инструкция по экспорту
Экспорт потоков в Node-RED — это стандартизированная процедура.
* Все потоки: Эта опция выбирается по умолчанию и является необходимой для сдачи финального проекта. Она экспортирует все вкладки (flows) вашего проекта в единый файл.
* Текущий поток: Экспортирует только ту вкладку, которая активна в данный момент.
* Выбранные узлы: Экспортирует только предварительно выделенные вами узлы. Удобно для обмена небольшими фрагментами логики.
> 💡 Подсказка: Перед экспортом убедитесь, что все узлы `Debug` деактивированы, а не просто свернуты. Активные узлы Debug, оставленные в проекте, могут создавать избыточную нагрузку на контроллер и затруднять диагностику в будущем. Деактивировать все узлы отладки можно на боковой панели «Информация» -> «Debug».
Очистка потока перед экспортом
Профессионально подготовленный проект не содержит ничего лишнего.
- Удалите неиспользуемые узлы конфигурации. На боковой панели перейдите во вкладку «Конфигурация». Вы увидите список всех конфигурационных узлов (например, MQTT-брокеры, Modbus-клиенты). Если рядом с узлом есть пометка `(0)`, это означает, что он не используется ни в одном из потоков. Смело удаляйте такие узлы.
- Деактивируйте или удалите отладочные узлы. Как уже упоминалось, все узлы `Debug` должны быть деактивированы. В идеале — удалены, если они не являются неотъемлемой частью логики для демонстрации (например, вывод в журнал событий).
- Проверьте комментарии. Убедитесь, что все комментарии актуальны и описывают логику, а не являются временными заметками вроде «потом доделать».
Структура JSON-файла и правила именования
Экспортированный файл — это массив JSON-объектов. Каждый объект описывает один узел, его тип, ID, положение на холсте, конфигурацию и связи (`wires`). Понимание этой структуры полезно для ручного анализа или версионирования проекта.
Пример фрагмента JSON:
[
{
"id": "a1b2c3d4.e5f6g7",
"type": "inject",
"z": "f9e8d7c6.b5a4c3",
"name": "Инициировать состояние 'Дома'",
"props": [
{
"p": "payload"
},
{
"p": "topic",
"vt": "str"
}
],
"repeat": "",
"crontab": "",
"once": false,
"onceDelay": 0.1,
"topic": "system/state/set",
"payload": "{\"state\":\"home\",\"priority\":10}",
"payloadType": "json",
"wires": [
[
"h9g8f7e6.d5c4b3"
]
]
},
{
"id": "h9g8f7e6.d5c4b3",
"type": "debug",
"z": "f9e8d7c6.b5a4c3",
"name": "Лог смены состояния",
"active": false,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "true",
"targetType": "full",
"statusVal": "",
"statusType": "auto",
"wires": []
}
]
В данном примере мы видим узел `inject`, который отправляет команду на смену состояния, и связанный с ним деактивированный (`"active": false`) узел `debug`.
Правило именования файла: Для унификации и простоты проверки, назовите ваш файл по следующему шаблону:`COURSE-07-PROJECT-Фамилия-FLOW.json` (например, `COURSE-07-PROJECT-Иванов-FLOW.json`)
---
Техническая документация: структура и содержание
Техническая документация — это ваш способ общения с инженером, который будет работать с проектом после вас. Документ должен быть ясным, структурированным и самодостаточным. Рекомендуемый формат — PDF.
> 🔗 Связанный материал: Не дублируйте информацию. Вместо детального пересказа графа состояний подробно опишите его в соответствующем разделе и сошлитесь на урок `COURSE-07-M10-L08`, где были разработаны его фундаментальные принципы. Ваша задача — показать, как этот граф был реализован.
Стандартная структура документа
Хороший технический документ имеет четкую и предсказуемую структуру.
* Название курса и модуля: `COURSE-07: Сценарии умного дома`, `Модуль 10: Финальный проект`.
* Название проекта: «Реализация сценарного слоя для объекта “Умный коттедж”».
* Автор: Ваше ФИО.
* Дата сдачи.
* 1-2 абзаца, описывающие общую цель проекта. Какую задачу решает ваша система? Например: «Данный проект реализует централизованную систему управления состояниями и сценариями для умного дома. Система управляет режимами “Дома”, “Никого нет”, “Ночь”, а также обрабатывает аварийные ситуации, такие как протечка воды и превышение концентрации CO2».
* Приведите финальную версию вашего графа состояний, разработанного в `COURSE-07-M10-L08`. Это может быть скриншот или диаграмма.
* Кратко опишите логику приоритетов: как система выбирает активное состояние при одновременном поступлении нескольких запросов.
* Это самая важная часть документации. Представьте каждый сценарий (3+ аварийных, 5+ штатных) в виде структурированной таблицы.
| ID Сценария | Название | Триггер (условие запуска) | Описание логики | Выполняемые действия |
| :-------------- | :---------------------------- | :--------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `SCN-SAFETY-001` | Авария: Протечка воды | Сообщение от датчика протечки с `msg.payload.value == true` | Устанавливает системное состояние "Авария: Протечка" (приоритет 99). Состояние сохраняется до ручного сброса. | 1. Перекрывает вводы воды (реле R8, R9). 2. Отключает розеточные группы на 1 этаже (реле R10). 3. Отправляет PUSH-уведомление. |
| `SCN-AUTO-005` | Режим: Никого нет (Away) | MQTT-команда `system/state/set` с payload `{"state":"away"}` | Переводит систему в состояние "Away". Имитирует присутствие, включая и выключая свет в гостиной (R1) и спальне (R2) в случайные моменты времени. | 1. Отключает все розетки, кроме неотключаемых. 2. Устанавливает климат-контроль в экономный режим. 3. Активирует имитацию. |
| ... | ... | ... | ... | ... |
* Опишите все допущения, которые вы сделали. Например: «Предполагается, что все датчики и исполнительные устройства подключены и исправны. Система не обрабатывает отказ самого контроллера».
* Укажите известные ограничения: «Сценарий имитации присутствия использует псевдослучайный генератор и не гарантирует уникальной последовательности включений каждый день».
* Краткая пошаговая инструкция для другого инженера: «1. Импортируйте файл `COURSE-07-PROJECT-Фамилия-FLOW.json` в Node-RED через меню 'Импорт'. 2. Убедитесь, что настроен MQTT-брокер с адресом `mqtt://localhost:1883`. 3. Нажмите кнопку 'Развернуть' (Deploy). 4. Система инициализируется в состоянии 'Default'. Для запуска отправьте MQTT-сообщение...».
Стиль документа должен быть техническим, точным и безличным. Избегайте жаргона и субъективных оценок. Ваша цель — максимальная ясность для читателя-инженера.
---
Практика комментирования: Function-node и Comment-node
Комментарии в коде — это не признак слабости, а маркер профессионализма. Они помогают понять намерение разработчика, а не только механику кода. В Node-RED есть два основных инструмента для этого: узел `Comment` и комментарии внутри узла `Function`.
Узел `Comment` для высокоуровневых описаний
Узел `Comment` — это, по сути, текстовый блок на холсте. Его главная задача — группировать и описывать логические блоки потока.
- Назначение: Используйте `Comment` для создания "заголовков" для групп узлов. Это помогает быстро сориентироваться в сложном потоке.
- Как использовать:
2. Дважды щелкните по нему и введите текст. Используйте Markdown для форматирования (например, `# Блок обработки состояний`).
3. Разместите узел над группой узлов, которую он описывает. Вы можете объединить узлы в группу (`Ctrl+G`), чтобы они перемещались вместе с комментарием.
Пример: <Текстовое описание: Над группой узлов, реализующих машину состояний (switch, change, function), расположен большой узел Comment с заголовком "# Central State Machine".>Комментарии внутри узлов `Function`
Узел `Function` позволяет писать произвольный JavaScript-код, и здесь комментирование имеет решающее значение.
- Синтаксис:
`/ Многострочный комментарий */`
- Что комментировать:
* Структуру данных: Если функция ожидает на входе или возвращает сложный `msg.payload`, опишите его структуру.
* Взаимодействие с внешним миром: Комментируйте код, который формирует команды для специфического оборудования.
Пример хорошо комментированного узла `Function`
Задача: Валидатор входящей команды на смену состояния. Он проверяет, что команда имеет правильную структуру и что запрашиваемый приоритет не ниже текущего./**
* Валидатор команды на изменение системного состояния.
* Проверяет структуру входящего msg.payload и сравнивает
* приоритет нового состояния с текущим.
*
* @input msg.payload {object} Ожидается объект вида:
* { "state": "away", "priority": 20, "source": "mobile_app" }
*
* @output [0] {msg} Сообщение проходит дальше, если валидация успешна.
* @output [1] {msg} Сообщение с ошибкой, если валидация провалена.
*/
// Получаем текущее состояние и его приоритет из контекста потока.
// Было установлено в предыдущих уроках (см. COURSE-07-M10-L09).
const currentState = flow.get("systemState") || { priority: 0, state: "default" };
const newState = msg.payload;
// 1. Валидация структуры входящего сообщения.
if (!newState || typeof newState.state !== 'string' || typeof newState.priority !== 'number') {
node.error("Неверный формат команды. Отсутствует 'state' или 'priority'.", msg);
node.status({ fill: "red", shape: "dot", text: "Invalid command format" });
return [null, msg]; // Отправляем на выход для ошибок
}
// 2. Валидация приоритета. Новое состояние не может "перебить"
// состояние с более высоким (меньшее число) или равным приоритетом.
// Исключение: команда сброса "reset".
if (newState.state !== 'reset' && newState.priority >= currentState.priority) {
node.warn(`Попытка понизить приоритет с ${currentState.priority} до ${newState.priority}. Игнорируется.`);
node.status({ fill: "yellow", shape: "ring", text: `Ignored: P${newState.priority} >= P${currentState.priority}` });
// Не возвращаем ничего, просто останавливаем поток.
return null;
}
// Если все проверки пройдены, добавляем временную метку
// и передаем сообщение дальше по потоку.
newState.ts = Date.now();
node.status({ fill: "green", shape: "dot", text: `OK: ${newState.state} (P${newState.priority})` });
return [msg, null];
Анти-паттерны (как делать НЕ надо):
- Избыточные комментарии: `i++; // Увеличить i на 1` — Код очевиден, комментарий не несет пользы.
- Неактуальные комментарии: Комментарий описывает старую логику, которую уже изменили. Это хуже, чем отсутствие комментария, так как вводит в заблуждение.
- Комментарии-заглушки: `// TODO: исправить это позже` — в финальном проекте таких комментариев быть не должно.
---
Запись видео-демонстрации: что и как показывать
Видео-демонстрация — это быстрый и эффективный способ доказать, что ваш проект работает так, как заявлено. Она не заменяет документацию, а дополняет ее.
> ⚠️ Внимание: Во время записи демонстрации убедитесь, что в кадр не попадает конфиденциальная информация: пароли, API-ключи, реальные адреса или телефонные номера в настройках узлов или уведомлениях.
Цель и инструменты
Цель: За 3-5 минут показать работу 1-2 аварийных и 2-3 штатных сценариев, демонстрируя реакцию системы. Рекомендованные инструменты для записи экрана:- OBS Studio: Мощный, бесплатный, кроссплатформенный инструмент. Позволяет настроить сцены, источники видео и звука. Идеальный выбор.
- Kazam: Более простой инструмент для Linux, который отлично подходит для быстрой записи всего экрана или его части.
Содержание демонстрации
Придерживайтесь четкого плана, чтобы видео получилось информативным и не затянутым.
* Откройте интерфейс Node-RED. Кратко покажите ваш главный поток.
* Покажите на панели отладки или в узле `status` текущее состояние системы (например, `systemState: "home"`).
* С помощью узла `inject` или MQTT-клиента сымитируйте триггер аварии (например, сигнал от датчика протечки).
* Прокомментируйте голосом: «Сейчас я имитирую протечку воды».
* Покажите результат:
* Изменение системного состояния на «Авария» (видно по `status` или в журнале событий).
* Появление сообщения об ошибке/тревоге в панели отладки.
* (Если возможно) Показать, как изменилось состояние виртуального реле (например, узел `ui_switch` в Node-RED Dashboard).
* Покажите, как вы вручную сбрасываете аварию, возвращая систему в штатный режим.
* Сымитируйте смену состояния, например, на «Ночь».
* Прокомментируйте: «Активирую режим “Ночь”».
* Покажите результат: изменение состояния, отключение «виртуального» света в гостиной и включение ночника.
* Запустите еще один сценарий, показывающий другую логику (например, «Никого нет»).
* Покажите, как система реагирует на новое состояние, отключая лишние потребители.
* Кратко подведите итог: «Таким образом, система корректно обрабатывает как штатные, так и аварийные состояния в соответствии с заданными приоритетами».
Формат: Видео должно быть в формате `.mp4` с разрешением не ниже 720p. Аудио-комментарии желательны, но не обязательны, если действия на экране очевидны. Имя файла: `COURSE-07-PROJECT-Фамилия-VIDEO.mp4`.---
Итоги и финальный чек-лист сдачи проекта
Вы на финишной прямой. Подготовка артефактов — это процесс упаковки вашей интеллектуальной работы в профессиональный, готовый к использованию продукт. Эта процедура полностью отражает реальную практику сдачи проектов в коммерческой эксплуатации, где ценятся не только технические навыки, но и умение документировать и презентовать свою работу.
Резюмируем состав пакета для сдачи:
Финальный чек-лист для самопроверки
Перед отправкой проекта пройдитесь по этому списку, чтобы убедиться, что всё готово.
- [ ] Flow (`.json`):
* [ ] Файл сохранен в форматированном (pretty) виде.
* [ ] Все узлы `Debug` деактивированы или удалены.
* [ ] Удалены все неиспользуемые узлы конфигурации.
* [ ] Ключевые логические блоки и узлы `Function` снабжены адекватными комментариями.
* [ ] Имя файла соответствует стандарту.
- [ ] Документация (`.pdf`):
* [ ] Описание сценариев представлено в виде таблицы.
* [ ] Есть ссылка на урок по разработке графа состояний, а не его полное копирование.
* [ ] Имя файла соответствует стандарту.
- [ ] Видео-демонстрация (`.mp4`):
* [ ] Показана работа как минимум одного аварийного и двух штатных сценариев.
* [ ] Видно изменение системного состояния (в логе или статусе узла).
* [ ] В кадр не попала конфиденциальная информация.
* [ ] Имя файла соответствует стандарту.
Выполнив все пункты этого чеклиста, вы можете быть уверены, что ваш финальный проект соответствует высоким стандартам нашей академии. Успешной сдачи