pz-teacher/Django_restapi_company_files
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: Home
Pages
Home
1 Home
student edited this page 2026-04-13 08:47:35 +02:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Company Files – Wiki (instrukcja akademicka)

Projekt demonstracyjny do zajęć z backendów: Django REST API + osobny, uproszczony frontend (statyczny HTML/JS). Temat: zarządzanie firmowymi plikami (upload i udostępnianie), wewnętrzne wiadomości oraz lista zadań TODO.

Spis treści

1. Cel dydaktyczny

Po zrealizowaniu ćwiczeń student:

  • rozumie rozdział warstw (frontend ↔ REST API),
  • potrafi zaprojektować modele danych i relacje (w tym relacje „dostępowe”),
  • wdraża autoryzację JWT i sprawdzanie uprawnień obiektowych,
  • testuje API w Swagger UI oraz curl/fetch,
  • potrafi wskazać najważniejsze ryzyka bezpieczeństwa dla uploadu plików i współdzielenia.

2. Struktura repozytorium i uzasadnienie

Repo jest celowo zorganizowane jak mini-monorepo:

  • backend/ – Django + DRF (logika, dane, autoryzacja, API)
  • frontend/ – statyczny HTML/CSS/JS (minimalny klient do prezentacji API)
  • requirements.txt – zależności backendu

Uzasadnienie:

  • warstwy można wdrażać niezależnie,
  • typowy układ „API + osobny UI” jest bliższy realnym projektom,
  • łatwo pokazać CORS i JWT w praktyce.

3. Architektura (diagramy)

3.1. Diagram komponentów

flowchart LR
  B[Przeglądarka] -->|HTTP: HTML/CSS/JS| F[Frontend statyczny]
  B -->|HTTP JSON + JWT| API[Django REST API]
  API -->|ORM| DB[(SQLite)]
  API -->|FileField| FS[(MEDIA_ROOT / media/)]
  API --> DOCS[Swagger/OpenAPI]

3.2. Sekwencja: logowanie + lista dokumentów

sequenceDiagram
  participant U as Użytkownik (Frontend)
  participant A as API (JWT)
  participant D as API (Documents)

  U->>A: POST /api/auth/token/ (username, password)
  A-->>U: access + refresh (JWT)
  U->>D: GET /api/documents/ (Authorization: Bearer access)
  D-->>U: lista dokumentów (własne + udostępnione)

3.3. Sekwencja: upload + download

sequenceDiagram
  participant U as Frontend
  participant API as Django REST API
  participant FS as Storage (media/)

  U->>API: POST /api/documents/ (multipart/form-data)
  API->>FS: zapis pliku
  API-->>U: 201 + metadane dokumentu
  U->>API: GET /api/documents/{id}/download/
  API->>FS: odczyt pliku
  API-->>U: FileResponse (download)

4. Model danych

Główne byty:

  • Document – dokument z plikiem i metadanymi (właściciel, tytuł, daty).
  • DocumentShare – udostępnienie dokumentu użytkownikowi z uprawnieniem read lub write.
  • Message – wiadomość wewnętrzna (nadawca, odbiorca, temat, treść, znacznik przeczytania).
  • TodoItem – zadanie użytkownika (tytuł, opis, status, opcjonalny termin).

Uzasadnienie:

  • oddzielna tabela udostępnień to dobry wzorzec pod przyszłe rozszerzenia (role/grupy/wygasanie/audyt),
  • wiadomości i TODO to proste, czytelne CRUD-y do ćwiczenia filtrów i uprawnień.

5. Autoryzacja (JWT)

Stosujemy JWT (SimpleJWT), bo to typowe podejście dla klientów SPA i aplikacji mobilnych.

Endpointy:

  • POST /api/auth/token/ → access + refresh
  • POST /api/auth/token/refresh/ → nowy access

Wymagany nagłówek:

  • Authorization: Bearer <access>

6. Uprawnienia i reguły dostępu (ACL)

Dokumenty

  • Właściciel: pełny dostęp (CRUD + download + share).
  • Udostępnione:
    • GET/HEAD/OPTIONS – dozwolone, jeśli istnieje share,
    • PUT/PATCH – dozwolone tylko przy permission=write,
    • DELETE – tylko właściciel (nawet przy write).

Udostępnienia

  • zarządzanie udostępnieniami dokumentu jest dozwolone tylko dla właściciela.

Wiadomości

  • użytkownik widzi tylko swoje wiadomości (inbox/outbox),
  • oznaczenie jako przeczytane działa tylko dla odbiorcy.

TODO

  • użytkownik zarządza tylko własnymi zadaniami.

7. Endpointy API (przegląd)

Dokumentacja:

  • Swagger UI: GET /api/docs/
  • OpenAPI schema: GET /api/schema/

Autoryzacja:

  • POST /api/auth/token/
  • POST /api/auth/token/refresh/

Użytkownicy:

  • GET /api/users/me/
  • GET /api/users/?q=...

Dokumenty:

  • GET/POST /api/documents/
  • GET/PATCH/PUT/DELETE /api/documents/{id}/
  • GET /api/documents/{id}/download/
  • GET/POST /api/documents/{id}/shares/ (tylko właściciel)

TODO:

  • GET/POST /api/todos/
  • GET/PATCH/PUT/DELETE /api/todos/{id}/

Wiadomości:

  • GET/POST /api/messages/
  • GET /api/messages/?mailbox=inbox|outbox
  • POST /api/messages/{id}/mark-read/

8. Uruchomienie (dev)

Wymagania:

  • Python 3.11+ (projekt działa na 3.13)

8.1. Backend

python3 -m pip install -r requirements.txt
cd backend
python3 manage.py migrate
python3 manage.py createsuperuser
python3 manage.py runserver

Linki:

8.2. Frontend (statyczny)

cd frontend
python3 -m http.server 5173

Otwórz: http://127.0.0.1:5173/

9. Testowanie API

9.1. Swagger UI

  1. Otwórz GET /api/docs/
  2. Zaloguj się przez POST /api/auth/token/ i skopiuj access
  3. Wysyłaj żądania z Authorization: Bearer <access>

9.2. curl (smoke test)

Token:

curl -s -X POST http://127.0.0.1:8000/api/auth/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"HASLO"}'

Lista dokumentów:

curl -s http://127.0.0.1:8000/api/documents/ \
  -H "Authorization: Bearer ACCESS_TOKEN"

10. Bezpieczeństwo (media / ACL / production storage)

Ta sekcja jest celowo „akademicka”: pokazuje, co w dev jest uproszczone, a w produkcji wymaga dodatkowych mechanizmów.

10.1. Upload i przechowywanie plików

Ryzyka:

  • upload złośliwych plików,
  • brak limitów rozmiaru i liczby plików,
  • problemy wydajnościowe przy serwowaniu plików przez aplikację,
  • zbyt łatwe udostępnienie pliku „publicznie” (np. błędna konfiguracja serwera).

Dobre praktyki (production):

  • limity uploadu (Django + reverse proxy),
  • walidacja MIME/rozszerzeń, ewentualnie skanowanie AV,
  • obiektowy storage (S3/MinIO) zamiast lokalnego dysku,
  • podpisywane URL-e / dedykowana warstwa download,
  • audyt: kto pobierał pliki i kiedy.

10.2. ACL i IDOR

Ryzyka:

  • IDOR (dostęp do obiektu po ID bez sprawdzenia uprawnień),
  • błędy w logice „owner vs shared” prowadzące do wycieku danych.

Dobre praktyki:

  • uprawnienia obiektowe zawsze po stronie backendu,
  • zasada najmniejszych uprawnień (read jako domyślne),
  • rozważ wygasanie udostępnień i historię zmian.

10.3. JWT

Ryzyka:

  • kradzież tokenu (np. XSS),
  • zbyt długie TTL,
  • brak rotacji/blacklisty refresh tokenów.

Dobre praktyki:

  • krótki TTL dla access,
  • ochrona frontendu przed XSS,
  • rozważenie rotacji/blacklisty refresh tokenów w produkcji.

11. Proponowany scenariusz laboratoriów

  1. Rozruch: instalacja, migracje, admin, Swagger.
  2. JWT: tokeny, nagłówek Authorization, refresh tokenu.
  3. TODO: CRUD + PATCH is_done.
  4. Wiadomości: inbox/outbox + mark-read.
  5. Dokumenty: upload multipart + download.
  6. Udostępnianie: read/write, weryfikacja dostępu (testy negatywne).
  7. Frontend: wykonanie tych samych operacji z przeglądarki.

12. Kryteria oceniania (rubryka)

  • Poprawność funkcjonalna (40%): endpointy i przypadki użycia działają zgodnie z opisem.
  • Autoryzacja i uprawnienia (25%): brak IDOR, poprawna kontrola dostępu do dokumentów/wiadomości/TODO.
  • Jakość API (20%): sensowne kody HTTP, walidacje, spójność, pagination gdzie potrzeba.
  • Czytelność i utrzymanie (15%): modularność, nazewnictwo, porządek w aplikacji.

13. Możliwości rozbudowy (zadania dodatkowe)

Poniższe propozycje są „dodatkowymi możliwościami rozbudowy” (zadania osobno), zgodnie z tematem z zajęć:

  • Diagramy: diagram klas (modele/relacje), diagramy ACL, diagram wdrożeniowy (dev vs prod).
  • Scenariusze laboratoriów: warianty ćwiczeń, checklisty testów negatywnych, praca w parach (owner/share).
  • Zadania domowe:
    • wersjonowanie dokumentów (historia pliku),
    • wygasające udostępnienia (expiry),
    • grupy/role i dziedziczenie uprawnień,
    • wyszukiwarka + filtrowanie + sortowanie,
    • powiadomienia o wiadomościach/udostępnieniach.
  • Bezpieczeństwo: media/ACL/production storage:
    • limity uploadu + walidacja MIME,
    • migracja storage do S3/MinIO,
    • podpisywane linki do pobrań,
    • audyt logów pobrań,
    • rotacja/blacklista refresh tokenów i polityki TTL.