Плюсы, минусы, подводные камни спецификаций - на примере Единой информационной системы жилищного строительства (ЕИСЖС).

Информационно и технически Единая информационная система жилищного строительства (ЕИСЖС) позволяет переводить отрасли жилищного строительства на проектное финансирование.

Каждый сервис внутри ЕИСЖС — это сложная информационная система с большим количеством интеграций, и поэтому увеличение количества разрабатываемых сервисов требует структурированного подхода к аналитике всех проектов.

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

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

Основа нашего подхода в части аналитики - шаблон спецификации требований, который разработан с учетом особенностей систем внутри ЕИСЖС и рабочих процессов при разработке программного обеспечения внутри ДОМ.РФ.

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

В отличие от технического задания (как приложения к договору) или постановки - в виде описания в трекере задач, - спецификация описывает актуальные требования к системе с учетом всех ранее выполненных изменений. Система меняется, и вместе с ней меняется спецификация. По спецификации можно отследить как путь развития системы, так и актуальное состояние системы.

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

• Бизнес-заказчик;

• Аналитик;

• Архитектор;

• Разработчик;

• Тестировщик;

• Технический писатель.

 Вот, что дает нам единый подход, понятный и привычный всем участникам процесса развития ЕИСЖС:

• позволяет сократить время на погружение нового специалиста в проект, а также на переключение сотрудников ИТ-подразделения между проектами;

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

• облегчает восприятие IT-информации для сотрудников бизнес-подразделений, в интересах обеспечения деятельности которых разрабатываются сервисы;

• приводит к тому, что спецификация согласуется с заказчиком, поэтому записи спецификации являются зафиксированной договоренностью между исполнителем и заказчиком;

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

В основе рассматриваемого шаблона лежит подход Boundary-Control-Entity, который лучше других подходит к разрабатываемым нами системам и проектам.

Его принцип - в декомпозиции требований на три слабосвязанных слоя: требования к данным, требования к функциям и требования к интерфейсу.

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

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

Как оценить качество нашей спецификации?

Мы используем основные классические свойства:

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

• Завершенность. Требование полностью определено в одном месте, и вся необходимая информация присутствует (необходимо избегать повторного описания требования в разных местах). Например, описание проверки ФЛК может быть описано и в сценарии, и в описании интерфейса. Такое дублирование с высокой долей вероятности приедет к нарушению целостности спецификации и появлению противоречий. Поэтому описывайте каждое требование только один раз и используйте ссылки.

• Атомарность. Спецификация не может быть разбита на более мелкие требования без потери завершенности.  Каждый элемент не может быть декомпозирован на более мелкие требования. При этом необходимо придерживаться здравого смысла, не вынося в отдельное описание каждое поле. В нашем случае мы пришли к тому, что отдельная страница спецификации (страница wiki) должна содержать описание одного элемента, такого как “сущность”, “функция”, “элемент интерфейса” (например, витрина данных, pop-up, меню и т.д.).

• Непротиворечивость. Требование не противоречит другим требованиям. Понятие непротиворечивости тесно связано с понятием завершённости. Одно требование – одно описание!

• Идентифицируемость. Элемент спецификации должен быть однозначно идентифицируемым. Наименования элементов и страниц описания должны быть уникальным и единым в рамках спецификаций всех систем. Для этого можно использовать префикс системы, код в иерархии описания, название функции. При разработке большого количества систем - в настоящее время мы развиваем одновременно более 50 информационных систем, а поддерживаем еще больше - крайне важно поддерживать единый реестр терминов и определений, в том числе использовать для одинакового функционала одинаковые названия функций. Даже если ранее какая-то из функций (например, загрузка файла) не была выделена в микросервис, одинаковое наименование функции в целом ряде систем приведет к необходимости вынесения одинакового функционала в виде отдельного сервиса.

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

Как упоминалось выше, в нашем описании мы используем большое количество слоев. На рисунке ниже приведен раздел описания одной из систем в составе ЕИСЖС, которая называется «Каталог жилищных программ»:

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

Раздел архитектуры содержит схему развертывания. В нем отдельно следует выделить страницу нефункциональных требований. Страница фактически ведется по ГОСТ 34. Нефункциональные требования важны как при проектировании архитектуры системы, так и при разработке отчетной документации техническими писателями.

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

• Концепция продукта (или паспорт проекта). Краткое определение системы: для чего нужна, кто является пользователями, какие основные бизнес функции автоматизирует, высокоуровневая идея продукта, его полное и сокращенное название. Краткое описание назначения продукта/системы. Для систем, которые были созданы давно или другими командами, данный раздел может остаться пустым, т.к. восстановление утраченной информации и первоначальной цели проекта может быть затруднительно. Однако для новых проектов его заполнение обязательно, т.к. помогает и исполнителям, и заказчикам точнее сформулировать назначение системы в целом.

• Глоссарий. Содержит ссылку на единый глоссарий всех систем ЕИСЖС, но также расширяет его уникальными для данной системы терминами и определениями.

• Бизнес-модель. Описание предметной области (сущности, автоматизируемые бизнес-процессы). Аналитик описывает понятными айтишнику словами основные требования к общей концепции системы и к бизнес-процессам в целом, основываясь на нормативной документации или иных документах, регламентирующих функции системы. До начала разработки содержание раздела согласуется с заказчиком (в нашем случае - сотрудниками бизнес-подразделений ДОМ.РФ) и помогает выстроить единый взгляд на бизнес-процессы продукта.

• Описание пользователей. Кто является пользователями (в т.ч. и внешние системы). В сценариях данные пользователи должны будут выступать в качестве участников. Позволяет выявить лишних пользователей или недостаточность пользовательских ролей. При описании пользователей необходимо следить, чтобы в сценариях не было пользователей, не описанных в этом разделе, а также чтобы все описанные здесь пользователи выступали участниками в планируемых сценариях.

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

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

Отдельный вид сущности – статусная модель. Помимо статусной модели в виде таблицы необходимо приводить варианты переходов между статусами, как минимум в виде последовательности статусов в той же таблице, либо в виде отдельной диаграммы.

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

• Требования к функциям. Рекомендуется приводить в виде вариантов использования (use case), где это возможно. Надо обязательно указывать участников, цель, активаторы (какое событие является начальным), предусловия и постусловия выполнения сценария. Если в сценарии возможны различные ветки, необходимо описывать все альтернативные сценарии. Важно помнить: если не описано, значит, не реализовано. Значит, будет выявлено как баг после выпуска системы в прод. Нужно определить логическую модель основных функций (диаграмма прецедентов).

• Требования к интерфейсу. Можно разделить на два вида: пользовательский интерфейс и программный (API).

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

Для разработки макетов наши дизайнеры используют figma. Однако при описании пользовательских интерфейсов лучше не ограничиваться ссылкой на figma. Мы рекомендуем помимо ссылки приводить так же скриншоты: figma сторонний инструмент, и мы не может гарантировать его доступность в будущем. Вкладывание скриншотов позволяет отследить изменения в макетах figma, которые не были описаны по тем или иным причинам. Однако следует помнить, что в случае отсутствия дизайнера на проекте возможны случаи “отставания” макетов и скриншотов от описания, поэтому считаем, что для разработчика приоритетно описание.

Для каждого элемента интерфейса необходимо указать:

• обозначение;

• тип (например, выпадающий список, текстовое поле, кнопка);

• требования ФЛК (при наличии);

• источник данных, т.е. маппинг экранной формы и сущностей, либо формулу для вычисления, если поле вычисляемое, либо условные выражения, которые будут использованы для заполнения поля);

• условия доступности/видимости;

• комментарий при необходимости.

Описание программных интерфейсов также стандартизировано. В wiki должны быть созданы разделы для интерфейсов разрабатываемой системы и для используемых интерфейсов смежных систем (при наличии).

• Требования к шаблонам и печатным формам

Данный раздел необходим, если в системе есть генерируемые печатные формы либо входящие документы, которые должны быть оформлены по шаблону. Все требования к этим документам приводятся в отдельном разделе, который должен содержать маппинг полей шаблона/документа полям БД для печатных форм, заполняемых значениями из БД, формулы для расчета показателей в случае необходимости. Для документов, которые загружаются в систему извне, приводятся требования к ФЛК, которые необходимо выполнить при приеме документа в систему. В разделе должны быть приложены исходники/шаблоны документов, которые должны актуализироваться их по мере необходимости.

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

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

2. Ведите лист изменений (см. рисунок) на каждой странице wiki с указанием причины внесения изменений (ссылка на договор, задачу jira или иной первоисточник). При такой записи вам будет намного проще восстановить ключевые моменты изменения системы вместо того, чтобы разбираться в истории сохранения страниц без понимания, почему были внесены те или иные изменения.

3. Выделяйте изменения при доработках элементов спецификации любым удобным вашей команде способом. Например, на рисунке ниже видны два этапа внесения изменений в требования ФЛК, каждое из которых было вызвано внесением изменений в нормативные документы, регламентирующие функционирование системы.

В комментариях к этой же странице обязательно указывайте причину внесения изменений, например: