📋 Стандарты и методологические ссылки

Этот раздел систематизирует ключевые отраслевые стандарты, методологии и лучшие практики, формирующие основу для Software Design Document (SDD). Применение данных подходов обеспечивает:

• Четкость и однозначность требований
• Высокое качество архитектуры и документации
• Минимизацию рисков и неоднозначностей в разработке
• Соответствие международным стандартам качества

---

EARS (Easy Approach to Requirements Syntax)

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

Ключевые шаблоны EARS

1. WHEN (Требования, управляемые событиями)

Назначение: Описание реакции системы на конкретные события или триггеры
Формат: WHEN [событие/триггер] THEN [система] SHALL [действие]

Примеры:

• WHEN пользователь нажимает кнопку "Сохранить" THEN система SHALL валидировать все поля формы
• WHEN загрузка файла превышает 10 МБ THEN система SHALL отобразить сообщение об ошибке
• WHEN сессия пользователя истекает THEN система SHALL перенаправить на страницу входа

2. IF (Требования, управляемые состоянием)

Назначение: Описание поведения системы при определенных условиях
Формат: IF [условие] THEN [система] SHALL [действие]

Примеры:

• IF пользователь не аутентифицирован THEN система SHALL запретить доступ к защищенным ресурсам
• IF подключение к базе данных не удается THEN система SHALL отобразить сообщение о техническом обслуживании
• IF пользователь имеет права администратора THEN система SHALL показать панель администратора

3. WHILE (Непрерывные требования)

Назначение: Описание постоянного поведения системы в заданном состоянии
Формат: WHEN [состояние] THEN [система] SHALL [непрерывное поведение]

Примеры:

• WHEN файл загружается THEN система SHALL отображать индикатор прогресса
• WHEN пользователь печатает THEN система SHALL предоставлять обратную связь валидации в реальном времени
• WHEN система обрабатывает запрос THEN система SHALL предотвращать дублирующие отправки

4. WHERE (Контекстно-зависимые требования)

Назначение: Ограничение требования определенным контекстом или средой
Формат: WHERE [контекст] THEN [система] SHALL [поведение]

Примеры:

• WHERE пользователь находится на мобильном устройстве THEN система SHALL использовать адаптивную компоновку
• WHERE приложение работает в режиме продакшн THEN система SHALL логировать ошибки во внешний сервис
• WHERE несколько пользователей редактируют одновременно THEN система SHALL обрабатывать конфликты изящно

Рекомендации по применению EARS

Категория	Рекомендации	Примеры
Синтаксис	• Использовать активный залог • Единый термин "система" вместо синонимов	❌ "Должны быть валидированы поля" ✅ "Система SHALL валидировать поля"
Конкретность	• Избегать расплывчатых терминов • Указывать количественные параметры	❌ "Быстрый отклик" ✅ "Отклик менее 300 мс"
Структура	• Одно требование = одно утверждение • Четкие критерии проверки	❌ "Система SHALL валидировать и сохранять" ✅ Два отдельных требования

Анти-паттерны EARS

🚫 Составные требования
Пример: "WHEN пользователь вводит данные THEN система SHALL валидировать и сохранять"
Решение: Разделить на два требования с отдельными триггерами

🚫 Неоднозначные условия
Пример: "WHEN данные введены THEN система SHALL обработать"
Решение: Указать конкретные условия ("WHEN все обязательные поля заполнены")

🚫 Детали реализации
Пример: "WHEN отправка формы THEN система SHALL использовать REST API"
Решение: Фокусироваться на результате ("...система SHALL сохранить данные")

---

Отраслевые стандарты

IEEE 830-1998: Спецификация требований к ПО

Цель стандарта: Обеспечение структурированного подхода к документированию требований через SRS (Software Requirements Specification).

Ключевые характеристики качественного SRS

• Полнота: Все функциональные и нефункциональные требования учтены
• Однозначность: Отсутствие двусмысленных формулировок
• Проверяемость: Каждое требование имеет критерии верификации
• Согласованность: Отсутствие противоречий между требованиями
• Отслеживаемость: Связь с источниками и этапами жизненного цикла

Рекомендуемая структура SRS

1. Введение
   - Назначение документа
   - Область применения
   - Термины и определения
   - Ссылки на сопутствующие документы

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

3. Конкретные требования
   - Функциональные (FR-001, FR-002...)
   - Нефункциональные (NFR-001...)
   - Интерфейсы
   - Требования к данным

4. Приложения
   - Матрица трассировки
   - Диаграммы
   - Примеры сценариев

Формат записи требований

Каждое требование должно содержать:

• Уникальный идентификатор (FR-001)
• Краткое название
• Подробное описание
• Источник (заказчик/документ)
• Приоритет (Must/Should/Could)
• Критерии приемки
• Зависимости

---

Архитектурные принципы и методологии

Принципы SOLID

Принцип	Описание	Антипаттерн
Single Responsibility	Каждый компонент имеет только 1 актора-пользователя	Божественный объект (God Object)
Open/Closed	Открыт для расширения, закрыт для модификации	Частые изменения базового кода
Liskov Substitution	Подклассы должны заменять базовые классы	Нарушение контракта наследования
Interface Segregation	Специфичные интерфейсы вместо общих	"Пухлые" интерфейсы
Dependency Inversion	Зависимость от абстракций верхних слоев, а не реализаций	Жесткие прямые зависимости от реализации верхних слоев архитектуры

Domain-Driven Design (DDD)

Ключевые концепции:

• Универсальный язык: Единая терминология для бизнес-аналитиков и разработчиков
• Ограниченные контексты: Четкое разделение предметных областей
• Агрегаты: Группировка объектов с общей границей транзакций
• События домена: Фиксация значимых бизнес-событий

Рекомендации по применению:

1. Создать глоссарий предметной области
2. Выделить ядро домена (Core Domain)
3. Использовать шаблоны проектирования (Сущности, Значения, Репозитории)
4. Внедрить шину событий для коммуникации между контекстами

---

Методологии сбора требований

Пользовательские истории (User Stories)

Формат:
Как [роль], я хочу [функциональность], чтобы [бизнес-ценность]

Критерии качества (INVEST):

• Independent: Независимость от других историй
• Negotiable: Возможность детализации
• Valuable: Предоставляет ценность
• Estimable: Поддается оценке
• Small: Умещается в одну итерацию
• Testable: Имеет четкие критерии приемки

Пример:
Как менеджер по продажам, я хочу фильтровать заказы по дате, чтобы анализировать еженедельную выручку
Критерии приемки:

• WHEN введен диапазон дат THEN система SHALL отобразить заказы в этом периоде
• WHEN выбрана невалидная дата THEN система SHALL показать подсказку

Use Cases

Стандартная структура:

1. Название
2. Акторы
3. Предусловия
4. Основной поток (последовательность шагов)
5. Альтернативные потоки
6. Постусловия
7. Исключения

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

• Максимум 9 шагов в основном потоке
• Альтернативные потоки нумеруются (3a, 3b)
• Каждый шаг содержит действие актора и реакцию системы

---

Стандарты документирования

Требования к технической документации

Элемент	Рекомендации	Антипаттерны
Структура	• Логическая последовательность• Единая система заголовков	Смешение уровней детализации
Стиль	• Активный залог• Конкретные формулировки	Пассивные конструкции ("должно быть сделано")
Терминология	• Глоссарий в начале документа• Единообразие терминов	Синонимия в рамках документа
Визуализация	• Диаграммы для сложных процессов• Схемы данных	Избыточные графики без пояснений

Типы документации и их стандарты

1. API-документация

Обязательные элементы:

• Описание всех эндпоинтов с HTTP-методами
• Примеры запросов/ответов в JSON/YAML
• Коды ошибок с пояснениями
• Параметры аутентификации
• Ограничения скорости (rate limits)

Рекомендация: Автоматическая генерация через Swagger/OpenAPI

2. Пользовательская документация

Структура:

- Quick Start: 5-минутное руководство
- Основные сценарии: Пошаговые инструкции
- Расширенные возможности: Глубокое погружение
- FAQ: Решение типовых проблем
- Ссылки на сообщество

3. Архитектурная документация

Обязательные разделы:

• Контекстная диаграмма (C4 Model Level 1)
• Диаграмма компонентов (C4 Model Level 2)
• Описание ключевых решений (ADR)
• Матрица технологий
• План эволюции архитектуры

---

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