Документы и награды

Зачем нужно

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

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

В домене олимпиад источник для выдачи наград участникам — это AwardStatus, рассчитанный по результатам, зачёту, классу и утверждённым правилам наград. Сам PDF-документ, номер, код проверки и шаблон должны жить в общем механизме документов, но домен олимпиад задаёт правила, когда и какие документы должны быть созданы.

Что входит

Документ фиксирует:

• виды документов для участников;
• виды благодарственных писем для преподавателей, помощников, команд, организаций и площадок;
• связь AwardStatus и GeneratedDocument;
• требования к шаблонам документов;
• требования к подстановочным данным;
• правила генерации документов;
• статусы документа;
• номер документа и код проверки;
• публичную верификацию;
• права доступа;
• аудит;
• edge cases.

Что не входит

Документ не проектирует подробно:

• универсальный сервис генерации PDF;
• редактор шаблонов;
• визуальный дизайн дипломов;
• электронную подпись;
• юридическую силу документов;
• хранение файлов в инфраструктуре;
• финальные API-контракты.

4. Главный принцип модели

Нужно разделять четыре уровня.

Уровень	Что означает	Пример
AwardStatus	наградной статус по результатам	диплом 2 места
DocumentTemplate	шаблон документа	шаблон диплома 2 места для математики
DocumentGenerationJob	задание на генерацию	сгенерировать дипломы 5 класса очного зачёта
GeneratedDocument	конкретный созданный документ	PDF диплома Иванова

AwardStatus не является документом. Документ создаётся на основании AwardStatus, шаблона и данных участника.

Родительский доступ к документу ребёнка может возникнуть через family/claim flow или pending parent invite, созданный при сборе official data package. Такой invite не считается подтверждённым родительским аккаунтом, пока родитель не перейдёт по ссылке, не подтвердит доступ и не примет условия.

5. Основные сущности

Сущность	Назначение	Источник истины
AwardStatus	итоговый наградной статус участника	домен олимпиад
DocumentTemplate	шаблон документа	общий механизм документов
DocumentTemplateBinding	связь шаблона с сезоном, зачётом и наградой	олимпиады / документы
DocumentGenerationJob	задание на генерацию документов	общий механизм документов
GeneratedDocument	конкретный сгенерированный документ	общий механизм документов
DocumentNumber	уникальный номер документа	общий механизм документов
VerificationCode	код или QR для проверки	общий механизм документов
PublicDocumentVerification	публичная проверка документа	общий механизм документов
GratitudeLetterRequest	запрос благодарственного письма	домен олимпиад

6. Документы участников

Стартовый набор документов для участников:

Код	Название	Основание
diploma_1	диплом первого места	AwardStatus = diploma_1
diploma_2	диплом второго места	AwardStatus = diploma_2
diploma_3	диплом третьего места	AwardStatus = diploma_3
honorable_mention_1	похвальная грамота первой степени	AwardStatus = honorable_mention_1
honorable_mention_2	похвальная грамота второй степени	AwardStatus = honorable_mention_2
participation_certificate	сертификат участника	если включён правилами сезона

Правила:

1. Документ участника создаётся только после расчёта или утверждения AwardStatus.
2. Пороги AwardStatus задаются в AwardPolicy и ScoreThreshold.
3. У очного и онлайн-зачёта могут быть разные пороги и разные шаблоны документов.
4. У разных классов или категорий могут быть разные данные в документе.
5. Документ должен быть доступен участнику после генерации и публикации доступа.
6. Участник без аккаунта должен получить доступ к документу через AccountClaim или семейную группу.

7. Благодарственные письма

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

Виды:

Код	Получатель	Описание
teacher_gratitude	преподаватель	благодарность преподавателю, проводившему олимпиаду
assistant_gratitude	помощник	благодарность помощнику проведения или ввода ответов
team_gratitude	член команды проведения	благодарность человеку, которого указал организатор
organization_gratitude	организация	благодарность школе, кружку, центру или площадке
venue_gratitude	площадка	благодарность организации, выступившей открытой площадкой

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

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

8. GratitudeLetterRequest

GratitudeLetterRequest — запрос на генерацию благодарственного письма.

Поле	Описание
id	уникальный идентификатор
competition_season_id	сезон
identity_organization_id	external ref на identity-owned организацию, если применимо
competition_group_id	snapshot LearningGroup, если применимо
venue_id	площадка, если применимо
requested_by_user_id	кто запросил письмо
recipient_type	преподаватель, помощник, член команды, организация, площадка
recipient_user_id	пользователь-получатель, если есть
recipient_name_text	имя получателя текстом, если нет пользователя
organization_name_text	отображаемое название организации
role_text	роль получателя в проведении
status	статус запроса
generated_document_id	ссылка на документ, если создан

Статусы:

Статус	Значение
draft	запрос готовится
submitted	запрос отправлен
approved	запрос одобрен
rejected	запрос отклонён
generated	документ создан
cancelled	запрос отменён

Правила:

1. Возможность создать благодарственное письмо зависит от роли пользователя в выбранной организации или площадочном подслое.
2. Организатор может указать несколько людей команды проведения.
3. Название организации может быть уточнено для отображения в документе.
4. Генерация благодарственных писем должна быть аудируемой.
5. Если запрос не требует ручного одобрения, статус может переходить из submitted сразу в generated.

9. DocumentTemplateBinding

DocumentTemplateBinding связывает шаблон документа с правилами конкретного сезона, зачёта, класса и награды.

Поле	Описание
id	уникальный идентификатор
competition_season_id	сезон
result_track_id	зачёт, если шаблон зависит от зачёта
grade_category_id	класс или категория, если шаблон отличается
award_code	код награды
document_type	диплом, грамота, сертификат, благодарственное письмо
document_template_id	шаблон
status	статус связи

Правила:

1. Нельзя массово генерировать документы, если для нужной награды нет активного шаблона.
2. Шаблон может быть общим для нескольких классов или отдельным для конкретной категории.
3. Для очного и онлайн-зачёта можно назначить разные шаблоны.
4. Изменение шаблона после генерации документов не должно незаметно менять уже созданные документы.

10. DocumentGenerationJob

DocumentGenerationJob — задание на генерацию одного или многих документов.

Поле	Описание
id	уникальный идентификатор
competition_season_id	сезон
result_track_id	зачёт, если применимо
grade_category_id	класс или категория, если применимо
document_type	тип документа
trigger_type	вручную, автоматически, по расписанию
requested_by_user_id	кто запустил генерацию
status	статус задания
total_count	сколько документов нужно создать
success_count	сколько создано
failed_count	сколько не создано
started_at	начало
finished_at	завершение

Статусы:

Статус	Значение
queued	поставлено в очередь
running	выполняется
completed	завершено
completed_with_errors	завершено с ошибками
failed	полностью завершилось ошибкой
cancelled	отменено

Правила:

1. Массовая генерация должна создаваться через DocumentGenerationJob.
2. Задание должно хранить отчёт об ошибках.
3. Повторная генерация уже созданных документов должна требовать явного режима: пропустить, пересоздать, создать новую версию.
4. Автоматическая генерация может запускаться после события AwardStatusApproved или ResultsFinalized, если так настроено.

11. GeneratedDocument

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

Поле	Описание
id	уникальный идентификатор
document_type	тип документа
document_template_id	шаблон
document_generation_job_id	задание генерации
recipient_type	участник, преподаватель, помощник, член команды, организация, площадка
recipient_user_id	пользователь-получатель, если есть
student_record_id	ученик, если документ участника
award_status_id	наградной статус, если документ участника
competition_season_id	сезон
result_track_id	зачёт, если применимо
grade_category_id	класс или категория, если применимо
file_id	ссылка на файл
document_number_id	номер документа
verification_code_id	код проверки
status	статус документа
generated_at	дата генерации

Статусы:

Статус	Значение
draft	документ подготовлен, но не финализирован
generated	документ сгенерирован
published	документ доступен получателю
revoked	документ отозван
superseded	документ заменён новой версией
archived	документ архивирован
failed	документ не удалось создать

Правила:

1. Документ должен ссылаться на основание генерации: AwardStatus или GratitudeLetterRequest.
2. Документ участника должен сохранять связь с сезоном, зачётом и классом.
3. Документ не должен изменяться молча после публикации.
4. Исправление документа после публикации должно создавать новую версию или переводить старый документ в superseded.
5. Отзыв документа должен сохранять историю и причину.

12. Подстановочные данные

Шаблон документа должен получать данные из разных доменов.

Для документа участника:

Поле	Источник
имя участника	StudentRecord или StudentProfile
класс или категория	GradeCategory
название мероприятия	CompetitionEvent
название сезона	CompetitionSeason
тур	Tour, если документ туровый
зачёт	ResultTrack
балл	FinalResult
место	Place, если используется
наградной статус	AwardStatus
threshold snapshot	утверждённый порог и процентный ориентир, если применимо
город, страна, организация	StudentRecord, Organization или регистрационные данные
parent invite/contact	Identity contact/invite, если родитель ещё не подтвердил аккаунт
дата выдачи	настройки генерации
номер документа	DocumentNumber
код проверки	VerificationCode

Для благодарственного письма:

Поле	Источник
имя получателя	User или recipient_name_text
роль получателя	role_text
организация	Organization или organization_name_text
мероприятие	CompetitionEvent
сезон	CompetitionSeason
площадка	Venue, если применимо
дата выдачи	настройки генерации
номер документа	DocumentNumber
код проверки	VerificationCode

Правила:

1. Подстановочные данные должны фиксироваться на момент генерации документа.
2. Если после генерации изменилось имя или название организации, уже созданный документ не должен изменяться автоматически.
3. Для исправления нужен процесс перевыпуска.

13. DocumentNumber и VerificationCode

DocumentNumber — уникальный номер документа.

VerificationCode — код, по которому документ можно проверить публично.

Правила:

1. У опубликованного документа должен быть уникальный номер или код проверки, если включена публичная верификация.
2. Код проверки не должен раскрывать лишние персональные данные.
3. Публичная проверка должна показывать только минимальный набор данных.
4. Отозванный документ должен проверяться как отозванный, а не исчезать без следа.
5. Если документ заменён новой версией, публичная проверка должна показывать актуальный статус.

14. PublicDocumentVerification

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

Минимально показываемые данные:

Поле	Комментарий
статус документа	действителен, отозван, заменён, не найден
тип документа	диплом, грамота, сертификат, благодарственное письмо
получатель	ограниченный или полный формат, зависит от политики
мероприятие и сезон	для какого события выдан
наградной статус	если применимо
дата выдачи	дата генерации или публикации
номер документа	если используется

Правила:

1. Публичная проверка не должна раскрывать больше данных, чем разрешено политикой.
2. Для детского документа нужно особенно осторожно выбирать публичные поля.
3. Проверка должна работать даже после завершения и архивации сезона.

15. Доступ к документам

Актор	Доступ
Ученик	свои документы
Родитель	документы детей своей семейной группы
Преподаватель	документы учеников CompetitionGroup snapshot, если разрешено
Помощник	свои благодарственные письма, если они сгенерированы
Административный подслой выбранной организации	документы учеников и благодарственные письма организации в рамках роли
Площадочный подслой	благодарственные письма площадки, если разрешено
Администратор «Систематики»	документы сезона
Публичный пользователь	только проверка по коду, если включена

Правила:

1. Документ участника должен быть доступен через личный или семейный кабинет.
2. Документы учеников без аккаунта должны стать доступны после AccountClaim.
3. Преподавательский доступ к документам учеников должен зависеть от Learning Group snapshot, роли и сезона.
4. Публичный доступ к PDF не равен публичной проверке по коду.

16. Статусная модель: документ участника

Состояние	Значение
award_calculated	наградной статус рассчитан
award_approved	наградной статус утверждён
template_bound	найден активный шаблон
generation_queued	генерация поставлена в очередь
generated	документ создан
published	документ доступен получателю
verified_publicly	документ проверен по коду
superseded	документ заменён новой версией
revoked	документ отозван
archived	документ архивирован

17. Админские требования

Администратор должен иметь возможность:

• назначить шаблоны документов для сезона, зачёта, класса и награды;
• проверить, у каких наград нет шаблонов;
• запустить массовую генерацию документов;
• увидеть статус DocumentGenerationJob;
• увидеть ошибки генерации;
• пересоздать документ;
• отозвать документ;
• создать новую версию документа;
• открыть или закрыть доступ к документам;
• выгрузить список созданных документов;
• проверить документ по номеру или коду;
• управлять благодарственными письмами, если требуется модерация.

18. Права доступа

Право	Назначение
document_template.bind	назначить шаблон для сезона или награды
document_generation.run	запускать генерацию документов
document_generation.view	видеть задания генерации
generated_document.view_own	смотреть свой документ
generated_document.view_child	смотреть документ ребёнка
generated_document.view_group	смотреть документы учеников CompetitionGroup snapshot
generated_document.view_gratitude_own	смотреть своё благодарственное письмо
generated_document.admin_view	административно смотреть документы
generated_document.publish	публиковать документы
generated_document.revoke	отзывать документы
generated_document.regenerate	пересоздавать документы
gratitude_request.create	создать запрос благодарственного письма
gratitude_request.review	рассмотреть запрос благодарственного письма
public_document.verify	проверить документ по коду

19. Требования к аудиту

Аудироваться должны:

• назначение шаблона;
• изменение шаблона, если оно влияет на будущие документы;
• запуск генерации;
• ошибка генерации;
• создание документа;
• публикация документа;
• скачивание документа администратором, если это требуется политикой;
• отзыв документа;
• перевыпуск документа;
• создание благодарственного письма;
• создание благодарственного письма помощнику, команде, организации или площадке;
• изменение имени получателя или названия организации в запросе благодарственного письма;
• публичная проверка документа, если требуется логировать такие события.

20. Доменные события

Событие	Когда возникает
AwardDocumentGenerationRequested	запрошена генерация документов по наградам
DocumentTemplateBound	шаблон связан с сезоном или наградой
DocumentGenerationStarted	генерация началась
DocumentGenerated	документ создан
DocumentPublished	документ опубликован получателю
DocumentRevoked	документ отозван
DocumentSuperseded	документ заменён новой версией
GratitudeLetterRequested	запрошено благодарственное письмо
GratitudeLetterGenerated	благодарственное письмо создано
PublicDocumentVerified	документ проверен публично

21. Нестандартные случаи

Ситуация	Требуемое поведение
AwardStatus рассчитан, но шаблон не назначен	документ не создаётся, администратор видит ошибку настройки
Изменилось ФИО участника после генерации	старый документ не меняется автоматически; нужен перевыпуск
Изменились пороги наград после генерации	требуется пересчёт AwardStatus и решение по документам
Документ был выдан ошибочно	документ отзывается, история сохраняется
Ученик без аккаунта получил диплом	документ сохраняется, доступ открывается после AccountClaim
Преподаватель указал имя помощника с ошибкой	нужен перевыпуск благодарственного письма
Результат удержан от публикации	документ участника не публикуется до release результата
Порог награды утверждён вручную после процентного ориентира	документ генерируется только после утверждения AwardStatus
Организация изменила публичное название	уже созданное письмо не меняется без перевыпуска
Публичная проверка открыта для детского диплома	показывается только разрешённый минимальный набор данных

Готовность

1. Добавить модель DocumentTemplateBinding для олимпиад.
2. Добавить связь AwardStatus с GeneratedDocument.
3. Добавить модель GratitudeLetterRequest для преподавателей, помощников, команды, организации и площадки.
4. Добавить проверку наличия шаблонов перед генерацией.
5. Добавить массовый запуск DocumentGenerationJob по сезону, зачёту и классу.
6. Добавить статусы GeneratedDocument.
7. Добавить DocumentNumber и VerificationCode или интеграцию с общим механизмом документов.
8. Добавить права доступа к документам участника, ребёнка, CompetitionGroup snapshot и организации.
9. Добавить аудит генерации, публикации, отзыва и перевыпуска документов.
10. Добавить публичную проверку документа по коду или QR, если включено настройками.

24. Статус документа

Документ является первой версией модели документов и наград в домене олимпиад. Следующий рекомендуемый документ: связь с банком задач и тренажёром.