Написання специфікації вимог до веб-застосунку
Специфікація вимог (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 UTC, з уведомленням за 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 (Оформлення замовлення)
└→ INT-001 (Оплата ЮKassa)
└→ INT-002 (Доставка SDEK)
Трасування вимог
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.