Определяет типизированные, версионированные шаблоны уведомлений с утверждёнными переменными, рендерингом для конкретных каналов, локализацией с fallback, фикстурами для предпросмотра, экранированием и неизменяемым доказательством того, что было отправлено.
Статус пакета: справочный контекст готов к проверке человеком. Контракт и тестовые сценарии завершены, но не утверждается, что реализация, которая его приняла, прошла их.
Решение
Рассматривать шаблон как скомпилированный контент с типизированной схемой входных данных и неизменяемой опубликованной версией. Валидировать и рендерить по каналу, экранировать недоверенные значения в зависимости от контекста вывода и записывать точную версию шаблона плюс дайджест переменных для доказательства доставки.
Область применения
- Идентичность шаблона, схема, версии, жизненный цикл, переменные, локализация, варианты каналов, предпросмотр, утверждение, рендеринг и доказательства.
- Варианты для email, push и встроенных уведомлений, представляющие одно намерение уведомления.
- Защита контента и рендеринга.
Вне этого блока
- Политика повторной доставки или классификация предпочтений получателя.
- Разрешение произвольного исполняемого кода шаблона или удалённых включений.
Контракт
- Версия шаблона объявляет намерение, канал, локаль, схему переменных, чувствительность, обязательные ссылки и команду-владельца.
- Отправляться могут только опубликованные неизменяемые версии; правки создают новую версию.
- Доступ к переменным разрешён по списку и типизирован; отсутствие обязательных или неожиданных чувствительных переменных приводит к ошибке рендеринга.
- Экранирование следует контексту вывода для текста, HTML, компонентов URL и push-пейлоадов.
- Локализация с fallback явная и даёт один полный вариант канала, никогда не собирает предложение из смешанных локалей.
- Фикстуры предпросмотра и снимков покрывают длинные имена, пустые необязательные поля, RTL, враждебную разметку и максимальные размеры пейлоада.
Руководство по реализации
- Использовать ограниченный язык шаблонов без доступа к файловой системе, сети или произвольному коду.
- Формировать URL из утверждённых ID маршрутов и типизированных параметров, а не из авторских в шаблоне источников.
- Генерировать plain-text email из намеренно проверенного варианта, а не из ненадёжного удаления HTML.
- Сохранять ID/версию шаблона, локаль, канал, результат рендеринга и дайджест контента; ограничивать доступ к отрендеренному чувствительному контенту.
Обработка ошибок и меры защиты
- Если нет валидного fallback для локали, остановить доставку и зафиксировать ошибку рендеринга.
- Если отрендеренный вывод превышает лимиты канала, завершить с ошибкой или использовать утверждённый вариант с усечением без усечения текста действий, критичных для безопасности.
- Если опубликованная версия отозвана, сообщения в очереди следуют явной политике отмены или закрепления.
Верификация и эксплуатация
- Измерять ошибки рендеринга по шаблону/версии/локали, использованию fallback, переполнению пейлоада, отсутствию переменных и возрасту утверждения.
- Снимок-рендерить каждую опубликованную комбинацию локали/канала в CI.
- Проверять ссылки, классификацию приватности и элементы отписки или предпочтений при публикации.
Исполняющиеся на вид примеры в этом пакете — это фикстуры и контракты приёмки. Запустите
python tools/validate.py из корня коллекции для проверки структуры пакета и метаданных; затем
реализуйте и выполните сценарии в целевом репозитории.
Предположения при принятии
- Имена и числовые значения в
example.yaml— это профиль принятия, а не универсальные значения по умолчанию. - Команда, принимающая пакет, должна сопоставить акторов, классы данных, словарь ошибок и владение со своей системой.
Ссылки
- Внешний нормативный источник не требуется; этот пакет определяет решение проекта.