71

internal/http/handlers.go

@@ -32,6 +32,19 @@ import (
 	"github.com/gorilla/mux"
 )
 
+// @Summary Получить персональную ссылку
+// @Description Получение персональной ссылки агента для вакансии
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param agent_id path string true "ID агента"
+// @Param vacancy_id path string true "ID вакансии"
+// @Success 200 {object} types.PersonalLinkResponse "Персональная ссылка"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/agents/{agent_id}/vacancies/{vacancy_id} [get]
 func (h *handler) getPersonalLinkHandler(w http.ResponseWriter, r *http.Request) {
 	handlerName := "getPersonalLinkHandler"
 	vars := mux.Vars(r)
@@ -70,6 +83,18 @@ func (h *handler) getPersonalLinkHandler(w http.ResponseWriter, r *http.Request)
 	}
 }
 
+// @Summary Получить анкету
+// @Description Получение HTML формы анкеты для клиента
+// @Tags clients
+// @Accept json
+// @Produce text/html
+// @Param link query string true "Зашифрованная ссылка с параметрами"
+// @Success 200 {string} string "HTML форма анкеты"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 404 {object} map[string]string "Вакансия не найдена"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/anketa [get]
+//
 //nolint:funlen // TODO: make it sudo super clean
 func (h *handler) getAnketaHandler(w http.ResponseWriter, r *http.Request) {
 	handlerName := "getAnketaHandler"
@@ -235,6 +260,19 @@ func (h *handler) extractPermissions(permMap *auth.GetPermissionsByUsersIdRespon
 	return perm
 }
 
+// @Summary Получить список сотрудников компании
+// @Description Получение списка сотрудников компании
+// @Tags employees
+// @Accept json
+// @Produce json
+// @Param company_id path string true "ID компании"
+// @Param uid query string true "ID пользователя"
+// @Success 200 {object} rmodel.EmployeeResponse "Список сотрудников"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/companies/{company_id}/employees [get]
 func (h *handler) getEmployeesHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getEmployeesHandler"
 
@@ -292,6 +330,16 @@ func (h *handler) getEmployeesHandler(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// @Summary Получить статус валидации пользователя
+// @Description Получение статуса валидации пользователя по UID
+// @Tags system
+// @Accept json
+// @Produce json
+// @Param uid path string true "UID пользователя"
+// @Success 200 {object} map[string]string "Статус валидации"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/{uid}/validation [get]
 func (h *handler) getUserValidationStatusHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getValidationStatusHandler"
 
@@ -331,6 +379,16 @@ func (h *handler) getUserValidationStatusHandler(w http.ResponseWriter, r *http.
 	}
 }
 
+// @Summary Получить файл документа
+// @Description Получение файла документа по имени
+// @Tags system
+// @Accept json
+// @Produce application/octet-stream
+// @Param file path string true "Имя файла"
+// @Success 200 {file} file "Файл документа"
+// @Failure 404 {object} map[string]string "Файл не найден"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/docs/{file} [get]
 func (h *handler) getFileHandler(w http.ResponseWriter, r *http.Request) {
 	vars := mux.Vars(r)
 	fileName := vars["file"]
@@ -389,6 +447,17 @@ func (h *handler) getFileHandler(w http.ResponseWriter, r *http.Request) {
 	_, _ = w.Write([]byte(link))
 }
 
+// @Summary Подтверждение email
+// @Description Подтверждение email адреса пользователя по токену
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param uid query string true "ID пользователя"
+// @Param token query string true "Токен подтверждения"
+// @Success 200 {object} map[string]string "Email успешно подтвержден"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/verify_email [patch]
 func (h *handler) verifyEmailHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "verifyEmailHandler"
 
@@ -528,6 +597,16 @@ func (h *handler) sendNewUserNotificationToAdmin(userInfo *auth.UserInfo, userNa
 	return nil
 }
 
+// @Summary Статус подтверждения email
+// @Description Получение статуса подтверждения email адреса пользователя
+// @Tags auth
+// @Accept json
+// @Produce json
+// @Param uid query string true "ID пользователя"
+// @Success 200 {object} map[string]string "Статус подтверждения email"
+// @Failure 400 {object} map[string]string "Неверные параметры запроса"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Router /api/v1/verify_email [get]
 func (h *handler) getEmailVerificationStatusHandler(w http.ResponseWriter, r *http.Request) {
 	const handlerName = "getEmailVerificationStatusHandler"
 
@@ -638,6 +717,23 @@ func (h *handler) validateEmail(email string) (bool, error) {
 	return isValidEmail, nil
 }
 
+// @Summary Получить события пользователя
+// @Description Получение ленты событий пользователя с возможностью фильтрации
+// @Tags feed
+// @Accept json
+// @Produce json
+// @Param uid path string true "ID пользователя"
+// @Param user_type query string true "Тип пользователя (agent/distributor)"
+// @Param event_type query string false "Тип события (через запятую)"
+// @Param show_cancelled query bool false "Показывать отмененные события"
+// @Param limit query int false "Лимит событий"
+// @Param offset query int false "Смещение"
+// @Success 200 {object} []feed.Event "Список событий"
+// @Failure 400 {object} map[string]string "Неверные данные запроса"
+// @Failure 401 {object} map[string]string "Неавторизованный доступ"
+// @Failure 500 {object} map[string]string "Внутренняя ошибка сервера"
+// @Security BearerAuth
+// @Router /api/v1/feed/{uid}/events [get]
 func (h *handler) GetUserEventsHandler(w http.ResponseWriter, r *http.Request) {
 	handlerName := "GetUserEventsHandler"
 	query := r.URL.Query()