6.04. ПЗ по ГОСТ 19.404-79

В РАЗРАБОТКЕНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНО

Руководителю Аналитику Техническому писателю

Пояснительная записка (ГОСТ 19.404–79)

ГОСТ

Основано на ГОСТ 19.404–79.

1. Введение: ГОСТ 19.404–79 в контексте современной документации

ГОСТ 19.404–79 — советский стандарт, утверждённый 11 декабря 1979 г. (введён с 01.01.1981), входящий в Единую систему программной документации (ЕСПД). Стандарт регламентирует содержание и оформление пояснительной записки (ПЗ) как программного документа, формируемого на стадиях эскизного проекта и технического проекта ПО.

⚠️ Примечание:
В современной практике (2020‑е) ПЗ не является обязательным в большинстве коммерческих IT‑проектов (Agile, DevOps), но сохраняет актуальность:

при работе с государственными заказчиками или наследуемыми регламентами (ГОСТ 19, 34);

при подготовке экспертиз, сертификаций, госконтрактов;

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

1.1 Назначение документа

Пояснительная записка выполняет аналитико-обосновывающую функцию:

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

В отличие от технического задания (ГОСТ 19.201), ПЗ не предписывает что должно быть сделано, а объясняет почему и как выбрано конкретное решение.

1.2 Область применения

Стандарт применяется только к стадиям:

Стадия	Наименование документа в ЕСПД	Примечание
Эскизный проект	Пояснительная записка	ГОСТ 19.404–79, п. 1
Технический проект	Пояснительная записка	То же
Рабочая документация	не применяется	На этой стадии ПЗ заменяется техническим описанием (ГОСТ 19.502) и программой и методикой испытаний (ГОСТ 19.503)

🔍 Уточнение по терминологии ЕСПД (ГОСТ 19.101–77)

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

Тема разработки — условное обозначение проекта (например, «01.ТП.2025-Интегратор»).

Документ — единица документации, имеющая самостоятельное значение (в т.ч. ПЗ).

1.3 Общая структура пояснительной записки (по ГОСТ)

ГОСТ 19.404–79 предписывает пять обязательных разделов, при этом допускает:

объединение разделов/подразделов,
добавление новых подразделов,
исключение аннотации и содержания (п. 1.1).

№	Раздел	Обязательность	Комментарий
1	Введение	✅	Наименование программы, основание для разработки
2	Назначение и область применения	✅	Краткая функциональная характеристика
3	Технические характеристики	✅	Самый объёмный, 4 обязательных подраздела
4	Ожидаемые технико‑экономические показатели	✅	Обоснование выбора решения
5	Источники, использованные при разработке	✅	Перечень литературы/НТД с ссылками в тексте
—	Приложения	⚪ Опционально	Таблицы, расчёты, методики, схемы

📌 Формальное оформление регулируется ГОСТ 19.105–78 (титульный лист, лист утверждения, шрифт, поля, нумерация и т.п.). Для учебных и open‑source проектов можно использовать упрощённую структуру, но логика разделов остаётся той же.

2. Пошаговое руководство по составлению пояснительной записки

Ниже изложена процедура подготовки ПЗ в виде последовательных шагов. Каждый шаг — отдельный раздел или подраздел документа. Для удобства ориентира приводятся:

обязательность (по ГОСТ),
минимальный содержательный объём,
связь с другими документами ЕСПД,
типичные формулировки и запрещённые приёмы.

⚠️ Важно: В современном техническом письме следует избегать:

пассивных конструкций без указания субъекта («было решено…» → «разработчик принял решение…»);

общих фраз без обоснования («выбран наиболее эффективный алгоритм» → «выбран алгоритм X, обеспечивающий O(n log n) при среднем объёме данных 10⁶, что на 40 % быстрее метода Y в тестах на наборе Z»);

ссылок на «общепринятую практику» без конкретики.

Шаг 1. Введение

Требование ГОСТ 19.404–79, п. 2.1
Обязательность: ✅

Что включать:

Элемент	Пример формулировки	Комментарий
Наименование программы	«Система интеллектуального маршрутизатора событий `EventFlow-X`»	Может совпадать с названием из технического задания (ГОСТ 19.201, п. 3.2)
Условное обозначение темы разработки	«Тема 04.ТП.2025-EventFlow»	Обычно формируется по внутреннему регламенту организации
Документ — основание для разработки	«Техническое задание ТЗ-04-2025, утверждено ООО „Алгоритмика“, 15.03.2025»	Должна быть конкретная ссылка (реквизиты, дата, утверждающая сторона)

Как оформлять:

Не более 150–200 слов.
Не дублировать введение из технического задания — акцент на факте начала разработки, а не на постановке задачи.
Если разработка ведётся по государственному контракту, указать номер и дату контракта.

Шаг 2. Назначение и область применения

Требование ГОСТ 19.404–79, п. 2.2
Обязательность: ✅

Что включать:

Подпункт	Описание	Пример содержания
Назначение	Что делает программа (не как, а зачем)	«Обеспечивает фильтрацию, маршрутизацию и агрегацию событий из распределённых источников (логи, метрики, трейсы) в единую шину данных с гарантией доставки уровня at-least-once»
Область применения	Где и при каких условиях может использоваться	«Предназначена для эксплуатации в инфраструктуре мониторинга DevOps‑платформ с объёмом входящих событий до 50 000 msg/s на один узел; совместима с Kafka `≥`3.4, Prometheus `≥`2.45, OpenTelemetry Collector `≥`0.85»

Шаг 3. Технические характеристики

Требование ГОСТ 19.404–79, п. 2.3
Обязательность: ✅ (с 4 подразделами)

Это ядро ПЗ. Ниже — подробно по каждому подразделу.

3.1 Постановка задачи, математические методы, допущения и ограничения

Элемент	Требования	Пример наполнения
Постановка задачи	Кратко: что требуется решить, какие входные/выходные объекты	«Требуется реализовать модуль дедупликации событий по составному ключу (source_id, timestamp, hash(payload)) с окном 15 мин и tolerancе `±`2 с»
Математические методы	Название метода, его свойства, обоснование выбора	«Применён алгоритм Count-Min Sketch с параметрами `ε=0.001`, `δ=0.01` (мат. ожидание ошибки `<`0.1 % при `10⁹` уникальных ключей). Выбор обоснован компромиссом между памятью (`≤`256 МБ) и точностью»
Допущения и ограничения	Что принимается как данность и что лежит за пределами решения	«Предполагается: (1) синхронизация часов источников через NTP с drift `≤`50 мс; (2) отсутствие malicious traffic; (3) размер payload `≤`64 КБ»

📌 Совет технического писателя:
Если математика присутствует — обязательно укажите источник: название статьи/книги, автор, год, стр. (для перечисления в разделе 5). Не пишите «по известной методике».

3.2 Описание алгоритма и функционирования

Элемент	Требования	Как оформлять
Структурная схема/блок-схема	Обязательна, если алгоритм сложнее линейного	В приложении; в основном тексте — ссылка: см. Приложение А, рис. 1
Описание логики	По шагам, с указанием условий, циклов, параллелизма	«1. При поступлении события вычисляется ключ K = SHA256(source_id ‖ timestamp_rounded)…»
Обоснование выбора схемы	Сравнение с альтернативами (таблица рекомендуется)	См. ниже — пример сравнения в «Типичных ошибках»
Интеграция с другими программами	Имена, протоколы, форматы, точки взаимодействия	«Интеграция с ELMA365 через REST API v3 (POST /api/v3/events) с OAuth2, Bearer-токеном, время жизни 1 ч»

3.3 Организация входных и выходных данных

Подпункт	Что указывать
Форматы	JSON Schema, Avro IDL, XSD (привести ссылку на спецификацию или приложение)
Типы данных	Точные типы (int64, UTF-8, ISO 8601), кодировки
Объёмы и частоты	Например: «Входной поток — до 20 000 msg/s, средний размер сообщения — 1.2 КБ; буферизация — 30 с в памяти, затем сброс в Kafka»
Обоснование	Почему выбран именно этот формат/метод: «JSON выбран из-за: (1) поддержки в 100 % клиентских библиотек, (2) читаемости для отладки, (3) совместимости с OpenTelemetry»

📌 Приведите фрагмент формата в блоке кода, например:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "EventFlow-X Ingestion Format",
  "type": "object",
  "required": ["id", "source", "timestamp", "payload"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "source": { "type": "string", "maxLength": 64 },
    "timestamp": { "type": "string", "format": "date-time" },
    "payload": { "type": "object" }
  }
}

3.4 Выбор технических и программных средств

Элемент	Обязательные сведения
Аппаратные требования	CPU (ядра, модель), RAM, дисковая подсистема (SSD/NVMe, IOPS), сеть (GbE+) — с расчётами
Программное обеспечение	ОС (версия, ядро), runtime (JRE 17+, .NET 8, Python 3.11+), зависимости (версии, licensing)
Обоснование	Почему — с цифрами: «Выбран Ubuntu 22.04 LTS: (1) стабильно поддерживается до 2027 г., (2) наличие kernel `≥`5.15 для eBPF-фильтрации, (3) 89 % парка заказчика на этой ОС»
Распределение носителей данных	Где хранятся какие данные: «Журналы событий — на отдельном NVMe RAID-1 (512 ГБ), конфигурации — в etcd кластере (3 ноды), кэш — в Redis (RAM-only, maxmemory 4 ГБ)»

🔍 Критерий качества ПЗ:
Читатель должен, не обращаясь к другим документам, воспроизвести окружение и понять, почему оно таково.

Шаг 4. Ожидаемые технико-экономические показатели

Требование ГОСТ 19.404–79, п. 2.4
Обязательность: ✅

Что включать:

Показатель	Пример данных	Формат представления
Производительность	«Пропускная способность — 45 000 msg/s на 1 узел (CPU 8C/16T, 32 ГБ RAM)»	Таблица + график (в приложении)
Надёжность	«MTBF ≥ 2000 ч, аварийный сброс состояния — `≤`5 с»	С расчётом на основе отказов компонентов
Экономический эффект	«Снижение TCO на 35 % против аналога на Apache NiFi: (1) снижение CPU-нагрузки на 60 %, (2) уменьшение числа узлов с 6 до 2»	Сравнительная таблица
Риски и митигации	«Риск: перегрузка сети при пике. Митигация: backpressure + adaptive batching»	Кратко, но конкретно

⚠️ Типичная ошибка:
Указание «повышение эффективности» без измеримых величин.
✅ Правильно: «среднее время обработки события сокращено с 12.8 мс (NiFi) до 4.2 мс (EventFlow-X) в условиях нагрузки 25 000 msg/s».

Шаг 5. Источники, использованные при разработке

Требование ГОСТ 19.404–79, п. 2.5
Обязательность: ✅

Правила оформления:

Только те источники, на которые есть прямая ссылка в тексте (например, «[3, с. 45]»).
Единую нумерацию по порядку упоминания.
Формат по ГОСТ 7.0.5–2008 (библиографическая ссылка):

Cormen T.H., Leiserson C.E., Rivest R.L., Stein C. Introduction to Algorithms. — 3rd ed. — MIT Press, 2009. — 1312 p.  
Kafka Improvement Proposal (KIP-219): “Immutable Metadata in ZooKeeper” // Apache Software Foundation. — 2018. — URL: https://cwiki.apache.org/confluence/display/KAFKA/KIP-219 (дата обращения: 2025-10-15).  
ГОСТ 19.701-90. Схемы алгоритмов, программ, данных и систем. Условные обозначения. — Введ. 1992-01-01.

📌 Если используется open-source компонент — указать:

название, версия,

лицензия (MIT, Apache 2.0, GPL-3 и т.п.),

источник (GitHub URL, релиз).

3. Типичные ошибки и как их избежать

(Особенно полезно при обучении студентов и junior-техписателей)

№	Ошибка	Последствия	Как избежать
1	Отсутствие обоснования выбора — «выбран Kafka, потому что он популярный»	Невозможно провести аудит решений, риски остаются неоценёнными	Всегда формулировать: альтернативы → критерии → результат сравнения → выбор. Таблица обязательна при `≥`2 вариантах.
2	Смешение ПЗ с техническим заданием — описание требований вместо объяснения решений	Документ теряет аналитическую ценность, дублирует ТЗ	ПЗ = «почему мы так сделали», ТЗ = «что нам нужно». Проверка: если можно заменить «мы» на «заказчик», это ТЗ.
3	Неполнота по подразделам 3.1–3.4 — пропущен один из четырёх	Нарушение ГОСТ, возможна отклонка при госэкспертизе	Использовать чек-лист (см. в конце) — проверять каждый подраздел отдельно.
4	Ссылки без выходных данных — «см. документацию Kafka»	Невоспроизводимость, устаревание ссылок	Указывать версию, URL, дату обращения, страницу.
5	Отсутствие расчётов — «памяти достаточно»	Оценка рисков невозможна	Приводить формулы или ссылки на них: `Q = λ × L` (Литтл), где `λ = 10⁴ msg/s`, `L = 0.003 с → Q = 30` сообщений в очереди*.
6	Неадекватные приложения — блок-схема без легенды, JSON без схемы	Снижается юзабилити документа	Каждое приложение должно иметь: номер, название, пояснение в тексте, соответствие формату (UML, BPMN, JSON Schema и т.п.).

Пример: Пояснительная записка к программе `EventFlow-X`

Тема разработки: 04.ТП.2025-EventFlow
Основание: Техническое задание ТЗ-04-2025, утверждено ООО „Алгоритмика“, 15.03.2025.

1. Введение

Разработка программы EventFlow-X ведётся в рамках темы 04.ТП.2025-EventFlow на основании технического задания ТЗ-04-2025, утверждённого ООО „Алгоритмика“ 15.03.2025. Программа предназначена для обработки, фильтрации и маршрутизации потоковых событий в распределённой телеметрической системе.

2. Назначение и область применения

Назначение:
Программа EventFlow-X обеспечивает:

приём событий по протоколам HTTP/JSON, gRPC/Protobuf, Kafka (binary);
дедупликацию по составному ключу в скользящем окне 15 мин;
маршрутизацию в зависимости от правила (на основе JMESPath);
агрегацию по временным окнам (Tumbling, Sliding);
гарантию доставки уровня at-least-once.

Область применения:
Программа эксплуатируется в составе DevOps‑платформы заказчика для обработки:

логов приложений (до 30 000 msg/s),
метрик Prometheus (до 10 000 msg/s),
трейсов OpenTelemetry (до 5 000 msg/s).

Требования к окружению:

Linux (Ubuntu 22.04+ или RHEL 9+);
поддержка cgroups v2 и eBPF (для ограничения ресурсов и мониторинга);
доступ к Kafka ≥3.4 (bootstrap‑серверы), Redis ≥7.0 (для state store).

3. Технические характеристики

3.1 Постановка задачи, математические методы, допущения и ограничения

Постановка задачи:
Требуется реализовать модуль потоковой обработки событий S1-DEDUP, обеспечивающий устранение дубликатов с максимальной скоростью обработки ≥40 000 msg/s при заданной конфигурации железа (8 ядер, 32 ГБ RAM). Входной ключ дедупликации: N где ts_rounded = floor(timestamp / 1000) * 1000 (округление до секунды), а допуск по времени — ±2 с.

Математический метод:
Для компактного представления множества ключей применён алгоритм Count-Min Sketch (CMS) [1, с. 278] с параметрами:

ошибка по частоте: N,
вероятность ошибки: N,
число хеш-функций: N,
ширина таблицы: N,
объём памяти: N.

При прогнозируемом объёме уникальных ключей ≤10⁷ вероятность ложноположительного срабатывания ≤0.1 %.

Допущения и ограничения:

Разница во времени между источниками не превышает ±2 с после синхронизации NTP.
Размер payload ≤64 КБ — ограничение обработчика gRPC.
Атаки типа replay не рассматриваются — предполагается предфильтрация на edge-нодах.
Частота событий от одного источника не превышает 5 000 msg/s (иначе — throttling).

3.2 Описание алгоритма и функционирования

Общая схема обработки:

Приём события → валидация формата → парсинг.
Вычисление ключа K.
Запрос в state store (Redis, pipeline ≥100 ops).
Если K отсутствует — запись в CMS + отправка в output pipeline; иначе — отбрасывание.
Асинхронная отправка подтверждения источнику (ACK/NACK).

Интеграция с другими программами:

Компонент	Протокол	Точка взаимодействия	Версия API
Kafka (вход)	Kafka Binary Protocol	`bootstrap.servers: kafka-prod:9092`	≥3.4
Redis (state store)	RESP3	`redis-cluster:6380`	`≥`7.0
ELMA365 (alerting)	REST/HTTPS	`POST /api/v3/alerts`	OAuth2, scope `alerts:write`
Отладочный UI	WebSocket	`/ws/debug`	внутренний API

Обоснование выбора схемы:
Сравнение методов дедупликации:

Метод	Память (на 10⁷ ключей)	Latency (μs)	Гарантии	Поддержка distributed
БД (PostgreSQL `UNIQUE`)	~2.1 ГБ	850 ±120	Строгая	Требуется шардирование
Bloom Filter	12 МБ	3.1 ±0.4	Ложноположительные	Нет state sync
Count-Min Sketch	54 КБ	2.8 ±0.3	Ложноотрицательных нет	Поддерживается (Redis + hash ring)

Выбран CMS как оптимальный по соотношению память/производительность/расширяемость.

📎 См. Приложение А: блок-схема модуля S1-DEDUP (рис. 1).

3.3 Организация входных и выходных данных

Входные данные — события в формате:

{
  "id": "uuid",
  "source": "string(≤64)",
  "timestamp": "string(ISO 8601)",
  "payload": { /* arbitrary JSON ≤64 KB */ }
}

Полная спецификация — в event.schema.json (см. Приложение Б).

Выходные данные — маршрутизированные события + метрики:

Поток	Формат	Назначение
`events.primary`	JSON (см. выше + поле `"route":"primary"`)	Kafka topic `events-primary`
`events.archive`	Avro (schema `v2.Event`)	S3 bucket `/archive/year=2025/month=11/`
`metrics.system`	Prometheus exposition format	Экспорт `:9090/metrics` (`event_dropped_total`, `dedup_hit_ratio`)

Обоснование форматов:

JSON — для отладки, совместимости с legacy-потребителями;
Avro — для архива: схема evolve‑безопасна, ~40 % экономии места против JSON;
Prometheus — стандарт де-факто для мониторинга в Kubernetes.

3.4 Выбор технических и программных средств

Категория	Выбор	Обоснование
ОС	Ubuntu 22.04.5 LTS (kernel 5.15.0-101)	Поддержка eBPF + LTS до 2027 г.; 89 % парка заказчика.
Runtime	.NET 8 (LTS), self-contained	JIT + AOT для критичных модулей; GC Latency Mode `SustainedLowLatency`; сравнительные тесты: +22 % throughput против Java 17 [2].
State Store	Redis 7.2 (Cluster Mode, 3 master + 3 replica)	Поддержка `PFADD` (HyperLogLog), `BITFIELD`, нативные pipeline/transactions; latency p99 `<` 0.5 мс в локальной сети.
Диски	NVMe SSD RAID-1 (512 ГБ, 50 000 IOPS)	Минимизация latency для журналирования; расчёт: при 40 000 msg/s × 1.2 КБ ≈ 48 МБ/с → запас 10×.
Сеть	10 GbE + flow control	Гарантия отсутствия потерь при пике 60 000 msg/s.

Распределение носителей данных:

Данные	Носитель	Объём (на узел)	Режим доступа
Входные буферы	RAM (managed heap)	`≤4 ГБ	Чтение/запись
State store (CMS)	RAM (Redis)	`≤`256 МБ	Чтение/запись
Журналы (debug)	NVMe (ext4, noatime)	64 ГБ (rolling 7 days)	Запись append-only
Конфигурации	etcd (3-нодовый кластер)	`<`1 МБ	Чтение (редко — запись)

4. Ожидаемые технико-экономические показатели

Показатель	Значение	Метод расчёта
Пропускная способность	45 200 msg/s (p50), 39 800 msg/s (p99)	Нагрузочное тестирование (k6, 10 мин, 8 нод)
Среднее время обработки	3.4 мс/msg	Замер на CPU Intel Xeon E-2388G
Память (peak RSS)	5.8 ГБ	`dotnet-counters`
MTBF	`≥`2200 ч	Расчёт по компонентам: MTBF_Kafka=5000 ч, MTBF_Redis=4000 ч, MTBF_Node=10000 ч → по формуле последовательной надёжности
Экономия TCO (за 3 года)	1 420 000 ₽	Сравнение с Apache NiFi: 6 узлов → 2 узла, экономия железа, лицензий, эксплуатации

Риски и меры митигации:

Риск	Вероятность	Воздействие	Мера
Перегрузка Redis	Средняя	Потеря событий	Adaptive backpressure + fallback на локальный `MemoryCache`
Утечка памяти в .NET GC	Низкая	Остановка узла	Мониторинг GC pauses >100 мс + автоматический restart
Несовместимость с Kafka 4.0+	Низкая	Останов интеграции	CI/CD — nightly-тесты против всех поддерживаемых версий Kafka

Пояснительная записка (ГОСТ 19.404–79)

1. Введение: ГОСТ 19.404–79 в контексте современной документации​

1.1 Назначение документа​

1.2 Область применения​

1.3 Общая структура пояснительной записки (по ГОСТ)​

2. Пошаговое руководство по составлению пояснительной записки​

Шаг 1. Введение​

Что включать:​

Как оформлять:​

Шаг 2. Назначение и область применения​

Что включать:​

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

Шаг 3. Технические характеристики​

3.1 Постановка задачи, математические методы, допущения и ограничения​

3.2 Описание алгоритма и функционирования​

3.3 Организация входных и выходных данных​

3.4 Выбор технических и программных средств​

Шаг 4. Ожидаемые технико-экономические показатели​

Что включать:​

Шаг 5. Источники, использованные при разработке​

Правила оформления:​

3. Типичные ошибки и как их избежать​

Пример: Пояснительная записка к программе EventFlow-X​

1. Введение​

2. Назначение и область применения​

3. Технические характеристики​

3.1 Постановка задачи, математические методы, допущения и ограничения​

3.2 Описание алгоритма и функционирования​

3.3 Организация входных и выходных данных​

3.4 Выбор технических и программных средств​

4. Ожидаемые технико-экономические показатели​

1. Введение: ГОСТ 19.404–79 в контексте современной документации

1.1 Назначение документа

1.2 Область применения

1.3 Общая структура пояснительной записки (по ГОСТ)

2. Пошаговое руководство по составлению пояснительной записки

Шаг 1. Введение

Что включать:

Как оформлять:

Шаг 2. Назначение и область применения

Что включать:

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

Шаг 3. Технические характеристики

3.1 Постановка задачи, математические методы, допущения и ограничения

3.2 Описание алгоритма и функционирования

3.3 Организация входных и выходных данных

3.4 Выбор технических и программных средств

Шаг 4. Ожидаемые технико-экономические показатели

Что включать:

Шаг 5. Источники, использованные при разработке

Правила оформления:

3. Типичные ошибки и как их избежать

Пример: Пояснительная записка к программе `EventFlow-X`

1. Введение

2. Назначение и область применения

3. Технические характеристики

3.1 Постановка задачи, математические методы, допущения и ограничения

3.2 Описание алгоритма и функционирования

3.3 Организация входных и выходных данных

3.4 Выбор технических и программных средств

4. Ожидаемые технико-экономические показатели