Add docker
This commit is contained in:
Evgenii Saenko
387
docs/part1-2-brief.md
Normal file
387
docs/part1-2-brief.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# 📘 Бриф по Главе 1
|
||||
|
||||
## Тема: Рекламно-информационный сайт предприятия
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Цель главы
|
||||
|
||||
Определить значение рекламно-информационного сайта в деятельности организации, проанализировать предметную область и существующие решения, сформулировать требования к создаваемой системе и обосновать выбор инструментов и технологий для её реализации.
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Структура и содержание
|
||||
|
||||
### **1.1. Введение в тему**
|
||||
|
||||
Рекламно-информационные сайты играют ключевую роль в цифровой деятельности организаций. Они обеспечивают представление компании в сети, выполняют функции информирования, продвижения и коммуникации с клиентами. Основная задача таких систем — создание единого центра актуальной информации, доступного пользователям в круглосуточном режиме.
|
||||
|
||||
---
|
||||
|
||||
### **1.2. Роль рекламно-информационного сайта в деятельности компании**
|
||||
|
||||
* Сайт выступает инструментом маркетингового взаимодействия, каналом распространения информации и формирования имиджа.
|
||||
* Обеспечивает комплексное продвижение товаров и услуг, снижает зависимость от традиционных каналов рекламы.
|
||||
* Выполняет функции оперативного обновления информации, аналитики пользовательской активности и обратной связи.
|
||||
* Повышает уровень доверия к компании, способствует укреплению бренда и конкурентоспособности.
|
||||
|
||||
---
|
||||
|
||||
### **1.3. Анализ предметной области и существующих решений**
|
||||
|
||||
* Предметная область охватывает процессы разработки веб-ресурсов, организации хранения и обработки данных, а также взаимодействие с пользователем.
|
||||
* Типичные функции сайтов-аналогов: главная страница, разделы «О компании», каталог услуг, новости, формы обратной связи, адаптивная верстка.
|
||||
* Современные тенденции: использование систем управления контентом (CMS), интеграция с социальными сетями, мультимедийный контент, адаптивный дизайн и персонализированные сервисы.
|
||||
* Вывод: сайт должен быть информативным, интуитивно понятным и обеспечивать оперативное обновление данных при высокой производительности.
|
||||
|
||||
---
|
||||
|
||||
### **1.4. Постановка задачи**
|
||||
|
||||
#### **Функциональные требования:**
|
||||
|
||||
* публикация сведений об организации, услугах и новостях;
|
||||
* поиск по содержимому сайта;
|
||||
* формы обратной связи и администрирование контента;
|
||||
* централизованное хранение данных в базе.
|
||||
|
||||
#### **Нефункциональные требования:**
|
||||
|
||||
* корректное отображение на различных устройствах;
|
||||
* безопасность и защита данных;
|
||||
* высокая скорость работы и возможность масштабирования;
|
||||
* удобство сопровождения и расширяемость архитектуры.
|
||||
|
||||
Задача разработки заключается в создании системы, обеспечивающей удобный доступ к информации и эффективное управление содержимым со стороны организации.
|
||||
|
||||
---
|
||||
|
||||
### **1.5. Обоснование выбора инструментов и технологий**
|
||||
|
||||
| Компонент | Технология | Аргументация выбора |
|
||||
| --------------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| **Фронтенд** | React | Модульная структура, высокая производительность, повторное использование компонентов. |
|
||||
| **Бэкенд** | Kotlin (Ktor / Spring Boot) | Строгая типизация, устойчивость, поддержка асинхронных операций, интеграция с Java-экосистемой. |
|
||||
| **База данных** | PostgreSQL | Реляционная модель, транзакционная целостность, масштабируемость, надёжность. |
|
||||
| **Веб-сервер** | NGINX | Высокая производительность, стабильность, возможности балансировки нагрузки. |
|
||||
|
||||
📌 Совокупность данных технологий обеспечивает создание надёжной, безопасной и масштабируемой системы, соответствующей современным требованиям веб-разработки.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Ключевые выводы по главе
|
||||
|
||||
1. Рекламно-информационный сайт является стратегически значимым элементом цифрового присутствия организации.
|
||||
2. Анализ аналогичных решений позволил определить актуальные тенденции и стандарты для разработки.
|
||||
3. Сформулированные требования отражают как пользовательские, так и внутренние потребности компании.
|
||||
4. Выбор инструментов (React, Kotlin, PostgreSQL, NGINX) обоснован с позиций эффективности, надёжности и дальнейшего развития проекта.
|
||||
5. Итогом первой главы является определение концептуальной базы и технологического фундамента для последующего проектирования системы.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Итоговая роль главы
|
||||
|
||||
Первая глава закладывает методологическую и техническую основу дипломного проекта.
|
||||
На её основе формируется архитектура системы, разрабатывается структура базы данных и описываются механизмы взаимодействия клиентской и серверной частей, которые раскрываются в последующих разделах работы.
|
||||
|
||||
|
||||
Brief: Проектирование и разработка веб-приложения «BankInfo»
|
||||
|
||||
(суммаризация второй главы)
|
||||
|
||||
1. Архитектурная концепция
|
||||
|
||||
Веб-приложение реализовано как трёхуровневая система:
|
||||
|
||||
Frontend — React SPA (React 19, TypeScript, MobX, MUI, React Router, Zod)
|
||||
|
||||
Backend — Ktor (Kotlin), Ktorm ORM, HikariCP, JWT
|
||||
|
||||
Database — PostgreSQL 14 (схема public)
|
||||
|
||||
Ключевые принципы проектирования:
|
||||
|
||||
модульность и слабая связанность;
|
||||
|
||||
разделение ответственности по слоям;
|
||||
|
||||
REST-взаимодействие между клиентом и сервером;
|
||||
* статeless-авторизация через JWT;
|
||||
* строгая типизация DTO и валидируемых данных.
|
||||
|
||||
---
|
||||
|
||||
## **2. Архитектура приложения**
|
||||
|
||||
### **2.1. Общая схема взаимодействия**
|
||||
|
||||
Поток данных:
|
||||
|
||||
```
|
||||
Client (React SPA)
|
||||
→ REST API /api/v1/*
|
||||
→ Ktor Server (Routing → Controllers → Services → Repositories)
|
||||
→ PostgreSQL (SQL через Ktorm)
|
||||
← JSON Response
|
||||
```
|
||||
|
||||
В приложении предусмотрено место под:
|
||||
|
||||
* **Рисунок 2.1** — Architecture / Deployment diagram
|
||||
* **Приложение А** — увеличенная схема
|
||||
|
||||
---
|
||||
|
||||
### **2.2. Backend**
|
||||
|
||||
Структура серверной части:
|
||||
|
||||
```
|
||||
app/
|
||||
├─ Database (HikariCP)
|
||||
├─ HTTP plugins
|
||||
├─ Serialization (kotlinx)
|
||||
├─ Security (JWT)
|
||||
└─ Routing (подключение модулей)
|
||||
|
||||
modules/
|
||||
├─ aНиже — **брив (brief-doc) по всей второй главе**, оформленный в Markdown.
|
||||
Это краткая, структурированная, сжатая версия всей главы 2 — идеально подходит:
|
||||
|
||||
* для презентации,
|
||||
* для защиты диплома,
|
||||
* для приложений,
|
||||
* для рабочего черновика.
|
||||
|
||||
Готов к копированию в отдельный файл `brief-chapter-2.md`.
|
||||
|
||||
---
|
||||
|
||||
# **Brief: Проектирование и разработка веб-приложения «BankInfo»**
|
||||
|
||||
*(суммаризация второй главы)*
|
||||
|
||||
---
|
||||
|
||||
## **1. Архитектурная концепция**
|
||||
|
||||
Веб-приложение реализовано как трёхуровневая система:
|
||||
|
||||
* **Frontend** — React SPA (React 19, TypeScript, MobX, MUI, React Router, Zod)
|
||||
* **Backend** — Ktor (Kotlin), Ktorm ORM, HikariCP, JWT
|
||||
* **Database** — PostgreSQL 14 (схема `public`)
|
||||
|
||||
Ключевые принципы проектирования:
|
||||
|
||||
* модульность и слабая связанность;
|
||||
* раздdmin
|
||||
├─ news
|
||||
├─ services
|
||||
├─ serviceCategory
|
||||
└─ lead
|
||||
```
|
||||
|
||||
Используемые паттерны:
|
||||
|
||||
* **Layered Architecture**
|
||||
* **Controller → Service → Repository**
|
||||
* **DTO Boundary**
|
||||
* **Repository Pattern (DDD)**
|
||||
* **Exception Mapping** через StatusPages
|
||||
* **Dependency Injection (ручной)**
|
||||
* **Stateless Auth** через JWT
|
||||
|
||||
Основные технические особенности:
|
||||
|
||||
* валидация slug/username/email реализована сервисами;
|
||||
* eager-loading связей в услугах (JOIN в Ktorm);
|
||||
* SQL-пагинация через `LIMIT/OFFSET`;
|
||||
* единый формат ошибок;
|
||||
* отсутствие уникальных ограничений на уровне БД по slug/email (осознанное решение).
|
||||
|
||||
---
|
||||
|
||||
### **2.3. Frontend**
|
||||
|
||||
Стек:
|
||||
|
||||
* React 19
|
||||
* TypeScript
|
||||
* MobX (`observer`, observable state tree)
|
||||
* React Router v7 (nested routing)
|
||||
* MUI (design system)
|
||||
* Zod (schema validation)
|
||||
* Vite (bundler)
|
||||
|
||||
Структура каталогов:
|
||||
|
||||
```
|
||||
src/
|
||||
├─ app/ (маршруты, App)
|
||||
├─ modules/ (публичные страницы + админка)
|
||||
├─ stores/ (MobX)
|
||||
├─ api/ (httpClient + SDK + DTO + Zod)
|
||||
├─ shared/ (UI-компоненты, тема)
|
||||
├─ providers/ (StoreProvider, ThemeProvider)
|
||||
└─ assets/
|
||||
```
|
||||
|
||||
Паттерны:
|
||||
|
||||
* **Component-based architecture**
|
||||
* **Separation of concerns**
|
||||
* **Observer Pattern (MobX)**
|
||||
* **Gateway/API Client**
|
||||
* **DTO Boundary для фронтенда**
|
||||
* **Layout Composition** для админки
|
||||
* **Design System Architecture** (MUI)
|
||||
|
||||
Поток данных:
|
||||
|
||||
```
|
||||
Component → Store → API → Store → UI
|
||||
```
|
||||
|
||||
Вставляется как:
|
||||
|
||||
* **Рисунок 2.3** — Data Flow Diagram
|
||||
* **Приложение В** — полная версия
|
||||
|
||||
---
|
||||
|
||||
## **3. REST API**
|
||||
|
||||
Основная структура: `/api/v1/*`
|
||||
|
||||
Ключевые маршруты:
|
||||
|
||||
| Endpoint | Метод | Назначение |
|
||||
| ------------- | ------------------- | -------------------------- |
|
||||
| `/auth/login` | POST | Авторизация администратора |
|
||||
| `/news` | GET/POST/PUT/DELETE | Управление новостями |
|
||||
| `/services` | GET/POST/PUT/DELETE | Услуги |
|
||||
| `/categories` | GET/POST/PUT/DELETE | Категории |
|
||||
| `/leads` | GET/POST | Лиды |
|
||||
| `/users` | GET/POST/PUT/DELETE | Администраторы |
|
||||
|
||||
Все административные endpoints защищены JWT-middleware.
|
||||
|
||||
---
|
||||
|
||||
## **4. Модель данных**
|
||||
|
||||
### **Основные сущности:**
|
||||
|
||||
* **Admin**
|
||||
* **News**
|
||||
* **ServiceCategory**
|
||||
* **Service**
|
||||
* **Lead**
|
||||
|
||||
### **Особенности БД:**
|
||||
|
||||
* PostgreSQL 14.19
|
||||
* схема: `public`
|
||||
* `timestamptz` для временных полей
|
||||
* `varchar` дефолтной длины
|
||||
* единственный FK: `services.category_id → categories.id`
|
||||
* уникальность slug/username/email **не** enforced в БД (реализуется сервисами)
|
||||
|
||||
### **Реализация через Ktorm:**
|
||||
|
||||
* интерфейсы Entity
|
||||
* объекты Table
|
||||
* `Database.sequenceOf(Table)`
|
||||
* сущности загружаются с категориями через JOIN (eager)
|
||||
* DTO разделены на публичные и административные
|
||||
|
||||
ER-диаграмма:
|
||||
|
||||
* **Рисунок 2.4** — ER Diagram
|
||||
* **Приложение Д** — масштабируемая версия
|
||||
|
||||
---
|
||||
|
||||
## **5. UI / UX проектирование**
|
||||
|
||||
Публичные страницы:
|
||||
|
||||
* Главная
|
||||
* Услуги
|
||||
* Услуга
|
||||
* Новости
|
||||
* Новость
|
||||
* О компании
|
||||
* Контакты / форма лида
|
||||
|
||||
Административная панель:
|
||||
|
||||
* Dashboard
|
||||
* Администраторы
|
||||
* Услуги
|
||||
* Категории
|
||||
* Новости
|
||||
* Лиды
|
||||
|
||||
`sitemap`:
|
||||
|
||||
* **диаграмма (Рисунок 2.5)**
|
||||
* **Приложение Е**
|
||||
|
||||
---
|
||||
|
||||
## **6. Реализация**
|
||||
|
||||
### **Backend:**
|
||||
|
||||
* безопасная авторизация JWT
|
||||
* унифицированные CRUD-модули
|
||||
* SQL-запросы через Ktorm
|
||||
* централизованная обработка ошибок
|
||||
* слабая связанность сущностей
|
||||
* ручная структура БД (без миграций)
|
||||
|
||||
### **Frontend:**
|
||||
|
||||
* реактивность MobX
|
||||
* строгая типизация API через Zod
|
||||
* модульная структура pages/features/components
|
||||
* единая тема оформления
|
||||
* локальная валидация форм
|
||||
* защищённые маршруты для админки
|
||||
|
||||
---
|
||||
|
||||
## **7. Тестирование**
|
||||
|
||||
### **Проверялось:**
|
||||
|
||||
* корректность REST API
|
||||
* авторизация и работа с JWT
|
||||
* маршруты и вложенная навигация
|
||||
* формы и валидация
|
||||
* реактивность MobX
|
||||
* стабильность CRUD-операций
|
||||
* отображение данных на публичных страницах
|
||||
* стабильность админ-панели
|
||||
|
||||
---
|
||||
|
||||
## **8. Общий вывод**
|
||||
|
||||
Система имеет следующую совокупность свойств:
|
||||
|
||||
* надёжная архитектурная основа;
|
||||
* модульность и расширяемость;
|
||||
* современный стек технологий;
|
||||
* строгие границы ответственности между слоями;
|
||||
* безопасная модель аутентификации;
|
||||
* предсказуемые, универсальные CRUD-процессы;
|
||||
* реактивность клиентской части;
|
||||
* типобезопасный сетевой слой;
|
||||
* минимальная связанность базы данных;
|
||||
* удобная административная панель;
|
||||
* чистая архитектура backend и frontend.
|
||||
|
||||
С точки зрения инженерии ПО, проект демонстрирует высокий уровень проработки, следование современным практикам и архитектурным принципам, а также готовность к дальнейшему развитию и эксплуатационному использованию
|
||||
|
||||
Reference in New Issue
Block a user