Написание спецификации требований к веб-приложению
Спецификация требований (Software Requirements Specification, SRS) отличается от ТЗ по аудитории и глубине: ТЗ — договор с заказчиком на уровне «что делает система», SRS — инструмент для разработчиков и тестировщиков на уровне «как именно система это делает». В реальных проектах документы часто объединяют, но важно понимать разницу в детализации.
Классификация требований
Требования делятся на три категории, и важно не путать их:
Функциональные (FR) — что система умеет делать. «Пользователь может сбросить пароль по email».
Нефункциональные (NFR) — характеристики поведения системы. «Страница входа должна отвечать за 200ms при 500 одновременных пользователях».
Ограничения — внешние условия, которые нельзя изменить. «Интеграция только с российскими платёжными шлюзами», «GDPR-совместимость», «деплой в закрытый контур без доступа к интернету».
Формат описания функциональных требований
Лучший формат для разработчиков — User Story + Acceptance Criteria + технические детали:
## FR-047: Двухфакторная аутентификация (TOTP)
**Как** зарегистрированный пользователь,
**Я хочу** включить 2FA через приложение-аутентификатор,
**Чтобы** защитить аккаунт от несанкционированного доступа.
### Acceptance Criteria
**Включение 2FA:**
- AC-047-1: При переходе в настройки безопасности отображается раздел "Двухфакторная аутентификация"
- AC-047-2: При нажатии "Включить" система генерирует TOTP-секрет (RFC 6238, SHA-1, 6 цифр, 30 сек.)
- AC-047-3: QR-код для Google Authenticator / Authy отображается корректно
- AC-047-4: После ввода первого верного кода 2FA активируется
- AC-047-5: Система выдаёт 10 одноразовых резервных кодов (8 символов, a-z0-9)
**Вход с 2FA:**
- AC-047-6: После ввода верного пароля появляется форма ввода кода
- AC-047-7: Код принимается с допуском ±1 временного окна (90 сек. назад или вперёд)
- AC-047-8: Неверный код — ошибка, счётчик попыток (+1), лимит 5 попыток
- AC-047-9: Резервный код принимается как 2FA, после использования инвалидируется
**Отключение:**
- AC-047-10: Для отключения 2FA требуется текущий пароль + валидный 2FA-код
### Технические детали
**API:**
POST /api/auth/2fa/setup → { secret, qr_url, backup_codes } POST /api/auth/2fa/verify Body: { code } → { enabled: true } POST /api/auth/2fa/disable Body: { password, code } POST /api/auth/2fa/challenge Body: { code | backup_code } → { token }
**Хранение:**
- `totp_secret` шифруется AES-256-GCM перед сохранением в БД
- Ключ шифрования — из KMS, не хранится в коде
- `backup_codes` — bcrypt-хэши, не plaintext
**Миграция БД:**
```sql
ALTER TABLE users
ADD COLUMN totp_secret_enc TEXT,
ADD COLUMN totp_enabled BOOLEAN NOT NULL DEFAULT FALSE,
ADD COLUMN totp_verified_at TIMESTAMPTZ;
CREATE TABLE totp_backup_codes (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
code_hash TEXT NOT NULL,
used_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
Связанные требования: FR-001 (Регистрация), FR-002 (Вход), NFR-SEC-003
Зависимости: Библиотека otplib или аналог, поддерживающий RFC 6238
### Нефункциональные требования: как их делать измеримыми
Неизмеримые NFR бесполезны: «система должна быть быстрой» — невозможно проверить. Все NFR должны иметь конкретный метрику, условие измерения и источник данных.
```markdown
## NFR-PERF-001: Производительность API
| Метрика | Целевое значение | Условие измерения |
|---------|-----------------|-------------------|
| P50 latency | < 50ms | Нагрузка 100 rps, 4 ядра CPU |
| P95 latency | < 200ms | То же |
| P99 latency | < 500ms | То же |
| Error rate | < 0.1% | Нагрузка 100 rps, 10 минут |
| Throughput | ≥ 200 rps | До деградации P95 > 500ms |
**Инструмент проверки:** k6 (сценарий в `tests/load/api-baseline.js`)
**Частота проверки:** Перед каждым релизом в staging
## NFR-AVAIL-001: Доступность
- Uptime ≥ 99.5% в месяц (≤ 3.65 часа простоя)
- Плановые простои: до 30 минут, в 02:00–04:00 МСК, с уведомлением за 48 часов
- RTO (Recovery Time Objective): ≤ 30 минут
- RPO (Recovery Point Objective): ≤ 1 час
**Измерение:** UptimeRobot (HTTP-проверка каждую минуту, 3 региона)
## NFR-SEC-001: Управление сессиями
- JWT access token TTL: 15 минут
- Refresh token TTL: 30 дней, ротация при каждом использовании
- Максимум активных сессий на пользователя: 5
- При компрометации: инвалидация всех токенов пользователя за O(1)
**Проверка:** Ручное тестирование по чеклисту OWASP Session Management
Управление зависимостями между требованиями
В реальных проектах требования зависят друг от друга. Граф зависимостей помогает понять порядок разработки:
FR-001 (Регистрация)
└→ FR-002 (Вход)
└→ FR-047 (2FA)
└→ FR-048 (Резервные коды 2FA)
└→ FR-003 (Восстановление пароля)
└→ FR-010 (Email-верификация)
FR-020 (Каталог товаров)
└→ FR-021 (Корзина)
└→ FR-022 (Checkout)
└→ INT-001 (Оплата ЮKassa)
└→ INT-002 (Доставка СДЭК)
Трассируемость требований
SRS ценен, когда по любому куску кода можно сказать: «это реализует FR-047». Это достигается через:
- Именование тестов по идентификаторам требований:
describe('FR-047: TOTP 2FA', () => {
it('AC-047-7: принимает код с допуском ±1 окна', async () => {
// ...
});
it('AC-047-8: блокирует после 5 неверных попыток', async () => {
// ...
});
});
- Комментарии к ключевым решениям в коде:
// NFR-SEC-001: ротация refresh token при каждом использовании
async function refreshAccessToken(refreshToken: string) {
const session = await validateAndInvalidateRefreshToken(refreshToken);
const newRefreshToken = await createRefreshToken(session.userId);
const accessToken = createAccessToken(session.userId);
return { accessToken, refreshToken: newRefreshToken };
}
Ревью спецификации
Спецификация должна пройти ревью у трёх групп:
- Заказчик / Product Owner: корректны ли бизнес-правила?
- Разработчики: реализуемо ли технически, нет ли противоречий?
- QA: можно ли это протестировать, достаточно ли деталей?
Типичные проблемы, которые выявляет ревью:
- Неоднозначность: «пользователь может загрузить несколько файлов» — сколько максимум? Какой размер?
- Противоречия: в одном месте «сортировка по умолчанию — по дате», в другом — «по популярности»
- Пропущенные сценарии: описан happy path, не описаны ошибки
Сроки
SRS для приложения с 40–60 функциональными требованиями — три-четыре недели. Включает: анализ бизнес-процессов, проведение структурированных интервью, написание, два раунда ревью, итоговое согласование. Документ не статичный — при изменении требований версия обновляется через PR.