MruOS
Kalendarz studencki do zarządzania planem zajęć (wersja produkcyjna: https://mru-os.vercel.app). Wpisujesz zajęcia raz, jako serię (przedmiot, typ, sala, godziny, dni tygodnia, zakres semestru), a MruOS pokazuje je w widoku miesiąca i dnia, uwzględniając dni wolne, zajęcia co dwa tygodnie i pojedyncze zmiany terminów.
Funkcje
- Widok tygodnia (domyślny, z „tydzień N semestru” i godzinami dopasowanymi do planu), miesiąca i dnia; kalendarz otwiera się na dzisiejszym dniu i mieści się na ekranie. Zajęcia to bloki z jasnym tłem i paskiem w kolorze zajęć, z czytelnym tekstem na każdym kolorze.
- Serie zajęć: co tydzień lub co dwa tygodnie, zakres jako daty albo tygodnie semestru, z opcjonalnym prowadzącym.
- Edycja „tylko ten termin” (np. zmiana sali) albo „cała seria”, odwoływanie terminów.
- Ostrzeżenia o kolizjach.
- Ustawienia w jednym miejscu: rok akademicki, import (JSON, XLSX z planów UMK CM) i eksport (JSON, ICS), kalendarz w telefonie, wygląd (jasny, ciemny albo jak w systemie) i konto.
- Strona logowania na start; „Wypróbuj bez konta” (plan zapisany w przeglądarce) albo konto: plan na serwerze, przeniesienie lokalnego planu przy pierwszym logowaniu, „Nie wylogowuj mnie” na 30 dni.
- Konto i prywatność: zmiana hasła (wylogowuje pozostałe urządzenia), wylogowanie innych urządzeń, pobranie i usunięcie swoich danych, czasowa blokada po 10 nieudanych logowaniach, strona „Prywatność”.
- Import planu z pliku Excel (.xlsx) w formacie siatki dni × godzin z blokami zajęć: wybór grup dla każdego przedmiotu, ostrzeżenia o kolizjach, podgląd i oznaczenie miejsc do poprawy.
- Import planu Wydziału Ekonomicznego UG z PDF (CELCAT): wybór grupy i promotora seminarium, tygodnie I i II liczone jak na UG, jednorazowe spotkania i zmiany sal z uwag w planie, prowadzący przy zajęciach.
- Harmonogram roku akademickiego: semestry z okresami zajęć, przerw i sesji, dni wolne (święta ustawowe wyliczane automatycznie) i zamiany dni (np. czwartek z zajęciami według planu poniedziałkowego); tygodnie planu liczone według okresów zajęć, dni wolne, przerwy i zamiany widoczne w kalendarzu.
- Kolokwia, egzaminy i notatki: w czasie zajęć albo w osobnym terminie, oznaczenia w kalendarzu (⚑ kolokwium, ★ egzamin, ✎ notatka), panel „Nadchodzące” z najbliższymi 14 dniami i lista wpisów, które straciły swoje zajęcia.
- Kopia zapasowa JSON i eksport do kalendarza (.ics) z wyborem: kolokwia i egzaminy z przypomnieniami, notatki w opisach zajęć, dni wolne, przerwy i sesja. Kolokwium lub egzamin w czasie zajęć to jedno wydarzenie z zajęciami.
- Subskrypcja kalendarza (dla kont): tajny link
/api/ical/<kod>.ics dla Kalendarza Google, iPhone’a i Maca, który aktualizuje się sam; link widać tylko przy tworzeniu, nowy link unieważnia stary, ustawienia zmienia się bez nowego linku.
- Obsługa klawiaturą i układ dla telefonu: szczegóły w panelu wysuwanym od dołu, „Nadchodzące” jako pasek nad kalendarzem.
Architektura
przeglądarka ──► Vercel (frontend, apps/web)
│ /api/* → przekierowanie + nagłówek X-Origin-Secret
▼
Render (API, apps/api) ──► MongoDB Atlas
Frontend i API działają pod jednym adresem, więc ciasteczko sesji jest httpOnly, Secure, SameSite=Lax. API odrzuca żądania, które nie przyszły przez Vercel (brak sekretu originu), dzięki czemu limit prób logowania liczy się dla prawdziwego adresu IP.
| Katalog | Zawartość |
|---|
apps/web | React, React Router, Vite, Tailwind, FullCalendar |
apps/api | Express, Mongoose, sesje, argon2 |
packages/shared | Typy, schematy zod, wyliczanie terminów z reguł powtarzania |
e2e | Testy Playwright (desktop i emulacja telefonu) |
Uruchomienie lokalne
Wymagania: Node.js 22+ i pnpm 10.
pnpm install
pnpm dev # frontend: http://localhost:5173, API: http://localhost:3001
Bez pliku .env API startuje z tymczasową bazą MongoDB w pamięci: konta i plany działają, ale znikają przy każdym restarcie API (także po zmianie kodu). Żeby dane przetrwały, skopiuj .env.example do .env i ustaw MONGODB_URI (np. osobna baza mruos-dev w Atlasie) oraz SESSION_SECRET (min. 32 znaki).
Bez działającego API aplikacja nadal działa w trybie lokalnym (zapis w przeglądarce).
Testy i jakość
pnpm lint # ESLint i sprawdzanie typów
pnpm test # testy jednostkowe i integracyjne (MongoDB w pamięci)
pnpm exec playwright install chromium # jednorazowo
pnpm test:e2e # testy E2E na własnym API i bazie w pamięci
pnpm build
CI (GitHub Actions) uruchamia lint, testy, build oraz testy E2E dla każdego pusha i pull requesta.
Która wersja działa
Każde wdrożenie podaje swój commit:
- aplikacja: na dole strony „Ustawienia” („Wersja aplikacji: d5b820c z 10.10.2026, 20:25 · API: d5b820c”) i w konsoli przeglądarki przy starcie; „+ lokalne zmiany” oznacza kod jeszcze niezacommitowany (np.
pnpm dev),
- API:
GET /health zwraca {"status":"ok","version":"d5b820c"}.
Na Vercelu i Renderze commit pochodzi z ich zmiennych VERCEL_GIT_COMMIT_SHA i RENDER_GIT_COMMIT, lokalnie z git.
Środowiska i wydania
| Środowisko | Gałąź | Frontend (Vercel) | API (Render) | Baza (Atlas) |
|---|
| Produkcja | production | https://mru-os.vercel.app | mruos-api | mruos |
| Testowe | main | podglądy (main i pull requesty) | mruos-api-staging | mruos-staging |
Zmiany trafiają do main przez pull request i lądują w środowisku testowym. Po sprawdzeniu wydanie produkcyjne to:
git push origin main:production
Wdrożenie od zera
Wartości oznaczone <...> wygeneruj lub skopiuj z paneli usług. Sekrety wpisuj tylko w panelach, nigdy do repozytorium.
1. MongoDB Atlas
- W istniejącym klastrze (najlepiej region Frankfurt) utwórz dwóch użytkowników bazy z rolą
readWrite tylko do swojej bazy: jednego dla mruos, drugiego dla mruos-staging.
- Network Access: dodaj
0.0.0.0/0. Darmowy Render nie ma stałych adresów IP, więc ochroną są silne, losowe hasła użytkowników.
- Skopiuj connection string dla każdego użytkownika i dopisz nazwę bazy:
mongodb+srv://<user>:<hasło>@<klaster>/mruos?retryWrites=true&w=majority
(dla środowiska testowego: /mruos-staging).
2. Sekrety originu
Wygeneruj dwa różne sekrety, jeden dla produkcji i jeden dla środowiska testowego:
openssl rand -hex 32
3. Render (API)
- Utwórz gałąź produkcyjną:
git push origin main:production.
- Render → New → Blueprint → wybierz repozytorium. Render odczyta
render.yaml i utworzy mruos-api oraz mruos-api-staging.
- Dla każdego serwisu podaj
MONGODB_URI (odpowiednia baza) i ORIGIN_SECRET (odpowiedni sekret). SESSION_SECRET Render wygeneruje sam.
- Zanotuj adresy serwisów, np.
https://mruos-api.onrender.com. Sprawdzenie: <adres>/health zwraca {"status":"ok"}.
Darmowy serwis usypia po 15 minutach bez ruchu; pierwsze żądanie po przerwie trwa do około minuty.
4. Vercel (frontend)
-
Vercel → Add New → Project → repozytorium, Root Directory: apps/web. Resztę ustawień czyta apps/web/vercel.json.
-
Settings → Git → Production Branch: production.
-
Settings → Environment Variables:
| Zmienna | Production | Preview |
|---|
API_ORIGIN | https://mruos-api.onrender.com | https://mruos-api-staging.onrender.com |
ORIGIN_SECRET | sekret produkcyjny | sekret testowy |
API_ORIGIN bez końcowego /.
-
Wdróż ponownie i sprawdź, że rejestracja działa pod domeną produkcyjną, a odświeżenie strony /konto otwiera aplikację (pozostałe adresy trafiają do index.html).
5. Ochrona gałęzi
GitHub → Settings → Branches → reguła dla main (i production): wymagaj zielonych checków quality i e2e przed merge.
Zmienne środowiskowe API
| Zmienna | Wymagana | Opis |
|---|
MONGODB_URI | w produkcji | Connection string z nazwą bazy; lokalnie bez niej baza w pamięci |
SESSION_SECRET | w produkcji | Min. 32 znaki, podpis ciasteczka sesji; lokalnie losowy |
ORIGIN_SECRET | w produkcji | Min. 32 znaki, taki sam jak w odpowiednim środowisku Vercel |
NODE_ENV | nie | production włącza ciasteczka Secure i wymaga ORIGIN_SECRET |
PORT | nie | Domyślnie 3001 (Render ustawia sam) |
WEB_ORIGIN | nie | Tylko przy frontendzie pod innym adresem (CORS) |
