11. Требования к программной документации

11.1 Общий подход

Настоящее техническое задание является основным техническим документом программного продукта.

В составе настоящего технического задания фиксируются:

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

Отдельные документы не должны дублировать техническое задание. Дополнительная документация должна описывать только то, что необходимо для использования, эксплуатации или интеграции программного продукта и не раскрыто в настоящем документе в достаточном объеме.

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

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

клиент
менеджер
суперменеджер

Пользовательская документация должна описывать:

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

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

11.3 Эксплуатационная документация

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

Эксплуатационная документация должна описывать:

состав сервисов и их назначение
порядок запуска и перезапуска сервисов через согласованный контур деплоя
используемые окружения и общие принципы конфигурации
порядок загрузки секретов из Vault
порядок просмотра логов и диагностики типовых сбоев
порядок проверки работоспособности клиентского, менеджерского и интеграционного контуров
порядок обновления приложения через Git и Dokploy
перечень технических контактов или зон ответственности, если они согласованы сторонами

Эксплуатационная документация не должна содержать бизнес-секреты, токены, пароли и иные чувствительные значения. Для секретов указываются только имена переменных, назначение и источник получения.

11.4 Интеграционная документация

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

Интеграционная документация должна описывать:

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

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

11.5 Перечень сторонних компонентов

Перечень сторонних компонентов формируется на основании фактических файлов проекта, включая package.json, lock-файлы, Dockerfile и конфигурационные файлы сервисов.

Перечень должен содержать:

наименование компонента
версию или диапазон версий
назначение компонента в продукте
источник установки или репозиторий, если он отличается от стандартного пакетного менеджера

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

7.3 KiB Raw Blame History Unescape Escape