Refactor/modules

docs/modules/project-rates.md

@@ -1,3 +1,174 @@
 # Project Rates
 
-TODO
+## Назначение
+
+Модуль `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>` с телом:
+
+```json
+{
+  "filters": {
+    "track": ["FinTech"]
+  }
+}
+```
+
+Фильтры применяются к дополнительным полям программы, которые хранятся в
+`PartnerProgramFieldValue`.
+
+### 3. Эксперт выставляет оценки
+
+Эксперт отправляет `POST /rate-project/rate/<project_id>` со списком значений:
+
+```json
+[
+  {
+    "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`;
+- запрет удаления назначения после выставленной оценки.