project-rates.md

Project Rates

Назначение

Модуль project_rates отвечает за экспертную оценку проектов внутри партнерских программ.

Он используется, когда проект уже привязан к программе и эксперты должны выставить оценки по критериям программы. Результаты оценок затем используются в интерфейсе оценки и в Excel-выгрузках партнерской программы.

Статус модуля

Модуль рабочий и используется вместе с partner_programs. Базовые сценарии зафиксированы regression-тестами, бизнес-логика оценки вынесена в service layer. При дальнейших изменениях важно сохранять текущий API-контракт и правила доступа экспертов.

Основные возможности

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

Архитектура

• project_rates/models.py - критерии, оценки и назначения проектов экспертам.
• project_rates/views.py - API оценки проекта и списка проектов для оценки.
• project_rates/services.py - бизнес-логика выставления оценок, фильтрации проектов для оценки и проверки лимитов.
• project_rates/serializers.py - request serializer оценки и response serializer списка проектов.
• project_rates/validators.py - проверка типа значения и числовых границ оценки.
• project_rates/signals.py - создание дефолтного критерия Комментарий для новой программы.
• project_rates/admin.py - управление критериями, оценками и bulk-назначением проектов экспертам.
• project_rates/tests/ - regression-тесты API, модели назначений, сериализации и критических правил.

Ключевые сущности

• Criteria - критерий оценки проекта. Принадлежит конкретной партнерской программе, имеет тип str, int, float или bool, а для числовых типов может иметь min_value и max_value.
• ProjectScore - оценка проекта конкретным экспертом по конкретному критерию. Уникальна по связке criteria, user, project.
• ProjectExpertAssignment - назначение проекта эксперту в программе. Нужно для режима распределенной оценки.

API

• GET /rate-project/<program_id> - список проектов программы для оценки.
• POST /rate-project/<program_id> - список проектов программы с фильтрами в JSON body.
• POST /rate-project/rate/<project_id> - выставление или обновление оценок проекта.

Основные сценарии

1. Эксперт открывает список проектов для оценки

Эксперт запрашивает GET /rate-project/<program_id>.

API возвращает только проекты, привязанные к программе через PartnerProgramProject и не находящиеся в черновике.

Если у проекта уже есть оценки текущего эксперта, поле criterias возвращает выставленные значения. Если текущий эксперт еще не оценивал проект, поле criterias возвращает список критериев программы.

2. Эксперт фильтрует проекты программы

Эксперт может отправить POST /rate-project/<program_id> с телом:

{
  "filters": {
    "track": ["FinTech"]
  }
}

Фильтры применяются к дополнительным полям программы, которые хранятся в PartnerProgramFieldValue.

3. Эксперт выставляет оценки

Эксперт отправляет POST /rate-project/rate/<project_id> со списком значений:

[
  {
    "criterion_id": 1,
    "value": "8"
  }
]

API проверяет, что:

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

При повторной отправке оценки того же эксперта по тому же критерию значение обновляется.

4. Распределенная оценка

Если у программы включено is_distributed_evaluation, эксперт видит и может оценивать только проекты, назначенные ему через ProjectExpertAssignment.

Назначение валидируется при сохранении:

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

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

5. Выгрузка результатов

Модуль partner_programs использует Criteria и ProjectScore для подготовки Excel-выгрузки оценок программы через /programs/<id>/export-rates/.

Связи с другими модулями

• partner_programs - программа, связь проекта с программой, дополнительные поля и выгрузка результатов.
• projects - оцениваемые проекты.
• users - эксперты программы и лидеры проектов.
• vacancy.tasks.send_email - уведомление лидера проекта после оценки.

Ограничения и правила

• Значения оценок хранятся строкой, а тип проверяется через критерий.
• ProjectScore.objects.bulk_create(..., update_conflicts=True) обновляет существующую оценку без создания дубля.
• max_project_rates ограничивает число разных экспертов, которые могут оценить один проект в программе; текущий эксперт может обновить свою оценку.
• Дефолтный критерий Комментарий создается сигналом при создании программы.
• Основная бизнес-логика оценки вынесена в project_rates/services.py; views отвечают за HTTP-контракт и преобразование ошибок в response.

Тесты

Текущие regression-тесты проверяют:

• обычную оценку проекта экспертом программы;
• обновление существующей оценки без дублей;
• запрет оценки экспертом, который не состоит в программе;
• запрет оценки проекта, который не привязан к программе;
• запрет оценки критериями из разных программ;
• ограничение max_project_rates;
• валидацию числовых границ и boolean-значений;
• список проектов программы без распределенной оценки;
• список проектов программы при распределенной оценке;
• фильтрацию проектов по дополнительным полям программы;
• response-поля scored, rated_experts, rated_count, max_rates;
• создание дефолтного критерия Комментарий;
• валидацию ProjectExpertAssignment;
• запрет удаления назначения после выставленной оценки.