1. MAIN GOAL.

Здесь нам необходимо описать назначение продукта/разработки.

2. Предыстория и краткое изложение сути проекта.

3. Формулировка потребностей и ценность проекта/BACCM Canvas.

В этом разделе мы фиксируем потребности, что удовлетворяются с помощью разработки и ценности, которые принесет данная разработка. Эффективно использовать в сочетании с BACCM Canvas.

4. Цель проекта по SMART

Хорошо сформулированная цель позволит определить направление работы и установить конкретные критерии для оценки успеха.

5. Стейкхолдеры продукта

Указываем внутренних и внешних участников проекта. Хорошей практикой является создание матрицы стейкхолдеров или сделать анализ стейкхолдеров с помощью mindmap.

6. Границы проекта и ограничения

Определяем границы разработки, ответственность команды (за какие этапы разработки ПО отвечает команда) и ограничения, включая бизнес-правила и регуляторные требования. Будет гораздо легче проанализировать требования и ограничения от регуляторов, если в предыдущем пункте мы сделали mindmap стейкхолдеров.

7. Функциональные требования и фичи

В данном разделе описываем функционал разрабатываемого продукта. Я предпочитаю описывать их в формате user story с указанием роли пользователя в системе: «Как покупатель, я хочу иметь возможность заказать товар в пункт выдачи», «Как администратор пункта выдачи я хочу иметь возможность отсканировать QR пользователя для получения подробной информации о его товарах»

Данный подход хорошо сочетается с матрицей прав, в которой мы явно укажем, какие пользователи у нас есть и какие у них права для работы с системой. Но можно описать ФТ в формате USE CASE. Также можно зафиксировать диаграмму прецедентов, чтобы не забыть или не потерять часть функционала разработки.

8. Требования к интерфейсу

Указываем требования к дизайну и пользовательскому интерфейсу. Указываем мастхев UI элементы и взаимодействие с ними.

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

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

Это свойства, которыми должна обладать система. Приведу примеры основных видов требований.

• Безопасность. Фиксируем использование защитных протоколов и подходов. Обычно у безопасников есть требования к ПО.

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

• Поддерживаемые устройства и ОС.

• Поддерживаемые протоколы и технологии.

• Производительность. Поддержка оптимального уровня производительности. Это может заполнить архитектор или разработчик.

  — RPS. Запросы в секунду: кол-во запросов в день/кол-во секунд в день.
  — Пропускная способность: узнаём размер JSON запросов и ответов (берём данные из контракта API) и умножаем на RPS. Пример: (запрос 200 байт + ответ 200 байт) * rps = кбайт/сек.
  — Отношение записи к чтению: считаем кол-во чтений и записей в базе данных для выполнения одного полного сценария использования и делим кол-во операций чтения на операции записи.
  — Размер хранилища: умножаем сложенные элементы записи на предполагаемое кол-во операций за год.

• Языки и локализация. Указываем, какие языки должно поддерживать ПО.

• Сохранение и продолжительность хранения данных. Например, требования хранить данные о пользователях 5 лет.

• SLI. Уровень доступности. SLI — оценка работы сервиса в данный момент. SLO — договор о поддержании уровня доступности, цель которой необходимо придерживаться. SLA — уровень доступности, за нарушение которой наступают последствия, санкции.

• Версионирование ПО. Ведение учёта версий и поддерживаемого этими версиями функционала. Например, данная фича должна работать на ПО версии не ниже 1.3.

НФТ можно также указывать в виде user story.

Как пользователь, я хочу, чтобы сервис был доступен 99,9% времени с 10 до 20 каждый день.

10. Матрица прав

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

11. Вопросы и проблемные моменты

Указываем нюансы, которые необходимо учесть при разработке или раскатке ПО в прод.

1. MAIN GOAL

Необходимо разработать функционал оформления экспресс-доставки в приложении маркетплейса.

2. Предыстория и краткое изложение сути проекта

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

<Подробное описание фичи и предыстория> …

3. Формулировка потребностей и ценность проекта/BACCM Canvas

4. Цель проекта по SMART

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

5. Стейкхолдеры продукта

6. Границы проекта и ограничения

Технические границы:

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

Функциональные границы:

— Разработка и документирование разрабатываемого функционала.

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

Организационные границы:

— Разработка проекта в определенные сроки и с установленным бюджетом.

— Соблюдение законодательства и требований в области доставки и защиты персональных данных.

7. Функциональные требования

Процесс оформления заказа:

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

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

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

...

Функционал службы поддержки:

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

...

8. Требования к интерфейсу

— Необходимо учесть все функциональные требования.

— Для выбора типа доставки необходимо использовать чекбокс.

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

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

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

Производительность. Поддержка оптимального уровня производительности.

• RPS. Запросы в секунду: предполагается, что будет 50 000 активных пользователей в день, для совершения заказа в среднем потребуется 5 запросов. Соответственно, сервис должен выдерживать 50 000*5/24/60/60 = 3 запроса в секунду.

• Пиковая нагрузка: предполагается, что ежедневная пиковая нагрузка будет 20 000 в течение одного часа. Соответственно, система должна выдержать пиковую нагрузку в 20 000*5/60/60 = 27 запросов в секунду.

• Пропускная способность: запрос, в среднем, весит 200 байт, а ответ 500 байт, соответственно, система должна обеспечивать пропускную способность в (200+500)*3 = 2100 байт в секунду в обычном режиме и (200+500)*27 = 18 900 байт в секунду в пиковой нагрузке.

• Отношение записи к чтению: для одного флоу, в среднем, мы делаем 5 запросов: 4 GET-запроса, а оставшийся — POST-запрос. Соответственно, чтение данных будет в 4 запросах, а запись в 1. Отношение записи к чтению — 1/4.

• Размер хранилища: умножаем сложенные элементы записи на предполагаемое кол-во операций за 5 лет . Для одной операции необходимо 200 байт памяти в хранилище, а таких операций предполагается 1 000 000 в течение первого года. Соответственно, необходимо выделить не меньше 190 мб.

10. Матрица прав

11. Вопросы и проблемные моменты

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

1. Логика работы системы

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

• Диаграммы последовательности: показывают шаги обработки запросов к API (эндпойнтам) и кейсов использования, включая вызовы API, работу с БД и другие операции.

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

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

2. Модель данных

В этом разделе фиксируем ER-диаграмма(ы), визуализирующие разрабатываемые сущности предметной области и связи между ними.

3. API. Описание контракта

Описать API (набор методов) можно разными способами: с помощью специальных инструментов (Swagger, API Blueprint) или самостоятельно. Самое главное, чтобы ваше описание API отражало следующие свойства:

• Описание запроса. Мы должны подробно указать назначение данного метода. Потомки скажут нам спасибо.

• Тип HTTP метода.

• URL.

• Обязательные headers (заголовки).

• Входные параметры. Это path, query и body параметры запроса.

• Параметры ответа.

• Примеры запроса и ответа.

Можно использовать такой формат описания API:

[HTTP-метод] [URL]

Описание: [Краткое описание функционала]

Headers/Заголовки:

Параметры запроса:

Query и path параметры:

Body параметры:

Параметры ответа:

Примеры запроса и ответа:

Пример запроса.

[cURL запроса]

✅Успешный ответ 200 ok.

[Пример ответа в формате JSON]

❌Неуспешный ответ 400 bad request.

[Пример ответа в формате JSON]

4. Корнер кейсы для тестирования бэка

Указываем, какие кейсы могут возникнуть, которые необходимо предусмотреть заранее. Ошибка на этапе проектирования системы стоит дороже, чем на этапе разработки. Так сказать, облегчаем работу нам из будущего :)

1. Логика работы системы

Диаграмма последовательности.

Описание взаимодействия систем для эндпоинта POST /api/v1/express-orders.

Диаграмма активности

Легенда:

Серый цвет — действие пользователя.
Зеленый цвет — UI действие.
Синий цвет — сетевое взаимодействие.

Диаграмма компонентов

POST /api/v1/express-orders.

Описание: Создание экспресс-заказа.

Заголовки:

Параметры запросы:

Body параметры.

Параметры ответа:

Пример запроса:

POST /api/v1/express-orders HTTP/1.1
Authorization: Bearer [ваш токен доступа]
Content-Type: application/json

{
  "delivery_address": "ул. Пушкина, д. 1, кв. 1",
  "products": [1, 2, 3],
  "payment_method_id": 2,
  "comment": "Пожалуйста, доставьте до 18:00"
}

Пример ответа:

✅Успешный ответ 201 ok.

{
  "id": 123, // ID созданного заказа
  "status": "created"
}

❌Неуспешный ответ 400 bad request.

{
  "error": "Неверный формат запроса.",
  "details": {
    "products": 
      "Пожалуйста, укажите хотя бы один товар."
    
  }
}

4. Корнер кейсы для тестирования бэка

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

• Необходимо предусмотреть, что будет, если отправить два одинаковых запроса, сработает ли проверка на ключ идемпотентности.

1. Навигация по экранам

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

2. UI логика экранов

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

3. Локализация

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

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

1. Навигация по экранам

2. UI логика экранов

3. Локализация

1. События

События — это «кирпичики» для построения и расчёта метрик. Можно использовать такой шаблон для описания событий.

2. Метрики

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

Этапы воронки (стадия флоу пользователя):

Продуктовые метрики:

Технические метрики:

3. Логирование

Хорошей практикой является проектирование логов для разборов инцидентов заранее. Можно использовать данный шаблон для указания параметров логов:

1. События

2. Метрики

Этапы воронки.

Продуктовые метрики.

Технические метрики.

3. Логирование