ПЗ по ГОСТ 19.404-79

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

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

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

ГОСТ

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

Пояснительная записка (ПЗ) - это документ, в котором разработчики объясняют, почему они приняли те или иные решения. Например, выбрал PostgreSQL вместо MySQL, потому что нам нужны JSON-запросы и транзакции. Redis добавил для кэша, так как 80% запросов — повторяющиеся.

ПЗ, можно сказать, это защита инженерных решений на бумаге.

---

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»

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

• Избегать расплывчатых формулировок: «для автоматизации процессов» → «для автоматической маршрутизации событий из 8 типов источников в 3 целевых системы в реальном времени».
• Можно добавить ограничения: «Не рекомендуется использовать в сетях с latency > 200 ms без буферизации».

---

Шаг 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 (библиографическая ссылка):

1. Cormen T.H., Leiserson C.E., Rivest R.L., Stein C. Introduction to Algorithms. — 3rd ed. — MIT Press, 2009. — 1312 p.  
2. 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).  
3. ГОСТ 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 %.

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

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

---

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

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

1. Приём события → валидация формата → парсинг.
2. Вычисление ключа K.
3. Запрос в state store (Redis, pipeline ≥100 ops).
4. Если K отсутствует — запись в CMS + отправка в output pipeline; иначе — отбрасывание.
5. Асинхронная отправка подтверждения источнику (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.Система	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

---