Дипломный проект на курсе "Backend-разработка на Node.js"
Запуск
- docker-compose build
- docker-compose up
Описание проекта
Дипломный проект представляет собой сайт-агрегатор просмотра и бронирования гостиниц. Ваша задача заключается в разработке бэкенда для сайта-агрегатора с реализацией возможности бронирования гостиниц на диапазон дат.
Цели проекта
- Разработка публичного апи.
- Разработка апи пользователя.
- Разработка апи администратора.
- Разработка чата консультанта.
Технологический стек
- Node.js
- Nest.js
- MongoDB
- Websocket
Допущения
Оплату бронирования реализовывать не нужно.
Глоссарий
В данном документе приводятся разные описания интерфейсов и типов. Для упрощения описания общие типы приводятся в данном разделе.
type ID = string | ObjectId;
1. Описание базовых модулей
Базовые модули служат для описания бизнес-логики и хранения данных.
1.1 Модуль "Пользователи"
Модуль "Пользователи" предназначается для создания, хранения и поиска профилей пользователей.
Модуль "Пользователи" используется функциональными модулями для регистрации и аутентификации.
Данные пользователя должны храниться в MongoDB.
Модель данных User
пользователя должна содержать следующие поля:
название | тип | обязательное | уникальное | по умолчанию |
---|---|---|---|---|
_id | ObjectId |
да | да | |
string |
да | да | ||
passwordHash | string |
да | нет | |
name | string |
да | нет | |
contactPhone | string |
нет | нет | |
role | string |
да | нет | client |
Модуль "Пользователи" должен быть реализован в виде NestJS модуля и экспортировать сервисы со следующими интерфейсами:
interface SearchUserParams {
limit: number;
offset: number;
email: string;
name: string;
contactPhone: string;
}
interface IUserService {
create(data: Partial<User>): Promise<User>;
findById(id: ID): Promise<User>;
findByEmail(email: string): Promise<User>;
findAll(params: SearchUserParams): Promoise<User[]>;
}
Поле role
может принимать одно из следующих значений:
client
admin
manager
При поиске IUserService.findAll()
поля email
, name
и contactPhone
должны проверяться на частичное совпадение.
1.2 Модуль "Гостиницы"
Модуль "Гостиницы" предназначается для хранения и поиска гостиниц и комнат.
Модуль "Гостиницы" используется функциональными модулями для показа списка мест для бронирования, а также для их добавления, включения и выключения.
Данные должны храниться в MongoDb.
Модель данных Hotel
должна содержать следующие поля:
название | тип | обязательное | уникальное | по умолчанию |
---|---|---|---|---|
_id | ObjectId |
да | да | |
title | ObjectId |
да | нет | |
description | string |
нет | нет | |
createdAt | Date |
да | нет | |
updatedAt | Date |
да | нет |
Модель данных HotelRoom
должна содержать следующие поля:
название | тип | обязательное | уникальное | по умолчанию |
---|---|---|---|---|
_id | ObjectId |
да | да | |
hotel | ObjectId |
да | нет | |
description | string |
нет | нет | |
images | string[] |
нет | нет | [] |
createdAt | Date |
да | нет | |
updatedAt | Date |
да | нет | |
isEnabled | boolean |
да | нет | true |
Свойство hotel
должно ссылаться на модель Hotel
Модуль "Гостиницы" должен быть реализован в виде NestJS модуля и экспортировать сервисы со следующими интерфейсами:
interface IHotelService {
create(data: any): Promise<Hotel>;
findById(id: ID): Promise<Hotel>;
search(params: Pick<Hotel, "title">): Promise<Hotel[]>;
}
interface SearchRoomsParams {
limit: number;
offset: number;
title: string;
isEnabled?: true;
}
interface HotelRoomService {
create(data: Partial<HotelRoom>): Promise<HotelRoom>;
findById(id: ID, isEnabled?: true): Promise<HotelRoom>;
search(params: SearchRoomsParams): Promise<HotelRoom[]>;
update(id: ID, data: Partial<HotelRoom>): Promise<HotelRoom>;
}
В методах findById
и search
флаг isEnabled
может принимать только значения:
true
- флаг должен использоваться в фильтрации,undefined
- флаг должен игнорироваться.
1.3 Модуль "Брони"
Модуль "Брони" предназначен для хранения и получения броней гостиниц конкретного пользователя.
Модуль "Брони" не должен использовать Модуль "Пользователи" и Модуль "Гостиницы" для получения данных.
Модуль "Брони" не должен хранить данные пользователей и гостиниц.
Модуль "Брони" должен использовать соединение с базой данных.
Данные должны храниться в MongoDb.
Модель данных Reservation
должна содержать следующие поля:
название | тип | обязательное | уникальное | по умолчанию |
---|---|---|---|---|
_id | ObjectId |
да | да | |
userId | ObjectId |
да | нет | |
hotelId | ObjectId |
да | нет | |
roomId | ObjectId |
да | нет | |
dateStart | Date |
да | нет | |
dateEnd | Date |
да | нет |
Модуль "Брони" должен быть реализован в виде NestJS модуля и экспортировать сервисы со следующими интерфейсами:
interface ReservationDto {
user: ID;
hotel: ID;
room: ID;
dateStart: Date;
dateEnd: Date;
}
interface ReservationSearchOptions {
user: ID;
dateStart: Date;
dateEnd: Date;
}
interface IReservation {
addReservation(data: ReservationDto): Promise<Reservation>;
removeReservation(id: ID): Promise<void>;
getReservations(
filter: ReservationSearchOptions
): Promise<Array<Reservation>>;
}
- Метод
IReservation.addReservation
должен проверять доступен ли номер на заданную дату
1.4 Модуль "Чат техподдержки"
Модуль "Чат техподдержки" предназначается для хранения обращений в техподдержку и сообщений в чате обращения.
Модуль объявлений используется функциональными модулями для реализации возможности общения пользователей.
Данные чатов должны храниться в MongoDB.
Модель данных чата SupportRequest
должна содержать следующие поля:
название | тип | обязательное | уникальное |
---|---|---|---|
_id | ObjectId |
да | да |
user | ObjectId |
да | нет |
createdAt | Date |
да | нет |
messages | Message[] |
нет | нет |
isActive | bool |
нет | нет |
Модель сообщения Message
должна содержать следующие поля:
название | тип | обязательное | уникальное |
---|---|---|---|
_id | ObjectId |
да | да |
author | ObjectId |
да | нет |
sentAt | Date |
да | нет |
text | string |
да | нет |
readAt | Date |
нет | нет |
Сообщение считается прочитанным, когда поле readAt
непустое.
Модуль "Чат техподдержки" должен быть реализован в виде NestJS модуля и экспортировать сервисы со следующими интерфейсами:
interface CreateSupportRequestDto {
user: ID;
text: string;
}
interface SendMessageDto {
author: ID;
supportRequest: ID;
text: string;
}
interface MarkMessagesAsReadDto {
user: ID;
supportRequest: ID;
createdBefore: Date;
}
interface GetChatListParams {
user: ID | null;
isActive: bool;
}
interface ISupportRequestService {
findSupportRequests(params: GetChatListParams): Promise<SupportRequest[]>;
sendMessage(data: SendMessageDto): Promise<Message>;
getMessages(supportRequest: ID): Promise<Message[]>;
subscribe(
handler: (supportRequest: SupportRequest, message: Message) => void
): () => void;
}
interface ISupportRequestClientService {
createSupportRequest(data: CreateSupportRequestDto): Promise<SupportRequest>;
markMessagesAsRead(params: MarkMessagesAsReadDto);
getUnreadCount(supportRequest: ID): Promise<Message[]>;
}
interface ISupportRequestEmployeeService {
markMessagesAsRead(params: MarkMessagesAsReadDto);
getUnreadCount(supportRequest: ID): Promise<Message[]>;
closeRequest(supportRequest: ID): Promise<void>;
}
- Метод
ISupportRequestClientService.getUnreadCount
должен возвращать количество сообщений, которые были отправлены любым сотрудником поддержки и не отмечены прочитанным. - Метод
ISupportRequestClientService.markMessagesAsRead
должен выставлять текущую дату в поле readAt всем сообщениям, которые не были прочитаны и были отправлены не пользователем. - Метод
ISupportRequestEmployeeService.getUnreadCount
должен возвращать количество сообщений, которые были отправлены пользователем и не отмечены прочитанным. - Метод
ISupportRequestEmployeeService.markMessagesAsRead
должен выставлять текущую дату в поле readAt всем сообщениям, которые не были прочитаны и были отправлены пользователем. - Метод
ISupportRequestEmployeeService.closeRequest
должен менять флагisActive
наfalse
. - Оповещения должны быть реализованы через механизм
EventEmitter
.
2. Описание модулей WEB API
2.1 API Модуля "Гостиницы"
Должно быть оформлено в виде отдельного NestJS модуля.
Ограничения
Если пользователь не аутентифицирован или его роль client
, то при поиске всегда должен использоваться флаг isEnabled: true
.
2.1.1 Поиск номеров
Описание
Основной API для поиска номеров.
Адрес
GET /api/common/hotel-rooms
Query параметры
- limit - количество записей в ответе,
- offset - сдвиг от начала списка,
- hotel - ID гостиницы для фильтра.
Формат ответа
[
{
"id": string,
"title": string,
"images": [string],
"hotel": {
"id": string,
"title": string
}
}
]
Доступ
Доступно всем пользователям, включая неаутентифицированных.
2.1.2 Информация о конкретном номере
Описание
Получение подробной информации о номере.
Адрес
GET /api/common/hotel-rooms/:id
Query параметры
Отсутствуют.
Формат ответа
{
"id": string,
"title": string,
"description": string,
"images": [string],
"hotel": {
"id": string,
"title": string,
"description": string
}
}
Доступ
Доступно всем пользователям, включая неаутентифицированных.
2.1.3 Добавление гостиницы
Описание
Добавление гостиницы администратором.
Адрес
POST /api/admin/hotels/
Body параметры
{
"title": string,
"description": string
}
Формат ответа
{
"id": string,
"title": string,
"description": string
}
Доступ
Доступно только аутентифицированным пользователям с ролью admin
.
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неadmin
2.1.4 Получение списка гостиниц
Описание
Получение списка гостиниц администратором.
Адрес
GET /api/admin/hotels/
Query параметры
- limit - количество записей в ответе,
- offset - сдвиг от начала списка.
Формат ответа
{
"id": string,
"title": string,
"description": string
}
Доступ
Доступно только аутентифицированным пользователям с ролью admin
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неadmin
2.1.5 Изменение описания гостиницы
Описание
Изменение описания гостиницы администратором.
Адрес
PUT /api/admin/hotels/:id
Body параметры
{
"title": string,
"description": string
}
Формат ответа
{
"id": string,
"title": string,
"description": string
}
Доступ
Доступно только аутентифицированным пользователям с ролью admin
.
Ошибки
401
- если пользователь не аутентифицирован,403
- если роль пользователя неadmin
.
2.1.6 Добавление номера
Описание
Добавление номера гостиницы администратором.
Адрес
POST /api/admin/hotel-rooms/
Body параметры
Данный запрос предполагает загрузку файлов и должен использовать формат multipart/form-data
.
title: string
description: string
hotelId: string
images[]: File
Формат ответа
{
"id": string,
"title": string,
"description": string,
"images": [string],
"isEnabled": boolean,
"hotel": {
"id": string,
"title": string,
"description": string
}
}
Доступ
Доступно только аутентифицированным пользователям с ролью admin
.
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неadmin
2.1.7 Изменение описания номера
Описание
Изменение описания гостиницы администратором.
Адрес
PUT /api/admin/hotel-rooms/:id
Body параметры
Данный запрос предполагает загрузку файлов и дожен использовать формат multipart/form-data
.
title: string
description: string
hotelId: string
isEnabled: boolean
images[]: File | string
При обновлении может быть отправлен одновременно список ссылок на уже загруженные картинки и список файлов с новыми картинками.
При использовании multer
список загруженных файлов можно получить через @UploadedFiles()
. Этот список нужно объденить со списком, который пришел в body
.
Формат ответа
{
"id": string,
"title": string,
"description": string,
"images": [string],
"isEnabled": boolean,
"hotel": {
"id": string,
"title": string,
"description": string
}
}
Доступ
Доступно только аутентифицированным пользователям с ролью admin
.
Ошибки
401
- если пользователь не аутентифицирован,403
- если роль пользователя неadmin
2.2 API Модуля "Бронирование"
Должно быть оформлено в виде отдельного NestJS модуля.
2.2.1 Бронирование номера клиентом
Описание
Создает бронь на номер для текущего пользователя на выбранную дату.
Адрес
POST /api/client/reservations
Body параметры
{
"hotelRoom": string,
"startDate": string,
"endDate": string
}
Формат ответа
{
"startDate": string,
"endDate": string,
"hotelRoom": {
"title": string,
"description": string,
"images": [string]
},
"hotel": {
"title": string,
"description": string
}
}
Доступ
Доступно только аутентифицированным пользователям с ролью client
.
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неclient
400
- если номер с указанным ID не существует или отключен
2.2.2 Список броней текущего пользователя
Описание
Список броней текущего пользователя.
Адрес
GET /api/client/reservations
Формат ответа
[
{
"startDate": string,
"endDate": string,
"hotelRoom": {
"title": string,
"description": string,
"images": [string]
},
"hotel": {
"title": string,
"description": string
}
}
]
Доступ
Доступно только аутентифицированным пользователям с ролью client
.
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неclient
2.2.3 Отмена бронирования клиентом
Описание
Отменяет бронь пользователя.
Адрес
DELETE /api/client/reservations/:id
Формат ответа
Пустой ответ
Доступ
Доступно только аутентифицированным пользователям с ролью client
.
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неclient
403
- еслиid
текущего пользователя не совпадает сid
пользователя в брони400
- если бронь с указанным ID не существует
2.2.4 Список броней конкретного пользователя
Описание
Список броней конкретного пользователя.
Адрес
GET /api/manager/reservations/:userId
Формат ответа
[
{
"startDate": string,
"endDate": string,
"hotelRoom": {
"title": string,
"description": string,
"images": [string]
},
"hotel": {
"title": string,
"description": string
}
}
]
Доступ
Доступно только аутентифицированным пользователям с ролью manager
.
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неmanager
2.2.5 Отмена бронирования менеджером
Описание
Отменяет бронь пользователя.
Адрес
DELETE /api/manager/reservations/:userId/:reservationId
Формат ответа
Пустой ответ.
Доступ
Доступно только аутентифицированным пользователям с ролью manager
.
Ошибки
401
- если пользователь не аутентифицирован403
- если роль пользователя неmanager
400
- если бронь с указанным ID для пользователя с указанным ID не существует
2.3 API Модуля "Аутентификация и авторизация"
Должно быть оформлено в виде отдельного NestJS модуля.
Модуль "Аутентификация и авторизация" предназначен:
- для управления сессией пользователя,
- для регистрации пользователей.
Хранение сессии должно реализовываться посредством библиотеки passportjs с хранением сессии в памяти приложения.
Аутентификация пользователя производится с помощью модуля "Пользователи". Каждому пользователю назначается одна из ролей - клиент, администратор, консультант.
2.3.1 Вход
Описание
Стартует сессию пользователя и выставляет Cookie.
Адрес
POST /api/auth/login
Body параметры
{
"email": string,
"password": string
}
Формат ответа
{
"email": string,
"name": string,
"contactPhone": string
}
Доступ
Доступно только не аутентифицированным пользователям.
Ошибки
401
- если пользователь с указанным email не существет или пароль неверный
2.3.2 Выход
Описание
Завершает сессию пользователя и удаляет Cookie.
Адрес
POST /api/auth/logout
Формат ответа
Пустой ответ.
Доступ
Доступно только аутентифицированным пользователям.
2.3.3 Регистрация
Описание
Позволяет создать пользователя с ролью client
в системе.
Адрес
POST /api/client/register
Body параметры
{
"email": string,
"password": string,
"name": string,
"contactPhone": string
}
Формат ответа
{
"id": string,
"email": string,
"name": string
}
Доступ
Доступно только не аутентифицированным пользователям.
Ошибки
400
- если email уже занят
2.4 API Модуля "Управление пользователями"
2.4.1 Создание пользователя
Описание
Позволяет пользователю с ролью admin
создать пользователя в системе.
Адрес
POST /api/admin/users/
Body параметры
{
"email": string,
"password": string,
"name": string,
"contactPhone": string,
"role": string
}
Формат ответа
{
"id": string,
"email": string,
"name": string,
"contactPhone": string,
"role": string
}
Доступ
Доступно только пользователям с ролью admin
.
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользоватьель неadmin
2.4.2 Получение списка пользователей
Описание
Позволяет пользователю с ролью admin
создать пользователя в системе.
Адрес
GET /api/admin/users/
GET /api/manager/users/
Query параметры
- limit - количество записей в ответе
- offset - сдвиг от начала списка
- name - фильтр по полю
- email - фильтр по полю
- contactPhone - фильтр по полю
Формат ответа
[
{
"id": string,
"email": string,
"name": string,
"contactPhone": string
}
]
Доступ
GET /api/admin/users/
Доступно только пользователям с ролью admin
GET /api/manager/users/
Доступно только пользователям с ролью manager
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользоватьель не подходит
2.5 API модуля "Чат с техподдрежкой"
2.5.1 Создание обращения в поддержку
Описание
Позволяет пользователю с ролью client
создать обращение в техподдержку.
Адрес
POST /api/client/support-requests/
Body параметры
{
"text": string
}
Формат ответа
[
{
"id": string,
"createdAt": string,
"isActive": boolean,
"hasNewMessages": boolean
}
]
Доступ
Доступно только пользователям с ролью client
.
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользователя не подходит
2.5.2 Получение списка обращений в поддержку для клиента
Описание
Позволяет пользователю с ролью client
получить список обращений для текущего пользователя.
Адрес
GET /api/client/support-requests/
Query параметры
- limit - количество записей в ответе
- offset - сдвиг от начала списка
- isActive - фильтр по полю
Формат ответа
[
{
"id": string,
"createdAt": string,
"isActive": boolean,
"hasNewMessages": boolean
}
]
Доступ
Доступно только пользователям с ролью client
.
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользователя не подходит
2.5.3 Получение списка обращений в поддержку для менеджера
Описание
Позволяет пользователю с ролью manager
получить список обращений от клиентов.
Адрес
GET /api/manager/support-requests/
Query параметры
- limit - количество записей в ответе
- offset - сдвиг от начала списка
- isActive - фильтр по полю
Формат ответа
[
{
"id": string,
"createdAt": string,
"isActive": boolean,
"hasNewMessages": boolean,
"client": {
"id": string,
"name": string,
"email": string,
"contactPhone": string
}
}
]
Доступ
Доступно только пользователям с ролью manager
.
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользователя не подходит
2.5.4 Получение истории сообщений обращения в техподдержку
Описание
Позволяет пользователю с ролью manager
или client
получить все сообщения из чата.
Адрес
GET /api/common/support-requests/:id/messages
Формат ответа
[
{
"id": string,
"createdAt": string,
"text": string,
"readAt": string,
"author": {
"id": string,
"name": string
}
}
]
Доступ
Доступно только пользователям с ролью manager
и пользователю с ролью client
, который создал обращение.
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользователя не подходит
2.5.5 Отправка сообщения
Описание
Позволяет пользователю с ролью manager
или client
отправлять сообщения в чат.
Адрес
POST /api/common/support-requests/:id/messages
Body параметры
{
"text": string
}
Формат ответа
[
{
"id": string,
"createdAt": string,
"text": string,
"readAt": string,
"author": {
"id": string,
"name": string
}
}
]
Доступ
Доступно только пользователям с ролью manager
и пользователю с ролью client
, который создал обращение.
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользователя не подходит
2.5.6 Отправка события, что сообщения прочитаны
Описание
Позволяет пользователю с ролью manager
или client
отправлять отметку, что сообщения прочитаны.
Адрес
POST /api/common/support-requests/:id/messages/read
Body параметры
{
"createdBefore": string
}
Формат ответа
{
"success": true
}
Доступ
Доступно только пользователям с ролью manager
и пользователю с ролью client
, который создал обращение.
Ошибки
401
- если пользоватьель не аутентифицирован403
- если роль пользователя не подходит
2.5.7 Подписка на сообщения из чата техподдержки
Описание
Позволяет пользователю с ролью manager
или client
получать новые сообщения в чате через websocket.
Команда
message: subscribeToChat payload: chatId
Формат ответа
{
"id": string,
"createdAt": string,
"text": string,
"readAt": string,
"author": {
"id": string,
"name": string
}
}
Доступ
Доступно только пользователям с ролью manager
и пользователю с ролью client
, который создал обращение.
Запуск приложения
Для запуска приложения в корне проекта должны находиться следующие файлы:
package.json
иpackage-lock.json
с описанными зависимостямиDockerfile
для сборки образа приложенияdocker-compose.yaml
с сервисом приложения и сервисом mondodbREADME.me
с описанием проекта и вариантами его запуска
Настройка параметров приложения должна производиться через переменные окружения. Это требование как для запуска в окрежении хоста, так и при работе с docker.
Список переменных окружения должен быть описан в файле .env-example
. Этот файл не должен содержать значений. Пример файла:
HTTP_HOST=
HTTP_PORT=
MONGO_URL=
Для запуска приложения должен использоваться скрипт npm start
, описанный в package.json
Как правильно задавать вопросы дипломному руководителю?
Что поможет решить большинство частых проблем:
- Попробовать найти ответ сначала самому в интернете. Скилл поиска ответов пригодится вам в профессиональной деятельности. И только после этого спрашивать дипломного руководителя.
- Если вопросов больше одного, то присылайте их в виде нумерованного списка. Так дипломному руководителю будет проще отвечать на каждый из них.
- При необходимости прикрепите к вопросу скриншоты и стрелочкой покажите, где не получается. Программу для этого можно скачать здесь https://app.prntscr.com/ru/
- По возможности, задавайте вопросы в комментариях к коду.
- Начинать работу над дипломом как можно раньше! Чтобы было больше времени на правки.
- Делайте диплом частями, а не всё сразу. Если сделать всё сразу, то количество комментариев от дипломного руководителя может вас деморализовать.
Что может стать источником проблем:
- Вопросы вида «Ничего не работает. Не запускается. Всё сломалось.». Дипломный руководитель не сможет ответить на такой вопрос без дополнительных уточнений. Цените своё время и время других.
- Откладывание диплом на последний момент.
- Ожидание моментального ответа на свой вопрос. Дипломные руководители - работающие разработчики, которые занимаются, кроме преподавания, своими проектами. Их время ограничено, поэтому постарайтесь задавать правильные вопросы, чтобы получать быстрые ответы!