Документация проекта j~dict!^w^

Личный японский словарь (∩^o^)⊃━☆

📖 j~dict!^w^ это...

...небольшое веб-приложение для ведения личного японского словаря. В нём вы можете создавать, читать, обновлять и удалять слова, а также организовывать слова по тегам и даже... управлять личным кабинетом и настраивать свою аватарку!😜

Этот пет-проект резюмирует практические навыки, полученные в процессе прохождения производстенной практики от Колледжа связи №54 им. П. М. Вострухина.

🏗 Архитектура

Диаграмма контейнеров

Основные части системы взаимодействуют следующим образом:

1. Пользователь работает с интерфейсом (Фронтенда);
2. Фронтенд отправляет запросы к Бэкенду (REST API);
3. Бэкенд сохраняет/читает данные из PostgreSQL и отправляет события изменений в Kafka.

graph LR
    User((Пользователь))

    subgraph FE["Фронтенд"]
        UI["Пользовательский интерфейс"]
        AuthStore["Хранилище авторизации"]
        WordStore["Хранилище слов"]
    end

    subgraph BE["Бэкенд"]
        API["REST API"]
        AuthService["Сервис авторизации"]
        WordService["Сервис словаря"]
        ImportService["Сервис импорта"]
        KafkaProducer["Продюсер Kafka"]
    end

    subgraph INF["Инфраструктура"]
        DB[(PostgreSQL)]
        Kafka{{Kafka}}
        Zookeeper["Zookeeper"]
    end

    User <--> UI
    UI --> API

    API --> AuthService
    API --> WordService
    API --> ImportService

    AuthService --> DB
    WordService --> DB
    ImportService --> WordService
    WordService --> KafkaProducer
    KafkaProducer --> Kafka
    Kafka -.-> Zookeeper

    classDef frontend fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px
    classDef backend fill:#E8F5E9,stroke:#43A047,stroke-width:2px
    classDef infra fill:#FFFDE7,stroke:#F9A825,stroke-width:2px
    classDef user fill:#FCE4EC,stroke:#C2185B,stroke-width:2px

    class UI,AuthStore,WordStore frontend
    class API,AuthService,WordService,ImportService,KafkaProducer backend
    class DB,Kafka,Zookeeper infra
    class User user

Loading

Диаграмма компонентов

Изнутри ИС настроена следующим образом:

• Фронтенд: Состоит из Vue-компонентов (UI), Pinia (хранение данных в памяти) и Axios (общение с сервером);
• Бэкенд: Разделен на слои:
  • Handlers (обработчики) - принимают HTTP-запросы;
  • Services (сервисы) - содержат бизнес-логику (правила работы);
  • Repositories (репозитории) - работают напрямую с базой данных.
• База данных и Kafka: Внешние системы для хранения данных и очереди событий.

classDiagram
    direction LR

    class Фронтенд {
        Компоненты интерфейса
        Управление состоянием
        HTTP-запросы
    }

    class Бэкенд {
        REST API
        Бизнес-логика
        Доступ к данным
    }

    class База данных {
        Пользователи
        Слова
    }

    class Kafka {
        События изменений слов
    }

    Фронтенд ..> Бэкенд : HTTP / JSON
    Бэкенд ..> PostgreSQL : SQL
    Бэкенд ..> Kafka : Публикация событий

    classDef frontend fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px
    classDef backend fill:#E8F5E9,stroke:#43A047,stroke-width:2px
    classDef infra fill:#FFFDE7,stroke:#F9A825,stroke-width:2px

Loading

🚀 Запуск проекта

Для запуска проекта необходимы установленные Docker и docker-compose.

Быстрый старт через Makefile

Самый простой способ запустить проект - использовать make. Команды выполняются из корня проекта.

# Запуск всех сервисов (в фоновом режиме, с пересборкой)
make up

# Просмотр логов всех сервисов
make logs

# Остановка сервисов
make down

Ручной запуск через docker-compose.yml

Используйте команды docker-compose из корня проекта напрямую:

docker-compose up --build -d

Приложение будет доступно по адресу: http://localhost:5173.

📚 API-Документация

API задокументировано с помощью Swagger. После запуска бэкенда Swagger-документация доступна по адресу:

http://localhost:8080/swagger/index.html

Основные эндпоинты

• Auth:
  • POST /api/auth/register - Регистрация
  • POST /api/auth/login - Вход
  • GET /api/auth/me - Получение текущего пользователя
• Words:
  • GET /api/words - Получение списка слов
  • POST /api/words - Добавление слова
  • PATCH /api/words/{id} - Обновление слова
  • DELETE /api/words/{id} - Удаление слова
• Import:
  • POST /api/words/import - Загрузка слов из CSV через Kafka

🛠 Технологический стек

Область	Технология
Бэкенд	Go (Golang), Gin Gonic, JWT-Auth
Фронтенд	Vue 3, Pinia, Vue Router, TailwindCSS, Vite
База данных	PostgreSQL 18
Брокер сообщений	Apache Kafka (для асинхронной обработки импорта)
Инфраструктура	Docker, docker-compose, Makefile
Документация	Swagger (OpenAPI)

📂 Структура проекта

├── backend/            # Код бэкенда
│   ├── cmd/            # Точка входа (main.go)
│   ├── internal/       # Бизнес-логика, хендлеры, сервисы
│   ├── db/migrations/  # SQL-миграции
│   └── docs/           # Swagger-документация
├── frontend/           # Код фронтенда
│   ├── src/            # Компоненты, сторы, представления
├── docker-compose.yml  # Описание сервисов и их связей
└── Makefile            # Команды для управления проектом

🌐 GitHub Pages (Демо)

В ветке gh-pages находится статическая версия фронтенда, которая используется для демо UI проекта на GitHub Pages.

ВАЖНО! Без запущенного локально бэкенда функционал API (авторизация, загрузка слов) работать не будет.

---

_{Веб-приложение // j~dict!^w^}
^{Made with love by MindlessMuse666}