Skip to content

Commit e4cdf85

Browse files
Toksi86Toksi86
committed
Задокументирован модуль курсов
1 parent 53d610c commit e4cdf85

1 file changed

Lines changed: 142 additions & 1 deletion

File tree

‎docs/modules/courses.md‎

Lines changed: 142 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,144 @@
11
# Courses
22

3-
TODO
3+
## Назначение
4+
5+
Курсы отвечают за обучение пользователей внутри Procollab: список курсов,
6+
доступность, структуру курса, прохождение уроков, ответы на задания, прогресс
7+
и экспорт результатов.
8+
9+
## Статус модуля
10+
11+
Модуль находится в хорошем состоянии и может использоваться как ориентир для
12+
рефакторинга других частей backend.
13+
14+
## Основные возможности
15+
16+
- просмотр списка доступных курсов;
17+
- просмотр карточки курса;
18+
- просмотр структуры курса: модули, уроки, задания;
19+
- контроль доступности курса, модуля, урока и задания;
20+
- отправка ответов на задания;
21+
- поддержка заданий с ручной проверкой;
22+
- пересчет прогресса пользователя;
23+
- экспорт результатов курса из Django admin.
24+
25+
## Архитектура
26+
27+
- `courses/models/` - модели курса, контента, ответов и прогресса.
28+
- `courses/api/views/` - HTTP endpoints.
29+
- `courses/api/serializers/` - request и response contracts.
30+
- `courses/queries/` - сборка read payload для API.
31+
- `courses/services/` - бизнес-логика: доступы, ответы, прогресс, экспорт.
32+
- `courses/admin_config/` - настройка Django admin.
33+
- `courses/tests/` - тесты модуля.
34+
35+
## Основные сущности
36+
37+
- `Course` - курс.
38+
- `CourseModule` - модуль курса.
39+
- `CourseLesson` - урок.
40+
- `CourseTask` - задание.
41+
- `CourseTaskOption` - вариант ответа.
42+
- `UserTaskAnswer` - ответ пользователя.
43+
- `UserCourseProgress` - прогресс по курсу.
44+
- `UserModuleProgress` - прогресс по модулю.
45+
- `UserLessonProgress` - прогресс по уроку.
46+
47+
## API
48+
49+
- `GET /courses/` - список курсов.
50+
- `GET /courses/<id>/` - детали курса.
51+
- `GET /courses/<id>/structure/` - структура курса.
52+
- `POST /courses/<id>/visit/` - отметка посещения курса.
53+
- `GET /courses/lessons/<id>/` - детали урока.
54+
- `POST /courses/tasks/<id>/answer/` - отправка ответа на задание.
55+
56+
## Основные сценарии
57+
58+
### 1. Выбор курса
59+
60+
Пользователь открывает список курсов и видит доступные ему карточки. Для каждой
61+
карточки отображаются статус, период доступности, состояние действия
62+
(`start`, `continue`, `lock`) и текущий прогресс.
63+
64+
Доступность курса зависит от:
65+
66+
- статуса курса;
67+
- типа доступа;
68+
- участия пользователя в партнерской программе;
69+
- дат начала и окончания курса;
70+
- факта завершения курса.
71+
72+
### 2. Выбор модуля
73+
74+
После открытия курса пользователь видит структуру из модулей. Модуль доступен,
75+
если доступен сам курс, модуль опубликован, наступила дата старта модуля и
76+
предыдущий модуль завершен.
77+
78+
Для каждого модуля отображаются уроки, прогресс и состояние доступности.
79+
80+
### 3. Выбор урока
81+
82+
Пользователь может открыть только доступный опубликованный урок. Урок доступен,
83+
если доступен его модуль и предыдущий урок завершен.
84+
85+
Урок состоит из заданий. Поддерживаются два основных типа заданий:
86+
87+
- информационные задания - пользователь должен ознакомиться с материалом;
88+
- задания с ответом - пользователь должен отправить текст, выбрать вариант или
89+
прикрепить файл.
90+
91+
Для заданий с ответом поддерживаются разные типы ответа:
92+
93+
- текст;
94+
- один вариант;
95+
- несколько вариантов;
96+
- файл;
97+
- текст и файл.
98+
99+
### 4. Прохождение урока
100+
101+
Пользователь проходит задания урока по порядку. Следующее задание открывается
102+
после завершения текущего.
103+
104+
После отправки ответа система обновляет:
105+
106+
- прогресс урока;
107+
- прогресс модуля;
108+
- прогресс курса;
109+
- текущее задание пользователя.
110+
111+
Если урок, модуль или курс завершены полностью, их прогресс становится 100%.
112+
113+
### 5. Проверка ответов
114+
115+
Задания могут проверяться автоматически или вручную.
116+
117+
При автоматической проверке результат определяется сразу после отправки ответа.
118+
Если ответ принят, пользователь может продолжить прохождение.
119+
120+
При ручной проверке ответ получает статус `pending_review`. Администратор
121+
проверяет ответ в Django admin и выставляет итоговый статус. После изменения
122+
review-полей прогресс пользователя пересчитывается автоматически.
123+
124+
## Ограничения и правила
125+
126+
- `file_ids` в ответах могут ссылаться только на файлы текущего пользователя.
127+
- Доступ к урокам и заданиям зависит от порядка прохождения.
128+
- Для опубликованных choice-заданий должен быть корректный набор правильных
129+
вариантов.
130+
- Upload flow в Django admin использует временные флаги `_has_pending_*`; это
131+
зафиксированный технический долг.
132+
133+
## Тесты
134+
135+
Тесты покрывают:
136+
137+
- API flow;
138+
- доступность курсов и уроков;
139+
- отправку ответов;
140+
- прогресс;
141+
- learning flow;
142+
- экспорт результатов;
143+
- ручную проверку через admin;
144+
- ограничения на прикрепление файлов.

0 commit comments

Comments
 (0)