Index: README.md =================================================================== --- README.md (revision 64e6f27b1d07573faa62c456741356533cddbdd7) +++ README.md (revision bc45cb5da7c6d8482bc21838561ed96e007b138d) @@ -1,271 +1,44 @@ -# SIMLAB – Виртуелна Хемиска Лабораторија (Flask + PostgreSQL) +# SIMLAB – Виртуелна Хемиска Лабораторија -Образовна веб-апликација за симулации на хемиски реакции и следење студентска активност. +Образовна веб-апликација изградена со **Flask + PostgreSQL** за симулации на хемиски реакции, управување со елементи, лабораториска опрема и активности на студенти. -## Содржина +--- -1. [Преглед](#1-преглед) -2. [Технологии / Стек](#2-технологии--стек) -3. [Структура на проект](#3-структура-на-проект) -4. [Улоги и дозволи](#4-улоги-и-дозволи) -5. [База на податоци (шема)](#5-база-на-податоци-шема) -6. [Логирање (logging)](#6-логирање-logging) -7. [Рути и функционалности](#7-рути-и-функционалности) -8. [Data-access слој (DatabaseManager)](#8-data-access-слој-databasemanager) -9. [Конфигурација и пуштање](#9-конфигурација-и-пуштање) -10. [Сигурност и приватност](#10-сигурност-и-приватност) -11. [Перформанси и интегритет](#11-перформанси-и-интегритет) -12. [Познати ограничувања](#12-познати-ограничувања) -13. [Тест сценарија за демонстрација](#13-тест-сценарија-за-демонстрација) -14. [Troubleshooting](#14-troubleshooting) -15. [Идни подобрувања](#15-идни-подобрувања) -- [Апендикс A — cURL примери](#апендикс-a--curl-примери) -- [Апендикс B — .env пример](#апендикс-b--env-пример) +## Главни функционалности +- Улоги: **Teacher** и **Student** со различни дозволи +- CRUD за **Elements**, **Lab Equipment**, **Reactions** +- Автоматско креирање на **Experiments** при додавање реакција +- Dashboard со статистики и извештаи (basic + advanced SQL) +- Bcrypt лозинки, Flask sessions, индекси и constraints за интегритет -## 1) Преглед +--- -SIMLAB е апликација за: -- управување со елементи, лаб. опрема, реакции и експерименти; -- симулација на реакции и логирање на учество на студенти; -- дашборд за наставници со статистики и повеќе извештаи (basic + advanced SQL). +## Технологии +- Backend: **Python 3.10+, Flask** +- Database: **PostgreSQL** (`psycopg2`, `RealDictCursor`) +- Templates: **Jinja2** +- Auth: **bcrypt** +- Logging: Python `logging` -**Слоеви:** -- Flask рути и Jinja2 шаблони -- Data access: `utils/database_manager.py` (SQL, транскации, извештаи) -- Auth: `utils/auth_manager.py` (bcrypt) +--- -**Напомена за тригери:** Во проектот не се користат DB тригери; временските полиња се решени со DEFAULT now() и timestamp од апликацијата. +## Setup & Run -## 2) Технологии / Стек +```bash +git clone https://github.com/MarijaIsailovska/SIMLAB.git +cd SIMLAB +python -m venv venv +source venv/bin/activate # или venv\Scripts\activate на Windows +pip install -r requirements.txt +``` -- **Backend:** Python 3.x, Flask -- **База:** PostgreSQL (psycopg2, RealDictCursor) -- **View:** Jinja2 templates -- **Сесии/Автентикација:** Flask session + bcrypt +## Database Highlights +- CHECK ограничувања за валидни атомски броеви, маса и физички својства +- Индекси за брзо пребарување и сортирање (реакции, експерименти, учества) +- UNIQUE constraints за идемпотентност при логирање на активности +- DEFAULT timestamps за автоматско логирање на учества и експерименти -- **Логирање:** Python logging со log.exception(...) - -## 3) Структура на проект - - - -## 4) Улоги и дозволи - -- **teacher:** CRUD на елементи/опрема/реакции, креирање експерименти, сите извештаи, „моите студенти". -- **student:** преглед елементи/опрема, симулација и зачувување учество, лични статистики и „моите експерименти". - -Заштита со декоратор: `@require_login(role=None|'teacher')`. - -## 5) База на податоци (шема) - -### Главни табели (извадок): - -- `"User"(user_id, user_name, user_surname, email, password, role)` -- `student(student_id FK->User, teacher_id FK->User)` -- `teacher(teacher_id FK->User)` -- `elements(..., teacher_id FK->User)` -- `labequipment(..., teacher_id FK->User)` -- `reaction(reaction_id, teacher_id FK, element1_id FK->elements, element2_id FK->elements, product, conditions)` -- `experiment(experiment_id, teacher_id FK, reaction_id FK, result, safety_warning, time_stamp TIMESTAMP DEFAULT now())` -- `experimentlabequipment(experiment_id FK, equipment_id FK)` (N:M) -- `userparticipatesinexperiment(user_id FK, experiment_id FK, participation_timestamp TIMESTAMPTZ DEFAULT now())` -- `userviewselement(user_id FK, element_id FK)` -- `userviewslabequipment(user_id FK, equipment_id FK)` - -### Препорачани UNIQUE ограничувања (идемпотентност): - -```sql -ALTER TABLE userviewselement - ADD CONSTRAINT uq_uve UNIQUE (user_id, element_id); - -ALTER TABLE userviewslabequipment - ADD CONSTRAINT uq_uvl UNIQUE (user_id, equipment_id); - -ALTER TABLE userparticipatesinexperiment - ADD CONSTRAINT uq_upe UNIQUE (user_id, experiment_id); -``` -## 6) Логирање (logging) - -Во `utils/database_manager.py`: -```pythonimport logging``` -log = logging.getLogger(name) - - -## 7) Рути и функционалности - -### Аутентикација -- `GET /login` – форма за логирање -- `POST /login` – проверка (email + bcrypt), сетира session -- `GET /register` – форма (студент бира ментор/teacher) -- `POST /register` – креира "User" (+ student или teacher) -- `GET /logout` – чисти сесија - -### Дашборд -- `GET /dashboard` – - - teacher: број студенти/реакции/експерименти/активности денес - - student: сопствени статистики -- `GET /api/dashboard-stats` – JSON за фронтенд видџети -- `GET /api/debug-dashboard` – помошен JSON (session + stats) - -### Елементи -- `GET /elements` – листа -- `GET /elements/` – детали (логира view во userviewselement) -- `GET|POST /elements/add` – teacher -- `GET|POST /elements//edit` – teacher - -### Лаб. опрема -- `GET /equipment`, `GET /equipment/` (логира view) -- `GET|POST /equipment/add`, `GET|POST /equipment//edit` – teacher - -### Реакции и експерименти -- `GET /reactions` – листа со збогатени полиња (симболи/имиња на елементи) -- `GET|POST /reactions/add` – teacher: една транскација → reaction + experiment (+ N:M experimentlabequipment) -- `GET|POST /reactions//edit` – teacher -- `POST /reactions//delete` – teacher - -### Виртуелна лабораторија (API) -- `GET /laboratory` – teacher/student views -- `POST /api/simulate-reaction` - - Body: `{"element1":"H","element2":"O"}` - - Response: `{success, product, conditions, reaction_id, experiment_id, elements}` -- `POST /api/check-reaction` – верификација без experiment_id -- `POST /save-experiment` – - - ако нема експеримент за реакцијата и корисник е teacher → креира experiment - - секогаш логира учество во userparticipatesinexperiment за тековниот корисник - -### „Мои експерименти" -- `GET /my-experiments` – - - student: експерименти во кои учествувал - - teacher: експерименти поврзани со него (преку join со UPE) - -### Извештаи – Мену -- `GET /reports` – избор на извештаи (teacher) - -### Basic извештаи (templates): -- `GET /reports/teacher_statistics` -- `GET /reports/inactive_students` -- `GET /reports/element_views` -- `GET /reports/detailed_experiments` -- `GET /reports/low_activity_students` -- `GET /reports/student_experiments` -- `GET /reports/user_activity` - -### Advanced SQL (generic renderer): -- `GET /reports/adv/student_experiment_counts` -- `GET /reports/adv/equipment_usage` -- `GET /reports/adv/students_experiments_detailed` -- `GET /reports/adv/experiment_participants?experiment_id=` -- `GET /reports/adv/avg_equipment_per_experiment` -- `GET /reports/adv/most_used_elements` -- `GET /reports/adv/most_performed_experiments` -- `GET /reports/adv/never_participated_students` -- `GET /reports/adv/students_below_threshold?max=3` -- `GET /reports/adv/student_views` - -## 8) Data-access слој (DatabaseManager) - -- Единствен влез за SQL операции (CRUD, извештаи). -- RealDictCursor → редовите се dict (олеснето рендерирање во Jinja/JSON). -- Метод `create_reaction_and_experiment(...)` користи една транскација за конзистентност. -- Track функции (userviewselement, userviewslabequipment, userparticipatesinexperiment) се идемпотентни со горните UNIQUE ограничувања. - -## 9) Конфигурација и пуштање - -### 9.1 Пререквизити -- Python 3.10+ -- PostgreSQL 13+ -- Зависности: -bash -pip install -r requirements.txt - -### 9.2 Конфигурација -Во кодот има хардкодирани креденцијали во `DatabaseManager.get_connection()`. **Препорака:** користи `.env` + `os.getenv` (пример во Апендикс B). **Никогаш не комитирај реални лозинки.** - -### 9.3 Пуштање (локално) -flask run -Отвори: http://127.0.0.1:5000/ - -## 10) Сигурност и приватност - -- **Лозинки:** bcrypt (во AuthManager) -- **Сесии:** Flask secret_key (чувај во ENV) -- **CSRF:** не е активен (за форми со POST препорачливо Flask-WTF) -- **RBAC:** проверка на рути со декоратор `@require_login(role=...)` - -## 11) Перформанси и интегритет - -- Индекси на сите FK и често користени JOIN колони. -- UNIQUE (user_id, experiment_id) на userparticipatesinexperiment + ON CONFLICT DO NOTHING во insertите. -- Транскации при креирање reaction + experiment (ACID). - -## 12) Познати ограничувања - -- Хардкодирани DB креденцијали (премести во ENV). -- Нема CSRF за форми. -- Нема миграции (Alembic) — DDL се извршува рачно. -- Нема unit тестови (може да се додадат за DatabaseManager и API). - -## 13) Тест сценарија за демонстрација - -1. **Регистрација/Логирање** – teacher + student. -2. **Елементи** – додавање (teacher), преглед (student) → проверка на userviewselement. -3. **Опрема** – додавање/преглед → проверка userviewslabequipment. -4. **Реакција+Експеримент** – креирање во една транскација; избор опрема (N:M). -5. **Симулација** `/api/simulate-reaction` + зачувување `/save-experiment` (како student) → userparticipatesinexperiment. -6. **Извештаи** – detailed_experiments, user_activity, teacher_statistics. -7. **Дашборд** – броеви се менуваат после активности. - -## 14) Troubleshooting - -**Празен „Детален преглед"** -- Проверете има ли редови во userparticipatesinexperiment. Дали `/save-experiment` вратил success=true? -- Препорака: participation_timestamp DEFAULT now() + UNIQUE на (user_id, experiment_id). - -**/api/simulate-reaction → success=false** -- Нема дефинирана реакција за симболите → креирај преку `/reactions/add`. - -**OperationalError: connection refused** -- Проверете DB host/port/credentials; дали PostgreSQL слуша и шемата постои. - -## 15) Идни подобрувања - -- ENV конфигурација + Alembic миграции. -- CSRF и rate-limiting за API. -- Role-based UI контроли (disable/hide actions). -- CSV/Excel export на извештаи. -- Unit тестови (pytest) за DatabaseManager и рути. - -## Апендикс A — cURL примери - -### Simulate reaction -```bash -curl -X POST http://127.0.0.1:5000/api/simulate-reaction \ - -H "Content-Type: application/json" \ - -d '{"element1":"H","element2":"O"}' \ - -b cookiejar.txt -c cookiejar.txt -Апендикс B — .env пример -env# Flask -FLASK_APP=app.py -FLASK_ENV=development -SECRET_KEY=change-me-please - -# PostgreSQL -DB_HOST=localhost -DB_PORT=9999 -DB_NAME=db_202425z_va_prj_simlab25 -DB_USER=db_202425z_va_prj_simlab25_owner -DB_PASS=replace-with-real-password -Пример за користење ENV во DatabaseManager.get_connection(): -pythonimport os -import psycopg2 -from psycopg2.extras import RealDictCursor - -def get_connection(): - return psycopg2.connect( - host=os.getenv('DB_HOST', 'localhost'), - port=int(os.getenv('DB_PORT', '5432')), - database=os.getenv('DB_NAME'), - user=os.getenv('DB_USER'), - password=os.getenv('DB_PASS'), - cursor_factory=RealDictCursor - ) +## Author +Изработено од Марија Исаиловска +Факултет за информатички науки и компјутерско инженерство – ФИНКИ +Предмет: Бази на податоци