Техническое задание на разработку портала для подрядчика

Роль ТЗ: цели, границы проекта и ожидания сторон

Техническое задание (ТЗ) для разработки портала — это документ, который фиксирует зачем создаётся портал, что именно входит в работу, как будет приниматься результат и кто что делает. Для подрядчика ТЗ — основа оценки сроков, стоимости и рисков. Для заказчика — инструмент управляемости: можно сравнивать фактический результат с согласованным ожиданием.

В рамках этого курса мы будем учиться писать ТЗ так, чтобы подрядчик мог реализовать портал предсказуемо, а заказчик — принять результат без споров. Эта статья задаёт фундамент: цели проекта, границы работ и ожидания сторон.

!Схема показывает, что ТЗ связывает цели, границы и правила взаимодействия в единый “контракт ожиданий”.

Зачем нужно ТЗ именно для портала

Портал почти всегда затрагивает несколько ролей и систем: сотрудников, клиентов, партнёров; авторизацию; контент; бизнес-процессы; интеграции; аналитику; иногда — документооборот и ЭП. Без чётких договорённостей легко получить ситуацию, когда:

Подрядчик делает то, что понял, а не то, что требовалось бизнесу.

Заказчик ожидает “как у конкурента”, но нигде это не зафиксировано.

Сроки и бюджет “ползут”, потому что постоянно всплывают неучтённые части работ.

ТЗ помогает перевести разговор из формата “хотим современный портал” в формат “вот измеримые цели, состав работ и критерии приёмки”.

Цели проекта: что считается успехом

Цели в ТЗ нужны не “для галочки”. Они определяют приоритеты, помогают решать спорные вопросы и защищают от бесконечного расширения требований.

Какие цели стоит фиксировать

Бизнес-цели: какой результат должен получить бизнес.

Пользовательские цели: какие проблемы пользователей решает портал.

Проектные цели: какие ограничения и параметры важны для реализации (например, сроки запуска).

Чтобы цели работали, их полезно делать проверяемыми: чтобы по итогам проекта можно было уверенно сказать “да, достигли” или “нет, не достигли”.

Пример формулировок целей (хорошо и плохо)

Плохо: “Сделать удобный портал”.

Хорошо: “Сократить время поиска регламентов сотрудниками за счёт единого каталога документов и поиска по тегам”.

Плохо: “Улучшить коммуникации”.

Хорошо: “Запустить новости и рассылки по подразделениям с подтверждаемой доставкой (просмотры/подписки) и ролями редакторов”.

Как цели связываются с требованиями

В корректном ТЗ каждое крупное требование можно “прибить” к цели:

Если требование не поддерживает цель — оно кандидат на исключение.

Если цель важна, но требований под неё нет — ТЗ неполное.

Границы проекта: что входит и что не входит

Границы — это способ заранее договориться, какие работы включены в договорённость, а какие потребуют отдельного согласования (по срокам, стоимости, команде).

Что такое “границы” простыми словами

Входит в проект (in scope): то, что подрядчик обязуется поставить.

Не входит (out of scope): то, что не делаем в рамках текущего проекта.

Допущения: что считается истинным “по умолчанию” (например, что заказчик предоставляет контент).

Ограничения: рамки, которые нельзя нарушать (например, использование конкретной платформы, требования ИБ).

Пример таблицы “входит/не входит” для портала

| Область | Входит в проект | Не входит в проект | |---|---|---| | Авторизация | SSO через корпоративный провайдер, роли пользователей | Настройка/разработка самого провайдера SSO | | Контент | Структура разделов, шаблоны страниц, редакторские роли | Наполнение всех разделов “под ключ” (если не оговорено) | | Интеграции | Интеграция с 1–2 системами по согласованным API | Любые дополнительные системы без отдельного согласования | | Поиск | Поиск по страницам и документам в портале | Поиск “по всем системам компании” |

Самые частые “скрытые” границы, которые нужно раскрыть

Данные и миграция: откуда переносим, в каком объёме, кто чистит данные, кто отвечает за качество.

Интеграции: какие системы, какие методы (API/файлы/шина), какие события и частота обмена.

Права доступа: роли, матрица прав, кто администрирует роли.

Нефункциональные требования: производительность, доступность, требования безопасности, аудит действий.

Поддержка после запуска: гарантия, SLA, сопровождение, обучение.

Если эти темы не зафиксировать, они часто превращаются в “сюрпризы” уже в ходе разработки.

Ожидания сторон: кто что делает и как принимаем работу

В IT-проектах конфликт чаще всего возникает не из-за “плохой разработки”, а из-за расхождения ожиданий: заказчик ожидал одно, подрядчик планировал другое. ТЗ должно уменьшать эту зону неопределённости.

Стороны и типовые ожидания

| Сторона | Чего обычно ждёт | Что важно зафиксировать в ТЗ | |---|---|---| | Заказчик (бизнес) | Достижения целей, понятного результата, прогнозируемых сроков | Критерии успеха, приоритеты, границы и этапность | | Заказчик (ИТ/ИБ) | Совместимости, безопасности, управляемости | Архитектурные ограничения, требования ИБ, окружения | | Подрядчик | Полноты требований и быстрых решений по вопросам | Процедуру согласований, ответственных, сроки обратной связи | | Пользователи | Удобства и пользы в ежедневных задачах | Роли пользователей, ключевые сценарии, UX-ограничения |

“Ожидания” в ТЗ, которые стоит формализовать

Роли и ответственность: кто утверждает требования, кто предоставляет контент, кто принимает релизы.

Правила коммуникации: каналы, частота статусов, формат протоколов встреч.

Процедура изменений: как добавляются новые требования и как пересчитываются сроки/стоимость.

Критерии приёмки: что считается “сделано” для функции/этапа.

Чтобы опираться на общепринятую терминологию, можно сверяться со стандартом IEEE по требованиям: IEEE 29148-2018 (ISO/IEC/IEEE 29148:2018).

ТЗ как “контракт ожиданий”, а не “роман на 200 страниц”

Качество ТЗ определяется не объёмом, а способностью документа ответить на ключевые вопросы проекта:

Зачем делаем портал и как измеряем успех.

Что делаем в рамках текущего проекта.

Как проверяем и принимаем результат.

Кто принимает решения и в какие сроки.

Иногда ТЗ делают слишком детальным там, где это не нужно (например, чрезмерное описание очевидных страниц), и слишком размытым там, где это критично (например, интеграции и права).

Минимальный каркас разделов ТЗ для этой темы

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

Цели и метрики успеха: бизнес-цели, пользовательские цели, приоритеты.

Область работ (scope): что входит/не входит, допущения, ограничения.

Стейкхолдеры и роли: ответственные, владельцы процессов, согласующие.

Критерии приёмки: правила приёмки, виды тестирования, требования к демонстрациям.

Управление изменениями: как вносятся изменения и как фиксируются договорённости.

Практический чек-лист для автора ТЗ

Перед передачей ТЗ подрядчику убедитесь, что:

Цели сформулированы так, чтобы можно было понять, достигнуты они или нет.

Есть таблица “входит/не входит”, и она покрывает спорные зоны (контент, интеграции, миграция, поддержка).

Определены роли и ответственные со стороны заказчика и подрядчика.

Указаны критерии приёмки хотя бы для ключевых функций и этапов.

Описан процесс изменений, чтобы новые идеи не ломали сроки “по умолчанию”.

В следующей статье курса логично перейти к структуре ТЗ для портала: какие разделы обязательны и как собрать требования так, чтобы их можно было оценить и реализовать.

Сбор и анализ требований: стейкхолдеры, интервью, артефакты

Сильное ТЗ начинается не с “описания экранов”, а с правильного сбора и анализа требований. В предыдущей статье мы зафиксировали роль ТЗ как контракта ожиданий: цели, границы (scope) и правила приёмки. Эта статья отвечает на практический вопрос: откуда берутся требования, кто их поставляет, как их извлечь и в каком виде зафиксировать, чтобы подрядчик мог оценить, спроектировать и реализовать портал предсказуемо.

!Схема помогает увидеть, кто влияет на требования и кто будет принимать результат

Что такое “требование” в контексте портала

Требование — это формулировка того, что система должна делать или каким свойством обладать.

Для портала требования обычно делятся на:

Функциональные: действия и возможности (например, “пользователь может подать заявку”, “новость можно отправить на согласование”).

Нефункциональные: качества и ограничения (например, “SSO обязателен”, “логирование действий администратора”, “время отклика до N секунд при заданной нагрузке”).

Интеграционные: обмен данными и событиями с другими системами (что, куда, когда, в каком формате, кто источник истины).

Контентные: структура, типы материалов, ответственность за наполнение, жизненный цикл публикаций.

Важно: требования — это не “решение” и не “дизайн”. Формулировка “сделать как у конкурента” — это не требование, пока не разложено на проверяемые пункты.

Стейкхолдеры: кого обязательно вовлекать

Стейкхолдеры — это люди и группы, которые:

формируют ожидания,

пользуются порталом,

принимают работу,

обеспечивают инфраструктуру и безопасность,

несут ответственность за контент и процессы.

Типовая карта стейкхолдеров для портала

| Группа | Зачем вовлекать | Что обычно “забывают”, но критично для ТЗ | |---|---|---| | Бизнес-владелец продукта | Формулирует цели, приоритеты, бюджетные рамки | Критерии успеха и приёмки по ценности, а не только по фичам | | Владельцы процессов | Описывают реальные сценарии: заявки, согласования, коммуникации | Исключения и “нестандартные случаи” (права, сроки, ручные обходы) | | Конечные пользователи | Подтверждают, что портал решает реальные задачи | “Боль” в текущих инструментах, привычные пути работы | | Контент-редакторы/коммуникации | Определяют модель публикаций и согласований | Роли редакторов, правила архивации, требования к поиску | | ИТ-архитектор/эксплуатация | Определяют ограничения платформы, окружения, мониторинг | Окружения, резервное копирование, обновления, поддержка | | ИБ (безопасность) | Определяют требования по доступам, аудитам, хранению данных | Логи, аудит, требования к сессиям, классификация данных | | Юристы/комплаенс | Проверяют обработку данных и юридические тексты | Согласия, сроки хранения, тексты оферт/политик | | Интеграционные команды/владельцы систем | Уточняют API, события, ограничения, SLA интеграций | Кто “источник истины”, частота обмена, обработка ошибок | | Служба поддержки | Определяет типовые обращения и ожидания пользователей | База знаний, шаблоны ответов, маршрутизация обращений |

Роли: кто принимает решения и кто консультирует

Чтобы не “зациклиться” на согласованиях, полезно зафиксировать ответственность в логике RACI:

Responsible: делает работу (например, аналитик собирает требования).

Accountable: принимает решение и несёт ответственность (владелец продукта/процесса).

Consulted: консультирует (ИБ, архитектура).

Informed: информируется (смежные команды).

Если у вас нет внутреннего стандарта, используйте простую таблицу “роль — зона решения — срок ответа”.

Интервью и воркшопы: как извлекать требования без хаоса

Интервью — основной инструмент для понимания потребностей, ограничений и сценариев. Для портала почти всегда нужен микс:

интервью один на один (глубина),

групповые воркшопы (согласование процессов),

анализ артефактов (подтверждение фактами),

прототипирование (быстрая проверка понимания).

Подходы и терминологию по elicitation (извлечению требований) удобно сверять с профессиональными практиками бизнес-анализа, например, в BABOK Guide от IIBA.

Подготовка к интервью

До интервью важно “настроить рамку”, иначе разговор уйдёт в детали интерфейса или субъективные вкусы.

Сформулируйте цель интервью (например, “понять процесс обработки обращений и точки интеграции”).

Определите роль интервьюируемого и зону ответственности.

Подготовьте список вопросов по темам:

1. задачи и частота, 2. входы/выходы процесса, 3. исключения и проблемные кейсы, 4. данные и источники, 5. права доступа, 6. критерии успеха.

Подготовьте “якоря”: текущие регламенты, формы, отчёты, примеры заявок.

Договоритесь о формате фиксации: запись/конспект, кто подтверждает итог.

Вопросы, которые дают “требования”, а не мнения

Ниже — формулировки, которые переводят обсуждение в проверяемую плоскость:

“Как выглядит успешный результат этого сценария?”

“Какие шаги происходят всегда, а какие иногда?”

“Что считается ошибкой и как вы её сейчас обрабатываете?”

“Кто имеет право видеть/редактировать/утверждать?”

“Откуда берутся данные и где они должны быть истинными?”

“Какие события должны быть зафиксированы в журнале аудита?”

Чтобы интервью не превратилось в спор о вкусах, полезно держаться принципов исследовательского общения и уточняющих вопросов, описанных в материалах по UX-исследованиям, например, у Nielsen Norman Group.

Воркшоп по сценариям: быстрый способ собрать “сквозные” требования

Формат: 60–120 минут, 5–8 участников (процесс + ИТ/ИБ + пользователь), фасилитатор.

Результат воркшопа — не “дизайн экрана”, а:

список сценариев (use cases) и их границы,

последовательность шагов,

роли и права,

данные и интеграции,

исключения,

критерии готовности.

Анализ требований: как превратить разговоры в структуру ТЗ

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

Нормализация: привести формулировки к одному стилю

Хорошее требование:

однозначное,

проверяемое,

привязано к роли/сценарию,

не содержит “скрытых” решений.

Пример нормализации:

Было: “Сделать удобную форму заявки”.

Стало: “Пользователь с ролью Сотрудник может создать заявку типа Доступ к системе; обязательные поля: система, подразделение, причина; после отправки заявка получает номер и статус На согласовании; пользователь видит статус в личном кабинете”.

Разрешение конфликтов: что делать, если разные группы хотят разное

Типовые конфликты в порталах:

бизнес хочет “быстрее и проще”, ИБ требует “строже и с аудитом”,

редакторы хотят “полную свободу”, бренд/юристы — “строгие шаблоны”,

пользователи хотят “всё в одном”, ИТ ограничено платформой и интеграциями.

Практика:

Вернуться к целям из ТЗ (что важнее для успеха).

Зафиксировать варианты решения и последствия.

Принять решение у владельца цели (Accountable), а не “голосованием”.

Записать компромисс как требование и как ограничение (если нужно).

Приоритизация: что делать в первую очередь

Чтобы подрядчик мог оценить этапность, требования стоит приоритизировать. Простой подход — MoSCoW:

Must: без этого портал нельзя запускать.

Should: сильно повышает ценность, но может подождать.

Could: желательно, если укладываемся.

Won’t (now): не делаем в этой фазе.

В ТЗ приоритет важен не как “хотелка”, а как основание для планирования релизов и управления изменениями.

Артефакты: в каком виде фиксировать результаты

Артефакты — это документы и модели, которые “упаковывают” требования так, чтобы их можно было согласовать и реализовать.

Ниже — набор артефактов, который чаще всего даёт максимальный эффект именно для портала.

Реестр стейкхолдеров

| Поле | Пример | |---|---| | ФИО/роль | Руководитель HR | | Зона ответственности | Контент раздела “Обучение” | | Влияние на решения | Высокое | | Что ожидает | Каталог курсов, заявки на обучение | | Формат участия | Интервью + согласование требований | | SLA на ответы | 2 рабочих дня |

Список пользовательских ролей и матрица доступа

Минимум: список ролей и ключевые права.

| Раздел/функция | Сотрудник | Руководитель | Редактор | Администратор | |---|---|---|---|---| | Просмотр новостей | Да | Да | Да | Да | | Публикация новости | Нет | Нет | Да | Да | | Управление ролями | Нет | Нет | Нет | Да |

Это можно развивать в полноценную матрицу RBAC, но даже простая версия снижает риски “поздних сюрпризов”.

Сценарии (use cases) или пользовательские истории

Для порталов удобны оба формата:

Use case хорош, когда много исключений, статусов и ролей.

User story удобна для бэклога и итеративной разработки.

Пример user story:

“Как сотрудник, я хочу видеть статус своих заявок, чтобы не писать в поддержку”.

Но в ТЗ важно добавлять критерии приёмки (acceptance criteria) — иначе история остаётся слишком общей.

Карта пути пользователя (user journey)

Полезна, когда портал обслуживает “сквозной опыт” (например, клиентский кабинет).

!Визуально связывает проблемы пользователя с конкретными требованиями

Модель контента

Для портала критично описать типы материалов и их жизненный цикл.

| Тип контента | Поля | Кто создаёт | Кто утверждает | Версионирование/архив | |---|---|---|---|---| | Новость | заголовок, текст, теги, вложения, аудитория | Редактор | Главный редактор | Архив через 90 дней | | Документ | название, версия, подразделение, доступ, файл | Владелец документа | Владелец процесса | Хранить историю версий |

Контекст интеграций и “контракты” обмена

Минимальный артефакт для каждой интеграции:

цель интеграции (зачем),

системы-участники и владелец каждой,

что является источником истины,

события/операции (создать/обновить/получить),

формат (API/файлы), частота, SLA,

ошибки и поведение при сбоях,

требования ИБ (токены, сети, шифрование, аудит).

Каталог требований с идентификаторами и трассируемостью

Каталог — это таблица, где каждое требование имеет ID, приоритет и источник.

| ID | Требование | Тип | Приоритет | Источник | Критерий приёмки | |---|---|---|---|---|---| | FR-01 | Пользователь может создать заявку “Доступ” | функциональное | Must | Владелец процесса | Заявка создаётся, присваивается номер, статус виден | | NFR-01 | Аудит действий администраторов | нефункциональное | Must | ИБ | В логе фиксируются логин, действие, объект, время |

Трассируемость означает, что вы можете ответить:

к какой цели относится требование,

из какого источника оно появилось,

в каком релизе реализуется,

как проверяется.

Для формального подхода к качеству требований можно ориентироваться на принципы из ISO/IEC/IEEE 29148:2018.

Минимальный процесс сбора требований для ТЗ (практический шаблон)

Ниже — последовательность, которую можно повторить почти в любом проекте портала.

Зафиксировать цели и границы (из предыдущей статьи) и список ключевых сценариев.

Составить реестр стейкхолдеров и расписание интервью.

Собрать артефакты текущего состояния:

1. регламенты, 2. формы заявок, 3. отчёты, 4. структуру контента, 5. список систем и интеграций.

Провести интервью и 1–2 воркшопа по ключевым процессам.

Сформировать:

1. роли и права, 2. сценарии и исключения, 3. интеграционные контракты, 4. нефункциональные требования.

Свести всё в каталог требований с ID, приоритетами и критериями приёмки.

Пройти согласование: владелец продукта + ИТ + ИБ (минимум).

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

Собрали требования только у “заказчика сверху”: получите сопротивление пользователей и пропущенные сценарии.

Описали интерфейсы вместо требований: подрядчик не сможет выбрать оптимальное решение и оценить риски.

Не выделили нефункциональные требования: проблемы всплывут на приёмке (скорость, безопасность, аудит).

Не зафиксировали источники истины и SLA интеграций: интеграции станут главным фактором срыва сроков.

Нет критериев приёмки: “сделано” будет трактоваться по-разному.

Что должно оказаться в ТЗ по итогам этой работы

После этапа сбора и анализа требований у вас должен получиться согласуемый набор разделов ТЗ:

список стейкхолдеров и ролей,

ключевые сценарии (use cases) и/или user stories с критериями приёмки,

матрица прав доступа,

модель контента,

интеграционные требования,

нефункциональные требования,

каталог требований с идентификаторами и приоритетами.

В следующей логичной части курса эти материалы превращаются в структурированное ТЗ, где требования будут разложены по разделам, и подрядчик сможет дать прозрачную оценку сроков, стоимости и рисков.

Structure of a Technical Specification: sections, template, and formatting rules

A portal project becomes predictable for a contractor when the Technical Specification (TS) is structured, consistent, and testable. In the previous articles we established:

TS as a contract of expectations: goals, scope boundaries, acceptance rules

requirements come from stakeholders, interviews, and artifacts, and must be normalized and prioritized

This article shows how to assemble those inputs into a TS that a contractor can estimate, design, implement, and deliver with minimal ambiguity.

!A TS structure map connecting goals to requirements and acceptance

What a “good TS” looks like for a portal

A contractor should be able to answer these questions directly from the TS:

What problem are we solving and how do we measure success?

What is in scope / out of scope and what assumptions apply?

Who are the users, roles, permissions, and key scenarios?

Which systems do we integrate with and what are the data contracts?

Which non-functional constraints apply (security, performance, availability, audit)?

How do we test and accept the work?

How do changes get approved and reflected in scope, timeline, and cost?

If the TS cannot answer these, the project will rely on “silent assumptions”, and those typically become disputes.

Recommended TS sections (portal-focused)

The exact numbering may vary, but the content blocks below are the most reusable for portal development.

TS cover page and document control

Include:

Document title: “Technical Specification: [Portal name]”

Version, status: Draft / Review / Approved

Authors and approvers

Date and change log

Links to referenced artifacts (if stored elsewhere)

A minimal change log table:

| Version | Date | Author | Change summary | Approved by | |---|---|---|---|---| | 0.1 | 2026-02-01 | BA | Initial draft | Pending |

Context, goals, and success metrics

This section anchors everything to business value.

Include:

Background: current state and pain points

Goals: business and user goals

Success metrics: how you will verify impact after launch

Example of measurable goals:

| Goal | Metric | Baseline | Target | Measurement method | |---|---|---|---|---| | Reduce time to find policies | Average search-to-open time | 4 min | 1.5 min | Portal analytics + user test |

Scope and boundaries

Use explicit boundaries to prevent scope creep.

Recommended structure:

In scope

Out of scope

Assumptions

Constraints

n Example boundary table:

| Area | In scope | Out of scope | |---|---|---| | Authentication | SSO via corporate IdP | Modifying the IdP itself | | Content | Templates, workflow, roles | Filling all pages unless agreed | | Integrations | HR system read-only profile sync | Building/repairing HR system APIs |

Stakeholders, roles, and responsibilities

This converts “who wants what” into “who decides what”.

Include:

Stakeholder registry (who provides requirements, who approves)

RACI-style responsibility allocation (optional)

Response SLA for clarifications (for predictable delivery)

Minimal stakeholder registry table:

| Stakeholder | Role | Decision area | Required involvement | |---|---|---|---| | Product Owner | Accountable | Priorities, acceptance | Weekly review | | Security Officer | Consulted/Approver | Security requirements | Approval gate | | Portal Admin | Consulted | Admin UX, support | Workshops |

User groups, roles, and access model

A portal is permission-heavy, so describe access early.

Include:

User groups and roles

Permission model approach: RBAC (role-based), ABAC (attribute-based), or hybrid

Access rules for content, workflows, and admin tools

Audit requirements for privileged actions

Example RBAC matrix (minimal):

| Feature | Employee | Manager | Editor | Admin | |---|---|---|---|---| | View news | Yes | Yes | Yes | Yes | | Publish news | No | No | Yes | Yes | | Manage roles | No | No | No | Yes |

Functional requirements

Write functional requirements as testable statements.

Recommended organization for portals:

Content management and publishing workflows

News and communications

Document library and search

Forms and service requests (tickets/applications)

Personal area (profile, tasks, requests)

Notifications (email/in-app/push if applicable)

Administration (users, roles, audit, configuration)

Requirement format

Use a consistent requirement record:

ID: FR-###

Statement: “The system shall …”

Priority: Must/Should/Could/Won’t (now)

Source: stakeholder/artifact

Acceptance criteria: how it will be verified

Notes/constraints

If you want standardized wording for requirement strength, refer to the terminology in Key words for use in RFCs to Indicate Requirement Levels (RFC 2119).

Example requirements table:

| ID | Requirement (functional) | Priority | Acceptance criteria | |---|---|---|---| | FR-01 | The system shall allow an Employee to create a request of type Access. | Must | Request is saved; number assigned; status becomes Submitted; user sees it in “My requests”. | | FR-02 | The system shall support an approval workflow with statuses and role-based steps. | Must | At least 2-step approval works; status history visible; step assignees enforced by roles. |

Non-functional requirements

Non-functional requirements (NFRs) are frequently the reason portals fail acceptance, especially around security and performance.

Recommended NFR categories:

Security and compliance

Performance and scalability

Availability and reliability

Logging, audit, and monitoring

Maintainability and supportability

Accessibility (if required)

Compatibility (browsers/devices)

Example NFR table:

| ID | Requirement (NFR) | Priority | Verification method | |---|---|---|---| | NFR-01 | Admin actions shall be auditable (who/what/when/from where). | Must | Audit log shows actor, timestamp, action, object, source IP/session. | | NFR-02 | Portal pages shall load within an agreed threshold under agreed load. | Must | Performance test report meets target on staging. |

If you need a formal reference for requirements quality and structure, see ISO/IEC/IEEE 29148:2018 (IEEE 29148-2018).

Integrations and data exchange

Portal integrations must be described as contracts, not as “connect to system X”.

For each integration include:

Purpose (why it exists)

Systems involved and owners

Source of truth per data entity

Operations/events (create/update/read)

Interface type (REST API, message bus, file)

Authentication method and network constraints

Frequency and latency expectations

Error handling and retries

Logging and audit expectations

Integration contract table (example):

| Field | Value | |---|---| | Integration ID | INT-01 | | Systems | Portal ↔ HR System | | Purpose | Show employee department and manager in profile | | Source of truth | HR System | | Method | REST API (read-only) | | Frequency | On login + daily sync | | Failure behavior | Show last known values + warning in logs |

Content model and editorial workflow

Portals are content-heavy, so define:

Content types (news, policy, FAQ, landing page, document)

Fields and metadata (tags, audience, validity period)

Lifecycle: draft → review → published → archived

Roles: author, editor, approver

Search behavior and indexing rules

Content type table (example):

| Content type | Required fields | Workflow | Archiving | |---|---|---|---| | News | Title, body, tags, audience | Author → Editor → Publish | Auto-archive after 90 days | | Policy document | Name, version, owner, file | Owner → Approver → Publish | Version history kept |

UX and UI constraints (without over-designing)

A TS should define behavior and acceptance, not pixel-level design. Still, some UX constraints are necessary:

Navigation principles (e.g., max depth for menus)

Search expectations (filters, sorting, highlighting)

Responsive behavior (desktop/mobile)

Key user journeys and critical screens

A practical compromise:

Put detailed UI into a separate prototype/design file

In the TS keep:

- screen list - key behavior rules - acceptance criteria for each critical flow

Environments, deployment, and operations

Contractors need clarity on where and how the portal will run.

Include:

Environment list: Dev/Test/Staging/Prod

Hosting model: on-prem/cloud, region, network segmentation

CI/CD expectations and access responsibilities

Backup and restore expectations

Monitoring and alerting requirements

Logging storage and retention

Environment table (example):

| Environment | Purpose | Access | Data policy | |---|---|---|---| | Staging | Acceptance testing | Business + QA | Masked or synthetic data | | Production | Real usage | Controlled | Real data, full security controls |

Testing strategy and acceptance criteria

Acceptance disputes usually happen because acceptance criteria were not written.

Include:

Types of testing: functional, integration, security, performance, regression, UAT

Entry/exit criteria for UAT

Definition of Done (DoD) per feature and per release

Acceptance evidence: test cases, reports, demo checklist

A minimal acceptance checklist structure:

For each requirement ID, specify verification:

- demo steps - test case ID - expected result

This provides traceability from goals → requirements → tests.

Deliverables and documentation

Specify what the contractor must deliver beyond the running portal:

Source code and build instructions

Infrastructure as Code (if used)

Admin guide and user guide

API documentation for integrations

Test results and known limitations

Training sessions (if required)

Change control (how the TS evolves)

Since portals evolve, define how changes are handled:

What counts as a change request

Who approves changes

How impact is assessed (scope/time/cost)

How the TS and requirement catalog are versioned

A simple rule that works well:

New requirement or changed acceptance criteria always gets a new or updated ID and a version note

Formatting and writing rules that reduce ambiguity

Use “shall” statements and avoid vague words

Avoid:

“fast”, “convenient”, “modern”, “user-friendly”, “as needed”, “etc.”

Replace with:

measurable targets, explicit behaviors, and acceptance criteria

Example rewrite:

Vague: “The portal should have a fast search.”

Testable: “Search results shall appear within the agreed threshold for the agreed dataset size on staging; results shall support filtering by content type and department.”

One requirement, one meaning

Rules:

Do not combine multiple features into one statement

Keep a single actor and a single primary outcome per requirement

Assign IDs and keep a requirements catalog

A contractor estimates and tracks work more reliably when each requirement has:

ID

priority

source

acceptance criteria

This also supports traceability during change control.

Separate “requirements” from “design”

Good TS:

defines what must be achieved and how it will be accepted

Optional attachments:

prototypes, UI kit, architecture proposal, BPMN diagrams

Use consistent terminology and a glossary

Add a short glossary for:

portal modules

roles

key process terms

external system names

Practical TS template (copy/paste outline)

Use this as a starting point and remove what you truly don’t need.

Document control

Context

Goals and success metrics

Scope and boundaries

Stakeholders and responsibilities

Users, roles, access model

Functional requirements

Non-functional requirements

Content model and editorial workflow

Integrations and data contracts

Data and migration (if applicable)

UX constraints and key user journeys

Environments and deployment

Testing approach and acceptance criteria

Deliverables and documentation

Change control and versioning

Glossary

Appendices (links to prototypes, diagrams, forms, existing regulations)

Common TS structure mistakes (and why they hurt)

Missing out-of-scope section: leads to “we assumed it was included” disputes

No acceptance criteria: acceptance becomes subjective

Integrations described without source-of-truth and failure behavior: timeline risk explodes late

Permissions described informally: security rework at the end

Over-detailed UI inside TS: slows changes and distracts from testable outcomes

What you should have after this article

A TS draft where:

goals and scope are explicit

requirements have IDs, priorities, sources, and acceptance criteria

integrations are described as contracts

non-functional requirements are stated and testable

acceptance process and evidence are defined

In the next part of the course, you can deepen this structure into estimable work packages: how contractors translate TS into effort, timeline, risks, and a delivery plan.

Functional requirements: roles, scenarios, user stories

Functional requirements describe what the portal must do for specific users, in specific situations, with a result that can be verified during acceptance. In the previous articles of this course, we established:

the TS as a contract of expectations (goals, scope, acceptance)

how to collect and normalize requirements from stakeholders

how to structure the TS so a contractor can estimate and deliver predictably

This article focuses on the most practical layer of a portal TS: defining roles, converting needs into scenarios (use cases) and/or user stories, and turning them into testable functional requirements with clear acceptance criteria.

!How roles lead to scenarios, which lead to user stories and finally to a requirement catalog

Why roles come first in portal requirements

A portal is typically role-heavy: the same feature behaves differently depending on who the user is and what permissions they have. If you start describing screens without roles, you usually get late rework around access, approval steps, and visibility.

A role is a named set of permissions and responsibilities in the portal.

Typical portal roles (example)

| Role | What they do | Typical sensitive permissions to clarify early | |---|---|---| | Employee | Reads content, submits requests, tracks status | Can they see only their own requests or also team requests? | | Manager | Approves requests, views team info | Can they delegate approvals? | | Editor | Creates and publishes content | Can they publish without approval? | | Admin | Manages users, roles, configuration | What actions must be audited? |

Role definition checklist

To define a role in the TS, specify:

Who belongs to the role (rules for assignment)

Main goals in the portal (why they use it)

Key actions (create, approve, publish, manage)

Visibility rules (what they can see)

Restrictions (what they must not do)

If your project uses role-based access control, name it explicitly as RBAC (Role-Based Access Control) and describe it in plain terms: permissions are granted to roles, and users receive one or more roles.

Scenarios (use cases): describing behavior end-to-end

A scenario (often documented as a use case) describes how a user achieves a goal in the system, step-by-step, including alternative flows and errors.

Use cases are especially strong for portal modules that have:

statuses

approvals

multiple actors

integrations

many exceptions

Use case template that works well in a TS

Use a consistent structure so a contractor can estimate and QA can test.

Use case ID and name

Goal

Primary actor (role)

Preconditions (what must already be true)

Trigger (what starts the scenario)

Main flow (happy path)

Alternative flows (valid variations)

Error flows (failures and system behavior)

Postconditions (what becomes true after completion)

Acceptance criteria (how you will verify it)

Example use case

UC-REQ-01: Submit an access request

Goal: an Employee submits a request to get access to a system.

Primary actor: Employee.

Preconditions:

- the user is authenticated via SSO - the user has the Employee role

Trigger: user selects Create request → Access request.

Main flow:

1. The portal shows the request form with required fields: target system, business reason, requested access level. 2. The user fills the form and submits. 3. The portal validates required fields. 4. The portal creates a request with a unique number and status Submitted. 5. The portal notifies the first approver (Manager) and shows the request in My requests.

Alternative flows:

1. If the user selects a system that requires additional approvals, an extra approval step is added.

Error flows:

1. If the notification service is unavailable, the request is still created and an error is logged; the user sees a message that notification may be delayed.

Postconditions:

- a new request exists and is visible to the Employee - the request is available to approvers in their queue

Acceptance criteria:

- a request number is generated - status history is visible to the Employee - approver receives a notification (or the failure behavior is followed and logged)

User stories: concise requirements for iterative delivery

A user story is a short statement of value from the perspective of a role.

A common format is:

“As a role, I want capability, so that benefit.”

User stories are convenient when the contractor works iteratively and you want a backlog-like structure. A widely used overview of user stories and acceptance criteria can be found in Atlassian’s guide to user stories.

User stories still need acceptance criteria

A story without acceptance criteria is usually too vague to accept objectively.

Good acceptance criteria are:

specific and testable

linked to roles and data conditions

limited in scope (do not hide new features)

Example user story with acceptance criteria

US-REQ-07: Track request status

Story: As an Employee, I want to see the current status and history of my requests, so that I do not need to contact support for updates.

Acceptance criteria:

- Employee can open My requests and see a list of their requests - each request shows: number, type, current status, last updated date - request details show status history with timestamps and approver role (not personal data unless allowed) - Employee cannot see requests created by other Employees

When to use scenarios vs user stories in a portal TS

You can use either approach, but in portal projects a hybrid is often best.

Practical selection rules

Use use cases when:

- there are approvals, statuses, or multiple roles - there are integrations and failure behavior matters - you need to describe alternative and error flows clearly

Use user stories when:

- the feature is small and user value is straightforward - the contractor delivers in iterations and estimates per item - you want a backlog-like list aligned with priorities

A good TS often includes:

use cases for complex workflows (requests, approvals, editorial workflows)

user stories for smaller portal capabilities (search filters, profile display, notification preferences)

Turning roles and scenarios into functional requirements

In the TS structure from the previous article, functional requirements are the testable statements the contractor will implement and the customer will accept.

Requirement writing rules (portal-oriented)

One requirement should express one primary behavior.

Each requirement should mention:

- actor or applicable roles - action - result - constraints (if needed)

Every requirement should have acceptance criteria or a clear verification method.

Avoid vague wording such as “user-friendly” or “fast” without a measurable target.

If you use requirement strength keywords, keep them consistent. For common interpretations of “must/shall/should”, see RFC 2119.

Functional requirement record (recommended)

| Field | Meaning | |---|---| | ID | Unique reference like FR-REQ-001 | | Statement | “The portal shall …” | | Roles | Who can perform it | | Priority | Must/Should/Could/Won’t (now) | | Source | Stakeholder / use case / regulation | | Acceptance criteria | What must be true to accept | | Notes | Clarifications, constraints |

Example functional requirements (from the use case above)

| ID | Statement | Roles | Priority | Acceptance criteria | |---|---|---|---|---| | FR-REQ-001 | The portal shall allow an Employee to submit an access request with required fields and create a unique request number. | Employee | Must | Required fields are validated; request number is created; status becomes Submitted; request appears in My requests. | | FR-REQ-002 | The portal shall support an approval workflow with statuses and status history visible to the request author. | Employee, Manager | Must | Approver queue exists; at least one approval step updates status; status history shows timestamps and status changes. | | FR-REQ-003 | The portal shall notify the first approver after request submission. | Manager | Should | Notification is sent and recorded; if notification fails, the request still exists and the failure is logged according to agreed behavior. |

Coverage: how to ensure you did not miss key portal functionality

Roles and scenarios help you find gaps. A practical coverage method is to ensure each role has at least:

entry points (what they see first)

top tasks (what they do most often)

exception handling (what happens when things go wrong)

Common portal functional areas to check

authentication and session behavior from a user perspective (login/logout, expired session handling)

content browsing and search (filters, sorting, access-aware results)

content publishing workflow (draft, review, publish, archive)

requests and forms (create, validate, attach files, track status)

approvals (queues, delegation rules, SLA reminders if applicable)

notifications (channels, preferences, failure behavior)

personal area (profile, tasks, bookmarks)

administration (user/role management, configuration changes)

Traceability: linking functional requirements to goals and acceptance

To keep the TS manageable and prevent scope creep:

link each functional requirement to:

- at least one goal - a role and scenario/story - acceptance evidence (test case, demo checklist)

A minimal traceability table can look like this:

| Goal | Use case / story | Functional requirements | Acceptance evidence | |---|---|---|---| | Reduce support load for request updates | US-REQ-07 | FR-REQ-002 | UAT checklist item UAT-12 + demo steps |

Traceability makes change control realistic: when something changes, you can immediately see what requirements and tests are impacted.

Typical mistakes in portal functional requirements

Writing “screens” instead of behavior: the contractor builds UI, but workflow rules and permissions are unclear.

Missing alternative and error flows: failures appear only during integration testing.

Role definitions without visibility rules: data exposure and security rework late in the project.

Mixing multiple features in one requirement: estimation and acceptance become ambiguous.

No acceptance criteria: “done” becomes subjective.

What should be produced after this article

You should be able to add to your TS:

a clear list of portal roles and their boundaries

a set of key use cases and/or user stories per module

a functional requirements catalog with IDs and acceptance criteria

a traceable link from roles → scenarios/stories → requirements → acceptance evidence

Non-functional requirements: security, performance, UX, SLA

Non-functional requirements (NFRs) define how the portal must behave and what qualities it must guarantee, rather than what features it has. In the previous parts of this course you:

fixed goals, scope boundaries, and acceptance as a “contract of expectations”

learned how to collect and normalize requirements from stakeholders

built a structured TS with IDs, priorities, and acceptance criteria

described functional requirements through roles, scenarios, and user stories

This article completes the picture: how to specify NFRs so a contractor can design architecture correctly, estimate realistically, and pass acceptance without late surprises.

!NFR pillars and how each is verified

What NFRs are and why they are critical in a portal TS

An NFR is a testable constraint or quality attribute that applies to the portal as a system: security, performance, availability, usability, accessibility, supportability, and operational rules.

Portals fail acceptance more often because of NFR gaps than because of missing features:

security and access rules are clarified too late

performance targets are not defined, so “fast” becomes subjective

UX expectations are discussed as “design taste”, not as measurable behavior

support and incident response are unclear after go-live

A practical rule for TS quality:

a functional requirement is usually accepted by demoing a flow

an NFR is usually accepted by evidence: test reports, logs, monitoring dashboards, audit trails, configuration exports

How to write NFRs so they are estimable and testable

A good NFR answers five questions:

What exactly is required?

Under which conditions (load, dataset size, user group, environment)?

How will it be verified (method and artifact)?

What is the priority (Must/Should/Could)?

What are the exclusions/assumptions?

Recommended NFR record format

Use a consistent catalog format (same as functional requirements, but with verification focus).

| Field | What it means | |---|---| | ID | Unique reference, e.g., NFR-SEC-001 | | Statement | “The portal shall …” with measurable wording | | Category | Security / Performance / UX / SLA & Ops | | Priority | Must / Should / Could / Won’t (now) | | Conditions | Load, environment, user group, dataset size | | Verification | Test method + required evidence | | Notes | Constraints, dependencies, assumptions |

Avoiding vague wording

Replace words like fast, secure, user-friendly with measurable rules.

| Vague | Testable rewrite | |---|---| | “The portal must be secure.” | “The portal shall enforce SSO authentication, role-based access control, and audit logging for privileged actions; verification: security test report + audit log review.” | | “Search should be fast.” | “For dataset size D and concurrent users C, search results shall return within the agreed percentile threshold; verification: performance test report on staging.” | | “The UI must be convenient.” | “Key flows shall be completable on mobile viewport width 360 px without horizontal scrolling; verification: responsive UI checklist + manual test.” |

For requirement wording consistency, many teams use the interpretation guidance from RFC 2119.

Security NFRs: what to specify for a portal

Security NFRs protect identities, data, and administrative capabilities. They also shape architecture, integrations, and operating model.

If you need a structured checklist for web application security verification, use OWASP Application Security Verification Standard (ASVS).

Identity and authentication

Specify:

authentication method (SSO, MFA policy, password rules if local auth exists)

session rules (idle timeout, absolute timeout, re-authentication for sensitive actions)

account lifecycle (provisioning, deprovisioning, role assignment sources)

If identity assurance is important, reference NIST SP 800-63 Digital Identity Guidelines.

Authorization and access control

Even if roles were described in functional requirements, security NFRs should state enforcement properties:

access checks are server-side, not only in UI

default-deny behavior for protected resources

least privilege for administrative actions

Data protection and privacy

Specify:

data classification assumptions (public/internal/confidential)

encryption in transit (TLS) and at rest (if applicable)

storage rules for personal data (fields, retention, masking in non-production)

file upload constraints (allowed types, virus scanning if required)

Logging, auditability, and traceability

A portal usually needs two different log “views”:

operational logs for troubleshooting

audit logs for accountability (especially for admins and editors)

OWASP guidance: OWASP Logging Cheat Sheet.

Security testing and vulnerability management

Specify what security evidence you expect:

static and dependency scanning (if required)

penetration testing scope and timing

vulnerability remediation SLAs by severity

Example security NFRs

| ID | Requirement | Priority | Verification evidence | |---|---|---|---| | NFR-SEC-001 | The portal shall authenticate users via corporate SSO and reject direct password login unless explicitly approved. | Must | Configuration review + login test cases | | NFR-SEC-002 | The portal shall enforce server-side authorization for all protected API endpoints based on the approved role model. | Must | Security test report + code review evidence (if agreed) | | NFR-SEC-003 | Privileged actions (role changes, permission edits, content publish) shall be recorded in an audit log with actor, timestamp, action, object, and source context. | Must | Audit log export + audit checklist | | NFR-SEC-004 | Non-production environments shall not contain real personal data unless explicitly approved; test data shall be masked or synthetic. | Must | Environment data policy document + spot-check |

Performance and scalability NFRs

Performance NFRs must define conditions, otherwise numbers are meaningless. The same portal can be “fast” at 10 users and “slow” at 2,000.

Define a simple load model

At minimum specify:

expected concurrent users (peak and typical)

key user actions under load (home page, search, request submission, admin operations)

dataset size assumptions (documents, pages, users)

peak periods and growth expectations

Define response targets the right way

Instead of “average time”, prefer percentile targets:

p95 response time: 95% of requests are faster than the target

p99 response time: worst-case user experience under load

If you want web-focused UX performance metrics, see Web Vitals. Use them only if they match your acceptance approach.

Typical portal performance NFR areas

page load and API response time for key pages

search latency and indexing time after content publication

file download/upload limits

background jobs and integrations (batch duration, retry behavior)

Example performance NFRs

| ID | Requirement | Priority | Conditions | Verification evidence | |---|---|---|---|---| | NFR-PERF-001 | Key end-user pages shall meet the agreed p95 response target. | Must | Peak concurrency and dataset size defined in TS | Load test report on staging | | NFR-PERF-002 | Search shall return results within the agreed p95 target and support filtering without full page reload. | Should | Dataset size for indexed content specified | Performance test report + demo | | NFR-PERF-003 | After content publication, new items shall become searchable within the agreed indexing window. | Should | Indexing method and schedule agreed | Test case + logs/screenshots |

UX NFRs: what belongs in TS (and what should not)

UX-related NFRs are about experience qualities and constraints that are testable, not about pixel-perfect design.

What belongs in the TS:

accessibility requirements

responsive behavior rules

navigation and information architecture constraints (in measurable terms)

consistency rules (terminology, feedback, error handling)

usability requirements for key flows (completion without training, clarity of errors)

What usually does not belong in the TS:

full UI layouts for every page

detailed visual design decisions (colors, exact spacing) unless you are contracting design delivery with acceptance rules

Accessibility

If the portal must be accessible, specify the target standard level and what is in scope.

Reference: Web Content Accessibility Guidelines (WCAG) 2.2.

Example wording pattern:

standard and level (e.g., WCAG 2.2 AA)

scope (public pages only, or all authenticated functions)

verification method (audit checklist, automated scans, manual testing)

Error handling and feedback as UX requirements

A common portal acceptance issue is “silent failures”:

forms submit but nothing happens

integration fails and the user sees a generic error

UX NFRs should require:

clear messages for user-correctable errors

stable behavior for system errors (what the user sees and what is logged)

Example UX NFRs

| ID | Requirement | Priority | Verification evidence | |---|---|---|---| | NFR-UX-001 | The portal shall be usable on desktop and mobile viewports; key flows shall not require horizontal scrolling at 360 px width. | Must | Responsive UI checklist + manual test | | NFR-UX-002 | User-facing error messages shall be actionable and shall not expose sensitive technical details. | Must | Test cases for validation/system errors | | NFR-UX-003 | If accessibility is required, the portal shall conform to WCAG 2.2 AA for the agreed scope. | Should | Accessibility audit report |

SLA and operational NFRs: availability, support, and recovery

SLA-related NFRs define what happens after go-live and how reliability is measured. They are part of the TS because they affect architecture, monitoring, logging, and deployment approach.

Clarify SLA, SLO, and SLI (simple definitions)

SLI (Service Level Indicator): a measured metric, e.g., availability percentage, latency p95

SLO (Service Level Objective): target value for an SLI, e.g., 99.9% monthly availability

SLA (Service Level Agreement): contractual agreement that may include SLOs plus support terms, penalties, and responsibilities

A practical introduction from Google’s reliability practice: Google SRE Workbook.

!Relationship between SLI, SLO, and SLA

What to specify in the TS (even if the contract is separate)

At minimum, specify:

service hours (24/7 or business hours)

availability target and measurement window

incident severity levels and response times

monitoring and alerting expectations

backup frequency and retention

disaster recovery targets:

- RPO (Recovery Point Objective): how much data loss is acceptable - RTO (Recovery Time Objective): how fast service must be restored

Example SLA/ops NFRs

| ID | Requirement | Priority | Verification evidence | |---|---|---|---| | NFR-SLA-001 | The production portal shall meet the agreed monthly availability target, excluding planned maintenance approved in advance. | Must | Monitoring reports + uptime calculation method | | NFR-SLA-002 | Incidents shall be classified by severity and handled within agreed response and resolution time targets. | Should | Incident process description + sample runbook | | NFR-OPS-001 | The portal shall provide health checks and metrics for monitoring (application, database, integrations) and shall log errors with correlation IDs. | Must | Monitoring dashboard + log samples | | NFR-DR-001 | Backup and restore procedures shall be defined; agreed RPO/RTO targets shall be met in a restore test. | Should | Restore test report |

Verification: how NFRs become acceptance criteria

NFR acceptance should not rely on “we tested it informally”. For each NFR, specify:

test type (security, load, accessibility, recovery)

environment (staging vs production)

required artifact (report, dashboard screenshot, exported configuration)

A minimal verification mapping table:

| NFR category | Typical verification | Evidence | |---|---|---| | Security | Security review + penetration test (scope-defined) | Security test report | | Performance | Load test with agreed model | Load test report | | UX | Checklist + user flow validation + accessibility audit (if required) | UX checklist + audit report | | SLA & Ops | Monitoring + incident process + restore test | Monitoring dashboards + runbooks + restore report |

Minimal TS section template for NFRs (copy/paste outline)

Security

- authentication and session rules - authorization and access enforcement - audit logging - data protection and environment data policy - security testing and vulnerability management

Performance and scalability

- load model assumptions - latency/throughput targets for key actions - search/indexing performance (if relevant)

UX constraints

- responsive behavior - accessibility target (if required) - error messaging and user feedback rules

SLA & operations

- availability target and measurement - support windows and incident handling - monitoring/logging requirements - backups and disaster recovery (RPO/RTO)

Practical checklist before you send the TS to a contractor

Each NFR is measurable and has a verification method and evidence type.

Performance targets include load and dataset assumptions.

Security requirements cover SSO/session rules, authorization enforcement, audit logging, and environment data policy.

UX requirements are expressed as testable constraints, not subjective design preferences.

SLA/ops requirements define availability measurement, incident handling, and recovery expectations.

NFR IDs exist in the catalog and can be traced to acceptance activities and responsible owners.

Интеграции и данные: API, миграции, отчёты, аналитика

Интеграции и данные — зона, где портальные проекты чаще всего “ломаются” на сроках и приёмке. В предыдущих статьях курса мы:

зафиксировали роль ТЗ как контракта ожиданий (цели, границы, приёмка)

научились собирать требования у стейкхолдеров

собрали структуру ТЗ и описали функциональные и нефункциональные требования

В этой статье мы разберём, как в ТЗ описывать интеграции и данные так, чтобы подрядчик мог:

оценить сложность и риски

выбрать корректную архитектуру обмена

заранее согласовать API и модели данных

провести миграции без потери качества

подготовить отчёты и аналитику с проверяемыми критериями приёмки

!Карта внешних систем и видов обмена помогает не пропустить интеграции и сразу определить типы контрактов

Термины, которые нужно понимать одинаково

Интеграция — обмен данными и/или командами между порталом и внешней системой.

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

Источник истины — система, которая считается “правильной” для конкретной сущности или поля (например, ФИО сотрудника берётся из HR, а не редактируется в портале).

Сущность — объект данных (например, Пользователь, Заявка, Документ, Подразделение).

Миграция — перенос данных из старых источников в новый портал.

Отчёты — выгрузки и сводки для бизнеса и эксплуатации.

Аналитика — метрики, события и показатели использования, которые собираются и анализируются (в портале, в BI или в хранилище).

Что обязательно описывать в ТЗ по интеграциям

Проблема формулировки “интеграция с системой X” в том, что она не отвечает на ключевые вопросы: что именно синхронизируем, кто владелец, как часто, что делаем при ошибке, как принимаем результат.

Минимальный перечень для каждой интеграции

цель интеграции (какую функцию поддерживает)

системы-участники и владельцы (кто согласует изменения)

сущности и поля (что передаём)

источник истины по сущности и по критичным полям

способ обмена (REST/GraphQL, события, файлы)

протокол безопасности (аутентификация, авторизация, сети)

частота и задержки (онлайн, по расписанию)

ограничения (лимиты, объёмы, окна обслуживания)

обработка ошибок и повторов

требования к логам и аудиту

критерии приёмки и доказательства (тесты, отчёты, логи)

Шаблон “контракта интеграции” для ТЗ

| Поле | Как писать в ТЗ | Пример | |---|---|---| | Integration ID | Уникальный идентификатор | INT-HR-01 | | Название | Коротко | Профиль сотрудника из HR | | Цель | Зачем | Показ ФИО/подразделения/руководителя в профиле | | Участники | Системы и владельцы | Портал (владелец: ИТ), HR (владелец: HRIS) | | Сущности | Перечень сущностей | Employee, Department | | Источник истины | По сущности и ключевым полям | Employee.FIO — HR | | Способ обмена | API/события/файлы | REST API | | Триггер/частота | Когда запускается | При логине + ночная синхронизация | | SLA/ожидания | Допустимые задержки | Обновление профиля не позднее 24 часов | | Ошибки | Поведение при сбое | Показ последнего значения, запись в лог, алерт | | Безопасность | Как защищено | mTLS/VPN, OAuth 2.0 client credentials | | Критерии приёмки | Что проверяем | Тестовый пользователь отображает корректное подразделение |

API в ТЗ: что нужно зафиксировать, чтобы подрядчик мог разработать и протестировать

Спецификация API как артефакт

Чтобы не обсуждать интеграцию “на словах”, в ТЗ стоит требовать спецификацию API (или приложить, если уже есть). На практике чаще всего используют OpenAPI.

стандарт: OpenAPI Specification

смысл для ТЗ: подрядчик видит эндпоинты, схемы данных, коды ошибок, а QA получает основу для тестов

В ТЗ можно указать: “API должно быть описано в OpenAPI, версия X.Y, размещено в репозитории/каталоге API, изменения через согласование”.

Что фиксировать по каждому API-методу

| Что описать | Зачем это нужно подрядчику и приёмке | |---|---| | URL, метод, назначение | однозначность реализации | | параметры и формат | чтобы не “догадываться” о структуре | | схема ответа | чтобы не менять фронт/бэкенд на поздней стадии | | коды ошибок и тексты | чтобы UX и поддержка работали предсказуемо | | требования к авторизации | чтобы не возникли блокирующие требования ИБ на финише | | идемпотентность | чтобы повторы запросов не создавали дубликаты | | пагинация/фильтрация/сортировка | чтобы API выдержало объём данных | | ограничения (rate limits) | чтобы портал не “положил” внешнюю систему |

Аутентификация и авторизация для интеграций

В ТЗ важно развести два класса:

пользовательские вызовы (от имени пользователя, например “показать мои заявки”)

сервисные вызовы (межсервисные, например “синхронизировать справочник подразделений”)

Для OAuth 2.0 полезен базовый ориентир: RFC 6749.

Если используется OpenID Connect для SSO, фиксируйте, что это именно OIDC, и опирайтесь на: OpenID Connect Core 1.0.

В ТЗ обязательно укажите:

где хранятся секреты и как они ротируются

какие окружения (dev/test/prod) и какие учётные данные на каждом

сетевые требования (VPN, allowlist, mTLS)

Версионирование API и совместимость

Чтобы изменения не ломали портал, зафиксируйте:

стратегию версионирования (например, /v1/ в URL или заголовки)

правила обратной совместимости (что считается “ломающим” изменением)

окно поддержки старых версий

События и файлы: когда API недостаточно

Не все интеграции выгодно делать синхронными API-вызовами.

Когда выбирать события

Событийный обмен уместен, если:

нужна реакция на изменения (например, “Заявка согласована”)

важна устойчивость при временной недоступности системы-получателя

нужно разгрузить источники от частых запросов

В ТЗ для событий фиксируйте:

перечень событий и их схемы

гарантии доставки (минимум: “хотя бы один раз” или “ровно один раз”)

правила дедупликации (как портал распознаёт повтор)

обработку “ядовитых” сообщений (куда попадают ошибки, кто разбирает)

Когда выбирать файлы

Файловый обмен (CSV/XLSX/XML) допускается, если:

интеграция исторически файловая и менять её дорого

нужен периодический импорт справочника

это временный мост до API

В ТЗ обязательно зафиксируйте:

формат, кодировку, разделители, примеры файлов

место обмена (SFTP, защищённое хранилище)

расписание и часовой пояс

правила валидации и отчёт об ошибках

Данные: источники истины, идентификаторы, качество

Матрица “сущность → источник истины”

Это один из самых полезных артефактов в ТЗ. Он снижает споры в стиле “почему в портале не так, как в CRM”.

| Сущность/данные | Источник истины | Где используется в портале | Комментарий | |---|---|---|---| | Пользователь (ФИО, табельный) | HR | Профиль, права, персонализация | Редактирование в портале запрещено | | Клиент | CRM | ЛК клиента, заявки | В портале только чтение | | Заявка (статусы) | Service Desk | Трекинг, уведомления | Портал создаёт, Service Desk ведёт жизненный цикл | | Документ (файл, версия) | DMS | Библиотека документов | В портале хранится ссылка + метаданные |

Идентификаторы и сопоставление записей

В ТЗ важно определить:

ключи: какой id является первичным (табельный номер, GUID, внешний ключ)

правила сопоставления при миграции и синхронизации

поведение при конфликте (два разных пользователя с одинаковым email)

Если это не определить, подрядчик будет вынужден выбирать “по умолчанию”, что затем сложно согласовать.

Временные зоны, локали и форматы

Даже в “простом” портале возникают ошибки, если не договориться заранее:

какой часовой пояс используется для дат (например, для SLA заявок)

какие форматы отображения дат в UI

как хранить даты в базе и передавать в API

Фиксируйте в ТЗ: “хранение времени в UTC, отображение — в локальном часовом поясе пользователя (если определён) или в часовом поясе компании”.

Миграции: как описать в ТЗ так, чтобы это можно было принять

Миграция — это не “одна задача”, а управляемый процесс. В ТЗ важно превратить её в набор проверяемых поставок.

Что нужно определить до оценки подрядчиком

какие источники данных (старый портал, файловые хранилища, базы)

что именно переносим (сущности, объём, период)

какие данные переносим “как есть”, а какие чистим

кто отвечает за качество данных (обычно заказчик подтверждает правила)

как подтверждаем корректность (выборочная сверка, контрольные отчёты)

Шаблон раздела “миграция данных” в ТЗ

| Блок | Что указать | |---|---| | Объекты миграции | сущности и поля, включая вложения | | Объём | количество записей, размер файлов, ожидаемый рост | | Трансформации | правила преобразования (например, справочник подразделений) | | Очистка данных | что делаем с дублями, пустыми полями, устаревшими документами | | Права и доступы | кто видит мигрированные данные | | Миграционные прогоны | тестовый прогон, предбоевой прогон, финальный прогон | | Окно миграции | дата/время, допустимый простой | | Откат | что делаем, если миграция провалилась | | Приёмка миграции | метрики и отчёты сверки |

Критерии приёмки миграции (примеры)

перенесено не менее согласованного процента записей, остальные попали в отчёт ошибок

для согласованной выборки записей совпадают ключевые поля “источник → портал”

вложения открываются, версии документов соответствуют правилам

настроены редиректы (если меняются URL) или опубликована карта соответствий

!Процесс миграции как последовательность этапов и контрольных точек приёмки

Отчёты и аналитика: что нужно описать в ТЗ

Важно разделять:

операционные отчёты (для ежедневной работы и контроля процессов)

аналитику использования (как портал применяется, где “узкие места”)

BI/корпоративную аналитику (если есть хранилище и BI-платформа)

Операционные отчёты

Для каждого отчёта в ТЗ укажите:

цель отчёта и пользователь отчёта

фильтры (период, подразделение, тип заявок)

поля и источники (из какой системы данные)

частоту обновления

экспорт (CSV/XLSX), права доступа

Пример спецификации отчёта:

| Атрибут | Пример | |---|---| | Report ID | REP-REQ-01 | | Название | Заявки по статусам | | Пользователи | Руководители подразделений, Service Desk | | Фильтры | период, подразделение, тип заявки | | Поля | номер, тип, статус, дата создания, дата изменения | | Частота | онлайн, обновление при изменении статуса | | Экспорт | XLSX, доступен только роли Manager |

Аналитика использования портала

Чтобы аналитика была пригодна, в ТЗ фиксируют не “подключить аналитику”, а событийную модель.

#### Минимальный набор событий

просмотр ключевой страницы (например, “Главная”, “Поиск”, “Каталог документов”)

использование поиска (запрос, фильтры, результат)

создание заявки и завершение (успех/ошибка)

публикация контента (для редакторских процессов)

#### Спецификация события

| Поле | Пример | |---|---| | Event ID | EVT-SRCH-01 | | Название | search_performed | | Когда отправляется | пользователь нажал “Найти” | | Атрибуты | роль, раздел, длина запроса, выбранные фильтры, количество результатов | | Исключения | не отправлять содержимое запроса, если есть чувствительные данные | | Цель метрики | оценка качества поиска и потребности в контенте |

Если в компании используется наблюдаемость (логи, метрики, трассировки), полезно опираться на практики OpenTelemetry: OpenTelemetry Documentation.

Приватность и ограничения аналитики

Даже для внутреннего портала важно заранее договориться:

какие персональные данные запрещено писать в события/логи

кто имеет доступ к аналитическим дашбордам

срок хранения аналитики

Эти пункты снижает риск, что ИБ или комплаенс заблокируют запуск на финальном этапе.

Проверяемость: как интеграции и данные становятся частью приёмки

Чтобы избежать ситуации “интеграция вроде есть, но работает нестабильно”, в ТЗ фиксируйте артефакты приёмки.

Что можно требовать как доказательства

спецификации API (OpenAPI) и примеры запросов/ответов

стендовые тест-кейсы интеграций и отчёт о прогоне

журнал ошибок интеграций и описание обработки повторов

отчёты сверки для миграции (количество, проценты, выборочная проверка)

дашборды/отчёты по аналитике и проверка отправки ключевых событий

Пример таблицы “интеграция → тесты → доказательства”

| Integration ID | Что тестируем | Где тестируем | Доказательство | |---|---|---|---| | INT-HR-01 | профиль сотрудника подтягивается и обновляется | staging | протокол теста + лог синхронизации | | INT-SD-02 | создание заявки и получение статуса | staging | тест-кейсы + скриншоты статусов | | INT-DMS-03 | доступ к документам по правам | staging | список проверочных пользователей + результаты |

Типовые ошибки в ТЗ по интеграциям и данным

нет источника истины, из-за чего системы “перетягивают” данные

частота обмена и задержки не описаны, и ожидания расходятся

нет поведения при сбоях (повторы, дедупликация, очередь ошибок)

миграция описана одной строкой без объёма и критериев приёмки

аналитика сформулирована как “подключить”, но нет событий и ограничений по данным

Что должно появиться в вашем ТЗ после этой статьи

реестр интеграций с контрактом на каждую интеграцию

матрица “сущность → источник истины”

требования к API (спецификация, безопасность, версии, ошибки)

раздел “миграция данных” с объёмом, правилами трансформаций и критериями приёмки

перечень отчётов и событий аналитики с атрибутами и ограничениями

привязка интеграций и миграции к приёмке через тесты и доказательства

Критерии приёмки: тестирование, документация, изменения и риски

Критерии приёмки в ТЗ превращают абстрактное «сделайте портал» в проверяемую договорённость: что именно считается готовым, как это будет проверяться, какие артефакты должны быть переданы, как фиксируются изменения и как управляются риски.

В предыдущих статьях курса вы:

зафиксировали цели, границы и ожидания сторон

собрали и нормализовали требования от стейкхолдеров

собрали структуру ТЗ и научились задавать функциональные и нефункциональные требования

описали интеграции, данные, миграции, отчёты и аналитику как контракт

Эта статья связывает всё это в единый механизм: приёмка как процесс, а не финальная встреча.

!Схема показывает, как требования превращаются в тесты и доказательства для приёмки

Что такое критерии приёмки и чем они отличаются от требований

Требование отвечает на вопрос что нужно (и иногда при каких условиях). Критерий приёмки отвечает на вопрос как мы докажем, что это сделано.

Типовая ошибка ТЗ: требования есть, но нет чётких правил, по которым заказчик принимает работу. Тогда приёмка превращается в спор вкусов или в «дописывание ТЗ задним числом».

Минимальная единица приёмки

Минимально удобная единица для проекта портала:

требование с ID

приоритет

способ верификации

ожидаемый результат

артефакт-доказательство

Это применимо и к функциональным требованиям, и к нефункциональным, и к интеграциям/миграциям.

Модель приёмки по этапам: чтобы не принимать «всё сразу»

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

Рекомендуемые приёмочные гейты

Приёмка требований: согласование каталога требований, scope и критериев

Приёмка прототипов ключевых потоков: подтверждение сценариев и ролей

Приёмка функционала по релизам: демонстрация + тесты

Интеграционная приёмка: тест-кейсы по контрактам интеграций

Приёмка нефункциональных требований: безопасность, производительность, доступность

Приёмка миграции: отчёты сверки + выборочная проверка

UAT: пользовательская приёмка на стенде

Go-live готовность: чек-лист эксплуатации, мониторинг, бэкапы, инструкции

> Практика разделения целей надёжности на измерения и контроль через SLI/SLO подробно описана в книге Google по SRE: Site Reliability Engineering (free online book).

Трассируемость: привязка требований к тестам и доказательствам

Трассируемость нужна, чтобы на вопрос «почему это делаем?» и «как принимаем?» отвечать ссылкой на конкретные ID, а не перепиской.

Таблица трассируемости (шаблон для ТЗ)

| Цель/ценность | Требования | Проверка | Доказательства | |---|---|---|---| | Снизить нагрузку на поддержку по статусам заявок | FR-REQ-002, FR-REQ-007 | UAT-12, TC-REQ-18 | протокол UAT + скриншоты/видео демо | | Соблюсти требования ИБ | NFR-SEC-001..004 | SEC-PT-01, SEC-CHK-02 | отчёт пентеста + экспорт настроек | | Обеспечить стабильную работу на пике | NFR-PERF-001..003 | PERF-LOAD-01 | отчёт нагрузочного теста |

Правило для ТЗ: у каждого приёмочного пункта должен быть артефакт, который подрядчик способен предоставить.

Тестирование: что фиксировать в ТЗ, чтобы оно было приемлемым

ТЗ не должно превращаться в тест-план на сотни страниц. Но оно обязано фиксировать:

виды тестирования

окружения и данные

входные/выходные критерии

кто участвует и кто утверждает

какие отчёты считаются доказательством

Виды тестирования и их смысл для приёмки

| Вид тестирования | Что проверяет | Типичный артефакт | |---|---|---| | Функциональное | соответствие сценариям/ролям/статусам | набор тест-кейсов + протокол прогона | | Интеграционное | обмен с внешними системами по контрактам | протокол интеграционных тестов + логи | | Регрессионное | что новое не сломало старое | отчёт регрессии, список проверенных кейсов | | Безопасность | уязвимости, контроль доступа, аудит | отчёт сканирования/пентеста, чек-лист OWASP | | Производительность | время отклика под нагрузкой | отчёт нагрузочного тестирования | | UAT | пригодность для пользователей и процессов | протокол UAT с результатами |

Для формализации требований к безопасности полезно ссылаться на признанные чек-листы, например: OWASP ASVS.

Окружения и данные для приёмки

В ТЗ обычно фиксируют:

перечень окружений: dev/test/staging/prod

где проводится UAT и нагрузка (обычно staging)

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

кто предоставляет тестовых пользователей по ролям

Таблица, которая часто спасает сроки:

| Окружение | Кто предоставляет доступ | Какие данные разрешены | Для чего используется | |---|---|---|---| | Staging (UAT) | заказчик + подрядчик | маскированные/синтетические | UAT, интеграции, нагрузка | | Production | эксплуатация заказчика | реальные | запуск и эксплуатация |

Definition of Done: «готово» на уровне фичи и релиза

В ТЗ полезно зафиксировать определение готовности, чтобы не принимать полуфункцию.

Пример Definition of Done для функциональной фичи:

реализовано требование(я) с указанными ID

пройдены тест-кейсы по критичным сценариям

учтены права доступа и серверная проверка доступа

добавлено логирование/аудит, если требуется

обновлена пользовательская и админская документация

известные ограничения зафиксированы и согласованы

Пример Definition of Done для релиза:

выполнена регрессия согласованного объёма

подготовлены release notes

подтверждены бэкапы и план отката

мониторинг и алерты настроены

Критерии приёмки по нефункциональным требованиям

Нефункциональные требования принимаются не демонстрацией, а доказательствами.

Безопасность

В ТЗ фиксируют:

что считается успешным прохождением проверки (например, нет критических уязвимостей)

кто проводит проверку (внутренний ИБ, внешний подрядчик)

какой скоуп пентеста (какие модули, роли, интеграции)

какие артефакты передаются (отчёт, подтверждение исправлений)

Практичный критерий:

критические и высокие уязвимости отсутствуют или закрыты до запуска

средние закрываются в согласованный срок по плану

доступы и аудит по ролям подтверждены чек-листом

Производительность

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

В ТЗ закрепляют:

сценарии нагрузки (например, главная, поиск, карточка документа, создание заявки)

метрики и порог (например, p95 по ключевым запросам)

окружение и инструмент прогона

формат отчёта

UX и доступность

UX в приёмке — это проверяемые ограничения, а не «нравится/не нравится».

Если нужна доступность, фиксируйте стандарт и уровень, например: WCAG 2.2.

Примеры проверяемых критериев:

ключевые сценарии выполняются на мобильном экране без горизонтального скролла

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

(если применимо) доступность соответствует согласованному уровню WCAG по выбранному охвату

Документация и поставка результатов: что именно передаёт подрядчик

Ошибка: считать, что результат проекта — только работающий портал. Для эксплуатации и снижения рисков нужны документы и артефакты.

Минимальный набор поставки (рекомендуемый для ТЗ)

исходный код и инструкции сборки/развёртывания (если применимо)

описание архитектуры на уровне компонентов и интеграций

документация администратора: пользователи, роли, настройки, аудит

пользовательская инструкция для ключевых сценариев

документация по интеграциям: OpenAPI/контракты, параметры окружений

эксплуатационные артефакты: мониторинг, алерты, бэкапы, план восстановления

результаты тестирования: протоколы, отчёты

список известных ограничений и технического долга (если остаётся)

Таблица «артефакт поставки → критерий приёмки»

| Артефакт | Критерий приёмки | Кто принимает | |---|---|---| | Руководство администратора | покрывает роли, права, публикации, аудит; актуально текущей версии | эксплуатация/ИТ | | OpenAPI для интеграции INT-HR-01 | соответствует фактическим эндпоинтам; содержит схемы и ошибки | интеграционная команда | | Отчёт нагрузочного теста | выполнен по согласованной модели; содержит вывод «порог достигнут/нет» | ИТ + владелец продукта | | Release notes | перечисляет изменения, миграции, известные ограничения | владелец продукта |

Управление изменениями: как дополнять ТЗ без «развала сроков»

Любой портал развивается. Вопрос не в том, будут ли изменения, а в том, как они оформляются.

В ТЗ важно закрепить процесс change control:

что считается изменением (новое требование, изменение критерия приёмки, новая интеграция)

кто подаёт запрос

кто оценивает влияние (подрядчик)

кто утверждает (владелец продукта/спонсор)

как меняются сроки/стоимость/scope

как версионируются требования и документ

Шаблон карточки Change Request (CR) для ТЗ

| Поле | Пример | |---|---| | CR ID | CR-014 | | Описание изменения | Добавить согласование публикаций для роли Editor | | Причина | Требование комплаенса | | Затронутые ID требований | FR-CNT-008, NFR-SEC-003 | | Влияние | +10 дней, +N бюджета, новые тест-кейсы | | Решение | Approved/Rejected/Deferred | | Дата вступления | релиз 1.2 |

Практика формулирования обязательности слов MUST/SHOULD полезна для единообразия, см.: RFC 2119.

Риски: что фиксировать в ТЗ и как связывать с приёмкой

Риск в проекте портала — это событие или условие, которое может сорвать сроки, бюджет или качество. Управление рисками в ТЗ нужно не ради формальности, а чтобы:

заранее выявить блокеры (особенно интеграции и ИБ)

договориться о действиях при наступлении риска

иметь прозрачные критерии переноса сроков или изменения объёма

Реестр рисков (минимальный формат)

| Risk ID | Риск | Триггер | Последствие | Митигирующее действие | Владелец | |---|---|---|---|---|---| | R-INT-01 | API HR недоступно/нестабильно | ошибки 5xx, частые таймауты | срыв сроков интеграции | ранний тест стенда, кеширование, режим деградации | владелец HR API | | R-SEC-02 | ИБ не согласовала модель ролей | нет утверждения NFR-SEC | блок запуска | воркшоп ИБ на ранней фазе, чек-лист OWASP | ИБ | | R-DATA-01 | низкое качество данных для миграции | много дублей/пустых полей | рост стоимости и сроков | правила очистки, пилот миграции | заказчик |

Режим деградации как часть критериев приёмки

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

Пример формулировки:

при недоступности HR API портал показывает последние синхронизированные данные и пишет ошибку в журнал с корреляционным ID

Минимальный раздел ТЗ «Критерии приёмки» (каркас)

Чтобы подрядчик мог оценить и выполнить, раздел удобно делать компактным, но строгим:

Приёмочные этапы и ответственные

Definition of Done (фича/релиз)

Матрица трассируемости «требование → тест → доказательство»

Правила UAT: вход/выход, сроки, порядок фиксации дефектов

Набор обязательных артефактов поставки

Процесс управления изменениями (CR)

Реестр ключевых рисков и план реагирования

Что должно получиться по итогам статьи

После добавления этой темы в ваше ТЗ подрядчик и заказчик должны одинаково понимать:

какие проверки обязательны и где они выполняются

какие документы и отчёты являются доказательствами готовности

как именно принимается функционал, интеграции, миграции и NFR

как оформляются изменения и как они влияют на сроки/стоимость

какие ключевые риски признаны и кто ими управляет