Для модуля Партнёрских программ добавлены документация и тесты

Author: Toksi86

docs/modules/partner-programs.md

@@ -1,3 +1,204 @@
 # Partner Programs
 
-TODO
+## Назначение
+
+Модуль `partner_programs` отвечает за партнерские программы: регистрацию
+участников, привязку проектов к программе, дополнительные поля заявки,
+сдачу проектов на проверку, фильтрацию и выгрузки проектов программы.
+
+Программа объединяет пользователей, проекты, новости, курсы и оценки проектов.
+
+## Статус модуля
+
+Модуль рабочий и используется продуктом, но пока остается архитектурно тяжелым:
+значительная часть бизнес-логики находится во `views.py`, а тесты только
+начинают приводиться к структуре, принятой для свежих модулей.
+
+## Основные возможности
+
+- список и детальная карточка партнерских программ;
+- регистрация пользователя в программе;
+- регистрация нового пользователя через внешнюю форму;
+- просмотр материалов и связанных курсов программы;
+- подача проекта в программу;
+- заполнение дополнительных полей проекта в программе;
+- сдача конкурсного проекта на проверку;
+- список и фильтрация проектов программы для менеджеров;
+- экспорт проектов и оценок;
+- публикация проектов после окончания программы;
+- новости программы через общий модуль `news`.
+
+## Архитектура
+
+- `partner_programs/models.py` - модели программ, участников, материалов,
+  проектов программы и дополнительных полей.
+- `partner_programs/views.py` - API программы, регистрации, подачи проектов,
+  фильтров и экспортов.
+- `partner_programs/serializers/` - request/response serializers и validation
+  дополнительных полей.
+- `partner_programs/services.py` - сервисы публикации проектов и подготовки
+  данных для Excel-выгрузок.
+- `partner_programs/selectors.py` - выборки участников для аналитики и
+  напоминаний.
+- `partner_programs/permissions.py` - проверки менеджера программы, админа и
+  лидера проекта.
+- `partner_programs/tasks.py` - celery-задача публикации проектов после
+  завершения программы.
+- `partner_programs/tests/` - regression-тесты API, serializers и сервисов.
+
+## Ключевые сущности
+
+- `PartnerProgram` - сама программа, даты регистрации, подачи и завершения,
+  настройки конкурсности и публикации проектов.
+- `PartnerProgramUserProfile` - участие пользователя в программе и данные
+  регистрационной формы.
+- `PartnerProgramProject` - связь проекта с программой, статус сдачи проекта и
+  дата сдачи.
+- `PartnerProgramField` - дополнительное поле программы.
+- `PartnerProgramFieldValue` - значение дополнительного поля для проекта в
+  программе.
+- `PartnerProgramMaterial` - материал программы: ссылка или файл.
+
+## API
+
+- `GET /programs/` - список опубликованных программ.
+- `GET /programs/?participating=1` - активные программы текущего участника.
+- `GET /programs/<id>/` - детальная карточка программы.
+- `GET /programs/<id>/schema/` - схема регистрационных данных программы.
+- `POST /programs/<id>/register/` - регистрация текущего пользователя в
+  программе.
+- `POST /programs/<id>/register_new/` - регистрация нового пользователя через
+  внешнюю форму.
+- `POST /programs/<id>/set_liked/` - лайк программы.
+- `POST /programs/<id>/set_viewed/` - просмотр программы.
+- `GET /programs/<id>/news/` - новости программы.
+- `POST /programs/<id>/news/` - создание новости программы менеджером.
+- `GET /programs/<id>/projects/apply/` - данные формы подачи проекта.
+- `POST /programs/<id>/projects/apply/` - подача проекта в программу.
+- `POST /programs/partner-program-projects/<link_id>/submit/` - сдача проекта
+  на проверку.
+- `PUT /projects/<project_id>/program-fields/` - обновление дополнительных
+  полей проекта в программе.
+- `GET /programs/<id>/filters/` - доступные фильтры проектов программы.
+- `POST /programs/<id>/projects/filter/` - фильтрация проектов по
+  дополнительным полям.
+- `GET /programs/<id>/projects/` - список проектов программы.
+- `GET /programs/<id>/export-projects/` - Excel-выгрузка проектов.
+- `GET /programs/<id>/export-rates/` - Excel-выгрузка оценок.
+
+## Основные сценарии
+
+### 1. Пользователь смотрит список программ
+
+Список `/programs/` показывает только программы с `draft = False`.
+Для авторизованного пользователя response дополнительно показывает признак
+`is_user_member`.
+
+Фильтр `participating=1` возвращает только активные программы, в которых
+текущий пользователь является участником.
+
+### 2. Пользователь открывает программу
+
+Детальная карточка возвращает разные поля для участника и не-участника.
+Если пользователь авторизован, просмотр программы фиксируется через общий
+механизм просмотров.
+
+Связанные курсы программы возвращаются в поле `courses`; для каждого курса
+указывается `is_available`.
+
+### 3. Пользователь регистрируется в программе
+
+`POST /programs/<id>/register/` создает `PartnerProgramUserProfile` для текущего
+пользователя и сохраняет переданные данные формы в `partner_program_data`.
+
+Если срок регистрации завершен или пользователь уже зарегистрирован, API
+возвращает ошибку.
+
+### 4. Пользователь подает проект в программу
+
+Участник программы открывает форму `/programs/<id>/projects/apply/`, получает
+список дополнительных полей и отправляет проект.
+
+При успешной подаче создаются:
+
+- черновой непубличный `Project`;
+- связь `PartnerProgramProject`;
+- значения `PartnerProgramFieldValue`;
+- связь `PartnerProgramUserProfile.project` с новым проектом.
+
+Подача запрещена не-участнику, после дедлайна, при повторной подаче проекта и
+при некорректных дополнительных полях.
+
+### 5. Лидер обновляет поля проекта в программе
+
+`PUT /projects/<project_id>/program-fields/` обновляет значения дополнительных
+полей проекта.
+
+Изменять значения может только лидер проекта. Для конкурсной программы после
+сдачи проекта на проверку редактирование блокируется.
+
+### 6. Лидер сдает проект на проверку
+
+`POST /programs/partner-program-projects/<link_id>/submit/` переводит связь
+проекта с программой в `submitted = True` и заполняет `datetime_submitted`.
+
+Сдача доступна только лидеру проекта, только для конкурсных программ и только
+до дедлайна подачи проектов.
+
+### 7. Менеджер работает с проектами программы
+
+Менеджер или администратор программы может:
+
+- смотреть список проектов программы;
+- получать список доступных фильтров;
+- фильтровать проекты по значениям дополнительных полей;
+- выгружать проекты и оценки в Excel.
+
+## Связи с другими модулями
+
+- `projects` - проекты подаются в программу и связываются через
+  `PartnerProgramProject`.
+- `users` - участники и менеджеры программы.
+- `news` - новости программы создаются и читаются через общий news API.
+- `feed` - текстовые новости программы могут попадать в общую ленту как
+  `type_model = "news"`.
+- `courses` - курс может быть связан с программой и доступен участникам
+  программы.
+- `project_rates` - оценки проектов используются в выгрузке результатов.
+- `mailing` / `vacancy.tasks.send_email` - уведомления после регистрации в
+  программе.
+- `files` - материалы программы могут ссылаться на `UserFile`.
+
+## Ограничения и правила
+
+- Дополнительные поля программы задаются через `PartnerProgramField`.
+- Значения дополнительных полей хранятся в `PartnerProgramFieldValue`.
+- После сдачи проекта в конкурсной программе значения полей редактировать
+  нельзя.
+- Служебные feed-карточки программ пока не поддерживаются; новости программ в
+  feed отображаются как обычные новости.
+- Основной API-код пока сосредоточен во `views.py`; перед крупным рефакторингом
+  нужно зафиксировать больше regression-тестов.
+
+## Тесты
+
+Текущие regression-тесты проверяют:
+
+- validation дополнительных полей: `text`, `textarea`, `checkbox`, `select`,
+  `radio`, `file`;
+- список программ и фильтр `participating`;
+- регистрацию текущего пользователя в программе;
+- регистрацию нового пользователя через внешнюю форму;
+- запрет повторной регистрации и регистрации после дедлайна;
+- detail программы с курсами для участника и не-участника;
+- подачу проекта участником программы;
+- запрет подачи проекта не-участником, после дедлайна, с дублями полей,
+  незаполненными обязательными полями и полями другой программы;
+- обновление дополнительных полей проекта лидером;
+- запрет обновления полей не-лидером и после сдачи конкурсного проекта;
+- сдачу проекта на проверку;
+- запрет сдачи проекта не-лидером, после дедлайна и для неконкурсной программы;
+- список фильтров программы;
+- фильтрацию проектов программы по дополнительным полям;
+- список проектов программы для менеджера;
+- публикацию проектов после завершения программы.