From 675c3a661c584b229f37f9769fab9e1a45075889 Mon Sep 17 00:00:00 2001 From: Joao Carreira Date: Wed, 7 Oct 2026 00:25:09 +0100 Subject: [PATCH] feat: improve calendar sharing --- README.md | 17 ++++++ app/static/app.css | 12 +++++ app/templates/admin_schedules.html | 1 + app/templates/calendar.html | 87 ++++++++++++++++++++++++------ app/web.py | 9 ++++ docs/DOMAIN.md | 3 +- 6 files changed, 113 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 3967b16..1a8d922 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,23 @@ docker compose down Stopping the service leaves the host data directory intact. +## Add shifts to a phone's calendar + +Sign in, open **Calendário** from the rota, and choose your team's calendar +(administrators can also choose **Rota completa**): + +- **iPhone / Apple Calendar** opens the native subscription confirmation. +- **Google Calendar / Android** opens Google Calendar on the web. Google requires + its desktop interface to add subscriptions: request the desktop site in your phone's + browser, or add it on a computer, then enable the calendar in the mobile app. +- **Outlook** opens the web subscription screen; use the same account as the mobile app. +- **Copiar endereço** supplies the feed URL for another app or manual setup. + +The page includes step-by-step instructions for each platform. Subscribe by URL +rather than importing a downloaded `.ics` file so future changes appear automatically. +Providers control refresh timing; updates may take several hours. Google and Outlook +need an Internet-accessible feed address. + ## Run tests From the repository root, run one command: diff --git a/app/static/app.css b/app/static/app.css index 683250d..38e1fdc 100644 --- a/app/static/app.css +++ b/app/static/app.css @@ -70,6 +70,16 @@ input:focus,select:focus,button:focus-visible,a:focus-visible,summary:focus-visi .flash{padding:12px 14px;border-radius:9px;margin-bottom:18px;background:var(--brand-soft);border-left:4px solid var(--brand)} .flash.error{background:#f8e8e8;color:#7d2525;border-left-color:var(--danger)} .calendar-list{display:flex;flex-direction:column;gap:8px;padding-bottom:35px} +.calendar-subscribe-actions{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px;margin:14px 0} +.calendar-subscribe-actions .button{display:flex;align-items:center;justify-content:center;text-align:center;min-height:48px} +.calendar-feed label{display:block;margin-bottom:6px;font-size:.9rem;font-weight:600} +.calendar-url-row{display:flex;align-items:center;flex-wrap:wrap;gap:8px} +.calendar-url-row input{flex:1 1 260px;min-width:0} +.calendar-copy-status{min-height:1.45em;margin:8px 0 0;font-size:.9rem} +.calendar-help details+details{margin-top:8px} +.calendar-help summary{padding:10px 0;min-height:44px} +.calendar-help ol{padding-left:24px;margin-top:4px} +.calendar-help li+li{margin-top:8px} .day-card{display:grid;grid-template-columns:74px 1fr;overflow:hidden} .day-card.today{outline:2px solid var(--brand);outline-offset:1px} .day-label{padding:14px;text-align:center;border-right:1px solid var(--line);display:flex;flex-direction:column;background:#fffafa} @@ -114,6 +124,8 @@ th{font-size:.8rem;text-transform:uppercase;color:var(--muted);background:#fff7f .nav{order:3;width:100%;padding-bottom:4px} .account{margin-left:auto} .form-grid{grid-template-columns:1fr} + .calendar-subscribe-actions{grid-template-columns:1fr} + .calendar-url-row button{width:100%;min-height:44px} .day-card{grid-template-columns:58px 1fr} .day-label{padding:10px 7px} .assignment{align-items:flex-start;flex-direction:column} diff --git a/app/templates/admin_schedules.html b/app/templates/admin_schedules.html index 2e59631..2e2c397 100644 --- a/app/templates/admin_schedules.html +++ b/app/templates/admin_schedules.html @@ -43,6 +43,7 @@

Calendário da equipa

Um único endereço com a rota completa, para qualquer calendário.

+

Adicionar ao calendário do telemóvel

diff --git a/app/templates/calendar.html b/app/templates/calendar.html index d8fa30a..1d63e60 100644 --- a/app/templates/calendar.html +++ b/app/templates/calendar.html @@ -5,38 +5,95 @@

Rota

Calendário

-

Adiciona o endereço ao Google Calendar, Apple Calendar ou Outlook. O calendário atualiza-se sozinho, não é preciso repetir o processo.

+

Os teus turnos na app de calendário do telemóvel. Subscreve uma vez: as alterações à rota aparecem automaticamente, quando a app atualizar o calendário.

{% for feed in feeds %} -
+

{{ feed.title }}

-
- - - Subscrever + +

No iPhone, confirma a subscrição na app Calendário. No Google e Outlook, adiciona pelo navegador à conta que usas no telemóvel. Ver os passos.

+ +
+ + +
+

+{% else %} +
Ainda não tens uma equipa ativa com calendário.
{% endfor %}
+
+

Como adicionar no telemóvel

+
+ iPhone / iPad — Apple Calendar +
    +
  1. Toca em iPhone / Apple Calendar no calendário que queres adicionar.
  2. +
  3. Permite abrir a app Calendário e confirma Subscrever.
  4. +
  5. Se o botão não abrir a app, copia o endereço. Na app Calendário, abre Calendários → Adicionar calendário → Adicionar calendário de assinatura e cola-o.
  6. +
+
+
+ Android / Google Calendar +
    +
  1. Toca em Google Calendar / Android e entra na conta Google que usas no telemóvel.
  2. +
  3. O Google exige a versão para computador para adicionar subscrições. No navegador do telemóvel, ativa Site para computador; se não conseguires, abre esta página num computador.
  4. +
  5. Confirma a adição. Se não aparecer essa opção, copia o endereço e, no Google Calendar, escolhe Outros calendários → + → A partir de URL, cola-o e adiciona o calendário.
  6. +
  7. Na app Google Calendar, abre o menu e ativa o novo calendário. Se não aparecer, verifica as definições de sincronização.
  8. +
+
+
+ Outlook +
    +
  1. Toca em Outlook e entra na conta que usas na app.
  2. +
  3. Confirma a subscrição no Outlook na Web. Se necessário, usa Adicionar calendário → Subscrever a partir da Web e cola o endereço copiado.
  4. +
  5. Na app Outlook, seleciona o novo calendário nessa conta. Se a versão móvel não mostrar a opção de subscrever, usa o navegador em modo computador.
  6. +
+
+

Escolhe uma subscrição por endereço, em vez de importar um ficheiro .ics, para receber futuras alterações. A atualização depende da app e pode demorar algumas horas. Para Google e Outlook, o endereço tem de estar acessível pela Internet.

+
+ diff --git a/app/web.py b/app/web.py index 045addc..cb2eb18 100644 --- a/app/web.py +++ b/app/web.py @@ -4,6 +4,7 @@ import calendar from collections.abc import Sequence import secrets from datetime import date, datetime, time, timedelta +from urllib.parse import urlencode from fastapi import APIRouter, Depends, Form, HTTPException, Request from fastapi.responses import HTMLResponse, RedirectResponse, Response @@ -316,6 +317,14 @@ def calendar_page(request: Request, db: Session = Depends(get_db)): "url": _shared_calendar_url(request), } ) + for feed in feeds: + feed["webcal_url"] = "webcal://" + feed["url"].split("://", 1)[-1] + feed["google_url"] = "https://calendar.google.com/calendar/render?" + urlencode( + {"cid": feed["url"]} + ) + feed["outlook_url"] = "https://outlook.live.com/calendar/0/addfromweb?" + urlencode( + {"url": feed["url"], "name": feed["title"]} + ) return request.app.state.templates.TemplateResponse( request=request, name="calendar.html", diff --git a/docs/DOMAIN.md b/docs/DOMAIN.md index 7481a41..cf6986a 100644 --- a/docs/DOMAIN.md +++ b/docs/DOMAIN.md @@ -18,7 +18,8 @@ Every start copies the SQLite file aside before anything else runs, using SQLite ## Calendar feeds - `/calendar/.ics` is an iCalendar feed anybody can subscribe to from Google Calendar, Apple Calendar or Outlook. Every team has its own token, created the first time someone assigned to it opens `/calendar`, and its feed only carries the shifts assigned to it. -- `/calendar` is the page holding those links: the rota only has a button pointing there, so it keeps showing nothing but who works each day. A user gets one feed per team it is assigned to, each titled `Turnos de `. Each address sits in a readonly field with a **Copiar** button (clipboard when the browser allows it, selecting the field otherwise) plus a `webcal://` shortcut. +- `/calendar` is the page holding those links: the rota only has a button pointing there, so it keeps showing nothing but who works each day. A user gets one feed per active team it is assigned to, each titled `Turnos de `, plus the whole-rota feed for administrators. Each feed has mobile-sized **iPhone / Apple Calendar**, **Google Calendar / Android**, and **Outlook** actions. Apple opens a `webcal://` subscription; Google and Outlook open web subscription flows with the feed address encoded in the link. The page includes platform-specific instructions, a readonly address field, and **Copiar endereço**, with clipboard-error handling and a native-selection fallback for phones. +- Google does not add URL subscriptions through its mobile app: use its desktop web interface (request the desktop site on the phone, or use a computer), then enable the calendar in the mobile app using the same account. Outlook subscriptions also use its web interface. Subscriptions refresh according to the provider's schedule, rather than instantly; Google and Outlook must be able to fetch the address over the Internet. Importing a downloaded `.ics` file is a snapshot and is not the subscription workflow. - Administrators also get one shared feed with the whole rota, using the team token in `CALENDAR_TOKEN` (generated on first use and shown on `/admin/schedules`). - A feed publishes one month back and six months forward. Times carry the bar's timezone (`DTSTART;TZID=Europe/Lisbon:20261017T203000`) and the feed declares it in `X-WR-TIMEZONE` plus a `VTIMEZONE` block with the European summer-time rules (WET/WEST), so every client shows a night at 20:30 and keeps the right offset across the year. The zone comes from `TIMEZONE`; an unknown zone falls back to `Europe/Lisbon`. Times and names are private member data: the token is the only protection, so the shared link goes only to the team. - Each event title is ` · · ` so a list of shifts reads at a glance; a shift without a team keeps ` · `.