Update technical specification structure

docs/tz/documentation-requirements.md

@@ -0,0 +1,89 @@
+# 11. Требования к программной документации
+
+## 11.1 Общий подход
+
+Настоящее техническое задание является основным техническим документом программного продукта.
+
+В составе настоящего технического задания фиксируются:
+
+- назначение и границы продукта
+- функциональные требования
+- роли пользователей и права доступа
+- требования к данным, сущностям и модели базы данных
+- требования к интерфейсам
+- требования к интеграциям
+- архитектура, стек, компоненты и эксплуатационный контур
+- нефункциональные требования
+- порядок контроля, приемки и гарантийного сопровождения
+
+Отдельные документы не должны дублировать техническое задание. Дополнительная документация должна описывать только то, что необходимо для использования, эксплуатации или интеграции программного продукта и не раскрыто в настоящем документе в достаточном объеме.
+
+## 11.2 Пользовательская документация
+
+Пользовательская документация должна быть подготовлена в объеме, достаточном для работы пользователей в предусмотренных ролях:
+
+- клиент
+- менеджер
+- суперменеджер
+
+Пользовательская документация должна описывать:
+
+- вход в личный кабинет и завершение регистрации
+- работу с профилем и каналами уведомлений
+- просмотр каталога готовой продукции
+- добавление товаров в корзину и отправку заявки
+- создание заявки на расчет индивидуальной продукции
+- просмотр заказов, статусов, условий и истории изменений
+- работу с бонусным кабинетом, бонусным балансом и заявками на вывод
+- действия менеджера по обработке клиентов, заявок, заказов и бонусных операций
+- действия суперменеджера в административных разделах, если они отличаются от действий менеджера
+
+Документация должна быть написана прикладным языком и ориентирована на выполнение пользовательских сценариев, а не на описание внутренней реализации.
+
+## 11.3 Эксплуатационная документация
+
+Эксплуатационная документация должна быть подготовлена в объеме, достаточном для сопровождения программного продукта после передачи результата работ.
+
+Эксплуатационная документация должна описывать:
+
+- состав сервисов и их назначение
+- порядок запуска и перезапуска сервисов через согласованный контур деплоя
+- используемые окружения и общие принципы конфигурации
+- порядок загрузки секретов из Vault
+- порядок просмотра логов и диагностики типовых сбоев
+- порядок проверки работоспособности клиентского, менеджерского и интеграционного контуров
+- порядок обновления приложения через Git и Dokploy
+- перечень технических контактов или зон ответственности, если они согласованы сторонами
+
+Эксплуатационная документация не должна содержать бизнес-секреты, токены, пароли и иные чувствительные значения. Для секретов указываются только имена переменных, назначение и источник получения.
+
+## 11.4 Интеграционная документация
+
+Для интеграции с 1С должна быть подготовлена интеграционная спецификация либо отдельный раздел настоящего технического задания, если к моменту согласования ТЗ формат обмена уже определен.
+
+Интеграционная документация должна описывать:
+
+- состав событий, передаваемых из 1С
+- состав методов получения данных из 1С
+- структуру payload для каждого события и метода
+- обязательные и необязательные поля
+- правила сопоставления идентификаторов
+- требования к авторизации, подписи или иному механизму защиты запросов
+- порядок обработки дублей
+- порядок фиксации ошибок и повторной обработки сообщений
+- критерии приемки интеграционного обмена
+
+Если точный формат обмена с 1С не определен на момент утверждения ТЗ, он фиксируется отдельной согласованной интеграционной спецификацией до начала завершающего этапа интеграции.
+
+## 11.5 Перечень сторонних компонентов
+
+Перечень сторонних компонентов формируется на основании фактических файлов проекта, включая `package.json`, lock-файлы, Dockerfile и конфигурационные файлы сервисов.
+
+Перечень должен содержать:
+
+- наименование компонента
+- версию или диапазон версий
+- назначение компонента в продукте
+- источник установки или репозиторий, если он отличается от стандартного пакетного менеджера
+
+Ключевые сторонние компоненты, используемые в текущей реализации, перечислены в разделе технической архитектуры настоящего технического задания.