Installation Setup - moiaa/College_Management_System GitHub Wiki

📥 Установка и настройка локального окружения

Эта инструкция поможет вам сохранить репозиторий локально и настроить окружение для разработки.

🔧 Требования

Перед началом убедитесь, что у вас установлено:

Проверка версий

python --version    # Должно быть 3.10 или выше
git --version       # Должно быть 2.x

📥 Шаг 1: Сохраните репозиторий локально

Вариант A: Clone (рекомендуется)

  1. Откройте терминал (Command Prompt, PowerShell, Terminal)

  2. Перейдите в папку, где будете хранить проект:

    cd Documents/Projects

  3. Клонируйте репозиторий:

    git clone https://github.com/moiaa/College_Management_System.git

  4. Перейдите в папку проекта:

    cd College_Management_System

Вариант B: Download ZIP (только для просмотра)

  1. Нажмите зелёную кнопку Code на главной странице репозитория
  2. Выберите Download ZIP
  3. Распакуйте архив в удобную папку

⚠️ Важно: Этот вариант не подходит для разработки, так как не включает Git-историю!

🐍 Шаг 2: Создайте виртуальное окружение

Виртуальное окружение изолирует зависимости проекта от других ваших проектов.

Windows:

python -m venv venv
venv\Scripts\activate

macOS/Linux:

python3 -m venv venv
source venv/bin/activate

✅ Проверка: Перед именем окружения в терминале появится (venv):

(venv) user@computer:~$

📦 Шаг 3: Установите зависимости

pip install --upgrade pip
pip install -r requirements.txt

Это установит все необходимые библиотеки:

  • SQLAlchemy (работа с БД)
  • FastAPI (API)
  • python-jose, passlib (аутентификация)
  • pytest (тесты)
  • и другие

🗄️ Шаг 4: Инициализируйте базу данных

python main.py init

Что происходит:

  • Создаётся файл college.db в корне проекта
  • Создаются все таблицы согласно моделям

✅ Проверка: В папке проекта должен появиться файл college.db

🧪 Шаг 5: Добавьте тестовые данные (опционально)

python scripts/seed_data.py

Что происходит:

  • Создаются тестовые пользователи:
    • admin / admin123
    • teacher1 / teacher123
    • student1 / student123
  • Добавляются тестовые курсы, расписание, оценки

⚙️ Шаг 6: Настройте переменные окружения

  1. Скопируйте файл .env.example в .env:

    cp .env.example .env

  2. Откройте .env и измените при необходимости:

    DATABASE_URL=sqlite:///./college.db
SECRET_KEY=your-secret-key-change-in-production
DEBUG=True

🚀 Шаг 7: Проверьте установку

Запустите тесты:

pytest

Проверьте стиль кода:

flake8 .

Оба шага должны пройти без ошибок на чистом клоне main — если что-то красное, см. ❓ FAQ, прежде чем считать, что вы что-то настроили не так.

Запустите сервер и проверьте, что всё реально работает вместе

Мало того, что pytest/flake8 зелёные — само приложение должно подниматься и отвечать. Запустите:

python main.py run

и, пока сервер работает, откройте в браузере (или проверьте через curl в другом окне терминала):

  • http://127.0.0.1:8000/health — должен вернуть {"status": "ok"}. Это подтверждает, что backend вообще поднялся.
  • http://127.0.0.1:8000/frontend/_example/ — должна открыться рабочая страница-пример: список записей и форма добавления. Если страница загрузилась и добавление новой записи в форме реально появляется в списке — значит backend, frontend и база данных работают вместе как единое целое, именно так, как должно работать и у вас в модуле после того, как вы напишете код (см. docs/examples/example_module/README.md и 🚀 Начало работы).

Если любой из этих двух пунктов не сработал — это повод разобраться сейчас, а не после того, как поверх уже написан код модуля.

Остановить сервер — Ctrl+C в терминале, где он запущен.

📁 Структура проекта после установки

College_Management_System/
├── .env                  ← ваши локальные настройки (создаётся вручную на Шаге 6, в Git не попадает)
├── .env.example           ← шаблон для .env
├── .flake8                 ← настройки flake8
├── .gitignore
├── college.db              ← база данных (появится после Шага 4, в Git не попадает)
├── venv/                    ← виртуальное окружение (создаётся на Шаге 2, в Git не попадает)
├── core/                    ← ядро системы: БД, аутентификация, общее FastAPI-приложение (core/api.py)
├── modules/                 ← backend-часть модулей (Python/FastAPI) — 7 папок, ваш код сюда
├── frontend/                ← frontend-часть модулей (HTML/CSS/JS) — 7 папок + _example/, ваш код сюда
├── docs/                    ← документация и рабочий пример (docs/examples/example_module/)
├── scripts/                 ← инициализация БД, тестовые данные
├── tests/                   ← общие тесты
├── .github/workflows/       ← CI (pytest + flake8 на каждый push/PR)
├── main.py                  ← точка входа (python main.py run / init)
└── requirements.txt         ← зависимости

🔄 Шаг 8: Обновление репозитория

Если в репозитории появились изменения:

git pull origin main

Если есть конфликты, см. инструкцию 🔧 Работа с Git и GitHub.

❓ Частые проблемы

Ошибка: python: command not found

Решение: Установите Python и добавьте его в PATH.

Ошибка: No module named 'sqlalchemy'

Решение: Активируйте виртуальное окружение и установите зависимости:

source venv/bin/activate
pip install -r requirements.txt

Ошибка: database is locked

Решение: Закройте все программы, которые могут использовать БД (DB Browser, другой терминал).

Ошибки конкретно про python-jose, отсутствующий .env.example или ModuleNotFoundError из-за папки модуля (student-portal и т.п.) сюда не относятся — это признак устаревшей локальной копии репозитория, разобрано отдельно в ❓ FAQ (раздел «Установка»).

📚 Следующие шаги

После настройки переходите к:

📞 Помощь

Если что-то не работает:

  1. Проверьте ❓ FAQ
  2. Создайте Issue с описанием проблемы
  3. Обратитесь к преподавателю