Implement external calendar integration and enhance API functionality

- Added support for fetching and parsing external ICS calendars, allowing events to be displayed on the duty grid.
- Introduced a new API endpoint `/api/calendar-events` to retrieve calendar events within a specified date range.
- Updated configuration to include `EXTERNAL_CALENDAR_ICS_URL` for specifying the ICS calendar URL.
- Enhanced the web application to visually indicate days with events and provide event summaries on hover.
- Improved documentation in the README to include details about the new calendar integration and configuration options.
- Updated tests to cover the new calendar functionality and ensure proper integration.

db/models.py

@@ -32,7 +32,8 @@ class Duty(Base):
     user_id: Mapped[int] = mapped_column(
         Integer, ForeignKey("users.id"), nullable=False
     )
-    start_at: Mapped[str] = mapped_column(Text, nullable=False)  # ISO 8601
-    end_at: Mapped[str] = mapped_column(Text, nullable=False)  # ISO 8601
+    # UTC, ISO 8601 with Z suffix (e.g. 2025-01-15T09:00:00Z)
+    start_at: Mapped[str] = mapped_column(Text, nullable=False)
+    end_at: Mapped[str] = mapped_column(Text, nullable=False)
 
     user: Mapped["User"] = relationship("User", back_populates="duties")

db/repository.py

@@ -40,7 +40,12 @@ def get_duties(
     from_date: str,
     to_date: str,
 ) -> list[tuple[Duty, str]]:
-    """Return list of (Duty, full_name) overlapping the given date range (ISO date strings)."""
+    """Return list of (Duty, full_name) overlapping the given date range.
+
+    from_date/to_date are YYYY-MM-DD (first/last day of month in client's local calendar).
+    Duty.start_at and end_at are stored in UTC (ISO 8601 with Z); lexicographic comparison
+    with date strings yields correct overlap.
+    """
     q = (
         session.query(Duty, User.full_name)
         .join(User, Duty.user_id == User.id)
@@ -55,6 +60,7 @@ def insert_duty(
     start_at: str,
     end_at: str,
 ) -> Duty:
+    """Create a duty. start_at and end_at must be UTC, ISO 8601 with Z (e.g. 2025-01-15T09:00:00Z)."""
     duty = Duty(user_id=user_id, start_at=start_at, end_at=end_at)
     session.add(duty)
     session.commit()

db/schemas.py

@@ -23,8 +23,8 @@ class UserInDb(UserBase):
 
 class DutyBase(BaseModel):
     user_id: int
-    start_at: str  # ISO 8601
-    end_at: str  # ISO 8601
+    start_at: str  # UTC, ISO 8601 with Z
+    end_at: str  # UTC, ISO 8601 with Z
 
 
 class DutyCreate(DutyBase):
@@ -43,3 +43,10 @@ class DutyWithUser(DutyInDb):
     full_name: str
 
     model_config = ConfigDict(from_attributes=True)
+
+
+class CalendarEvent(BaseModel):
+    """External calendar event (e.g. holiday) for a single day."""
+
+    date: str  # YYYY-MM-DD
+    summary: str