# 📘 Бриф по Главе 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.

С точки зрения инженерии ПО, проект демонстрирует высокий уровень проработки, следование современным практикам и архитектурным принципам, а также готовность к дальнейшему развитию и эксплуатационному использованию