Kivi-App, учебное приложение на Angular 8.3.23 и Typescript

Технологии

• Frontend: Angular 8.3.23 и Typescript
• Backend: PHP и MySQL
• JWT Authentication c HTTP Interceptors, Guards
• Unit тестирование для Angular: Jasmine + Karma
• E2E тестирование: Jasmine + Protractor
• Виртуализация: Docker и Docker-Compose

Приложение

Приложение Kivi-App представляет собой "набросок" будущего сайта с панелью администрирования и бекендом, включая CRUD взаимодействия между ними.

• Пользовательская часть сайта имеет 4 страницы:

• /
• /rafting
• /semeyniy-rafting
• /error404 (страница ошибки 404)
  На этих страницах можно оставлять заказы через 5 видов форм.

• Панель администрирования имеет систему авторизации через JWT Auth и 4 страницы:

• /admin/login (страница входа)
• /admin/dashboard (страница со списком заказов с ссылками на изменение и удаление заказов)
• /admin/create-order (страница создания нового заказа)
• /admin/order/%ID заказа%/edit (страница изменения заказа) В админпанели можно посмотреть список всех заказов, создавать новые заказы, а также редактировать и удалять уже имеющиеся.

Frontend, элементы Angular

• Компоненты

• Пользовательская часть: frontend/src/app/shared/components/
• Админка: frontend/src/app/admin/

• Сервисы

• Пользовательская часть: frontend/src/app/shared/services/
• Админка: frontend/src/app/admin/shared/services/

• Pipe frontend/src/app/shared/pipes/
• Получение данных из Json файла frontend/src/app/shared/components/first-block/first-block.component.ts (строка 58)
• Роутеры:

• Пользовательской части frontend/src/app/app-routing.module.ts
• Админки с защитой роутов frontend/src/app/admin/admin.module.ts
• AuthGuard frontend/src/app/admin/shared/auth.guard.ts

• Формы обратной связи, содержат валидатор с обработкой ошибок, выполняют отправку данных, получают и обрабатывают ответ от сервера:

• Форма заказа 1 frontend/src/app/shared/components/callorder-form/
• Форма заказа 2 frontend/src/app/shared/components/first-form/
• Форма заказа 3 frontend/src/app/shared/components/footer-form/
• Форма заказа 4 frontend/src/app/shared/components/question-form/
• Форма заказа 5 frontend/src/app/shared/components/top-form/
• Форма входа в админку: frontend/src/app/admin/login-page/
• Форма создания заказа в админке: frontend/src/app/admin/create-order/
• Кастомные валидаторы для форм: frontend/src/app/shared/form.validators.ts

• Модули, 4 для пользовательских страниц приложения, 1 для админки и 2 для более удобной и оптимизированной группировки прочих сущностей Angular:

• Главная страница: frontend/src/app/main/main.module.ts
• Страница /rafting: frontend/src/app/rafting/rafting.module.ts
• Страница /semeyniy-rafting: frontend/src/app/semeyniy-rafting/semeyniy-rafting.module.ts
• Страница ошибки 404: frontend/src/app/error404/error404.module.ts
• Модуль для основных сущностей: frontend/src/app/shared/shared.module.ts
• Модуль для доп. сущностей на 3-х основных страницах: frontend/src/app/shared/pages.module.ts
• Модуль для панели администрирования: frontend/src/app/admin/admin.module.ts

• Механизм авторизации через JWT токены для админки:

• Получение токена, его хранение в Local Storage и удаление токена
• Проверка валидности токена
• Обработка ошибок
  frontend/src/app/admin/shared/services/auth.service.ts

• Интерсептор для проверки валидности текущего токена в админке: frontend/src/app/shared/auth.interceptor.ts
• Ленивая загрузка изображений в пользовательской части с ng-lazyload-image и youtube видео с помощью директивы inView
• WYSIWYG редактор ngx-quill для формы создания новых заказов в админке
• Пагинация на странице списка заказов frontend/src/app/admin/dashboard-page/ с помощью jw-angular-pagination
• Ru локализация в date pipe на странице списка заказов frontend/src/app/admin/dashboard-page/
• Поддержка PWA. Если собрать приложение в режиме prodact, то оно будет работать как PWA, с использованием встроенного Service Worker
• Вывод тегов <script ...> в шаблонах. Обеспечивающий компонент frontend/src/app/shared/components/scripthack и пример вывода тега в шаблоне frontend/src/app/components/subscribe-block/subscribe-block.component.html
• Вывод видео с Youtube, url видео загружается из JSON файла frontend/src/app/shared/components/video-block/

Тестирование frontend

• Unit тестирование пользовательской части приложения Jasmine + Karma
• End-to-end тестирование пользовательской части приложения Jasmine + Protractor

Backend

• Бекенд работает на PHP и MySQL.

• В пользовательской части сайта обработка данных из форм заказа производится PHP скриптом: backend/requests.add.php. При корректном выполнении сценария данные из форм записываются в БД на MySQL. Также PHP скрипт модифицирует полученные данные перед отправкой их обратно на frontend, что служит маркером успешного получения и обработки этих данных бекендом. При ошибке записи данных в БД сервер также отправляет на frontend сообщение о возникшей проблеме.
• Панель администрирования обменивается данными с бекендом через 4 endpoints:
• Страница входа в админку (/admin/login), endpoint: backend/jwt/api/login.php
• Страница списка заказов (/admin/dashboard), endpoint: backend/jwt/api/get_orders.php
• Страница создания нового заказа (/admin/create-order), endpoint: backend/jwt/api/create_order.php
• Страница редактирования заказа (admin/order/%id заказа%/edit), endpoint: backend/jwt/api/update_order.php
  А также функция удаления заказа через backend/jwt/api/delete_order.php

• Аутентификация c токенами через библиотеку JWT

Виртуализация

• Выполнена на Docker и Docker-Compose
• 2 Dockerfile для:

• frontend frontend/Dockerfile
• backend backend/Dockerfile

• 3 конфига Docker-Compose, используемых для:

• разработки приложения docker-compose.yaml
• Unit тестирования dc-angular-unit-tests.yaml
• E2E тестирования dc-angular-e2e-tests.yaml

Инсталяция и запуск

Для работы с приложением рекомендуется использовать Docker, под него сделаны все необходимые настройки для совместной работы frontend и backend. Инсталяция и запуск приложения описаны для Docker.

1. Склонировать приложение.
2. Установить зависимости:

docker run --rm -v ${PWD}/frontend/:/opt/kivi -w /opt/kivi node:12 npm install

3. Первый запуск и build образа:

docker-compose up --build -d

Последующие запуски:

docker-compose up -d

4. Создание рабочей БД kiviapp для приложения. Создание структуры БД kiviapp и пользователя админки [email protected] / 11111111 возможно 2-мя способами:

• Запустив скрипт: http://localhost:80/create.new.table.php
• Через PhpMyAdmin, http://localhost:8081/ (root / root), запросы с таблицами лежат в файле backend/create.new.table.php)

Остановка приложения

docker-compose kill

Функционал приложения

Демонстрация возможностей приложения

1. Вход в пользовательску часть: http://localhost:4200/. Здесь можно заполнить и отправить любую форму обратной связи. Если данные из корректно заполненной формы успешно попали на сервер, то появится сообщение об успешной отправке запроса.
2. Вход в панель администрирования: http://localhost:4200/admin/login ([email protected] / 11111111). Здесь можно создать новый заказ на странице "Новый заказ", а также редактировать или удалять уже созданные заказы.

Формы обратной связи в пользовательской части

На каждой станице есть 5 различных форм обратной связи, позволяющих посетителям отправлять заказы услуг. 4 формы в модальных окнах доступны по кнопкам:

• Заказать звонок (шапка)
• Задать вопрос (шапка)
• Заказать (шапка)
• Заказать сейчас (контент)
  Пятая форма расположена внизу страницы.

Каждая форма умеет проверять введенные данные и подсказывать какие ошибки ввода нужно исправить, если они есть. Если все данные введены корректно, то форма пытается отправить их на сервер и ждет его ответ. После получения ответа сервера он выводится на экран. Как пример обработки ошибок могут быть 3 варианта ответа:

• Отправка данных прошла успешно
• Отправить данные не удалось
• Сервер неверно обработал полученные данные

Unit тестирование

Тестами покрыто примерно 80% всех функций модуля сайта (app.module.ts). Код тестов содержится рядом с кодом приложения: frontend/src/app/

Работа с Unit тестами (через Docker и Docker-Compose)

1. Запуск:

docker-compose -f dc-angular-unit-tests.yaml up -d 

Далее открыть вкладку браузера: http://localhost:9876/, ждем 10-15 секунд и перегружаем ее (в некоторых случаях 2-3 раза). Если все сработало, то во вкладке должна отобразиться информация о ходе тесирования.
Для повторного запуска тестов нужно перезагрузить эту же вкладку браузера.

2. Остановка и очистка контейнеров Docker после завершения Unit тестирования:

docker-compose -f dc-angular-unit-tests.yaml kill
docker-compose -f dc-angular-unit-tests.yaml down 

E2E тестирование

Разбито на 2 части. Покрыты только некоторые элементы страницы и проверены 3 коротких use case для форм обратной связи. Код тестов расположен тут: frontend/e2e/src/

Первая часть, элементы страницы

Тестами покрыта генерация различных типов элементов:

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

Путь: frontend/e2e/src/app-kivi-default.e2e-spec.ts

Вторая часть, формы обратной связи

Выполняется проверка 3 сценариев:

1. Открытие/закрытие модального окна одной из форм
2. Обработка 2-х ошибок корректности заполнения формы
3. Отправка валидных данных на работающий и неработающий backend. Т.е. при работающем или неработающем backend один из тестов будет не пройден.

Путь: frontend/e2e/src/app-kivi-test-form.e2e-spec.ts

Работа с E2E тестами (через Docker и Docker-Compose)

1. Первый запуск с созданием образа:

docker-compose -f dc-angular-e2e-tests.yaml up --build -d

Последующие запуски:

docker-compose -f dc-angular-e2e-tests.yaml up -d

2. Результаты тестов запишутся в файл frontend/logs.txt
3. Остановка и очистка контейнеров Docker:

docker-compose -f dc-angular-e2e-tests.yaml kill
docker-compose -f dc-angular-e2e-tests.yaml down

Внимание! Используемый для Е2Е тестов Docker образ trion/ng-cli-e2e работает некорректно с тестами, связанными с передачей запросов на backend. Это тесты:

• Use case 3 (send valid data to working server): should have success message
• Use case 3 (send valid data to broken server): should have error server data sending message

Решает проблему запуск Е2Е тестов локально:

ng e2e

При этом можно воспользоваться запущенными в Docker контейнерами с PHP и MySQL.