Ботаническа Енциклопедия

Пълнофункционална дигитална ботаническа платформа за управление на растителна библиотека, статии и съдържание.

🚀 Технологичен Стек

Backend

• FastAPI - Модерен, бърз Python web framework
• PostgreSQL - Релационна база данни
• SQLAlchemy - ORM за работа с базата данни
• Redis - Кеширане и rate limiting (опционално)
• JWT - Автентикация и авторизация
• Pillow (PIL) - Обработка на изображения (автоматично resize, WebP конверсия)

Frontend

• Next.js 14 (App Router) - React framework
• TypeScript - Типова безопасност
• CSS Modules - Стилизиране

Инфраструктура

• Docker & Docker Compose - Контейнеризация и локално развитие
• Alembic - Database migrations (планирано)

📋 Функционалности

Публична част

• 🌱 Каталог с растения - Преглед на всички растения с преводи
• 🔍 Търсене - Търсене по име, латинско име, описание
• 📖 Детайлни страници - Пълна информация за всяко растение
• 🌍 Многоезичност - Поддръжка на bg, en, ru, fr, es, de
• ❤️ Любими - Потребители могат да запазват любими растения/страници/факти
• 📱 Социални споделяния - Споделяне във Facebook, X, LinkedIn, Telegram, WhatsApp и др.
• 🔗 SEO оптимизация - OG tags, Twitter Cards, мета данни

Админ панел

• 👨‍💼 Управление на растения - CRUD операции с bulk actions
• 📄 Страници (Pages) - CMS система за статични страници
• 📰 Статии (Articles) - Редакционен модул за новини/блог (в процес на разработка)
• 🏷️ Таксономии - Управление на категории и таксономии
• 🖼️ Медии - Управление на изображения с автоматична обработка
• 👥 Потребители - Управление на потребители и роли
• 📊 Audit Log - История на промените
• 🔄 Преводи - Workflow за преводи (draft → review → published)
• 📤 Експорт/Импорт - Импорт и експорт на данни

Системни функции

• 🔐 RBAC (Role-Based Access Control) - Роли и права за достъп
• ⚡ Кеширане - Redis кеширане за подобрена производителност
• 🛡️ Rate Limiting - Защита срещу злоупотреби
• 📝 Structured Logging - Структурирани логове (планирано)
• 🏥 Health Checks - Проверка на здравословното състояние на системата

🛠️ Инсталация и Стартиране

Предварителни изисквания

• Docker и Docker Compose
• Git

Стъпка 1: Клониране на репозиторията

git clone <repository-url>
cd "green world"

Стъпка 2: Настройка на environment променливи

Създайте .env файл в корена на проекта (опирайте се на .env.example ако съществува):

# Database (в docker-compose.yml се задават директно, но можете да ги override-нете)
POSTGRES_DB=botanical_encyclopedia
POSTGRES_USER=botanical_user
POSTGRES_PASSWORD=botanical_pass

# Backend
SECRET_KEY=your-secret-key-change-in-production
REDIS_URL=redis://redis:6379/0  # Опционално - за кеширане и rate limiting

# Frontend (по избор)
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_BASE_URL=http://localhost:1111

Забележка: Ако нямате .env файл, docker-compose.yml използва default стойности. Redis е опционален - приложенията ще работят и без него с fallback логика.

Стъпка 3: Стартиране с Docker Compose

# Стартиране на всички услуги
docker compose up -d

# Проверка на статуса
docker compose ps

# Преглед на логове
docker compose logs -f

Стъпка 4: Инициализация на базата данни

Базата данни се инициализира автоматично при първото стартиране. Ако имате миграции, изпълнете ги:

# Влезте в backend контейнера
docker compose exec backend bash

# Изпълнете миграции (ако имате Alembic)
# alembic upgrade head

# Или изпълнете SQL скриптове ръчно
# psql -U botanical_user -d botanical_db -f /path/to/migration.sql

Стъпка 5: Създаване на админ потребител

# Създаване на администратор с потребителско име 'admin' и парола 'admin123'
docker compose exec backend python -m app.create_admin_user

# Ако потребителят вече съществува, може да коригирате паролата:
docker compose exec backend python -m app.fix_admin_password

Стандартни данни за вход:

• Потребителско име: admin
• Парола: admin123

⚠️ ВАЖНО: Сменете паролата веднага след първо влизане в production!

Стъпка 6: Достъп до приложението

• Frontend: http://localhost:1111
• Backend API: http://localhost:8000
• API Documentation (Swagger): http://localhost:8000/docs
• Admin Panel: http://localhost:1111/admin
• Admin Login: http://localhost:1111/admin/login

📁 Структура на проекта

green world/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── routers/        # API endpoints
│   │   │   ├── admin_*.py  # Admin endpoints
│   │   │   ├── plants.py   # Public plants API
│   │   │   └── ...
│   │   ├── models.py       # Plant models
│   │   ├── admin_models.py # Admin models (Users, Roles, Media)
│   │   ├── article_models.py # Article/CMS models
│   │   ├── page_models.py  # Page builder models
│   │   ├── auth.py         # Authentication & authorization
│   │   ├── database.py     # Database connection
│   │   └── utils/          # Utilities (image processing, cache)
│   ├── requirements.txt    # Python dependencies
│   └── Dockerfile
│
├── frontend/               # Next.js frontend
│   ├── app/               # Next.js App Router
│   │   ├── [lang]/        # Internationalized routes
│   │   │   ├── plant/     # Plant detail pages
│   │   │   ├── profile/   # User profile
│   │   │   └── ...
│   │   ├── admin/         # Admin panel
│   │   │   ├── plants/    # Plants management
│   │   │   ├── pages/     # Pages management
│   │   │   ├── media/     # Media library
│   │   │   └── ...
│   │   └── components/    # Shared components
│   ├── package.json       # Node.js dependencies
│   └── Dockerfile
│
├── database/
│   └── migrations/        # SQL migration scripts (001_*.sql, ...)
│
├── docker-compose.yml     # Docker Compose configuration
└── README.md             # This file

🔧 Разработка

Backend Development

# Влезте в backend контейнера
docker compose exec backend bash

# Инсталирайте зависимости (ако има нови)
pip install -r requirements.txt

# Стартиране на development сървър (ако не е в Docker)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Development

# Влезте в frontend контейнера
docker compose exec frontend bash

# Инсталирайте зависимости (ако има нови)
npm install

# Стартиране на development сървър (ако не е в Docker)
npm run dev

Database Migrations

Миграциите са SQL скриптове в database/migrations/. За да изпълните нова миграция:

# Влезте в backend контейнера
docker compose exec backend bash

# Свържете се с PostgreSQL
psql -U botanical_user -d botanical_db -h postgres

# Или изпълнете SQL файл
psql -U botanical_user -d botanical_db -h postgres -f /path/to/migration.sql

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

• JWT токени за автентикация
• bcrypt за хеширане на пароли
• RBAC (Role-Based Access Control) за авторизация
• Rate limiting за защита срещу злоупотреби
• CORS конфигурация за frontend достъп
• SQL injection защита чрез SQLAlchemy ORM
• XSS защита чрез React автоматично escaping

📊 API Endpoints

Public API

• GET /api/v1/plants - Списък с растения
• GET /api/v1/plants/{slug} - Детайли за растение
• GET /api/v1/menu - Меню структура
• GET /api/v1/auth/me - Текущ потребител

Admin API (изисква автентикация)

• GET /api/v1/admin/plants - Управление на растения
• GET /api/v1/admin/pages - Управление на страници
• GET /api/v1/admin/media - Медии
• GET /api/v1/admin/users - Потребители
• GET /api/v1/admin/audit - Audit log

Пълна API документация: http://localhost:8000/docs

🎯 Следващи стъпки (Roadmap)

Вижте SYSTEM_IMPROVEMENTS_PLAN.md за пълен план за подобрения.

Приоритети

1. RBAC формализиране - Стандартни роли и permissions
2. Observability - Health checks, structured logging, metrics
3. Performance оптимизация - Кеширане, индекси, оптимизация на заявки
4. Articles/CMS модул - Завършване на редакционния модул
5. Workflow подобрения - Draft/review/publish workflow с audit trail

📝 Лиценз

[Посочете лиценза тук]

👥 Автори

[Посочете авторите тук]

🤝 Принос

[Инструкции за принос тук]