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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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