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

1. 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.
2. 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.
3. 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)

1. Utwórz gałąź produkcyjną: git push origin main:production.
2. Render → New → Blueprint → wybierz repozytorium. Render odczyta render.yaml i utworzy mruos-api oraz mruos-api-staging.
3. Dla każdego serwisu podaj MONGODB_URI (odpowiednia baza) i ORIGIN_SECRET (odpowiedni sekret). SESSION_SECRET Render wygeneruje sam.
4. 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)

1. Vercel → Add New → Project → repozytorium, Root Directory: apps/web. Resztę ustawień czyta apps/web/vercel.json.

2. Settings → Git → Production Branch: production.

3. 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 /.

4. 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)