chat_service¶

1. Назначение¶

chat_service обеспечивает диалоги между пользователем и администратором: создание conversation, отправку сообщений, контроль непрочитанных и операции mark-as-read.

2. API-каталог¶

Базовый префикс: /api/chat/.

Conversations¶

Метод	Путь	Назначение
GET/POST	`/conversations/`	Список/создание
GET/PUT/PATCH/DELETE	`/conversations/{id}/`	Операции с диалогом
GET	`/conversations/my_conversation/`	Получить или создать свой диалог
POST	`/conversations/{id}/mark_as_read/`	Массовое чтение сообщений

Messages¶

Метод	Путь	Назначение
GET/POST	`/messages/`	Список/создание сообщений
GET/PUT/PATCH/DELETE	`/messages/{id}/`	Операции с сообщением
POST	`/messages/{id}/mark_as_read/`	Пометка одного сообщения

3. Модель данных¶

`Conversation`¶

user FK -> auth_app.User
is_active
created_at, updated_at
индексы по активности и времени

`Message`¶

conversation FK
sender FK -> auth_app.User
content (до 5000 символов на уровне serializer)
is_read
created_at

4. Доступ и права¶

Базово используется IsAuthenticated.
Админ (is_staff) видит все диалоги и сообщения.
Пользователь видит только свои conversation/message.
Session auth требует корректного CSRF-flow для write-запросов.

5. Edge-cases¶

В POST /conversations/ для admin возможен 500 при невалидном user id.
Нет уникального ограничения на один conversation на пользователя.
Без conversation в /messages/ поведение различается для admin/user.

6. Диаграмма mark-as-read¶

sequenceDiagram
  participant U as UserOrAdmin
  participant C as chat_service
  U->>C: POST /conversations/{id}/mark_as_read
  alt user_request
    C->>C: mark admin messages as read
  else admin_request
    C->>C: mark user messages as read
  end
  C-->>U: 200 updated count

7. Конфигурация¶

Внешний порт: 8007.
Основные env: DATABASE_URL, SECRET_KEY, DEBUG.
Зависимость от auth_service через AUTH_USER_MODEL.

8. Дополнительная детализация внутренних функций (append-only)¶

8.1 Функции conversation lifecycle¶

`ConversationViewSet.get_queryset(self)`¶

Источник: chat_service/chat_app/views.py
Назначение: вернуть список диалогов с учетом роли и unread-агрегаций.
Вход:
request.user.
Выход:
staff: все conversation;
user: только свой conversation;
с аннотацией unread_count.

`ConversationViewSet.perform_create(self, serializer)`¶

Назначение: создать conversation (в т.ч. admin-сценарий для конкретного пользователя).
Вход:
serializer data;
для staff возможен request.data.user.
Выход:
созданный conversation.
Edge-cases:
при невалидном user id в admin-ветке возможна ошибка создания.

`ConversationViewSet.my_conversation(self, request)`¶

Назначение: вернуть или создать личный диалог пользователя.
Side effects:
get_or_create может создавать запись conversation при первом обращении.
Ошибки:
403 для staff-пользователя (endpoint предназначен для regular user).

`ConversationViewSet.mark_as_read(self, request, pk=None)`¶

Назначение: массово пометить сообщения прочитанными в диалоге.
Side effects:
update Message.is_read=True для соответствующей стороны диалога.

8.2 Функции message lifecycle¶

`MessageViewSet.get_queryset(self)`¶

Источник: chat_service/chat_app/views.py
Вход:
optional query param conversation.
Выход:
role-aware queryset сообщений.
Edge-cases:
при недоступной conversation часть веток возвращает пустой набор, а не исключение.

`MessageViewSet.create(self, request, *args, **kwargs)`¶

Назначение: отправить сообщение в conversation.
Вход:
conversation, content.
Выход:
201 с созданным сообщением;
400/403/404 в невалидных сценариях.
Side effects:
запись Message;
обновление Conversation.updated_at.

`MessageViewSet.mark_as_read(self, request, pk=None)`¶

Назначение: пометить конкретное сообщение как прочитанное.
Ограничение:
действие доступно только владельцу сообщения (как получателю) или staff.

8.3 Serializer-уровень и модельные хелперы¶

`MessageCreateSerializer.validate_content(self, value)`¶

Источник: chat_service/chat_app/serializers.py
Назначение: нормализация и валидация текста сообщения.
Вход:
строка content.
Выход:
trimmed content.
Ошибки:
validation error при пустом тексте или длине больше 5000 символов.

`Conversation.unread_count_for_user` / `unread_count_for_admin`¶

Источник: chat_service/chat_app/models.py
Назначение: вычислить unread счетчики для разных ролей.
Выход:
int количество непрочитанных сообщений.

9. Соответствие master-документации¶

Источник верхнего уровня: Master-документация проекта.

Контроль	Требование	Проверка	Артефакт
Message contract	Контракты conversation/message API синхронизированы с frontend	smoke сценарии чатов	QA report
Access boundaries	Role-aware доступ и unread-логика не деградируют	проверка owner/admin выборок	integration tests
Operational safety	Массовые mark-as-read операции контролируемы	нагрузочная/функциональная проверка	test notes
Delivery quality	Документация и реализация обновляются синхронно	MkDocs strict + code review	build + PR