Fix HEAD support for UptimeRobot, email alerter bug, update docs

README.md

@@ -14,13 +14,69 @@ FastAPI backend for the SolarWine agrivoltaic vineyard control system.
 
 ## Endpoints
 
-- `GET /api/health` — health check
-- `GET /api/weather/current` — current weather (IMS station 43)
-- `GET /api/sensors/snapshot` — vine sensor readings (ThingsBoard)
-- `GET /api/energy/current` — current power output
-- `GET /api/photosynthesis/current` — photosynthesis rate (FvCB/ML)
+### Health & Monitoring
+- `GET|HEAD /api/health` — system health (uptime, Redis, TB, IMS, Gemini status)
+- `GET /api/health/data` — data freshness per source (age, ok/degraded)
+- `GET /api/health/data-sources` — per-source green/yellow/red status with thresholds
+
+### Weather (IMS Station 43)
+- `GET /api/weather/current` — latest weather readings + data age
+- `GET /api/weather/history?start_date&end_date&format` — historical weather (hourly)
+- `GET /api/weather/forecast` — weather forecast
+
+### Vine Sensors (ThingsBoard)
+- `GET /api/sensors/snapshot` — latest readings (treatment vs reference)
+- `GET /api/sensors/history?type&area&hours` — sensor time-series
+- `GET /api/sensors/soil-moisture?hours` — soil moisture history
+- `GET /api/sensors/rain?hours` — rainfall history
+
+### Energy
+- `GET /api/energy/current` — current power output (kW)
+- `GET /api/energy/daily/{date}` — daily production + hourly profile
+- `GET /api/energy/history` — energy generation time-series
+- `GET /api/energy/predict/{date}` — predicted daily generation
+
+### Photosynthesis
+- `GET /api/photosynthesis/current?model` — current A rate (FvCB or ML)
+- `GET /api/photosynthesis/forecast` — 24h predicted A profile
+
+### Control System
 - `GET /api/control/status` — last control loop tick
-- `POST /api/chatbot/message` — AI vineyard advisor
-- `GET /api/biology/rules` — biology rules
+- `GET /api/control/plan` — current day-ahead plan
+- `GET /api/control/budget` — energy budget status
+- `GET /api/control/trackers` — tracker angles and modes
+
+### Chatbot (Gemini AI)
+- `POST /api/chatbot/message` — send message to vineyard advisor
+- `POST /api/chatbot/feedback` — submit feedback on response
+- `GET /api/chatbot/briefing` — current system status briefing
+
+### Biology
+- `GET /api/biology/phenology` — current growth stage
+- `GET /api/biology/rules` — all biology rules
+- `GET /api/biology/rules/{name}` — single rule detail
+- `GET /api/biology/chill-units?season_start` — accumulated chill units
+
+### Auth
+- `POST /api/auth/login` — JWT token (guest mode when JWT_SECRET unset)
+
+### Events
+- `GET /api/events/stream` — SSE stream for live frontend updates
 
 Interactive docs at `/docs`.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `IMS_API_TOKEN` | Yes | IMS weather API token |
+| `THINGSBOARD_HOST` | Yes | ThingsBoard server URL |
+| `THINGSBOARD_USERNAME` | Yes | ThingsBoard login |
+| `THINGSBOARD_PASSWORD` | Yes | ThingsBoard password |
+| `GOOGLE_API_KEY` | No | Gemini AI for chatbot/advisor |
+| `JWT_SECRET` | No | JWT signing key (guest mode if unset) |
+| `ADMIN_PASSWORD` | No | Login password |
+| `REDIS_URL` | No | Upstash Redis for shared cache |
+| `SENTRY_DSN` | No | Sentry error tracking |
+| `SMTP_HOST` | No | Email alerts (with ALERT_EMAIL_TO) |
+| `ALERT_EMAIL_TO` | No | Alert recipient email(s) |

backend/HF_README.md

@@ -14,13 +14,69 @@ FastAPI backend for the SolarWine agrivoltaic vineyard control system.
 
 ## Endpoints
 
-- `GET /api/health` — health check
-- `GET /api/weather/current` — current weather (IMS station 43)
-- `GET /api/sensors/snapshot` — vine sensor readings (ThingsBoard)
-- `GET /api/energy/current` — current power output
-- `GET /api/photosynthesis/current` — photosynthesis rate (FvCB/ML)
+### Health & Monitoring
+- `GET|HEAD /api/health` — system health (uptime, Redis, TB, IMS, Gemini status)
+- `GET /api/health/data` — data freshness per source (age, ok/degraded)
+- `GET /api/health/data-sources` — per-source green/yellow/red status with thresholds
+
+### Weather (IMS Station 43)
+- `GET /api/weather/current` — latest weather readings + data age
+- `GET /api/weather/history?start_date&end_date&format` — historical weather (hourly)
+- `GET /api/weather/forecast` — weather forecast
+
+### Vine Sensors (ThingsBoard)
+- `GET /api/sensors/snapshot` — latest readings (treatment vs reference)
+- `GET /api/sensors/history?type&area&hours` — sensor time-series
+- `GET /api/sensors/soil-moisture?hours` — soil moisture history
+- `GET /api/sensors/rain?hours` — rainfall history
+
+### Energy
+- `GET /api/energy/current` — current power output (kW)
+- `GET /api/energy/daily/{date}` — daily production + hourly profile
+- `GET /api/energy/history` — energy generation time-series
+- `GET /api/energy/predict/{date}` — predicted daily generation
+
+### Photosynthesis
+- `GET /api/photosynthesis/current?model` — current A rate (FvCB or ML)
+- `GET /api/photosynthesis/forecast` — 24h predicted A profile
+
+### Control System
 - `GET /api/control/status` — last control loop tick
-- `POST /api/chatbot/message` — AI vineyard advisor
-- `GET /api/biology/rules` — biology rules
+- `GET /api/control/plan` — current day-ahead plan
+- `GET /api/control/budget` — energy budget status
+- `GET /api/control/trackers` — tracker angles and modes
+
+### Chatbot (Gemini AI)
+- `POST /api/chatbot/message` — send message to vineyard advisor
+- `POST /api/chatbot/feedback` — submit feedback on response
+- `GET /api/chatbot/briefing` — current system status briefing
+
+### Biology
+- `GET /api/biology/phenology` — current growth stage
+- `GET /api/biology/rules` — all biology rules
+- `GET /api/biology/rules/{name}` — single rule detail
+- `GET /api/biology/chill-units?season_start` — accumulated chill units
+
+### Auth
+- `POST /api/auth/login` — JWT token (guest mode when JWT_SECRET unset)
+
+### Events
+- `GET /api/events/stream` — SSE stream for live frontend updates
 
 Interactive docs at `/docs`.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `IMS_API_TOKEN` | Yes | IMS weather API token |
+| `THINGSBOARD_HOST` | Yes | ThingsBoard server URL |
+| `THINGSBOARD_USERNAME` | Yes | ThingsBoard login |
+| `THINGSBOARD_PASSWORD` | Yes | ThingsBoard password |
+| `GOOGLE_API_KEY` | No | Gemini AI for chatbot/advisor |
+| `JWT_SECRET` | No | JWT signing key (guest mode if unset) |
+| `ADMIN_PASSWORD` | No | Login password |
+| `REDIS_URL` | No | Upstash Redis for shared cache |
+| `SENTRY_DSN` | No | Sentry error tracking |
+| `SMTP_HOST` | No | Email alerts (with ALERT_EMAIL_TO) |
+| `ALERT_EMAIL_TO` | No | Alert recipient email(s) |

backend/api/main.py

@@ -261,7 +261,7 @@ app.add_middleware(
     CORSMiddleware,
     allow_origins=[o.strip() for o in allowed_origins],
     allow_credentials=True,
-    allow_methods=["GET", "POST", "OPTIONS"],
+    allow_methods=["GET", "HEAD", "POST", "OPTIONS"],
     allow_headers=["Content-Type", "Authorization"],
 )
 

backend/api/routes/health.py

@@ -31,7 +31,7 @@ async def _check_thingsboard() -> bool:
         return False
 
 
-@router.get("/health")
+@router.api_route("/health", methods=["GET", "HEAD"])
 async def health():
     redis = get_redis_client()
     redis_ok = redis.ping() if redis else False

backend/services/data_flow_monitor.py

@@ -80,6 +80,7 @@ class DataFlowMonitor:
             if wx and "error" not in wx:
                 age = float(wx.get("age_minutes", -1))
                 if age < 0:
+                    log.warning("IMS weather returned negative age_minutes — data provider issue")
                     age = None
                 status = _classify(age, IMS_STALE_YELLOW_MIN, IMS_STALE_RED_MIN)
                 return {

backend/services/email_alerter.py

@@ -59,10 +59,11 @@ class EmailAlerter:
             message = info.get("message", f"{source_name} is down")
             age = info.get("age_minutes")
             subject = f"[SolarWine] Data flow alert: {source_name}"
+            age_line = f"Age: {age:.0f} min\n" if age is not None else ""
             body = (
                 f"Data source: {source_name}\n"
                 f"Status: RED\n"
-                f"Age: {age:.0f} min\n" if age is not None else ""
+                f"{age_line}"
                 f"Detail: {message}\n"
                 f"\nChecked at: {status.get('checked_at', 'unknown')}\n"
                 f"Overall system status: {status.get('overall', 'unknown')}\n"