Skip to main content

Составление ТЗ

В тексте периодически встречаются слова Модель и Справочник. Здесь это синонимы.

Шаблон для описания структуры данных

https://docs.google.com/document/d/1HFmzIuHap1sfu1RYq-Hu81rl3auIXiYjnnlVV6ebBjE/edit?usp=sharing

Шаблон ТЗ (возможно, устарело)

https://docs.google.com/document/d/1ih62LIWJADSaADf5_WOs3-n6jQcRxs82hTnSUjxAcuE/edit#

Структура ТЗ

Основные части технического задания:

  1. Оглавление, терминология, основание для разработки
  2. Карта сайта
  3. Структура данных (Model)
  4. Страницы и их описание (View)
  5. Функционал (Controller)
  6. Глобальные настройки сайта
  7. Языковые версии сайта
  8. Роли пользователей
  9. Перечень нотификаций (уведомлений) и способ информирования
  10. Требования к серверу
  11. ПО
  12. Железо
  13. Требования к браузерам/ОС пользователей Desktop
  14. Требования к браузерам/ОС пользователей Mobile
  15. Требования по доступности (масштаб, валидность, читалки, скорость загрузки и тд)

Пример карты сайта

  • Список новостей /news
  • Новость /news/{news_slug}
  • Каталог /catalog
  • Категория товаров /catalog/{category-slug}
  • Товар /catalog/category/{product_slug}

Структура данных (Model)

Структура данных состоит из

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

Пример описания полей в ТЗ

Список доступных полей Пример заполнения структуры БД

Модель: Товар

Имя параметра Описание Тип поля Обязательный Пример
Название товара Редактируется, не уникальное, максимум 200 символов Text Да Утюг Tefal SuperIron
Количество на складе Не редактируется Number Да 100
Дата создания Не редактируется DateTime Да 2021-02-17 11:23:02
slug Редактируется, уникальное, максимум 50 символов, только латинница и знаки дефиса, в нижнем регистре Text Да utjug-tefal-superiron
Описание товара Редактируется, не уникальное, максимум 2000 символов WYSIWYG Нет Благодаря функции нежного отпаривания этим утюгом вы можете пытать представителя компании Amway так, что он не потеряет сознание долгое время. Однако, для лучшего эффекта рекомендуем показывать ему обучающие видео Миши Радионова из Студии Флаг про DNS и заставлять проходить тесты. С другой стороны,

утюг все-таки гуманнее.

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

Пример описания связей

Список доступных связей и поведений при удалении Пример заполнения структуры БД

Модель М1 Модель М2 Название связи для М1 Название связи для М2 Роль М1 Роль М2 Тип связи Поля связи Поведение при удалении родителя
1 Кампания Лист или сегмент Источник получателей Кампания Child Parent морф 1 ко многим - set null
2 Кампания Отчет Отчеты Кампания Parent Child 1 ко многим - cascade
3 Юзер Список рассылки Список рассылки Получатели Child Parent 1 ко многим - restrict
4 Юзер Отчет События Получатели - - Многие ко многим type (строка) -
5 Юзер Город Город Юзер Child Parent 1 ко многим - set null

Страницы и их описание (View)

Если нет дизайна/прототипов

Иногда, нужно описать функциональность без прототипа и без дизайна. Обычно, это нужно на этапе оценки. В таком случае вы можете запомнить, как легко выделеить задачи типа View, они похожи:

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

Про вставку дизайнов/прототипов

Если у вас есть дизайн, вставляете в ТЗ картинки дизайна. Если нет дизайна, то вставляете прототипы. Не надо вставлять ссылки на прототипы или дизайны на внешних ресурсах. Если очень хочется, то можно, но картинки должны быть прямо вставлены в документ тоже. Потому что контент на внешних ссылках может измениться, а вставленная в документ картинка не может.

Как описывать прототипы

Не нужно описывать в прототипах очевидные вещи.

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

  • Что является кликабельным элементом, а что нет. Что произойдет по клику
  • Также описать, если что-то происходит при наведении курсора на элемент
  • Также описать, если элементы как-то реагируют на скролинг (прилипают к окну, анимируются, пропадают)
  • Как будет выглядеть тот или иной набор элементов (список товаров, новостей), если в нем не будет элементов или их будет мало. Или, если в каком то элементе будет слишком много текста или слишком большая картинка
  • Наоборот, как будет выглядеть набор элементов или элемент, в котором слишком много контента (наприме, в каталоге товаров описания товаров могут скрываться или обрезаться)
  • Описать попапы
  • Описать галереи
  • ВАЖНО. Описать, чем будет отличаться страница и ее функционал для разных ролей пользователей
  • Описать в чем будет отличие для страниц сущностей в разных состояниях. Например, список заказов в разных статусах, карточка товара в наличии и не в наличии

ФОС (Формы Обратной Связи)

Описать:

  • Валидацию полей
    • Необходимость заполнения полей
    • Минимальная/максимальна длина поля
    • Допустимые символы (например, только цифры)
    • Соответствие регулярному выражению (например, регулярка для емейла)
    • Кому уходит письмо (обычно, админу и отправителю)
    • Куда еще сохраняется письмо (CRM, БД, логи и тд)
  • Маски полей
  • Куда попадаем после отправки формы
  • Обработка ошибки отправки сервером

Сперва опишите общие блоки, такие как шапка и подвал.

Не надо в описании прототипов описывать бизнес-логику.

Надо ссылаться на соответствующие разделы в "Функциональных возможностях". Например, логику расчета рейтинга не надо описывать на странице списка исполнителей, но надо сослаться на описание этой логики. Так у вас не будет дублирования описания бизнес-логики и вы избежите рассинхронизации (в одном месте изменили логику, а в другом забыли).

Базовые правила в нашем ТЗ

  • Админка на наше усмотрение. Клиент дает бизнес-задачу по админке (чего хочет добиться), мы сами подбираем решение.
  • Все, что не описано в ТЗ, остается на наше усмотрение.
  • Функциональный модуль считается реализованным, если посетитель сайта может им воспользоваться.
  • Функциональность, зависящая от интеграций со сторонними сервисами может корректироваться Исполнителем в ходе работы. Все форс-мажоры интеграций с внешними системами финансово ложатся на клиента.

Общие советы по написанию ТЗ

DRY

ОЧень полезный принцип программирования, который стоит взять на вооружение. DRY — это Don't Repeat Yourself. Если вы повторяетесь, постарайтесь вынести повторение в отдельный раздел и ссылаться на него, там где это нужно. Тогда ваше ТЗ будет гораздо проще читать и в вам будет легче вносить в ТЗ исправления. Давайте я объясню. Легче читать, потому что читатель будет получать только уникальную информацию, а не повторяющиеся блоки текста. ТАкие повторы он начнет пропускать, вместе с этим, вполне вероятно, пропуская незаметные, но важные изменения. Насчет исправлений, тут причина та же, что и в программировании. Вы повторяет одно и то же. Затем вам нужно это имзенить. Вы меняете это в нескольких местах. Забываете про одно из мест. И тут ваше ТЗ начинает противоречить самому себе.

Примеры

Примеры ТЗ:

  • UNS https://yadi.sk/d/BPPUu8-M3T4sV7
    • Импорт/экспорт 1с
    • ЛК
  • Дока по интеграции ИМ с Ламодой https://docs.google.com/document/d/1mOkpHk65KcppUjtg03QRvNqgY9I47DfKyt7TnhFg2XE/edit#heading=h.gjdgxs
    • Импорт/экспорт куча примеров
  • Документация на Swagger для интеграции сайта с чем-угодно (надо залогиниться) https://wtu.flagstudio.ru/api/documentation
  • Интеграция с 1С в BeHIPO https://docs.google.com/document/d/1hldURwTbZeEON746WXBoFr6fuBeiLr0M9I795dbhfN4/edit?usp=sharing
  • Интеграция с 1С в БСГС https://docs.google.com/document/d/1PJwfnVlu--AXGNa7nmveAm-5Maa121Q5uluQviT9E-I/edit?usp=sharing