Inventory App — Система управления инвентарями

👤 Автор курсового проекта

Rinat Sarmuldin Email: ura07srr@gmail.com

Inventory App

• «Inventory App — это учебный проект системы управления инвентарями, разработанный на Symfony 6.4 с PostgreSQL.
• Основной акцент сделан на корректную архитектуру, безопасность и тестируемость.
• Проект поддерживает публичные и приватные инвентари, ACL-доступ, кастомные поля и настраиваемую генерацию идентификаторов элементов.
• Все критические сценарии доступа покрыты автоматическими тестами.»

---

📌 Функциональные возможности

• Регистрация и аутентификация пользователей
• Ролевая модель доступа (ROLE_ADMIN, ROLE_USER)
• Управление инвентарями (создание, редактирование, просмотр)
• Публичные и приватные инвентари
• ACL-доступ к инвентарям (READ / WRITE)
• Кастомные поля инвентаря:
  • разные типы данных
  • динамическая генерация форм
  • изменение порядка полей
• Генерация кастомных идентификаторов элементов инвентаря
• Защита доступа через Symfony Security + Voter

---

🧱 Архитектура проекта

Архитектура проекта построена с ориентацией на:

• Domain-Driven Design (упрощённый, без перегрузки)
• разделение ответственности между слоями
• тестируемость бизнес-логики без инфраструктуры

Проект с использованием слоистой архитектуры:

• Controller — HTTP-слой, обработка запросов
• Service — бизнес-логика приложения
• Domain — доменные правила, value object'ы, enum'ы и политики
• Repository — работа с БД через Doctrine ORM
• Entity — ORM-сущности
• DTO — объекты передачи данных между слоями
• Security / Voter — контроль доступа (ACL)

Такой подход обеспечивает:

• слабую связность компонентов
• удобство тестирования
• готовность к расширению и интеграциям

---

🚀 Требования (Ubuntu 24.04)

Для запуска проекта локально в Ubuntu 24.04 вам понадобятся:

• PHP 8.2 или выше + расширения (php-ctype, php-iconv, php-xml, php-pgsql, php-mbstring, php-intl)
• Composer
• PostgreSQL 16

---

🔐 Безопасность

• Используется Symfony Security
• Аутентификация на основе пользователей, хранимых в БД
• Авторизация реализована через Voter'ы
• Контроль доступа к инвентарям:
  • владелец
  • ACL (READ / WRITE)
  • публичный доступ

Отдельное внимание уделено защите от:

• несанкционированного доступа (IDOR)
• подмены URL-параметров
• CSRF-атак на деструктивные операции

Все проверки доступа и критические сценарии покрыты автоматическими тестами. Особое внимание уделено функциональному тестированию безопасности (CSRF-защита, Voter'ы).

---

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

Проект содержит модульные, интеграционные и функциональные тесты.

Тесты разделены по уровням:

• Unit — проверка доменной логики и сервисов
• Integration — проверка работы Doctrine и репозиториев
• Functional — проверка HTTP-слоя, security и пользовательских сценариев

Запуск тестов

Перед первым запуском тестов локально необходимо инициализировать тестовую базу данных:

php bin/console doctrine:database:create --env=test --if-not-exists
php bin/console doctrine:migrations:migrate --env=test --no-interaction
php bin/console doctrine:fixtures:load --env=test --no-interaction

После этого можно запускать PHPUnit:

# Если через Docker
docker compose exec app vendor/bin/phpunit

# Если локально
php bin/phpunit

• Набор тестов покрывает ключевые бизнес-сценарии и security-инварианты.

---

🛠 Установка и запуск

Вы можете запустить проект 2 способами: через Docker (рекомендуется) или локально.

🚢 Способ 1: Через Docker (быстрый запуск)

1. Клонирование репозитория

git clone git@github.com:07Rinat07/inventory-app-final.git
cd inventory-app-final

2. Запуск контейнеров

docker compose up -d --build

• Команда соберет образ, установит зависимости Composer, создаст основную и тестовую базы данных, выполнит миграции и загрузит фикстуры автоматически.

3. Запуск тестов

docker compose exec app vendor/bin/phpunit

• Все тесты (Unit, Integration, Functional) будут прогнаны внутри контейнера. Тестовая среда (APP_ENV=test) и тестовая база данных настраиваются автоматически.

4. Доступ к приложению

• Приложение будет доступно по адресу: http://localhost:8088/login
• Данные сессий сохраняются в директории var/sessions внутри проекта.
• Для выполнения команд Symfony консоли используйте:

docker compose exec app php bin/console ...

Способ 2: Локальный запуск (Ubuntu 24.04 без Docker)

⚙️ Переменные окружения

Основные параметры настраиваются через .env.local и .env.test.local. Важно: Для корректной работы тестов и приложения рекомендуется использовать разные базы данных или убедиться, что тестовая база инициализирована.

---

Шаги запуска

1. Клонирование репозитория

git clone git@github.com:07Rinat07/inventory-app-final.git
cd inventory-app-final

2. Установка зависимостей PHP и PostgreSQL

sudo apt update
sudo apt install -y php8.2 php8.2-cli php8.2-common php8.2-pgsql php8.2-xml php8.2-mbstring php8.2-curl php8.2-intl php8.2-zip
sudo apt install -y postgresql-16
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

3. Установка зависимостей проекта

composer install

4. Настройка PostgreSQL в Ubuntu

Создайте пользователя и предоставьте ему права на создание баз данных:

sudo -u postgres psql -c "CREATE USER inventory_user WITH PASSWORD 'inventory_pass';"
sudo -u postgres psql -c "ALTER USER inventory_user CREATEDB;"

5. Настройка подключения

Создайте файлы .env.local и .env.test.local. Вы можете использовать одну базу данных для обоих окружений (как в примере ниже) или разные (например, inventory_app и inventory_app_test).

Для .env.local:

DATABASE_URL="pgsql://inventory_user:inventory_pass@127.0.0.1:5432/inventory_app?serverVersion=16"

Для .env.test.local:

DATABASE_URL="pgsql://inventory_user:inventory_pass@127.0.0.1:5432/inventory_app?serverVersion=16"

6. Инициализация базы данных (миграции и фикстуры)

Выполните команды для подготовки базы данных:

# Для основного окружения (dev)
php bin/console doctrine:database:create --if-not-exists
php bin/console doctrine:migrations:migrate --no-interaction
php bin/console doctrine:fixtures:load --no-interaction

# Для тестового окружения (test)
php bin/console doctrine:database:create --env=test --if-not-exists
php bin/console doctrine:migrations:migrate --env=test --no-interaction
php bin/console doctrine:fixtures:load --env=test --no-interaction

7. Запуск сервера

# Использование встроенного сервера PHP
php -S localhost:8000/login -t public

8. Запуск тестов

# Запуск всех тестов для проверки корректности установки
php bin/phpunit

9. Проверка работоспособности

• Откройте http://localhost:8000/login
• Войдите, используя admin@test.com / admin12345
• Если тесты php bin/phpunit прошли успешно (OK), значит база данных и окружение настроены верно.

---

🔑 Тестовые аккаунты (фикстуры)

Email	Пароль	Роль	Описание
admin@test.com	admin12345	ROLE_ADMIN	Полный доступ
user@test.com	user12345	ROLE_USER	Доступ к своим и публичным инвентарям

📦 Структура данных (фикстуры)

• Инвентари
• Admin Private Inventory (приватный)
• Admin Public Inventory (публичный)
• User Private Inventory (приватный)
• ACL
• Пользователь user@test.com имеет просмотр доступ к публичному инвентарю администратора
• Кастомные поля
• Используются для проверки динамических форм

🧠 Принятые решения и ограничения

• JSON-хранение в БД не используется
• Динамическое создание таблиц не применяется
• Все данные нормализованы
• Используются явные связи и индексы
• Архитектура рассчитана на дальнейшее расширение и интеграции

10. Проверка безопасности в тестах
    • Реализована корректная работа с CSRF-токенами в функциональных тестах (InventoryDeleteSecurityTest) для Symfony 6.4.
    • Используется предварительный запрос для инициализации сессии и явная передача запроса в RequestStack.

📎 Дополнительно

Проект разработан в учебных целях как курсовая работа, с упором на:

• чистую архитектуру
• корректную работу с БД
• безопасность
• тестирование и покрытие кода
• удобство поддержки и расширения функционала