edit readme.md

2026-03-02 14:30:56 +04:00
parent d78668ce3a
commit 7e0bcb8b3e
2 changed files with 162 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,162 @@
-# kspsuti-teacher-schedule
- Teacher's schedule of KS PSUTI
+# 📅 Teacher Schedule
+
+Веб-приложение для просмотра расписания преподавателей ПГУТИ. Парсит расписание с сайта [lk.ks.psuti.ru](https://lk.ks.psuti.ru/?mn=3) и отображает в удобном тёмном интерфейсе с поиском по ФИО.
+
+![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white)
+![Flask](https://img.shields.io/badge/Flask-2.3+-000000?style=flat&logo=flask)
+![License](https://img.shields.io/badge/license-MIT-green?style=flat)
+
+## Возможности
+
+- 🔍 **Поиск по ФИО** — живой поиск по всем 100+ преподавателям с подсветкой совпадений
+- ⭐ **Избранные** — быстрые табы для часто просматриваемых преподавателей (настраиваются в `config.yaml`)
+- 📆 **Навигация по неделям** — переключение вперёд/назад
+- 🟢 **Текущая пара** — автоматически подсвечивается идущее сейчас занятие
+- 📊 **Статистика недели** — рабочие дни, количество пар, групп и часов
+- 📱 **Адаптивный интерфейс** — удобно на телефоне и десктопе
+
+## Скриншоты
+
+![screenshot](screen1.png)
+
+## Стек
+
+- **Backend:** Python 3, Flask, BeautifulSoup4 (lxml)
+- **Frontend:** Vanilla JS, CSS Grid, без фреймворков
+- **Deploy:** systemd + Caddy (автоматический HTTPS)
+
+## Быстрый старт
+
+### 1. Клонировать репозиторий
+
+```bash
+git clone https://github.com/kilyabin/kspsuti-teacher-schedule.git
+cd kspsuti-teacher-schedule
+```
+
+### 2. Создать виртуальное окружение и установить зависимости
+
+```bash
+bash setup.sh
+```
+
+### 3. Настроить `config.yaml`
+
+```yaml
+base_url: "https://lk.ks.psuti.ru"
+
+default_teacher: 244   # чье расписание будет при входе в веб-приложение, obj= из ссылки нужного преподавателя
+
+teachers:              # избранные — отображаются как быстрые табы
+  - id: 244
+    name: "ПОЛНОЕ ФИО"
+    short: "КРАТКО ФИО"
+  - id: 229
+    name: "ПОЛНОЕ ФИО"
+    short: "КРАТКОЕ ФИО"
+```
+
+ID преподавателя берётся из ссылки на сайте:  
+`https://lk.ks.psuti.ru/?mn=3&obj=`**244** → `id: 244`
+
+### 4. Запустить
+
+```bash
+source venv/bin/activate
+python app.py
+```
+
+Открыть в браузере: [http://localhost:5609](http://localhost:5609)
+
+---
+
+## Деплой на сервер
+
+### systemd сервис
+
+```bash
+sudo bash install-service.sh
+```
+
+Скрипт автоматически определяет путь к проекту и текущего пользователя, копирует unit-файл в `/etc/systemd/system/schedule.service` и запускает сервис.
+
+Управление сервисом:
+
+```bash
+sudo systemctl status schedule      # статус
+sudo systemctl restart schedule     # перезапуск
+sudo systemctl stop schedule        # остановить
+journalctl -u schedule -f           # логи в реальном времени
+```
+
+### Caddy — HTTPS по домену
+
+Установить Caddy ([официальная инструкция](https://caddyserver.com/docs/install)):
+
+```bash
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
+  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
+  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update && sudo apt install caddy
+```
+
+Конфиг `/etc/caddy/Caddyfile`:
+
+```caddy
+{
+    acme_ca https://acme-v02.api.letsencrypt.org/directory
+    email your@email.com
+}
+
+your.domain.com {
+    reverse_proxy localhost:5609
+    encode gzip
+}
+```
+
+```bash
+sudo systemctl reload caddy
+```
+
+Caddy автоматически получит TLS-сертификат от Let's Encrypt. Убедись что порты **80** и **443** открыты в файрволе и security groups облака.
+
+---
+
+## Структура проекта
+
+```
+.
+├── app.py                      # Flask-приложение, парсер расписания
+├── config.yaml                 # Настройки: URL, избранные преподаватели
+├── requirements.txt            # Зависимости Python
+├── setup.sh                    # Создаёт venv и ставит зависимости
+├── install-service.sh          # Устанавливает systemd сервис
+├── schedule.service.template   # Шаблон systemd unit-файла
+├── Caddyfile                   # Пример конфига Caddy
+└── templates/
+    └── index.html              # Фронтенд (всё в одном файле)
+```
+
+## API
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/teachers` | Избранные преподаватели из `config.yaml` |
+| GET | `/api/all-teachers` | Все преподаватели с сайта (кэш 1 час) |
+| GET | `/api/schedule?obj=244` | Расписание на текущую неделю |
+| GET | `/api/schedule?obj=244&wk=321` | Расписание на конкретную неделю |
+| GET | `/api/reload-config` | Перечитать `config.yaml` без перезапуска |
+
+## Обновление конфига без перезапуска
+
+Если добавил преподавателей в `config.yaml` на живом сервере:
+
+```bash
+curl http://localhost:5609/api/reload-config
+```
+
+## Лицензия
+
+MIT