tablo/README.md

Tablo

Русский · English

Веб-приложение для студентов: по фото расписания ИИ собирает редактируемое расписание, к каждому предмету можно добавить трекеры успеваемости и поделиться всем по ссылке.

Статус: личный проект, начинался как курсовая работа (2026) · работает на tablo.deev.su

Стек: Python 3.12 · Flask · SQLAlchemy + Alembic · PostgreSQL · OpenAI-совместимый Vision API · Playwright · Jinja2 + vanilla JS

Возможности

• Распознавание расписания по фото или скану
• Редактирование расписаний, предметов и занятий, периоды с переходом через Новый год
• 11 видов трекеров (посещаемость, оценки, дедлайны, серии дней и др.) на сетке с перетаскиванием
• Генерация трекера по описанию: «8 лабораторных и экзамен»
• Доступ по ссылке: просмотр, редактирование или копия как шаблон
• Объединение нескольких расписаний в одно: занятия одного предмета сводятся вместе
• Экспорт в JSON, CSV, PNG и версию для печати

Быстрый старт

git clone https://github.com/EDeev/tablo.git && cd tablo
cp .env.example .env      # задайте SECRET_KEY и ключ ИИ-провайдера
docker compose up -d

Откройте http://localhost:8000. Compose поднимает приложение и PostgreSQL, миграции применяются при старте. Готовый образ: docker pull ghcr.io/edeev/tablo или docker pull git.deev.su/edeev/tablo.

Установка без Docker

Нужны Python 3.11+ и PostgreSQL.

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium   # для экспорта в PNG
cp .env.example .env
flask --app run db upgrade
python run.py

Конфигурация

Переменная	Назначение
SECRET_KEY	подпись сессий Flask; без неё приложение не запустится
DATABASE_URL или DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD	подключение к PostgreSQL
OPENAI_API_KEY	ключ ИИ-провайдера
OPENAI_BASE_URL	адрес OpenAI-совместимого API, если это не OpenAI
OPENAI_MODEL	модель для распознавания и трекеров, по умолчанию gpt-4o

Important

Без OPENAI_API_KEY не работают распознавание расписаний и генерация трекеров. Всё остальное работает: расписание можно завести и править вручную.

Как выглядит

Мои расписания	Предмет и трекеры	Телефон

Как устроено

flowchart LR
    B[Браузер] --> F[Flask: auth · schedules · subjects · shares · export]
    F --> S[Сервисы: ai_scan · ai_metrics · merge · export]
    F --> P[(PostgreSQL)]
    S --> A[OpenAI-совместимый API]
    S --> C[Chromium через Playwright]

Подробности:

• docs/architecture.md — структура, формат расписания, трекеры, права доступа
• docs/deploy.md — Docker и устройство боевого сервера
• docs/explanatory_note.pdf — пояснительная записка к курсовой

Развёртывание

tablo.deev.su работает на VPS: gunicorn под systemd за nginx с сертификатом Let's Encrypt, PostgreSQL — на отдельном сервере, ИИ — Timeweb Cloud AI. Docker-образ собирает GitHub Actions на каждый тег v* и публикует в GitHub Packages и в реестр git.deev.su.

Разработка

pip install -r requirements-dev.txt
export TEST_DATABASE_URL=postgresql://tablo:tablo@localhost:5432/tablo_test
ruff check . && pytest

Тесты идут на настоящем PostgreSQL: права доступа и экспорт, ссылки, вход и защита от открытого редиректа, разбор периодов и времени, слияние расписаний. CI поднимает базу в сервис-контейнере и выполняет то же самое на каждый push.

Лицензия

MIT — см. LICENSE.

Автор

Деев Егор Викторович — GitHub · Telegram · egor@deev.space

---

_{⭐ Если проект оказался полезным, поставьте звёздочку на GitHub!}

_{Сделано с ❤️ — deev.space}