WorkTimeSystemAPI

API do rejestracji oraz podsumowywania czasu pracy pracowników. Projekt oparty na frameworku Symfony.

---

Spis treści

• Funkcjonalności
• Wymagania
• Instalacja
• Endpointy
  • Utworzenie pracownika
  • Rejestracja czasu pracy
  • Podsumowanie dnia
  • Podsumowanie miesiąca
• Walidacja i błędy
• Testy

---

Funkcjonalności

• Utworzenie nowego pracownika
• Rejestrowanie czasu pracy z walidacją (kolejność dat, maks. 12h, jedna rejestracja / dzień)
• Podsumowanie godzin i wynagrodzenia z konkretnego dnia
• Podsumowanie godzin i wynagrodzenia z całego miesiąca (w tym nadgodziny)
• Obsługa walidacji i wyjątków z tłumaczeniami
• REST API w formacie JSON z odpowiednimi statusami kodu
• Gotowa konfiguracja Docker Compose z bazą danych MariaDB i Adminerem

---

Wymagania

• PHP 8.2.12 lub nowszy
• Symfony 7.2.6
• Composer
• Baza danych MariaDB 11.7.2
• Docker (opcjonalnie)

---

Instalacja

1. Sklonuj repozytorium:

git clone https://github.com/mateusz-przybyla/WorkTimeSystemAPI.git
cd WorkTimeSystemAPI

2. Zainstaluj zależności:

composer install

3. Skonfiguruj .env

Domyślnie dane:

DATABASE_URL="mysql://mateusz:mateusz@127.0.0.1:3306/work_time_system_api_db?serverVersion=mariadb-11.7.2&charset=utf8mb4"

4. Uruchom bazę danych z Dockerem:

Możesz skorzystać z gotowego pliku compose.yaml, który uruchamia kontener bazy danych oraz Adminera.

docker compose up -d

• MariaDB 11.7.2 (na porcie 3306)
• Adminer (GUI do zarządzania DB – dostępny na http://localhost:8080)

5. Utwórz schemat bazy danych:

symfony console doctrine:migrations:migrate

6. Uruchom lokalny serwer Symfony:

symfony server:start

7. Przetestuj:

Przetestuj funkcjonalność API np. za pomoca platformy Postman: https://www.postman.com/

---

Endpointy

Strona powitania

GET /

• Odpowiedź:

{
    "response": "Witaj w WorkTimeSystem API."
}

Status kodu: 200 OK

---

Utworzenie pracownika

POST /api/employee

• Przykładowe żądanie:

{
  "firstname": "Jan",
  "surname": "Kowalski"
}

• Przykładowa odpowiedź:

{
  "response": {
    "uuid": "a29078ae-7f68-403c-9b1f-bd9b3e02f4d7"
  }
}

Status kodu: 201 Created

• Możliwe błędy:

{
  "error": "Nieprawidłowy format JSON."
}

Status kodu: 400 Bad Request

{
  "error": {
    "firstname": [
      "Imię jest wymagane."
    ],
    "surname": [
      "Nazwisko jest wymagane."
    ]
  }
}

Status kodu: 422 Unprocessable Entity

---

Rejestracja czasu pracy

POST /api/work-time

• Przykładowe żądanie:

{
  "uuid": "a29078ae-7f68-403c-9b1f-bd9b3e02f4d7",
  "startTime": "20.05.2024 08:00",
  "endTime": "20.05.2024 16:00"
}

• Przykładowa odpowiedź:

{
  "response": [
    "Czas pracy został dodany."
  ]
}

Status kodu: 201 Created

• Możliwe błędy:

{
  "error": "Nieprawidłowy format JSON."
}

Status kodu: 400 Bad Request

{
  "error": [
    "Nie znaleziono pracownika."
  ]
}

Status kodu: 404 Not Found

{
  "error": [
    "Pracownik już posiada zarejestrowany czas pracy w tym dniu."
  ]
}

Status kodu: 409 Conflict

{
  "error": {
    "uuid": [
      "To pole nie może być puste."
    ],
    "startTime": [
      "To pole nie może być puste."
    ],
    "endTime": [
      "To pole nie może być puste."
    ]
  }
}
{
  "error": [
    "Data zakończenia musi być po dacie rozpoczęcia.",
    "Czas pracy nie może przekraczać 12 godzin."
  ]
}

Status kodu: 422 Unprocessable Entity

---

Podsumowanie dnia

POST /api/summary/day

• Przykładowe żądanie:

{
  "uuid": "a29078ae-7f68-403c-9b1f-bd9b3e02f4d7",
  "date": "20.05.2024"
}

• Przykładowa odpowiedź:

{
  "response": {
    "total_after_conversion": "160 PLN",
    "hours_for_given_day": 8,
    "rate": "20 PLN"
  }
}

Status kodu: 200 OK

• Możliwe błędy:

{
  "error": "Nieprawidłowy format JSON."
}

Status kodu: 400 Bad Request

{
  "error": [
    "Nie znaleziono pracownika."
  ]
}

Status kodu: 404 Not Found

{
  "error": {
    "uuid": [
      "To pole nie może być puste."
    ],
    "date": [
      "To pole nie może być puste."
    ],
  }
}

Status kodu: 422 Unprocessable Entity

---

Podsumowanie miesiąca

POST /api/summary/month

• Przykładowe żądanie:

{
  "uuid": "a29078ae-7f68-403c-9b1f-bd9b3e02f4d7",
  "date": "05.2024"
}

• Przykładowa odpowiedź:

{
  "response": {
    "regular_hours_in_given_month": 40,
    "rate": "20 PLN",
    "overtime_hours_in_given_month": 5,
    "overtime_rate": "40 PLN",
    "total_after_conversion": "1000 PLN"
  }
}

Status kodu: 200 OK

• Możliwe błędy:

{
  "error": "Nieprawidłowy format JSON."
}

Status kodu: 400 Bad Request

{
  "error": [
    "Nie znaleziono pracownika."
  ]
}

Status kodu: 404 Not Found

{
  "error": {
    "uuid": [
      "To pole nie może być puste."
    ],
    "date": [
      "To pole nie może być puste."
    ],
  }
}

Status kodu: 422 Unprocessable Entity

---

Walidacja i błędy

Błędy walidacyjne i biznesowe są tłumaczone za pomocą komponentu translatora. Przykład błędu:

{
  "error": [
    "Czas pracy nie może przekraczać 12 godzin."
  ]
}

Wszystkie wyjątki HTTP (np. NotFoundHttpException, ConflictHttpException) są przechwytywane przez ApiExceptionListener, który zwraca odpowiedź w formacie JSON.

---

Testy

Testy jednostkowe uruchomisz za pomocą PHPUnit:

php bin/phpunit

Testowany jest m.in. serwis WorkTimeService, jego logika rozliczania i podsumowania czasu pracy.