Compare commits
7 Commits
mqtt-trans
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 03e3c11e90 | |||
| 4d652f0554 | |||
| 06411edfab | |||
| 365d8f58f3 | |||
| 3fc7d33e43 | |||
| b5f5f30005 | |||
| 2580aa5e0d |
20
.env.example
20
.env.example
@@ -20,8 +20,18 @@ DB_HOST=db
|
|||||||
# MQTT
|
# MQTT
|
||||||
MQTT_BROKER_HOST=mqtt
|
MQTT_BROKER_HOST=mqtt
|
||||||
MQTT_BROKER_PORT=1883
|
MQTT_BROKER_PORT=1883
|
||||||
# MQTT_USER=your_mqtt_user
|
# Required for authenticated broker access
|
||||||
# MQTT_PASSWORD=your_mqtt_password
|
MQTT_USER=your_mqtt_user
|
||||||
|
MQTT_PASSWORD=replace_with_a_32plus_char_random_password
|
||||||
|
# Optional: dedicated canary client account
|
||||||
|
MQTT_CANARY_USER=your_canary_mqtt_user
|
||||||
|
MQTT_CANARY_PASSWORD=replace_with_a_different_32plus_char_random_password
|
||||||
|
# Optional TLS settings
|
||||||
|
MQTT_TLS_ENABLED=false
|
||||||
|
MQTT_TLS_CA_CERT=
|
||||||
|
MQTT_TLS_CERTFILE=
|
||||||
|
MQTT_TLS_KEYFILE=
|
||||||
|
MQTT_TLS_INSECURE=false
|
||||||
MQTT_KEEPALIVE=60
|
MQTT_KEEPALIVE=60
|
||||||
|
|
||||||
# Dashboard
|
# Dashboard
|
||||||
@@ -39,6 +49,12 @@ HEARTBEAT_GRACE_PERIOD_PROD=170
|
|||||||
# Optional: force periodic republish even without changes
|
# Optional: force periodic republish even without changes
|
||||||
# REFRESH_SECONDS=0
|
# REFRESH_SECONDS=0
|
||||||
|
|
||||||
|
# Crash recovery (scheduler auto-recovery)
|
||||||
|
# CRASH_RECOVERY_ENABLED=false
|
||||||
|
# CRASH_RECOVERY_GRACE_SECONDS=180
|
||||||
|
# CRASH_RECOVERY_LOCKOUT_MINUTES=15
|
||||||
|
# CRASH_RECOVERY_COMMAND_EXPIRY_SECONDS=240
|
||||||
|
|
||||||
# Default superadmin bootstrap (server/init_defaults.py)
|
# Default superadmin bootstrap (server/init_defaults.py)
|
||||||
# REQUIRED: Must be set for superadmin creation
|
# REQUIRED: Must be set for superadmin creation
|
||||||
DEFAULT_SUPERADMIN_USERNAME=superadmin
|
DEFAULT_SUPERADMIN_USERNAME=superadmin
|
||||||
|
|||||||
5
.github/FRONTEND_DESIGN_RULES.md
vendored
Normal file
5
.github/FRONTEND_DESIGN_RULES.md
vendored
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
# FRONTEND Design Rules
|
||||||
|
|
||||||
|
Canonical source: [../FRONTEND_DESIGN_RULES.md](../FRONTEND_DESIGN_RULES.md)
|
||||||
|
|
||||||
|
Use the repository-root file as the maintained source of truth.
|
||||||
532
.github/copilot-instructions.md
vendored
532
.github/copilot-instructions.md
vendored
@@ -1,449 +1,113 @@
|
|||||||
# Copilot instructions for infoscreen_2025
|
# Copilot instructions for infoscreen_2025
|
||||||
|
|
||||||
# Purpose
|
## Purpose
|
||||||
These instructions tell Copilot Chat how to reason about this codebase.
|
This file is a concise, high-signal brief for coding agents.
|
||||||
Prefer explanations and refactors that align with these structures.
|
It is not a changelog and not a full architecture handbook.
|
||||||
|
|
||||||
Use this as your shared context when proposing changes. Keep edits minimal and match existing patterns referenced below.
|
|
||||||
|
|
||||||
## TL;DR
|
## TL;DR
|
||||||
Small multi-service digital signage app (Flask API, React dashboard, MQTT scheduler). Edit `server/` for API logic, `scheduler/` for event publishing, and `dashboard/` for UI. If you're asking Copilot for changes, prefer focused prompts that include the target file(s) and the desired behavior.
|
- Stack: Flask API + MariaDB, React/Vite dashboard, MQTT listener, scheduler, worker.
|
||||||
|
- Main areas:
|
||||||
|
- API logic in `server/`
|
||||||
|
- Scheduler logic in `scheduler/`
|
||||||
|
- UI logic in `dashboard/src/`
|
||||||
|
- Keep changes minimal, match existing patterns, and update docs in the same commit when behavior changes.
|
||||||
|
|
||||||
### How to ask Copilot
|
## Fast file map
|
||||||
- "Add a new route `GET /api/events/summary` that returns counts per event_type — implement in `server/routes/events.py`."
|
- `scheduler/scheduler.py` - scheduler loop, MQTT event publishing, TV power intent publishing, crash auto-recovery, command expiry sweep
|
||||||
- "Create an Alembic migration to add `duration` and `resolution` to `event_media` and update upload handler to populate them."
|
- `scheduler/db_utils.py` - event formatting, power-intent helpers, crash recovery helpers, command expiry sweep
|
||||||
- "Refactor `scheduler/db_utils.py` to prefer precomputed EventMedia metadata and fall back to a HEAD probe."
|
- `listener/listener.py` - discovery/heartbeat/log/screenshot/service_failed MQTT consumption
|
||||||
- "Add an ffprobe-based worker that extracts duration/resolution/bitrate and stores them on `EventMedia`."
|
- `server/init_academic_periods.py` - idempotent academic-period seeding + auto-activation for current date
|
||||||
|
- `server/initialize_database.py` - migration + bootstrap orchestration for local/manual setup
|
||||||
|
- `server/routes/events.py` - event CRUD, recurrence handling, UTC normalization
|
||||||
|
- `server/routes/eventmedia.py` - file manager, media upload/stream endpoints
|
||||||
|
- `server/routes/groups.py` - group lifecycle, alive status, order persistence
|
||||||
|
- `server/routes/system_settings.py` - system settings CRUD and supplement-table endpoint
|
||||||
|
- `server/routes/clients.py` - client metadata, restart/shutdown/restart_app command issuing, command status, crashed/service_failed alert endpoints
|
||||||
|
- `dashboard/src/settings.tsx` - settings UX and system-defaults integration
|
||||||
|
- `dashboard/src/components/CustomEventModal.tsx` - event creation/editing UX
|
||||||
|
- `dashboard/src/monitoring.tsx` - superadmin monitoring page
|
||||||
|
- `TV_POWER_INTENT_SERVER_CONTRACT_V1.md` - Phase 1 TV power contract
|
||||||
|
|
||||||
Keep docs synced with code. When you change services/MQTT/API/UTC/env or dev/prod run steps, update this file in the same commit (see `AI-INSTRUCTIONS-MAINTENANCE.md`).
|
## Service picture
|
||||||
|
- API: `server/` on `:8000` (health: `/health`)
|
||||||
|
- Dashboard: `dashboard/` (dev `:5173`, proxied API calls)
|
||||||
|
- MQTT broker: Mosquitto (`mosquitto/config/mosquitto.conf`)
|
||||||
|
- Listener: MQTT consumer that updates server-side state
|
||||||
|
- Scheduler: publishes active events and group-level TV power intents
|
||||||
|
- Nginx: routes `/api/*` and `/screenshots/*` to API, dashboard otherwise
|
||||||
|
- Prod bootstrap: `docker-compose.prod.yml` server command runs migrations, defaults init, and academic-period init before Gunicorn start
|
||||||
|
|
||||||
### When not to change
|
## Non-negotiable conventions
|
||||||
- Avoid editing generated assets under `dashboard/dist/` and compiled bundles. Don't modify files produced by CI or Docker builds (unless intentionally updating build outputs).
|
- Datetime:
|
||||||
|
- Store/compare in UTC.
|
||||||
|
- API returns ISO strings without `Z` in many routes.
|
||||||
|
- Frontend must append `Z` before parsing if needed.
|
||||||
|
- JSON naming:
|
||||||
|
- Backend internals use snake_case.
|
||||||
|
- API responses use camelCase (via `server/serializers.py`).
|
||||||
|
- DB host in containers: `db` (not localhost).
|
||||||
|
- Never put secrets in docs.
|
||||||
|
|
||||||
### Contact / owner
|
## MQTT contracts
|
||||||
- Primary maintainer: RobbStarkAustria (owner). For architecture questions, ping the repo owner or open an issue and tag `@RobbStarkAustria`.
|
- Event list topic (retained): `infoscreen/events/{group_id}`
|
||||||
|
- Group assignment topic (retained): `infoscreen/{uuid}/group_id`
|
||||||
|
- Heartbeat topic: `infoscreen/{uuid}/heartbeat`
|
||||||
|
- Logs topic family: `infoscreen/{uuid}/logs/{error|warn|info}`
|
||||||
|
- Health topic: `infoscreen/{uuid}/health`
|
||||||
|
- Dashboard screenshot topic: `infoscreen/{uuid}/dashboard`
|
||||||
|
- Client command topic (QoS1, non-retained): `infoscreen/{uuid}/commands` (compat alias: `infoscreen/{uuid}/command`)
|
||||||
|
- Client command ack topic (QoS1, non-retained): `infoscreen/{uuid}/commands/ack` (compat alias: `infoscreen/{uuid}/command/ack`)
|
||||||
|
- Service-failed topic (retained, client→server): `infoscreen/{uuid}/service_failed`
|
||||||
|
- TV power intent Phase 1 topic (retained, QoS1): `infoscreen/groups/{group_id}/power/intent`
|
||||||
|
|
||||||
### Important files (quick jump targets)
|
TV power intent Phase 1 rules:
|
||||||
- `scheduler/db_utils.py` — event formatting and scheduler-facing logic
|
- Schema version is `"1.0"`.
|
||||||
- `scheduler/scheduler.py` — scheduler main loop and MQTT publisher
|
- Group-only scope in Phase 1.
|
||||||
- `server/routes/eventmedia.py` — file uploads, streaming endpoint
|
- Heartbeat publish keeps `intent_id`; semantic transition rotates `intent_id`.
|
||||||
- `server/routes/events.py` — event CRUD and recurrence handling
|
- Expiry rule: `expires_at = issued_at + max(3 x poll_interval_sec, 90s)`.
|
||||||
- `server/routes/groups.py` — group management, alive status, display order persistence
|
- Canonical contract is `TV_POWER_INTENT_SERVER_CONTRACT_V1.md`.
|
||||||
- `dashboard/src/components/CustomEventModal.tsx` — event creation UI
|
|
||||||
- `dashboard/src/media.tsx` — FileManager / upload settings
|
|
||||||
- `dashboard/src/settings.tsx` — settings UI (nested tabs; system defaults for presentations and videos)
|
|
||||||
- `dashboard/src/ressourcen.tsx` — timeline view showing all groups' active events in parallel
|
|
||||||
- `dashboard/src/ressourcen.css` — timeline and resource view styling
|
|
||||||
- `dashboard/src/monitoring.tsx` — superadmin-only monitoring dashboard for client health, screenshots, and logs
|
|
||||||
|
|
||||||
|
## Backend patterns
|
||||||
|
- Routes in `server/routes/*`, registered in `server/wsgi.py`.
|
||||||
|
- Use one request-scoped DB session, commit on mutation, always close session.
|
||||||
|
- Keep enum/datetime serialization JSON-safe.
|
||||||
|
- Maintain UTC-safe comparisons in scheduler and routes.
|
||||||
|
- Keep recurrence handling backend-driven and consistent with exceptions.
|
||||||
|
- Academic periods bootstrap is idempotent and should auto-activate period covering `date.today()` when available.
|
||||||
|
|
||||||
|
## Frontend patterns
|
||||||
|
- Use Syncfusion-based patterns already present in dashboard.
|
||||||
|
- Keep API requests relative (`/api/...`) to use Vite proxy in dev.
|
||||||
|
- Respect `FRONTEND_DESIGN_RULES.md` for component and styling conventions.
|
||||||
|
- Keep role-gated UI behavior aligned with backend authorization.
|
||||||
|
- Holiday status banner in dashboard should render from computed state and avoid stale message reuse in 3rd-party UI components.
|
||||||
|
|
||||||
## Big picture
|
## Environment variables (high-value)
|
||||||
- Multi-service app orchestrated by Docker Compose.
|
- Scheduler: `POLL_INTERVAL_SECONDS`, `REFRESH_SECONDS`
|
||||||
- API: Flask + SQLAlchemy (MariaDB), in `server/` exposed on :8000 (health: `/health`).
|
- Power intent: `POWER_INTENT_PUBLISH_ENABLED`, `POWER_INTENT_HEARTBEAT_ENABLED`, `POWER_INTENT_EXPIRY_MULTIPLIER`, `POWER_INTENT_MIN_EXPIRY_SECONDS`
|
||||||
- Dashboard: React + Vite in `dashboard/`, dev on :5173, served via Nginx in prod.
|
- Monitoring: `PRIORITY_SCREENSHOT_TTL_SECONDS`
|
||||||
- MQTT broker: Eclipse Mosquitto, config in `mosquitto/config/mosquitto.conf`.
|
- Crash recovery: `CRASH_RECOVERY_ENABLED`, `CRASH_RECOVERY_GRACE_SECONDS`, `CRASH_RECOVERY_LOCKOUT_MINUTES`, `CRASH_RECOVERY_COMMAND_EXPIRY_SECONDS`
|
||||||
- Listener: MQTT consumer handling discovery, heartbeats, and dashboard screenshot uploads in `listener/listener.py`.
|
- Core: `DB_CONN`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_NAME`, `ENV`
|
||||||
- Scheduler: Publishes only currently active events (per group, at "now") to MQTT retained topics in `scheduler/scheduler.py`. It queries a future window (default: 7 days) to expand recurring events using RFC 5545 rules and applies event exceptions, but only publishes events that are active at the current time. When a group has no active events, the scheduler clears its retained topic by publishing an empty list. All time comparisons are UTC; any naive timestamps are normalized. Logging is concise; conversion lookups are cached and logged only once per media.
|
- MQTT auth/connectivity: `MQTT_BROKER_HOST`, `MQTT_BROKER_PORT`, `MQTT_USER`, `MQTT_PASSWORD` (listener/scheduler/server should use authenticated broker access)
|
||||||
- Nginx: Reverse proxy routes `/api/*` and `/screenshots/*` to API; everything else to dashboard (`nginx.conf`).
|
|
||||||
|
|
||||||
- Dev Container (hygiene): UI-only `Dev Containers` extension runs on host UI via `remote.extensionKind`; do not install it in-container. Dashboard installs use `npm ci`; shell aliases in `postStartCommand` are appended idempotently.
|
## Edit guardrails
|
||||||
|
- Do not edit generated assets in `dashboard/dist/`.
|
||||||
|
- Do not change CI/build outputs unless explicitly intended.
|
||||||
|
- Preserve existing API behavior unless task explicitly requires a change.
|
||||||
|
- Prefer links to canonical docs instead of embedding long historical notes here.
|
||||||
|
|
||||||
### Screenshot retention
|
## Documentation sync rule
|
||||||
- Screenshots sent via dashboard MQTT are stored in `server/screenshots/`.
|
When services/MQTT/API/UTC/env behavior changes:
|
||||||
- Screenshot payloads support `screenshot_type` with values `periodic`, `event_start`, `event_stop`.
|
1. Update this file (concise deltas only).
|
||||||
- `periodic` is the normal heartbeat/dashboard screenshot path; `event_start` and `event_stop` are high-priority screenshots for monitoring.
|
2. Update canonical docs where details live.
|
||||||
- For each client, the API keeps `{uuid}.jpg` as latest and the last 20 timestamped screenshots (`{uuid}_..._{type}.jpg`), deleting older timestamped files automatically.
|
3. Update changelogs separately (`TECH-CHANGELOG.md`, `DEV-CHANGELOG.md`, `dashboard/public/program-info.json` as appropriate).
|
||||||
- For high-priority screenshots, the API additionally maintains `{uuid}_priority.jpg` and metadata in `{uuid}_meta.json` (`latest_screenshot_type`, `last_priority_*`).
|
|
||||||
|
|
||||||
## Recent changes since last commit
|
## Canonical docs map
|
||||||
|
- Repo entry: `README.md`
|
||||||
### Latest (March 2026)
|
- Instruction governance: `AI-INSTRUCTIONS-MAINTENANCE.md`
|
||||||
|
- Technical release details: `TECH-CHANGELOG.md`
|
||||||
- **Monitoring System Completion (no version bump)**:
|
- Workspace/development notes: `DEV-CHANGELOG.md`
|
||||||
- End-to-end monitoring pipeline completed: MQTT logs/health → listener persistence → monitoring APIs → superadmin dashboard
|
- MQTT payload details: `MQTT_EVENT_PAYLOAD_GUIDE.md`
|
||||||
- API now serves aggregated monitoring via `GET /api/client-logs/monitoring-overview` and system-wide recent errors via `GET /api/client-logs/recent-errors`
|
- TV power contract: `TV_POWER_INTENT_SERVER_CONTRACT_V1.md`
|
||||||
- Monitoring dashboard (`dashboard/src/monitoring.tsx`) is active and displays client health states, screenshots, process metadata, and recent log activity
|
- Frontend patterns: `FRONTEND_DESIGN_RULES.md`
|
||||||
- **Screenshot Priority Pipeline (no version bump)**:
|
- Archived historical docs: `docs/archive/`
|
||||||
- Listener forwards `screenshot_type` from MQTT screenshot/dashboard payloads to `POST /api/clients/<uuid>/screenshot`.
|
|
||||||
- API stores typed screenshots, tracks latest/priority metadata, and serves priority images via `GET /screenshots/<uuid>/priority`.
|
|
||||||
- Monitoring overview exposes screenshot priority state (`latestScreenshotType`, `priorityScreenshotType`, `priorityScreenshotReceivedAt`, `hasActivePriorityScreenshot`) and `summary.activePriorityScreenshots`.
|
|
||||||
- Monitoring UI shows screenshot type badges and switches to faster refresh while priority screenshots are active.
|
|
||||||
- **MQTT Dashboard Payload v2 Cutover (no version bump)**:
|
|
||||||
- Dashboard payload parsing in `listener/listener.py` is now v2-only (`message`, `content`, `runtime`, `metadata`).
|
|
||||||
- Legacy top-level dashboard fallback was removed after migration soak (`legacy_fallback=0`).
|
|
||||||
- Listener observability summarizes parser health using `v2_success` and `parse_failures` counters.
|
|
||||||
- **Presentation Flags Persistence Fix**:
|
|
||||||
- Fixed persistence for presentation `page_progress` and `auto_progress` to ensure values are reliably stored and returned across create/update paths and detached occurrences
|
|
||||||
|
|
||||||
### Earlier (January 2026)
|
|
||||||
|
|
||||||
- **Ressourcen Page (Timeline View)**:
|
|
||||||
- New 'Ressourcen' page with parallel timeline view showing active events for all room groups
|
|
||||||
- Compact timeline display with adjustable row height (65px per group)
|
|
||||||
- Real-time view of currently running events with type, title, and time window
|
|
||||||
- Customizable group ordering with visual reordering panel (drag up/down buttons)
|
|
||||||
- Group order persisted via `GET/POST /api/groups/order` endpoints
|
|
||||||
- Color-coded event bars matching group theme
|
|
||||||
- Timeline modes: Day and Week views (day view by default)
|
|
||||||
- Dynamic height calculation based on number of groups
|
|
||||||
- Syncfusion ScheduleComponent with TimelineViews, Resize, and DragAndDrop support
|
|
||||||
- Files: `dashboard/src/ressourcen.tsx` (page), `dashboard/src/ressourcen.css` (styles)
|
|
||||||
|
|
||||||
### Earlier (November 2025)
|
|
||||||
|
|
||||||
- **API Naming Convention Standardization (camelCase)**:
|
|
||||||
- Backend: Created `server/serializers.py` with `dict_to_camel_case()` utility for consistent JSON serialization
|
|
||||||
- Events API: `GET /api/events` and `GET /api/events/<id>` now return camelCase fields (`id`, `subject`, `startTime`, `endTime`, `type`, `groupId`, etc.) instead of PascalCase
|
|
||||||
- Frontend: Dashboard and appointments page updated to consume camelCase API responses
|
|
||||||
- Appointments page maintains internal PascalCase for Syncfusion scheduler compatibility with automatic mapping from API responses
|
|
||||||
- **Breaking**: External API consumers must update field names from PascalCase to camelCase
|
|
||||||
|
|
||||||
- **UTC Time Handling**:
|
|
||||||
- Database stores all timestamps in UTC (naive timestamps normalized by backend)
|
|
||||||
- API returns ISO strings without 'Z' suffix: `"2025-11-27T20:03:00"`
|
|
||||||
- Frontend: Dashboard and appointments automatically append 'Z' to parse as UTC and display in user's local timezone
|
|
||||||
- Time formatting functions use `toLocaleTimeString('de-DE')` for German locale display
|
|
||||||
- All time comparisons use UTC; `new Date().toISOString()` sends UTC back to API
|
|
||||||
- API returns ISO strings without `Z`; frontend must append `Z` before parsing to ensure UTC
|
|
||||||
|
|
||||||
- **Dashboard Enhancements**:
|
|
||||||
- New card-based design for Raumgruppen (room groups) with Syncfusion components
|
|
||||||
- Global statistics summary: total infoscreens, online/offline counts, warning groups
|
|
||||||
- Filter buttons: All, Online, Offline, Warnings with dynamic counts
|
|
||||||
- Active event display per group: shows currently playing content with type icon, title, date, and time
|
|
||||||
- Health visualization with color-coded progress bars per group
|
|
||||||
- Expandable client details with last alive timestamps
|
|
||||||
- Bulk restart functionality for offline clients per group
|
|
||||||
- Manual refresh button with toast notifications
|
|
||||||
- 15-second auto-refresh interval
|
|
||||||
|
|
||||||
### Earlier changes
|
|
||||||
|
|
||||||
- Scheduler: when formatting video events the scheduler now performs a best-effort HEAD probe of the streaming URL and includes basic metadata in the emitted payload (mime_type, size, accept_ranges). Placeholders for richer metadata (duration, resolution, bitrate, qualities, thumbnails, checksum) are included for later population by a background worker.
|
|
||||||
- Streaming endpoint: a range-capable streaming endpoint was added at `/api/eventmedia/stream/<media_id>/<filename>` that supports byte-range requests (206 Partial Content) to enable seeking from clients.
|
|
||||||
- Event model & API: `Event` gained video-related fields (`event_media_id`, `autoplay`, `loop`, `volume`) and the API accepts and persists these when creating/updating video events.
|
|
||||||
- Dashboard: UI updated to allow selecting uploaded videos for events and to specify autoplay/loop/volume. File upload settings were increased (maxFileSize raised) and the client now validates video duration (max 10 minutes) before upload.
|
|
||||||
- FileManager: uploads compute basic metadata and enqueue conversions for office formats as before; video uploads now surface size and are streamable via the new endpoint.
|
|
||||||
|
|
||||||
- Event model & API (new): Added `muted` (Boolean) for video events; create/update and GET endpoints accept, persist, and return `muted` alongside `autoplay`, `loop`, and `volume`.
|
|
||||||
- Dashboard — Settings: Settings page refactored to nested tabs; added Events → Videos defaults (autoplay, loop, volume, mute) backed by system settings keys (`video_autoplay`, `video_loop`, `video_volume`, `video_muted`).
|
|
||||||
- Dashboard — Events UI: CustomEventModal now exposes per-event video `muted` and initializes all video fields from system defaults when creating a new event.
|
|
||||||
- Dashboard — Academic Calendar: Merged “School Holidays Import” and “List” into a single “📥 Import & Liste” tab; nested tab selection is persisted with controlled `selectedItem` state to avoid jumps.
|
|
||||||
|
|
||||||
Note: these edits are intentionally backwards-compatible — if the probe fails, the scheduler still emits the stream URL and the client should fallback to a direct play attempt or request richer metadata when available.
|
|
||||||
|
|
||||||
Backend rework notes (no version bump):
|
|
||||||
- Dev container hygiene: UI-only Remote Containers; reproducible dashboard installs (`npm ci`); idempotent shell aliases.
|
|
||||||
- Serialization consistency: snake_case internal → camelCase external via `server/serializers.py` for all JSON.
|
|
||||||
- UTC normalization across routes/scheduler; enums and datetimes serialize consistently.
|
|
||||||
|
|
||||||
## Service boundaries & data flow
|
|
||||||
- Database connection string is passed as `DB_CONN` (mysql+pymysql) to Python services.
|
|
||||||
- API builds its engine in `server/database.py` (loads `.env` only in development).
|
|
||||||
- Listener also creates its own engine for writes to `clients`.
|
|
||||||
- Scheduler queries a future window (default: 7 days) to expand recurring events using RFC 5545 rules, applies event exceptions (skipped dates, detached occurrences), and publishes only events that are active at the current time (UTC). When a group has no active events, the scheduler clears its retained topic by publishing an empty list. Time comparisons are UTC; naive timestamps are normalized. Logging is concise; conversion lookups are cached and logged only once per media.
|
|
||||||
- MQTT topics (paho-mqtt v2, use Callback API v2):
|
|
||||||
- Discovery: `infoscreen/discovery` (JSON includes `uuid`, hw/ip data). ACK to `infoscreen/{uuid}/discovery_ack`. See `listener/listener.py`.
|
|
||||||
- Heartbeat: `infoscreen/{uuid}/heartbeat` updates `Client.last_alive` (UTC); enhanced payload includes `current_process`, `process_pid`, `process_status`, `current_event_id`.
|
|
||||||
- Event lists (retained): `infoscreen/events/{group_id}` from `scheduler/scheduler.py`.
|
|
||||||
- Per-client group assignment (retained): `infoscreen/{uuid}/group_id` via `server/mqtt_helper.py`.
|
|
||||||
- Client logs: `infoscreen/{uuid}/logs/{error|warn|info}` with JSON payload (timestamp, message, context); QoS 1 for ERROR/WARN, QoS 0 for INFO.
|
|
||||||
- Client health: `infoscreen/{uuid}/health` with metrics (expected_state, actual_state, health_metrics); QoS 0, published every 5 seconds.
|
|
||||||
- Dashboard screenshots: `infoscreen/{uuid}/dashboard` uses grouped v2 payload blocks (`message`, `content`, `runtime`, `metadata`); listener reads screenshot data from `content.screenshot` and capture type from `metadata.capture.type`.
|
|
||||||
- Screenshots: server-side folder `server/screenshots/`; API serves `/screenshots/{uuid}.jpg` (latest) and `/screenshots/{uuid}/priority` (active high-priority fallback to latest).
|
|
||||||
|
|
||||||
- Dev Container guidance: If extensions reappear inside the container, remove UI-only extensions from `devcontainer.json` `extensions` and map them in `remote.extensionKind` as `"ui"`.
|
|
||||||
|
|
||||||
- Presentation conversion (PPT/PPTX/ODP → PDF):
|
|
||||||
- Trigger: on upload in `server/routes/eventmedia.py` for media types `ppt|pptx|odp` (compute sha256, upsert `Conversion`, enqueue job).
|
|
||||||
- Worker: RQ worker runs `server.worker.convert_event_media_to_pdf`, calls Gotenberg LibreOffice endpoint, writes to `server/media/converted/`.
|
|
||||||
- Services: Redis (queue) and Gotenberg added in compose; worker service consumes the `conversions` queue.
|
|
||||||
- Env: `REDIS_URL` (default `redis://redis:6379/0`), `GOTENBERG_URL` (default `http://gotenberg:3000`).
|
|
||||||
- Endpoints: `POST /api/conversions/<media_id>/pdf` (ensure/enqueue), `GET /api/conversions/<media_id>/status`, `GET /api/files/converted/<path>` (serve PDFs).
|
|
||||||
- Storage: originals under `server/media/…`, outputs under `server/media/converted/` (prod compose mounts a shared volume for this path).
|
|
||||||
|
|
||||||
## Data model highlights (see `models/models.py`)
|
|
||||||
- User model: Includes 7 new audit/security fields (migration: `4f0b8a3e5c20_add_user_audit_fields.py`):
|
|
||||||
- `last_login_at`, `last_password_change_at`: TIMESTAMP (UTC) tracking for auth events
|
|
||||||
- `failed_login_attempts`, `last_failed_login_at`: Security monitoring for brute-force detection
|
|
||||||
- `locked_until`: TIMESTAMP placeholder for account lockout (infrastructure in place, not yet enforced)
|
|
||||||
- `deactivated_at`, `deactivated_by`: Soft-delete audit trail (FK self-reference); soft deactivation is the default, hard delete superadmin-only
|
|
||||||
- Role hierarchy (privilege escalation enforced): `user` < `editor` < `admin` < `superadmin`
|
|
||||||
- Client monitoring (migration: `c1d2e3f4g5h6_add_client_monitoring.py`):
|
|
||||||
- `ClientLog` model: Centralized log storage with fields (id, client_uuid, timestamp, level, message, context, created_at); FK to clients.uuid (CASCADE)
|
|
||||||
- `Client` model extended: 7 health monitoring fields (`current_event_id`, `current_process`, `process_status`, `process_pid`, `last_screenshot_analyzed`, `screen_health_status`, `last_screenshot_hash`)
|
|
||||||
- Enums: `LogLevel` (ERROR, WARN, INFO, DEBUG), `ProcessStatus` (running, crashed, starting, stopped), `ScreenHealthStatus` (OK, BLACK, FROZEN, UNKNOWN)
|
|
||||||
- Indexes: (client_uuid, timestamp DESC), (level, timestamp DESC), (created_at DESC) for performance
|
|
||||||
- System settings: `system_settings` key–value store via `SystemSetting` for global configuration (e.g., WebUntis/Vertretungsplan supplement-table). Managed through routes in `server/routes/system_settings.py`.
|
|
||||||
- Presentation defaults (system-wide):
|
|
||||||
- `presentation_interval` (seconds, default "10")
|
|
||||||
- `presentation_page_progress` ("true"/"false", default "true")
|
|
||||||
- `presentation_auto_progress` ("true"/"false", default "true")
|
|
||||||
Seeded in `server/init_defaults.py` if missing.
|
|
||||||
- Video defaults (system-wide):
|
|
||||||
- `video_autoplay` ("true"/"false", default "true")
|
|
||||||
- `video_loop` ("true"/"false", default "true")
|
|
||||||
- `video_volume` (0.0–1.0, default "0.8")
|
|
||||||
- `video_muted` ("true"/"false", default "false")
|
|
||||||
Used as initial values when creating new video events; editable per event.
|
|
||||||
- Events: Added `page_progress` (Boolean) and `auto_progress` (Boolean) for presentation behavior per event.
|
|
||||||
- Event (video fields): `event_media_id`, `autoplay`, `loop`, `volume`, `muted`.
|
|
||||||
- WebUntis URL: WebUntis uses the existing Vertretungsplan/Supplement-Table URL (`supplement_table_url`). There is no separate `webuntis_url` setting; use `GET/POST /api/system-settings/supplement-table`.
|
|
||||||
|
|
||||||
- Conversions:
|
|
||||||
- Enum `ConversionStatus`: `pending`, `processing`, `ready`, `failed`.
|
|
||||||
- Table `conversions`: `id`, `source_event_media_id` (FK→`event_media.id` ondelete CASCADE), `target_format`, `target_path`, `status`, `file_hash` (sha256), `started_at`, `completed_at`, `error_message`.
|
|
||||||
- Indexes: `(source_event_media_id, target_format)`, `(status, target_format)`; Unique: `(source_event_media_id, target_format, file_hash)`.
|
|
||||||
|
|
||||||
## API patterns
|
|
||||||
- Blueprints live in `server/routes/*` and are registered in `server/wsgi.py` with `/api/...` prefixes.
|
|
||||||
- Session usage: instantiate `Session()` per request, commit when mutating, and always `session.close()` before returning.
|
|
||||||
- Examples:
|
|
||||||
- Clients: `server/routes/clients.py` includes bulk group updates and MQTT sync (`publish_multiple_client_groups`).
|
|
||||||
- Groups: `server/routes/groups.py` computes “alive” using a grace period that varies by `ENV`. - `GET /api/groups/order` — retrieve saved group display order
|
|
||||||
- `POST /api/groups/order` — persist group display order (array of group IDs) - Events: `server/routes/events.py` serializes enum values to strings and normalizes times to UTC. Recurring events are only deactivated after their recurrence_end (UNTIL); non-recurring events deactivate after their end time. Event exceptions are respected and rendered in scheduler output.
|
|
||||||
- Media: `server/routes/eventmedia.py` implements a simple file manager API rooted at `server/media/`.
|
|
||||||
- System settings: `server/routes/system_settings.py` exposes key–value CRUD (`/api/system-settings`) and a convenience endpoint for WebUntis/Vertretungsplan supplement-table: `GET/POST /api/system-settings/supplement-table` (admin+).
|
|
||||||
- Academic periods: `server/routes/academic_periods.py` exposes:
|
|
||||||
- `GET /api/academic_periods` — list all periods
|
|
||||||
- `GET /api/academic_periods/active` — currently active period
|
|
||||||
- `POST /api/academic_periods/active` — set active period (deactivates others)
|
|
||||||
- `GET /api/academic_periods/for_date?date=YYYY-MM-DD` — period covering given date
|
|
||||||
- User management: `server/routes/users.py` exposes comprehensive CRUD for users (admin+):
|
|
||||||
- `GET /api/users` — list all users (role-filtered: admin sees user/editor/admin, superadmin sees all); includes audit fields in camelCase (lastLoginAt, lastPasswordChangeAt, failedLoginAttempts, deactivatedAt, deactivatedBy)
|
|
||||||
- `POST /api/users` — create user with username, password (min 6 chars), role, and status; admin cannot create superadmin; initializes audit fields
|
|
||||||
- `GET /api/users/<id>` — get detailed user record with all audit fields
|
|
||||||
- `PUT /api/users/<id>` — update user (cannot change own role/status; admin cannot modify superadmin accounts)
|
|
||||||
- `PUT /api/users/<id>/password` — admin password reset (requires backend check to reject self-reset for consistency)
|
|
||||||
- `DELETE /api/users/<id>` — hard delete (superadmin only, with self-deletion check)
|
|
||||||
- Auth routes (`server/routes/auth.py`): Enhanced to track login events (sets `last_login_at`, resets `failed_login_attempts` on success; increments `failed_login_attempts` and `last_failed_login_at` on failure). Self-service password change via `PUT /api/auth/change-password` requires current password verification.
|
|
||||||
- Client logs (`server/routes/client_logs.py`): Centralized log retrieval for monitoring:
|
|
||||||
- `GET /api/client-logs/<uuid>/logs` – Query client logs with filters (level, limit, since); admin_or_higher
|
|
||||||
- `GET /api/client-logs/summary` – Log counts by level per client (last 24h); admin_or_higher
|
|
||||||
- `GET /api/client-logs/recent-errors` – System-wide error monitoring; admin_or_higher
|
|
||||||
- `GET /api/client-logs/monitoring-overview` – Includes screenshot priority fields per client plus `summary.activePriorityScreenshots`; superadmin_only
|
|
||||||
- `GET /api/client-logs/test` – Infrastructure validation (no auth); returns recent logs with counts
|
|
||||||
|
|
||||||
Documentation maintenance: keep this file aligned with real patterns; update when routes/session/UTC rules change. Avoid long prose; link exact paths.
|
|
||||||
|
|
||||||
## Frontend patterns (dashboard)
|
|
||||||
- Vite React app; proxies `/api` and `/screenshots` to API in dev (`vite.config.ts`).
|
|
||||||
- Uses Syncfusion components; Vite config pre-bundles specific packages to avoid alias issues.
|
|
||||||
- Environment: `VITE_API_URL` provided at build/run; in dev compose, proxy handles `/api` so local fetches can use relative `/api/...` paths.
|
|
||||||
- **API Response Format**: All API endpoints return camelCase JSON (e.g., `startTime`, `endTime`, `groupId`). Frontend consumes camelCase directly.
|
|
||||||
- **UTC Time Parsing**: API returns ISO strings without 'Z' suffix. Frontend appends 'Z' before parsing to ensure UTC interpretation: `const utcString = dateStr.endsWith('Z') ? dateStr : dateStr + 'Z'; new Date(utcString);`. Display uses `toLocaleTimeString('de-DE')` for German format.
|
|
||||||
|
|
||||||
- Dev Container: When adding frontend deps, prefer `npm ci` and, if using named volumes, recreate dashboard `node_modules` volume so installs occur inside the container.
|
|
||||||
- Theming: Syncfusion Material 3 theme is used. All component CSS is imported centrally in `dashboard/src/main.tsx` (base, navigations, buttons, inputs, dropdowns, popups, kanban, grids, schedule, filemanager, notifications, layouts, lists, calendars, splitbuttons, icons). Tailwind CSS has been removed.
|
|
||||||
- Scheduler (appointments page): top bar includes Group and Academic Period selectors (Syncfusion DropDownList). Selecting a period calls `POST /api/academic_periods/active`, moves the calendar to today’s month/day within the period year, and refreshes a right-aligned indicator row showing:
|
|
||||||
- Holidays present in the current view (count)
|
|
||||||
- Period label (display_name or name) with a badge indicating whether any holidays exist in that period (overlap check)
|
|
||||||
|
|
||||||
- Recurrence & holidays (latest):
|
|
||||||
- Backend stores holiday skips in `EventException` and emits `RecurrenceException` (EXDATE) for master events in `GET /api/events`. EXDATE tokens are formatted in RFC 5545 compact form (`yyyyMMddTHHmmssZ`) and correspond to each occurrence start time (UTC). Syncfusion uses these to exclude holiday instances reliably.
|
|
||||||
- Frontend lets Syncfusion handle all recurrence patterns natively (no client-side expansion). Scheduler field mappings include `recurrenceID`, `recurrenceRule`, and `recurrenceException` so series and edited occurrences are recognized correctly.
|
|
||||||
- Event deletion: All event types (single, single-in-series, entire series) are handled with custom dialogs. The frontend intercepts Syncfusion's built-in RecurrenceAlert and DeleteAlert popups to provide a unified, user-friendly deletion flow:
|
|
||||||
- Single (non-recurring) event: deleted directly after confirmation.
|
|
||||||
- Single occurrence of a recurring series: user can delete just that instance.
|
|
||||||
- Entire recurring series: user can delete all occurrences after a final custom confirmation dialog.
|
|
||||||
- Detached occurrences (edited/broken out): treated as single events.
|
|
||||||
- Single occurrence editing: Users can detach individual occurrences from recurring series. The frontend hooks `actionComplete`/`onActionCompleted` with `requestType='eventChanged'` to persist changes: it calls `POST /api/events/<id>/occurrences/<date>/detach` for single-occurrence edits and `PUT /api/events/<id>` for series or single events as appropriate. The backend creates `EventException` and a standalone `Event` without modifying the master beyond EXDATEs.
|
|
||||||
- UI: Events with `SkipHolidays` render a TentTree icon next to the main event icon. The custom recurrence icon in the header was removed; rely on Syncfusion’s native lower-right recurrence badge.
|
|
||||||
- Website & WebUntis: Both event types display a website. WebUntis reads its URL from the system `supplement_table_url` and does not provide a per-event URL field.
|
|
||||||
|
|
||||||
- Program info page (`dashboard/src/programminfo.tsx`):
|
|
||||||
- Loads data from `dashboard/public/program-info.json` (app name, version, build info, tech stack, changelog).
|
|
||||||
- Uses Syncfusion card classes (`e-card`, `e-card-header`, `e-card-title`, `e-card-content`) for consistent styling.
|
|
||||||
- Changelog is paginated with `PagerComponent` (from `@syncfusion/ej2-react-grids`), default page size 5; adjust `pageSize` or add a selector as needed.
|
|
||||||
|
|
||||||
- Groups page (`dashboard/src/infoscreen_groups.tsx`):
|
|
||||||
- Migrated to Syncfusion inputs and popups: Buttons, TextBox, DropDownList, Dialog; Kanban remains for drag/drop.
|
|
||||||
- Unified toast/dialog wording; replaced legacy alerts with toasts; spacing handled via inline styles to avoid Tailwind dependency.
|
|
||||||
|
|
||||||
- Header user menu (top-right):
|
|
||||||
- Shows current username and role; click opens a menu with "Passwort ändern" (lock icon), "Profil", and "Abmelden".
|
|
||||||
- Implemented with Syncfusion DropDownButton (`@syncfusion/ej2-react-splitbuttons`).
|
|
||||||
- "Passwort ändern": Opens self-service password change dialog (available to all authenticated users); requires current password verification, new password min 6 chars, must match confirm field; calls `PUT /api/auth/change-password`
|
|
||||||
- "Abmelden" navigates to `/logout`; the page invokes backend logout and redirects to `/login`.
|
|
||||||
|
|
||||||
- User management page (`dashboard/src/users.tsx`):
|
|
||||||
- Full CRUD interface for managing users (admin+ only in menu); accessible via "Benutzer" sidebar entry
|
|
||||||
- Syncfusion GridComponent: 20 per page (configurable), sortable columns (ID, username, role), custom action button template with role-based visibility
|
|
||||||
- Statistics cards: total users, active (non-deactivated), inactive (deactivated) counts
|
|
||||||
- Dialogs: Create (username/password/role/status), Edit (with self-edit protections), Password Reset (admin only, no current password required), Delete (superadmin only, self-check), Details (read-only audit info with formatted timestamps)
|
|
||||||
- Role badges: Color-coded display (user: gray, editor: blue, admin: green, superadmin: red)
|
|
||||||
- Audit information displayed: last login, password change, last failed login, deactivation timestamps and deactivating user
|
|
||||||
- Role-based permissions (enforced backend + frontend):
|
|
||||||
- Admin: can manage user/editor/admin roles (not superadmin); soft-deactivate only; cannot see/edit superadmin accounts
|
|
||||||
- Superadmin: can manage all roles including other superadmins; can permanently hard-delete users
|
|
||||||
- Security rules enforced: cannot change own role, cannot deactivate own account, cannot delete self, cannot reset own password via admin route (must use self-service)
|
|
||||||
- API client in `dashboard/src/apiUsers.ts` for all user operations (listUsers, getUser, createUser, updateUser, resetUserPassword, deleteUser)
|
|
||||||
- Menu visibility: "Benutzer" menu item only visible to admin+ (role-gated in App.tsx)
|
|
||||||
|
|
||||||
- Monitoring page (`dashboard/src/monitoring.tsx`):
|
|
||||||
- Superadmin-only dashboard for client monitoring and diagnostics; menu item is hidden for lower roles and the route redirects non-superadmins.
|
|
||||||
- Uses `GET /api/client-logs/monitoring-overview` for aggregated live status, `GET /api/client-logs/recent-errors` for system-wide errors, and `GET /api/client-logs/<uuid>/logs` for per-client details.
|
|
||||||
- Shows per-client status (`healthy`, `warning`, `critical`, `offline`) based on heartbeat freshness, process state, screen state, and recent log counts.
|
|
||||||
- Displays latest screenshot preview and active priority screenshot (`/screenshots/{uuid}/priority` when active), screenshot type badges, current process metadata, and recent ERROR/WARN activity.
|
|
||||||
- Uses adaptive refresh: normal interval in steady state, faster polling while `activePriorityScreenshots > 0`.
|
|
||||||
|
|
||||||
- Settings page (`dashboard/src/settings.tsx`):
|
|
||||||
- Structure: Syncfusion TabComponent with role-gated tabs
|
|
||||||
- 📅 Academic Calendar (all users)
|
|
||||||
- 📥 Import & Liste: CSV/TXT import and list combined
|
|
||||||
- 🗂️ Perioden: select and set active period (uses `/api/academic_periods` routes)
|
|
||||||
- 🖥️ Display & Clients (admin+)
|
|
||||||
- Default Settings: placeholders for heartbeat, screenshots, defaults
|
|
||||||
- Client Configuration: quick links to Clients and Groups pages
|
|
||||||
- 🎬 Media & Files (admin+)
|
|
||||||
- Upload Settings: placeholders for limits and types
|
|
||||||
- Conversion Status: placeholder for conversions overview
|
|
||||||
- 🗓️ Events (admin+)
|
|
||||||
- WebUntis / Vertretungsplan: system-wide supplement table URL with enable/disable, save, and preview; persists via `/api/system-settings/supplement-table`
|
|
||||||
- Presentations: general defaults for slideshow interval, page-progress, and auto-progress; persisted via `/api/system-settings` keys (`presentation_interval`, `presentation_page_progress`, `presentation_auto_progress`). These defaults are applied when creating new presentation events (the custom event modal reads them and falls back to per-event values when editing).
|
|
||||||
- Videos: system-wide defaults for `autoplay`, `loop`, `volume`, and `muted`; persisted via `/api/system-settings` keys (`video_autoplay`, `video_loop`, `video_volume`, `video_muted`). These defaults are applied when creating new video events (the custom event modal reads them and falls back to per-event values when editing).
|
|
||||||
- Other event types (website, message, other): placeholders for defaults
|
|
||||||
- ⚙️ System (superadmin)
|
|
||||||
- Organization Info and Advanced Configuration placeholders
|
|
||||||
- Role gating: Admin/Superadmin tabs are hidden if the user lacks permission; System is superadmin-only
|
|
||||||
- API clients use relative `/api/...` URLs so Vite dev proxy handles requests without CORS issues. The settings UI calls are centralized in `dashboard/src/apiSystemSettings.ts`.
|
|
||||||
- Nested tabs: implemented as controlled components using `selectedItem` with stateful handlers to prevent sub-tab resets during updates.
|
|
||||||
|
|
||||||
- Dashboard page (`dashboard/src/dashboard.tsx`):
|
|
||||||
- Card-based overview of all Raumgruppen (room groups) with real-time status monitoring
|
|
||||||
- Global statistics: total infoscreens, online/offline counts, warning groups
|
|
||||||
- Filter buttons: All / Online / Offline / Warnings with dynamic counts
|
|
||||||
- Per-group cards show:
|
|
||||||
- Currently active event (title, type, date/time in local timezone)
|
|
||||||
- Health bar with online/offline ratio and color-coded status
|
|
||||||
- Expandable client list with last alive timestamps
|
|
||||||
- Bulk restart button for offline clients
|
|
||||||
- Uses Syncfusion ButtonComponent, ToastComponent, and card CSS classes
|
|
||||||
- Auto-refresh every 15 seconds; manual refresh button available
|
|
||||||
- "Nicht zugeordnet" group always appears last in sorted list
|
|
||||||
|
|
||||||
- Ressourcen page (`dashboard/src/ressourcen.tsx`):
|
|
||||||
- Timeline view showing all groups and their active events in parallel
|
|
||||||
- Uses Syncfusion ScheduleComponent with TimelineViews (day/week modes)
|
|
||||||
- Compact row display: 65px height per group, dynamically calculated total height
|
|
||||||
- Group ordering panel with drag up/down controls; order persisted to backend via `/api/groups/order`
|
|
||||||
- Filters out "Nicht zugeordnet" group from timeline display
|
|
||||||
- Fetches events per group for current date range; displays first active event per group
|
|
||||||
- Color-coded event bars using `getGroupColor()` from `groupColors.ts`
|
|
||||||
- Resource-based timeline: each group is a resource row, events mapped to `ResourceId`
|
|
||||||
- Real-time updates: loads events on mount and when view/date changes
|
|
||||||
- Custom CSS in `dashboard/src/ressourcen.css` for timeline styling and controls
|
|
||||||
|
|
||||||
- User dropdown technical notes:
|
|
||||||
- Dependencies: `@syncfusion/ej2-react-splitbuttons` and `@syncfusion/ej2-splitbuttons` must be installed.
|
|
||||||
- Vite: add both to `optimizeDeps.include` in `vite.config.ts` to avoid import-analysis errors.
|
|
||||||
- Dev containers: when `node_modules` is a named volume, recreate the dashboard node_modules volume after adding dependencies so `npm ci` runs inside the container.
|
|
||||||
|
|
||||||
Note: Syncfusion usage in the dashboard is already documented above; if a UI for conversion status/downloads is added later, link its routes and components here.
|
|
||||||
|
|
||||||
## Local development
|
|
||||||
- Compose: development is `docker-compose.yml` + `docker-compose.override.yml`.
|
|
||||||
- API (dev): `server/Dockerfile.dev` with debugpy on 5678, Flask app `wsgi:app` on :8000.
|
|
||||||
- Dashboard (dev): `dashboard/Dockerfile.dev` exposes :5173 and waits for API via `dashboard/wait-for-backend.sh`.
|
|
||||||
- Mosquitto: allows anonymous in dev; WebSocket on :9001.
|
|
||||||
- Common env vars: `DB_CONN`, `DB_USER`, `DB_PASSWORD`, `DB_HOST=db`, `DB_NAME`, `ENV`, `MQTT_USER`, `MQTT_PASSWORD`.
|
|
||||||
- Alembic: prod compose runs `alembic ... upgrade head` and `server/init_defaults.py` before gunicorn.
|
|
||||||
- Local dev: prefer `python server/initialize_database.py` for one-shot setup (migrations + defaults + academic periods).
|
|
||||||
- Defaults: `server/init_defaults.py` seeds initial system settings like `supplement_table_url` and `supplement_table_enabled` if missing.
|
|
||||||
- `server/init_academic_periods.py` remains available to (re)seed school years.
|
|
||||||
|
|
||||||
## Production
|
|
||||||
- `docker-compose.prod.yml` uses prebuilt images (`ghcr.io/robbstarkaustria/*`).
|
|
||||||
- Nginx serves dashboard and proxies API; TLS certs expected in `certs/` and mounted to `/etc/nginx/certs`.
|
|
||||||
|
|
||||||
## Environment variables (reference)
|
|
||||||
- DB_CONN — Preferred DB URL for services. Example: `mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}`
|
|
||||||
- DB_USER, DB_PASSWORD, DB_NAME, DB_HOST — Used to assemble DB_CONN in dev if missing; inside containers `DB_HOST=db`.
|
|
||||||
- ENV — `development` or `production`; in development, `server/database.py` loads `.env`.
|
|
||||||
- MQTT_BROKER_HOST, MQTT_BROKER_PORT — Defaults `mqtt` and `1883`; MQTT_USER/MQTT_PASSWORD optional (dev often anonymous per Mosquitto config).
|
|
||||||
- VITE_API_URL — Dashboard build-time base URL (prod); in dev the Vite proxy serves `/api` to `server:8000`.
|
|
||||||
- HEARTBEAT_GRACE_PERIOD_DEV / HEARTBEAT_GRACE_PERIOD_PROD — Groups "alive" window (defaults 180s dev / 170s prod). Clients send heartbeats every ~65s; grace periods allow 2 missed heartbeats plus safety margin.
|
|
||||||
- REFRESH_SECONDS — Optional scheduler republish interval; `0` disables periodic refresh.
|
|
||||||
- PRIORITY_SCREENSHOT_TTL_SECONDS — Optional monitoring priority window in seconds (default `120`); controls when event screenshots are considered active priority.
|
|
||||||
|
|
||||||
## Conventions & gotchas
|
|
||||||
- **Datetime Handling**:
|
|
||||||
- Always compare datetimes in UTC; some DB values may be naive—normalize before comparing (see `routes/events.py`).
|
|
||||||
- Database stores timestamps in UTC (naive datetimes are normalized to UTC by backend)
|
|
||||||
- API returns ISO strings **without** 'Z' suffix: `"2025-11-27T20:03:00"`
|
|
||||||
- Frontend **must** append 'Z' before parsing: `const utcStr = dateStr.endsWith('Z') ? dateStr : dateStr + 'Z'; new Date(utcStr);`
|
|
||||||
- Display in local timezone using `toLocaleTimeString('de-DE', { hour: '2-digit', minute: '2-digit' })`
|
|
||||||
- When sending to API, use `date.toISOString()` which includes 'Z' and is UTC
|
|
||||||
- **JSON Naming Convention**:
|
|
||||||
- Backend uses snake_case internally (Python convention)
|
|
||||||
- API returns camelCase JSON (web standard): `startTime`, `endTime`, `groupId`, etc.
|
|
||||||
- Use `dict_to_camel_case()` from `server/serializers.py` before `jsonify()`
|
|
||||||
- Frontend consumes camelCase directly; Syncfusion scheduler maintains internal PascalCase with field mappings
|
|
||||||
- Scheduler enforces UTC comparisons and normalizes naive timestamps. It publishes only currently active events and clears retained topics for groups with no active events. It also queries a future window (default: 7 days) and expands recurring events using RFC 5545 rules. Event exceptions are respected. Logging is concise and conversion lookups are cached.
|
|
||||||
- Use retained MQTT messages for state that clients must recover after reconnect (events per group, client group_id).
|
|
||||||
- Clients should parse `event_type` and then read the corresponding nested payload (`presentation`, `website`, `video`, etc.). `website` and `webuntis` use the same nested `website` payload with `type: browser` and a `url`. Video events include `autoplay`, `loop`, `volume`, and `muted`.
|
|
||||||
- In-container DB host is `db`; do not use `localhost` inside services.
|
|
||||||
- No separate dev vs prod secret conventions: use the same env var keys across environments (e.g., `DB_CONN`, `MQTT_USER`, `MQTT_PASSWORD`).
|
|
||||||
- When adding a new route:
|
|
||||||
1) Create a Blueprint in `server/routes/...`,
|
|
||||||
2) Register it in `server/wsgi.py`,
|
|
||||||
3) Manage `Session()` lifecycle,
|
|
||||||
4) Return JSON-safe values (serialize enums and datetimes), and
|
|
||||||
5) Use `dict_to_camel_case()` for camelCase JSON responses
|
|
||||||
|
|
||||||
Docs maintenance guardrails (solo-friendly): Update this file alongside code changes (services/MQTT/API/UTC/env). Keep it concise (20–50 lines per section). Never include secrets.
|
|
||||||
- When extending media types, update `MediaType` and any logic in `eventmedia` and dashboard that depends on it.
|
|
||||||
- Academic periods: Events/media can be optionally associated with periods for educational organization. Only one period should be active at a time (`is_active=True`).
|
|
||||||
- Initialization scripts: legacy DB init scripts were removed; use Alembic and `initialize_database.py` going forward.
|
|
||||||
|
|
||||||
### Recurrence & holidays: conventions
|
|
||||||
- Do not pre-expand recurrences on the backend. Always send master events with `RecurrenceRule` + `RecurrenceException`.
|
|
||||||
- Ensure EXDATE tokens are RFC 5545 timestamps (`yyyyMMddTHHmmssZ`) matching the occurrence start time (UTC) so Syncfusion can exclude them natively.
|
|
||||||
- When `skip_holidays` or recurrence changes, regenerate `EventException` rows so `RecurrenceException` stays in sync.
|
|
||||||
- Single occurrence detach: Use `POST /api/events/<id>/occurrences/<date>/detach` to create standalone events and add EXDATE entries without modifying master events. The frontend persists edits via `actionComplete` (`requestType='eventChanged'`).
|
|
||||||
|
|
||||||
## Quick examples
|
|
||||||
- Add client description persists to DB and publishes group via MQTT: see `PUT /api/clients/<uuid>/description` in `routes/clients.py`.
|
|
||||||
- Bulk group assignment emits retained messages for each client: `PUT /api/clients/group`.
|
|
||||||
- Listener heartbeat path: `infoscreen/<uuid>/heartbeat` → sets `clients.last_alive` and captures process health data.
|
|
||||||
- Client monitoring flow: Client publishes to `infoscreen/{uuid}/logs/error` and `infoscreen/{uuid}/health` → listener stores/updates monitoring state → API serves `/api/client-logs/monitoring-overview`, `/api/client-logs/recent-errors`, and `/api/client-logs/<uuid>/logs` → superadmin monitoring dashboard displays live status.
|
|
||||||
|
|
||||||
## Scheduler payloads: presentation extras
|
|
||||||
- Presentation event payloads now include `page_progress` and `auto_progress` in addition to `slide_interval` and media files. These are sourced from per-event fields in the database (with system defaults applied on event creation).
|
|
||||||
|
|
||||||
## Scheduler payloads: website & webuntis
|
|
||||||
- For both `website` and `webuntis`, the scheduler emits a nested `website` object:
|
|
||||||
- `{ "type": "browser", "url": "https://..." }`
|
|
||||||
- The `event_type` remains `website` or `webuntis`. Clients should treat both identically for rendering.
|
|
||||||
- The WebUntis URL is set at event creation by reading the system `supplement_table_url`.
|
|
||||||
|
|
||||||
Questions or unclear areas? Tell us if you need: exact devcontainer debugging steps, stricter Alembic workflow, or a seed dataset beyond `init_defaults.py`.
|
|
||||||
|
|
||||||
## Academic Periods System
|
|
||||||
- **Purpose**: Organize events and media by educational cycles (school years, semesters, trimesters).
|
|
||||||
- **Design**: Fully backward compatible - existing events/media continue to work without period assignment.
|
|
||||||
- **Usage**: New events/media can optionally reference `academic_period_id` for better organization and filtering.
|
|
||||||
- **Constraints**: Only one period can be active at a time; use `init_academic_periods.py` for Austrian school year setup.
|
|
||||||
- **UI Integration**: The dashboard highlights the currently selected period and whether a holiday plan exists within that date range. Holiday linkage currently uses date overlap with `school_holidays`; an explicit `academic_period_id` on `school_holidays` can be added later if tighter association is required.
|
|
||||||
|
|
||||||
## Changelog Style Guide (Program info)
|
|
||||||
|
|
||||||
- Source: `dashboard/public/program-info.json`; newest entry first
|
|
||||||
- Fields per release: `version`, `date` (YYYY-MM-DD), `changes` (array of short bullets)
|
|
||||||
- Tone: concise, user-facing; German wording; area prefixes allowed (e.g., “UI: …”, “API: …”)
|
|
||||||
- Categories via emoji or words: Added (🆕/✨), Changed (🛠️), Fixed (✅/🐛), Removed (🗑️), Security (🔒), Deprecated (⚠️)
|
|
||||||
- Breaking changes must be prefixed with `BREAKING:`
|
|
||||||
- Keep ≤ 8–10 bullets; summarize or group micro-changes
|
|
||||||
- JSON hygiene: valid JSON, no trailing commas, don’t edit historical entries except typos
|
|
||||||
|
|
||||||
## Versioning Convention (Tech vs UI)
|
|
||||||
|
|
||||||
- Use one unified app version across technical and user-facing release notes.
|
|
||||||
- `dashboard/public/program-info.json` is user-facing and should list only user-visible changes.
|
|
||||||
- `TECH-CHANGELOG.md` can include deeper technical details for the same released version.
|
|
||||||
- If server/infrastructure work is implemented but not yet released or not user-visible, document it under the latest released section as:
|
|
||||||
- `Backend technical work (post-release notes; no version bump)`
|
|
||||||
- Do not create a new version header in `TECH-CHANGELOG.md` for internal milestones alone.
|
|
||||||
- Bump version numbers when a release is actually cut/deployed (or when user-facing release notes are published), not for intermediate backend-only steps.
|
|
||||||
- When UI integration lands later, include the user-visible part in the next release version and reference prior post-release technical groundwork when useful.
|
|
||||||
|
|||||||
@@ -12,6 +12,7 @@ Update the instructions in the same commit as your change whenever you:
|
|||||||
- Change DB models or time/UTC handling (e.g., `models/models.py`, UTC normalization in routes/scheduler)
|
- Change DB models or time/UTC handling (e.g., `models/models.py`, UTC normalization in routes/scheduler)
|
||||||
- Add/modify API route patterns or session lifecycle (files in `server/routes/*`, `server/wsgi.py`)
|
- Add/modify API route patterns or session lifecycle (files in `server/routes/*`, `server/wsgi.py`)
|
||||||
- Adjust frontend dev proxy or build settings (`dashboard/vite.config.ts`, Dockerfiles)
|
- Adjust frontend dev proxy or build settings (`dashboard/vite.config.ts`, Dockerfiles)
|
||||||
|
- Modify scheduler polling, power-intent semantics, or retention strategy
|
||||||
|
|
||||||
## What to update (and where)
|
## What to update (and where)
|
||||||
- `.github/copilot-instructions.md`
|
- `.github/copilot-instructions.md`
|
||||||
@@ -35,6 +36,27 @@ Update the instructions in the same commit as your change whenever you:
|
|||||||
- Include concrete examples from this repo when describing patterns (e.g., which route shows enum serialization).
|
- Include concrete examples from this repo when describing patterns (e.g., which route shows enum serialization).
|
||||||
- Never include secrets or real tokens; show only variable names and example formats.
|
- Never include secrets or real tokens; show only variable names and example formats.
|
||||||
|
|
||||||
|
## Scope boundaries (important)
|
||||||
|
To avoid turning `.github/copilot-instructions.md` into a shadow README/changelog, keep clear boundaries:
|
||||||
|
- `.github/copilot-instructions.md`: quick operational brief for agents (architecture snapshot, non-negotiable conventions, key paths, critical contracts).
|
||||||
|
- `README.md`: project entrypoint and documentation navigation.
|
||||||
|
- `TECH-CHANGELOG.md` and `DEV-CHANGELOG.md`: change history and release/development notes.
|
||||||
|
- Feature contracts/specs: dedicated files (for example `MQTT_EVENT_PAYLOAD_GUIDE.md`, `TV_POWER_INTENT_SERVER_CONTRACT_V1.md`).
|
||||||
|
|
||||||
|
Do not place long historical sections, release summaries, or full endpoint catalogs in `.github/copilot-instructions.md`.
|
||||||
|
|
||||||
|
## Size and quality guardrails
|
||||||
|
- Target size for `.github/copilot-instructions.md`: about 120-220 lines.
|
||||||
|
- If a new section exceeds ~10 lines, prefer linking to an existing canonical doc instead.
|
||||||
|
- Keep each section focused on actionability for coding agents.
|
||||||
|
- Remove duplicate rules if already stated in another section.
|
||||||
|
- Use concise bullets over long prose blocks.
|
||||||
|
|
||||||
|
Quick pre-commit check:
|
||||||
|
- Is this content a rule/pattern needed during coding now?
|
||||||
|
- If it is historical context, move it to changelog/archive docs.
|
||||||
|
- If it is deep reference material, move it to the canonical feature doc and link it.
|
||||||
|
|
||||||
## Solo-friendly workflow
|
## Solo-friendly workflow
|
||||||
- Update docs in the same commit as your change:
|
- Update docs in the same commit as your change:
|
||||||
- Code changed → docs changed (copilot-instructions, `.env.example`, `deployment.md` as needed)
|
- Code changed → docs changed (copilot-instructions, `.env.example`, `deployment.md` as needed)
|
||||||
@@ -100,4 +122,5 @@ exit 0 # warn only; do not block commit
|
|||||||
- Dev/Prod docs: `deployment.md`, `.env.example`
|
- Dev/Prod docs: `deployment.md`, `.env.example`
|
||||||
|
|
||||||
## Documentation sync log
|
## Documentation sync log
|
||||||
- 2026-03-24: Synced docs for completed monitoring rollout and presentation flag persistence fix (`page_progress` / `auto_progress`). Updated `.github/copilot-instructions.md`, `README.md`, `TECH-CHANGELOG.md`, `DEV-CHANGELOG.md`, and `CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` without a user-version bump.
|
- 2026-03-24: Synced docs for completed monitoring rollout and presentation flag persistence fix (`page_progress` / `auto_progress`). Updated `.github/copilot-instructions.md`, `README.md`, `TECH-CHANGELOG.md`, `DEV-CHANGELOG.md`, and `docs/archive/CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` without a user-version bump.
|
||||||
|
- 2026-04-01: Synced docs for TV power intent Phase 1 implementation and contract consistency. Updated `.github/copilot-instructions.md`, `MQTT_EVENT_PAYLOAD_GUIDE.md`, `docs/archive/TV_POWER_PHASE_1_SERVER_HANDOFF.md`, `TECH-CHANGELOG.md`, and `DEV-CHANGELOG.md` to match scheduler behavior (`infoscreen/groups/{group_id}/power/intent`, `schema_version: "1.0"`, transition + heartbeat semantics, poll-based expiry).
|
||||||
|
|||||||
@@ -891,7 +891,7 @@ Reset: After 5 minutes of successful operation
|
|||||||
- Base URL: `http://192.168.43.201:8000`
|
- Base URL: `http://192.168.43.201:8000`
|
||||||
- Health check: `GET /health`
|
- Health check: `GET /health`
|
||||||
- Test logs: `GET /api/client-logs/test` (no auth)
|
- Test logs: `GET /api/client-logs/test` (no auth)
|
||||||
- Full API docs: See `CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` on server
|
- Full API docs: See `docs/archive/CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` on server
|
||||||
|
|
||||||
**MQTT Broker:**
|
**MQTT Broker:**
|
||||||
- Host: `192.168.43.201`
|
- Host: `192.168.43.201`
|
||||||
@@ -974,6 +974,6 @@ watchdog.monitor_loop()
|
|||||||
**END OF SPECIFICATION**
|
**END OF SPECIFICATION**
|
||||||
|
|
||||||
Questions? Refer to:
|
Questions? Refer to:
|
||||||
- `CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` (server repo)
|
- `docs/archive/CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` (server repo)
|
||||||
- Server API: `http://192.168.43.201:8000/api/client-logs/test`
|
- Server API: `http://192.168.43.201:8000/api/client-logs/test`
|
||||||
- MQTT test: `mosquitto_sub -h 192.168.43.201 -t infoscreen/#`
|
- MQTT test: `mosquitto_sub -h 192.168.43.201 -t infoscreen/#`
|
||||||
|
|||||||
@@ -5,6 +5,37 @@ This changelog tracks all changes made in the development workspace, including i
|
|||||||
---
|
---
|
||||||
|
|
||||||
## Unreleased (development workspace)
|
## Unreleased (development workspace)
|
||||||
|
- Crash detection API: Added `GET /api/clients/crashed` returning clients with `process_status=crashed` or stale heartbeat; includes `crash_reason` field (`process_crashed` | `heartbeat_stale`).
|
||||||
|
- Crash auto-recovery (scheduler): Feature-flagged loop (`CRASH_RECOVERY_ENABLED`) scans crash candidates, issues `reboot_host` command, publishes to primary + compat MQTT topics; lockout window and expiry configurable via env.
|
||||||
|
- Command expiry sweep (scheduler): Unconditional per-cycle sweep in `sweep_expired_commands()` marks non-terminal `ClientCommand` rows past `expires_at` as `expired`.
|
||||||
|
- `restart_app` action registered in `server/routes/clients.py` API action map; sends same command lifecycle as `reboot_host`; safety lockout covers both actions.
|
||||||
|
- `service_failed` listener: subscribes to `infoscreen/+/service_failed` on every connect; persists `service_failed_at` + `service_failed_unit` to `Client`; empty payload (retain clear) silently ignored.
|
||||||
|
- Broker connection health: Listener health handler now extracts `broker_connection.reconnect_count` + `broker_connection.last_disconnect_at` and persists to `Client`.
|
||||||
|
- DB migration `b1c2d3e4f5a6`: adds `service_failed_at`, `service_failed_unit`, `mqtt_reconnect_count`, `mqtt_last_disconnect_at` to `clients` table.
|
||||||
|
- Model update: `models/models.py` Client class updated with all four new columns.
|
||||||
|
- `GET /api/clients/service_failed`: lists clients with `service_failed_at` set, admin-or-higher gated.
|
||||||
|
- `POST /api/clients/<uuid>/clear_service_failed`: clears DB flag and publishes empty retained MQTT to `infoscreen/{uuid}/service_failed`.
|
||||||
|
- Monitoring overview includes `mqtt_reconnect_count` + `mqtt_last_disconnect_at` per client.
|
||||||
|
- Frontend monitoring: orange service-failed alert panel (hidden when count=0), auto-refresh 15s, per-row Quittieren action.
|
||||||
|
- Frontend monitoring: client detail now shows MQTT reconnect count + last disconnect timestamp.
|
||||||
|
- Frontend types: `ServiceFailedClient`, `ServiceFailedClientsResponse`; helpers `fetchServiceFailedClients()`, `clearServiceFailed()` added to `dashboard/src/apiClients.ts`.
|
||||||
|
- `MQTT_EVENT_PAYLOAD_GUIDE.md`: added `service_failed` topic contract.
|
||||||
|
- MQTT auth hardening: Listener and scheduler now connect to broker with env-configured credentials (`MQTT_BROKER_HOST`, `MQTT_BROKER_PORT`, `MQTT_USER`, `MQTT_PASSWORD`) instead of anonymous fixed host/port defaults; optional TLS env toggles added in code path (`MQTT_TLS_*`).
|
||||||
|
- Broker auth enforcement: `mosquitto/config/mosquitto.conf` now disables anonymous access and enables password-file authentication. `docker-compose.yml` MQTT service now bootstraps/update password entries from env (`MQTT_USER`/`MQTT_PASSWORD`, optional canary user) before starting broker.
|
||||||
|
- Compose wiring: Added MQTT credential env propagation for listener/scheduler in both base and dev override compose files and switched MQTT healthcheck publish to authenticated mode.
|
||||||
|
- Backend implementation: Introduced client command lifecycle foundation for remote control in `server/routes/clients.py` with command persistence (`ClientCommand`), schema-based MQTT publish to `infoscreen/{uuid}/commands` (QoS1, non-retained), new endpoints `POST /api/clients/<uuid>/shutdown` and `GET /api/clients/commands/<command_id>`, and restart safety lockout (`blocked_safety` after 3 restarts in 15 minutes). Added migration `server/alembic/versions/aa12bb34cc56_add_client_commands_table.py` and model updates in `models/models.py`. Restart path keeps transitional legacy MQTT publish to `clients/{uuid}/restart` for compatibility.
|
||||||
|
- Listener integration: `listener/listener.py` now subscribes to `infoscreen/+/commands/ack` and updates command lifecycle states from client ACK payloads (`accepted`, `execution_started`, `completed`, `failed`).
|
||||||
|
- Frontend API client prep: Extended `dashboard/src/apiClients.ts` with `ClientCommand` typing and helper calls for lifecycle consumption (`shutdownClient`, `fetchClientCommandStatus`), and updated `restartClient` to accept optional reason payload.
|
||||||
|
- Contract freeze clarification: implementation-plan docs now explicitly freeze canonical MQTT topics (`infoscreen/{uuid}/commands`, `infoscreen/{uuid}/commands/ack`) and JSON schemas with examples; added transitional singular-topic compatibility aliases (`infoscreen/{uuid}/command`, `infoscreen/{uuid}/command/ack`) in server publish and listener ingest.
|
||||||
|
- Action value canonicalization: command payload actions are now frozen as host-level values (`reboot_host`, `shutdown_host`). API endpoint mapping is explicit (`/restart` -> `reboot_host`, `/shutdown` -> `shutdown_host`), and docs/examples were updated to remove `restart` payload ambiguity.
|
||||||
|
- Client helper snippets: Added frozen payload validation artifacts `implementation-plans/reboot-command-payload-schemas.md` and `implementation-plans/reboot-command-payload-schemas.json` (copy-ready snippets plus machine-validated JSON Schema).
|
||||||
|
- Documentation alignment: Added active reboot implementation handoff docs under `implementation-plans/` and linked them in `README.md` for immediate cross-team access (`reboot-implementation-handoff-share.md`, `reboot-implementation-handoff-client-team.md`, `reboot-kickoff-summary.md`).
|
||||||
|
- Programminfo GUI regression/fix: `dashboard/public/program-info.json` could not be loaded in Programminfo menu due to invalid JSON in the new alpha.16 changelog line (malformed quote in a text entry). Fixed JSON entry and verified file parses correctly again.
|
||||||
|
- Dashboard holiday banner fix: `dashboard/src/dashboard.tsx` — `loadHolidayStatus` now uses a stable `useCallback` with empty deps, preventing repeated re-creation on render. `useEffect` depends only on the stable callback reference.
|
||||||
|
- Dashboard Syncfusion stale-render fix: `MessageComponent` in the holiday banner now receives `key={`${severity}:${text}`}` to force remount when severity or text changes; without this Syncfusion cached stale DOM and the banner did not update reactively.
|
||||||
|
- Dashboard German text: Replaced transliterated forms (ae/oe/ue) with correct Umlauts throughout visible dashboard UI strings — `Präsentation`, `für`, `prüfen`, `Ferienüberschneidungen`, `verfügbar`, `Vorfälle`, `Ausfälle`.
|
||||||
|
- TV power intent (Phase 1): Scheduler publishes retained QoS1 group-level intents to `infoscreen/groups/{group_id}/power/intent` with transition+heartbeat semantics, startup/reconnect republish, and poll-based expiry (`max(3 × poll_interval_sec, 90s)`).
|
||||||
|
- TV power validation: Added unit/integration/canary coverage in `scheduler/test_power_intent_utils.py`, `scheduler/test_power_intent_scheduler.py`, and `test_power_intent_canary.py`.
|
||||||
- Monitoring system completion: End-to-end monitoring pipeline is active (MQTT logs/health → listener persistence → monitoring APIs → superadmin dashboard).
|
- Monitoring system completion: End-to-end monitoring pipeline is active (MQTT logs/health → listener persistence → monitoring APIs → superadmin dashboard).
|
||||||
- Monitoring API: Added/active endpoints `GET /api/client-logs/monitoring-overview` and `GET /api/client-logs/recent-errors`; per-client logs via `GET /api/client-logs/<uuid>/logs`.
|
- Monitoring API: Added/active endpoints `GET /api/client-logs/monitoring-overview` and `GET /api/client-logs/recent-errors`; per-client logs via `GET /api/client-logs/<uuid>/logs`.
|
||||||
- Dashboard monitoring UI: Superadmin monitoring page is integrated and displays client health status, screenshots, process metadata, and recent error activity.
|
- Dashboard monitoring UI: Superadmin monitoring page is integrated and displays client health status, screenshots, process metadata, and recent error activity.
|
||||||
|
|||||||
328
FRONTEND_DESIGN_RULES.md
Normal file
328
FRONTEND_DESIGN_RULES.md
Normal file
@@ -0,0 +1,328 @@
|
|||||||
|
# Frontend Design Rules
|
||||||
|
|
||||||
|
This file is the single source of truth for UI implementation conventions in the dashboard (`dashboard/src/`).
|
||||||
|
It applies to all feature work, including new pages, settings tabs, dialogs, and management surfaces.
|
||||||
|
|
||||||
|
When proposing or implementing frontend changes, follow these rules unless a specific exception is documented below.
|
||||||
|
This file should be updated whenever a new Syncfusion component is adopted, a color or pattern changes, or an exception is ratified.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Component Library — Syncfusion First
|
||||||
|
|
||||||
|
Use Syncfusion components as the default choice for every UI element.
|
||||||
|
The project uses the Syncfusion Material3 theme, registered globally in `dashboard/src/main.tsx`.
|
||||||
|
|
||||||
|
The following CSS packages are imported there and cover all components currently in use:
|
||||||
|
`base`, `navigations`, `buttons`, `inputs`, `dropdowns`, `popups`, `kanban`, `grids`, `schedule`, `filemanager`, `notifications`, `layouts`, `lists`, `calendars`, `splitbuttons`, `icons`.
|
||||||
|
When adding a new Syncfusion component, add its CSS import here — and add the new npm package to `optimizeDeps.include` in `vite.config.ts` to avoid Vite import-analysis errors in development.
|
||||||
|
|
||||||
|
Use non-Syncfusion elements only when:
|
||||||
|
- The Syncfusion equivalent does not exist (e.g., native `<input type="file">` for file upload)
|
||||||
|
- The Syncfusion component would require significantly more code than a simple HTML element for purely read-only or structural content (e.g., `<ul>/<li>` for plain lists)
|
||||||
|
- A layout-only structure is needed (a wrapper `<div>` for spacing is fine)
|
||||||
|
|
||||||
|
**Never** use `window.confirm()` for destructive action confirmations — use `DialogComponent` instead.
|
||||||
|
`window.confirm()` exists in one place in `dashboard.tsx` (bulk restart) and is considered a deprecated pattern to avoid.
|
||||||
|
|
||||||
|
Do not introduce Tailwind utility classes — Tailwind has been removed from the project.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Component Defaults by Purpose
|
||||||
|
|
||||||
|
| Purpose | Component | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| Navigation tabs | `TabComponent` + `TabItemDirective` | `heightAdjustMode="Auto"`, controlled with `selectedItem` state |
|
||||||
|
| Data list or table | `GridComponent` | `allowPaging`, `allowSorting`, custom `template` for status/actions |
|
||||||
|
| Paginated list | `PagerComponent` | When a full grid is too heavy; default page size 5 or 10 |
|
||||||
|
| Text input | `TextBoxComponent` | Use `cssClass="e-outline"` on form-heavy sections |
|
||||||
|
| Numeric input | `NumericTextBoxComponent` | Always set `min`, `max`, `step`, `format` |
|
||||||
|
| Single select | `DropDownListComponent` | Always set `fields={{ text, value }}`; do **not** add `cssClass="e-outline"` — only `TextBoxComponent` uses outline style |
|
||||||
|
| Boolean toggle | `CheckBoxComponent` | Use `label` prop, handle via `change` callback |
|
||||||
|
| Buttons | `ButtonComponent` | See section 4 |
|
||||||
|
| Modal dialogs | `DialogComponent` | `isModal={true}`, `showCloseIcon={true}`, footer with Cancel + primary |
|
||||||
|
| Notifications | `ToastComponent` | Positioned `{ X: 'Right', Y: 'Top' }`, 3000ms timeout by default |
|
||||||
|
| Inline info/error | `MessageComponent` | Use `severity` prop: `'Error'`, `'Warning'`, `'Info'`, `'Success'` |
|
||||||
|
| Status/role badges | Plain `<span>` with inline style | See section 6 for convention |
|
||||||
|
| Timeline/schedule | `ScheduleComponent` | Used for resource timeline views; see `ressourcen.tsx` |
|
||||||
|
| File management | `FileManagerComponent` | Used on the Media page for upload and organisation |
|
||||||
|
| Drag-drop board | `KanbanComponent` | Used on the Groups page; retain for drag-drop boards |
|
||||||
|
| User action menu | `DropDownButtonComponent` (`@syncfusion/ej2-react-splitbuttons`) | Used for header user menu; add to `optimizeDeps.include` in `vite.config.ts` |
|
||||||
|
| File upload | Native `<input type="file">` | No Syncfusion equivalent for raw file input |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Layout and Card Structure
|
||||||
|
|
||||||
|
Every settings tab section starts with a `<div style={{ padding: 20 }}>` wrapper.
|
||||||
|
Content blocks use Syncfusion card classes:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<div className="e-card">
|
||||||
|
<div className="e-card-header">
|
||||||
|
<div className="e-card-header-caption">
|
||||||
|
<div className="e-card-header-title">Title</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div className="e-card-content">
|
||||||
|
{/* content */}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
Multiple cards in the same tab section use `style={{ marginBottom: 20 }}` between them.
|
||||||
|
|
||||||
|
For full-page views (not inside a settings tab), the top section follows this pattern:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<div style={{ marginBottom: 24, display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
|
||||||
|
<div>
|
||||||
|
<h2 style={{ margin: 0, fontSize: 24, fontWeight: 600 }}>Page title</h2>
|
||||||
|
<p style={{ margin: '8px 0 0 0', color: '#6c757d' }}>Subtitle or description</p>
|
||||||
|
</div>
|
||||||
|
<ButtonComponent cssClass="e-success" iconCss="e-icons e-plus">New item</ButtonComponent>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Buttons
|
||||||
|
|
||||||
|
| Variant | `cssClass` | When to use |
|
||||||
|
|---|---|---|
|
||||||
|
| Primary action (save, confirm) | `e-primary` | Main save or confirm in forms and dialogs |
|
||||||
|
| Create / add new | `e-success` + `iconCss="e-icons e-plus"` | Top-level create action in page header |
|
||||||
|
| Destructive (delete, archive) | `e-flat e-danger` | Row actions and destructive dialog confirm |
|
||||||
|
| Secondary / cancel | `e-flat` | Cancel in dialog footer, low-priority options |
|
||||||
|
| Info / edit | `e-flat e-primary` or `e-flat e-info` | Row-level edit and info actions |
|
||||||
|
| Outline secondary | `e-outline` | Secondary actions needing a visible border (e.g., preview URL) |
|
||||||
|
|
||||||
|
All async action buttons must be `disabled` during the in-flight operation: `disabled={isBusy}`.
|
||||||
|
Button text must change to indicate the pending state: `Speichere…`, `Erstelle...`, `Archiviere…`, `Lösche...`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Dialogs
|
||||||
|
|
||||||
|
All create, edit, and destructive action dialogs use `DialogComponent`:
|
||||||
|
- `isModal={true}`
|
||||||
|
- `showCloseIcon={true}`
|
||||||
|
- `width="500px"` for forms (wider if tabular data is shown inside)
|
||||||
|
- `header` prop with specific context text (include item name where applicable)
|
||||||
|
- `footerTemplate` always has at minimum: Cancel (`e-flat`) + primary action (`e-primary`)
|
||||||
|
- Dialog body wrapped in `<div style={{ padding: 16 }}>`
|
||||||
|
- All fields disabled when `formBusy` is true
|
||||||
|
|
||||||
|
For destructive confirmations (archive, delete), the dialog body must clearly explain what will happen and whether it is reversible.
|
||||||
|
|
||||||
|
For blocked actions, use `MessageComponent` with `severity="Warning"` or `severity="Error"` inside the dialog body to show exact blocker details (e.g., linked event count, recurrence spillover).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Status and Type Badges
|
||||||
|
|
||||||
|
Plain `<span>` badges with inline style — no external CSS classes needed:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<span style={{
|
||||||
|
padding: '4px 12px',
|
||||||
|
borderRadius: '12px',
|
||||||
|
backgroundColor: color,
|
||||||
|
color: 'white',
|
||||||
|
fontSize: '12px',
|
||||||
|
fontWeight: 500,
|
||||||
|
display: 'inline-block',
|
||||||
|
}}>
|
||||||
|
Label
|
||||||
|
</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
See section 12 for the fixed color palette.
|
||||||
|
|
||||||
|
**Icon conventions**: Use inline SVG or icon font classes for small visual indicators next to text. Established precedents:
|
||||||
|
- Skip-holidays events render a TentTree icon immediately to the left of the main event-type icon; **always black** (`color: 'black'` or no color override).
|
||||||
|
- Recurring events rely on Syncfusion's native lower-right recurrence badge — do not add a custom recurrence icon.
|
||||||
|
|
||||||
|
**Role badge color mapping** (established in `users.tsx`; apply consistently for any role display):
|
||||||
|
|
||||||
|
| Role | Color |
|
||||||
|
|---|---|
|
||||||
|
| user | `#6c757d` (neutral gray) |
|
||||||
|
| editor | `#0d6efd` (info blue) |
|
||||||
|
| admin | `#28a745` (success green) |
|
||||||
|
| superadmin | `#dc3545` (danger red) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Toast Notifications
|
||||||
|
|
||||||
|
Use a component-local `ToastComponent` with a `ref`:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
const toastRef = React.useRef<ToastComponent>(null);
|
||||||
|
// ...
|
||||||
|
<ToastComponent ref={toastRef} position={{ X: 'Right', Y: 'Top' }} />
|
||||||
|
```
|
||||||
|
|
||||||
|
Default `timeOut: 3000`. Use `4000` for messages that need more reading time.
|
||||||
|
|
||||||
|
CSS class conventions:
|
||||||
|
- `e-toast-success` — successful operations
|
||||||
|
- `e-toast-danger` — errors
|
||||||
|
- `e-toast-warning` — non-critical issues or partial results
|
||||||
|
- `e-toast-info` — neutral informational messages
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Form Fields
|
||||||
|
|
||||||
|
All form labels:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<label style={{ display: 'block', marginBottom: 8, fontWeight: 500 }}>
|
||||||
|
Field label *
|
||||||
|
</label>
|
||||||
|
```
|
||||||
|
|
||||||
|
Help/hint text below a field:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<div style={{ fontSize: '12px', color: '#666', marginTop: 4 }}>
|
||||||
|
Hint text here.
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
Empty state inside a card:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<div style={{ fontSize: '14px', color: '#666' }}>Keine Einträge vorhanden.</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
Vertical spacing between field groups: `marginBottom: 16`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Tab Structure
|
||||||
|
|
||||||
|
Top-level and nested tabs use controlled `selectedItem` state with separate index variables per tab level.
|
||||||
|
This prevents sub-tab resets when parent state changes.
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
const [academicTabIndex, setAcademicTabIndex] = React.useState(0);
|
||||||
|
|
||||||
|
<TabComponent
|
||||||
|
heightAdjustMode="Auto"
|
||||||
|
selectedItem={academicTabIndex}
|
||||||
|
selected={(e: TabSelectedEvent) => setAcademicTabIndex(e.selectedIndex ?? 0)}
|
||||||
|
>
|
||||||
|
<TabItemsDirective>
|
||||||
|
<TabItemDirective header={{ text: '🗂️ Perioden' }} content={AcademicPeriodsContent} />
|
||||||
|
<TabItemDirective header={{ text: '📥 Import & Liste' }} content={HolidaysImportAndListContent} />
|
||||||
|
</TabItemsDirective>
|
||||||
|
</TabComponent>
|
||||||
|
```
|
||||||
|
|
||||||
|
Tab header text uses an emoji prefix followed by a German label, consistent with all existing tabs.
|
||||||
|
Each nested tab level has its own separate index state variable.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Statistics Summary Cards
|
||||||
|
|
||||||
|
Used above grids and lists to show aggregate counts:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<div style={{ marginBottom: 24, display: 'flex', gap: 16 }}>
|
||||||
|
<div className="e-card" style={{ flex: 1, padding: 16 }}>
|
||||||
|
<div style={{ fontSize: 14, color: '#6c757d', marginBottom: 4 }}>Label</div>
|
||||||
|
<div style={{ fontSize: 28, fontWeight: 600, color: '#28a745' }}>42</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Inline Warning Messages
|
||||||
|
|
||||||
|
For important warnings inside forms or dialogs:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<div style={{
|
||||||
|
padding: 12,
|
||||||
|
backgroundColor: '#fff3cd',
|
||||||
|
border: '1px solid #ffc107',
|
||||||
|
borderRadius: 4,
|
||||||
|
marginBottom: 16,
|
||||||
|
fontSize: 14,
|
||||||
|
}}>
|
||||||
|
⚠️ Warning message text here.
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
For structured in-page errors or access-denied states, use `MessageComponent`:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<MessageComponent severity="Error" content="Fehlermeldung" />
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Color Palette
|
||||||
|
|
||||||
|
Only the following colors are used in status and UI elements across the dashboard.
|
||||||
|
Do not introduce new colors for new components.
|
||||||
|
|
||||||
|
| Use | Color |
|
||||||
|
|---|---|
|
||||||
|
| Success / active / online | `#28a745` |
|
||||||
|
| Danger / delete / offline | `#dc3545` |
|
||||||
|
| Warning / partial | `#f39c12` |
|
||||||
|
| Info / edit blue | `#0d6efd` |
|
||||||
|
| Neutral / archived / subtitle | `#6c757d` |
|
||||||
|
| Help / secondary text | `#666` |
|
||||||
|
| Inactive/muted | `#868e96` |
|
||||||
|
| Warning background | `#fff3cd` |
|
||||||
|
| Warning border | `#ffc107` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Dedicated CSS Files
|
||||||
|
|
||||||
|
Use inline styles for settings tab sections and simpler pages.
|
||||||
|
Only create a dedicated `.css` file if the component requires complex layout, custom animations, or selector-based styles that are not feasible with inline styles.
|
||||||
|
|
||||||
|
Existing precedents: `monitoring.css`, `ressourcen.css`.
|
||||||
|
|
||||||
|
Do not use Tailwind — it has been removed from the project.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Loading States
|
||||||
|
|
||||||
|
For full-page loading, use a simple centered placeholder:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
<div style={{ padding: 24 }}>
|
||||||
|
<div style={{ textAlign: 'center', padding: 40 }}>Lade Daten...</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not use spinners or animated components unless a Syncfusion component provides them natively (e.g., busy state on `ButtonComponent`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Locale and Language
|
||||||
|
|
||||||
|
All user-facing strings are in German.
|
||||||
|
Date formatting uses `toLocaleString('de-DE')` or `toLocaleTimeString('de-DE', { hour: '2-digit', minute: '2-digit' })`.
|
||||||
|
Never use English strings in labels, buttons, tooltips, or dialog headers visible to the end user.
|
||||||
|
|
||||||
|
**UTC time parsing**: The API returns ISO timestamps **without** a `Z` suffix (e.g., `"2025-11-27T20:03:00"`). Always append `Z` before constructing a `Date` to ensure correct UTC interpretation:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const utcStr = dateStr.endsWith('Z') ? dateStr : dateStr + 'Z';
|
||||||
|
const date = new Date(utcStr);
|
||||||
|
```
|
||||||
|
|
||||||
|
When sending dates back to the API, use `date.toISOString()` (already UTC with `Z`).
|
||||||
@@ -18,6 +18,123 @@ This document describes the MQTT message structure used by the Infoscreen system
|
|||||||
- **Format**: Integer (group ID)
|
- **Format**: Integer (group ID)
|
||||||
- **Purpose**: Assigns clients to groups
|
- **Purpose**: Assigns clients to groups
|
||||||
|
|
||||||
|
### TV Power Intent (Phase 1)
|
||||||
|
- **Topic**: `infoscreen/groups/{group_id}/power/intent`
|
||||||
|
- **QoS**: 1
|
||||||
|
- **Retained**: Yes
|
||||||
|
- **Format**: JSON object
|
||||||
|
- **Purpose**: Group-level desired power state for clients assigned to that group
|
||||||
|
|
||||||
|
Phase 1 is group-only. Per-client power intent topics and client state/ack topics are deferred to Phase 2.
|
||||||
|
|
||||||
|
Example payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"intent_id": "9cf26d9b-87a3-42f1-8446-e90bb6f6ce63",
|
||||||
|
"group_id": 12,
|
||||||
|
"desired_state": "on",
|
||||||
|
"reason": "active_event",
|
||||||
|
"issued_at": "2026-03-31T10:15:30Z",
|
||||||
|
"expires_at": "2026-03-31T10:17:00Z",
|
||||||
|
"poll_interval_sec": 30,
|
||||||
|
"active_event_ids": [148],
|
||||||
|
"event_window_start": "2026-03-31T10:15:00Z",
|
||||||
|
"event_window_end": "2026-03-31T11:00:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Contract notes:
|
||||||
|
- `intent_id` changes only on semantic transition (`desired_state`/`reason` changes).
|
||||||
|
- Heartbeat republishes keep `intent_id` stable while refreshing `issued_at` and `expires_at`.
|
||||||
|
- Expiry is poll-based: `max(3 x poll_interval_sec, 90)`.
|
||||||
|
|
||||||
|
### Service-Failed Notification (client → server, retained)
|
||||||
|
- **Topic**: `infoscreen/{uuid}/service_failed`
|
||||||
|
- **QoS**: 1
|
||||||
|
- **Retained**: Yes
|
||||||
|
- **Direction**: client → server
|
||||||
|
- **Purpose**: Client signals that systemd has exhausted restart attempts (`StartLimitBurst` exceeded) — manual intervention is required.
|
||||||
|
|
||||||
|
Example payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "service_failed",
|
||||||
|
"unit": "infoscreen-simclient.service",
|
||||||
|
"client_uuid": "9b8d1856-ff34-4864-a726-12de072d0f77",
|
||||||
|
"failed_at": "2026-04-05T08:00:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Contract notes:
|
||||||
|
- Message is retained so the server receives it even after a broker restart.
|
||||||
|
- Server persists `service_failed_at` and `service_failed_unit` to the `clients` table.
|
||||||
|
- To clear after resolution: `POST /api/clients/<uuid>/clear_service_failed` — clears the DB flag and publishes an empty retained payload to delete the retained message from the broker.
|
||||||
|
- Empty payload (empty bytes) on this topic = retain-clear in transit; listener ignores it.
|
||||||
|
|
||||||
|
### Client Command Intent (Phase 1)
|
||||||
|
- **Topic**: `infoscreen/{uuid}/commands`
|
||||||
|
- **QoS**: 1
|
||||||
|
- **Retained**: No
|
||||||
|
- **Format**: JSON object
|
||||||
|
- **Purpose**: Per-client control commands (currently `restart` and `shutdown`)
|
||||||
|
|
||||||
|
Compatibility note:
|
||||||
|
- During restart transition, server also publishes legacy restart command to `clients/{uuid}/restart` with payload `{ "action": "restart" }`.
|
||||||
|
- During topic naming transition, server also publishes command payload to `infoscreen/{uuid}/command`.
|
||||||
|
|
||||||
|
Example payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"client_uuid": "9b8d1856-ff34-4864-a726-12de072d0f77",
|
||||||
|
"action": "reboot_host",
|
||||||
|
"issued_at": "2026-04-03T12:48:10Z",
|
||||||
|
"expires_at": "2026-04-03T12:52:10Z",
|
||||||
|
"requested_by": 1,
|
||||||
|
"reason": "operator_request"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Contract notes:
|
||||||
|
- Clients must reject stale commands where local UTC time is greater than `expires_at`.
|
||||||
|
- Clients must deduplicate by `command_id` and never execute a duplicate command twice.
|
||||||
|
- `schema_version` is required for forward-compatibility.
|
||||||
|
- Allowed command action values in v1: `reboot_host`, `shutdown_host`, `restart_app`.
|
||||||
|
- `restart_app` = soft app restart (no OS reboot); `reboot_host` = full OS reboot.
|
||||||
|
- API mapping for operators: restart endpoint emits `reboot_host`; shutdown endpoint emits `shutdown_host`.
|
||||||
|
|
||||||
|
### Client Command Acknowledgements (Phase 1)
|
||||||
|
- **Topic**: `infoscreen/{uuid}/commands/ack`
|
||||||
|
- **QoS**: 1 (recommended)
|
||||||
|
- **Retained**: No
|
||||||
|
- **Format**: JSON object
|
||||||
|
- **Purpose**: Client reports command lifecycle progression back to server
|
||||||
|
|
||||||
|
Compatibility note:
|
||||||
|
- During topic naming transition, listener also accepts acknowledgements from `infoscreen/{uuid}/command/ack`.
|
||||||
|
|
||||||
|
Example payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"status": "execution_started",
|
||||||
|
"error_code": null,
|
||||||
|
"error_message": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Allowed `status` values:
|
||||||
|
- `accepted`
|
||||||
|
- `execution_started`
|
||||||
|
- `completed`
|
||||||
|
- `failed`
|
||||||
|
|
||||||
## Message Structure
|
## Message Structure
|
||||||
|
|
||||||
### General Principles
|
### General Principles
|
||||||
@@ -120,7 +237,7 @@ Every event includes these common fields:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Note**: WebUntis events use the same payload structure as website events. The URL is fetched from system settings (`webuntis_url`) rather than being specified per-event. Clients treat `webuntis` and `website` event types identically—both display a website.
|
**Note**: WebUntis events use the same payload structure as website events. The URL is fetched from system settings (`supplement_table_url`) rather than being specified per-event. Clients treat `webuntis` and `website` event types identically—both display a website.
|
||||||
|
|
||||||
#### Video Events
|
#### Video Events
|
||||||
|
|
||||||
|
|||||||
824
README.md
824
README.md
@@ -6,641 +6,237 @@
|
|||||||
[](https://mariadb.org/)
|
[](https://mariadb.org/)
|
||||||
[](https://mosquitto.org/)
|
[](https://mosquitto.org/)
|
||||||
|
|
||||||
A comprehensive multi-service digital signage solution for educational institutions, featuring client management, event scheduling, presentation conversion, and real-time MQTT communication.
|
Multi-service digital signage platform for educational institutions.
|
||||||
|
|
||||||
## 🏗️ Architecture Overview
|
Core stack:
|
||||||
|
- Dashboard: React + Vite + Syncfusion
|
||||||
|
- API: Flask + SQLAlchemy + Alembic
|
||||||
|
- DB: MariaDB
|
||||||
|
- Messaging: MQTT (Mosquitto)
|
||||||
|
- Background jobs: Redis + RQ + Gotenberg
|
||||||
|
|
||||||
```
|
## Latest Release Highlights (2026.1.0-alpha.16)
|
||||||
┌───────────────┐ ┌──────────────────────────┐ ┌───────────────┐
|
|
||||||
│ Dashboard │◄──────►│ API Server │◄──────►│ Worker │
|
|
||||||
│ (React/Vite) │ │ (Flask) │ │ (Conversions) │
|
|
||||||
└───────────────┘ └──────────────────────────┘ └───────────────┘
|
|
||||||
▲ ▲
|
|
||||||
│ │
|
|
||||||
┌───────────────┐ │
|
|
||||||
│ MariaDB │ │
|
|
||||||
│ (Database) │ │
|
|
||||||
└───────────────┘ │
|
|
||||||
│ direct commands/results
|
|
||||||
|
|
||||||
Reads events ▲ Interacts with API ▲
|
- Dashboard holiday status banner now updates reliably after hard refresh and after switching between settings and dashboard.
|
||||||
│ ┌────┘
|
- Production startup now auto-initializes and auto-activates the academic period for the current date.
|
||||||
┌───────────────┐ │ │ ┌───────────────┐
|
- Dashboard German UI wording was polished with proper Umlauts.
|
||||||
│ Scheduler │──┘ └──│ Listener │
|
- User-facing changelog source: [dashboard/public/program-info.json](dashboard/public/program-info.json)
|
||||||
│ (Events) │ │ (MQTT Client) │
|
|
||||||
└───────────────┘ └───────────────┘
|
|
||||||
│ Publishes events ▲ Consumes discovery/heartbeats
|
|
||||||
▼ │ and forwards to API
|
|
||||||
┌─────────────────┐◄─────────────────────────────────────────────────────────────────┘
|
|
||||||
│ MQTT Broker │────────────────────────────────────────────────────────► Clients
|
|
||||||
│ (Mosquitto) │ Sends events to clients (send discovery/heartbeats)
|
|
||||||
└─────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
Data flow summary:
|
## Architecture (Short)
|
||||||
- Listener: consumes discovery and heartbeat messages from the MQTT Broker and updates the API Server (client registration/heartbeats).
|
|
||||||
- Listener screenshot flow: consumes `infoscreen/{uuid}/screenshot` and `infoscreen/{uuid}/dashboard`. Dashboard messages use grouped v2 schema (`message`, `content`, `runtime`, `metadata`); screenshot data is read from `content.screenshot`, capture type from `metadata.capture.type`, and forwarded to `POST /api/clients/{uuid}/screenshot`.
|
|
||||||
- Scheduler: reads events from the API Server and publishes only currently active content to the MQTT Broker (retained topics per group). When a group has no active events, the scheduler clears its retained topic by publishing an empty list. All time comparisons are done in UTC; any naive timestamps are normalized.
|
|
||||||
- Clients: send discovery/heartbeat via the MQTT Broker (handled by the Listener) and receive content from the Scheduler via MQTT.
|
|
||||||
- Worker: receives conversion commands directly from the API Server and reports results/status back to the API (no MQTT involved).
|
|
||||||
- MariaDB: is accessed exclusively by the API Server. The Dashboard never talks to the database directly; it only communicates with the API.
|
|
||||||
|
|
||||||
## 🌟 Key Features
|
- Dashboard talks only to API (`/api/...` via Vite proxy in dev).
|
||||||
|
- API is the single writer to MariaDB.
|
||||||
|
- Listener consumes MQTT discovery/heartbeat/log/screenshot topics and updates API state.
|
||||||
|
- Scheduler expands recurring events, applies exceptions, and publishes active content to retained MQTT topics.
|
||||||
|
- Worker handles document conversions asynchronously.
|
||||||
|
|
||||||
- **User Management**: Comprehensive role-based access control (user → editor → admin → superadmin)
|
## Quick Start
|
||||||
- Admin panel for user CRUD operations with audit tracking
|
|
||||||
- Self-service password change available to all users
|
|
||||||
- Audit trail: login times, password changes, deactivation history
|
|
||||||
- Soft-delete by default, hard-delete superadmin-only
|
|
||||||
- Modern React-based web interface with Syncfusion components
|
|
||||||
- Real-time client monitoring and group management
|
|
||||||
- Event scheduling with academic period support
|
|
||||||
- Media management with presentation conversion
|
|
||||||
- Holiday calendar integration
|
|
||||||
- Visual indicators: TentTree icon next to the main event icon marks events that skip holidays (icon color: black)
|
|
||||||
|
|
||||||
- **Event Deletion**: All event types (single, single-in-series, entire series) are handled with custom dialogs. The frontend intercepts Syncfusion's built-in RecurrenceAlert and DeleteAlert popups to provide a unified, user-friendly deletion flow:
|
|
||||||
- Single (non-recurring) event: deleted directly after confirmation.
|
|
||||||
- Single occurrence of a recurring series: user can delete just that instance.
|
|
||||||
- Entire recurring series: user can delete all occurrences after a final custom confirmation dialog.
|
|
||||||
- Detached occurrences (edited/broken out): treated as single events.
|
|
||||||
|
|
||||||
### 🎯 **Event System**
|
|
||||||
- **Presentations**: PowerPoint/LibreOffice → PDF conversion via Gotenberg
|
|
||||||
- **Websites**: URL-based content display
|
|
||||||
- **Videos**: Media file streaming with per-event playback settings (`autoplay`, `loop`, `volume`, `muted`); system-wide defaults configurable under Settings → Events → Videos
|
|
||||||
- **Messages**: Text announcements
|
|
||||||
- **WebUntis**: Educational schedule integration
|
|
||||||
- Uses the system-wide Vertretungsplan/Supplement-Table URL (`supplement_table_url`) configured under Settings → Events. No separate per-event URL is required; WebUntis events display the same as Website events.
|
|
||||||
- **Recurrence & Holidays**: Recurring events can be configured to skip holidays. The backend generates EXDATEs (RecurrenceException) for holiday occurrences using RFC 5545 timestamps (yyyyMMddTHHmmssZ), so the calendar never shows those instances. The scheduler queries a 7-day window to expand recurring events and applies event exceptions, but only publishes events that are active at the current time (UTC). The "Termine an Ferientagen erlauben" toggle does not affect these events.
|
|
||||||
- **Single Occurrence Editing**: Users can edit individual occurrences of recurring events without affecting the master series. The system provides a confirmation dialog to choose between editing a single occurrence or the entire series.
|
|
||||||
|
|
||||||
### 🏫 **Academic Period Management**
|
|
||||||
- Support for school years, semesters, and trimesters
|
|
||||||
- Austrian school system integration
|
|
||||||
- Holiday calendar synchronization
|
|
||||||
- Period-based event organization
|
|
||||||
|
|
||||||
### 📡 **Real-time Communication**
|
|
||||||
- MQTT-based client discovery and heartbeat monitoring
|
|
||||||
- Retained topics for reliable state synchronization
|
|
||||||
- WebSocket support for browser clients
|
|
||||||
- Automatic client group assignment
|
|
||||||
|
|
||||||
### 🔄 **Background Processing**
|
|
||||||
- Redis-based job queues for presentation conversion
|
|
||||||
- Gotenberg integration for LibreOffice/PowerPoint processing
|
|
||||||
- Asynchronous file processing with status tracking
|
|
||||||
- RQ (Redis Queue) worker management
|
|
||||||
|
|
||||||
## 🚀 Quick Start
|
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
- Docker & Docker Compose
|
- Docker + Docker Compose
|
||||||
- Git
|
- Git
|
||||||
- SSL certificates (for production)
|
|
||||||
|
|
||||||
### Development Setup
|
|
||||||
|
|
||||||
1. **Clone the repository**
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/RobbStarkAustria/infoscreen_2025.git
|
|
||||||
cd infoscreen_2025
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Environment Configuration**
|
|
||||||
```bash
|
|
||||||
cp .env.example .env
|
|
||||||
# Edit .env with your configuration
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Start the development stack**
|
|
||||||
```bash
|
|
||||||
make up
|
|
||||||
# or: docker compose up -d --build
|
|
||||||
```
|
|
||||||
|
|
||||||
Before running the dashboard dev server you may need to install Syncfusion packages used by the UI. Example (install only the packages you use):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# from the repository root
|
|
||||||
cd dashboard
|
|
||||||
npm install --save @syncfusion/ej2-react-splitbuttons @syncfusion/ej2-splitbuttons \
|
|
||||||
@syncfusion/ej2-react-grids @syncfusion/ej2-react-schedule @syncfusion/ej2-react-filemanager
|
|
||||||
```
|
|
||||||
|
|
||||||
License note: Syncfusion distributes components under a commercial license with a free community license for qualifying users. Verify licensing for your organization before using Syncfusion in production and document any license keys or compliance steps in this repository.
|
|
||||||
|
|
||||||
4. **Initialize the database (first run only)**
|
|
||||||
```bash
|
|
||||||
# One-shot: runs all Alembic migrations, creates default admin/group, and seeds academic periods
|
|
||||||
python server/initialize_database.py
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Access the services**
|
|
||||||
- Dashboard: http://localhost:5173
|
|
||||||
- API: http://localhost:8000
|
|
||||||
- Database: localhost:3306
|
|
||||||
- MQTT: localhost:1883 (WebSocket: 9001)
|
|
||||||
|
|
||||||
### Production Deployment
|
|
||||||
|
|
||||||
1. **Build and push images**
|
|
||||||
```bash
|
|
||||||
make build
|
|
||||||
make push
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Deploy on server**
|
|
||||||
```bash
|
|
||||||
make pull-prod
|
|
||||||
make up-prod
|
|
||||||
```
|
|
||||||
|
|
||||||
For detailed deployment instructions, see:
|
|
||||||
- [Debian Deployment Guide](deployment-debian.md)
|
|
||||||
- [Ubuntu Deployment Guide](deployment-ubuntu.md)
|
|
||||||
|
|
||||||
## 🛠️ Services
|
|
||||||
|
|
||||||
### 🖥️ **Dashboard** (`dashboard/`)
|
|
||||||
- **Technology**: React 19 + TypeScript + Vite
|
|
||||||
- **UI Framework**: Syncfusion components (Material 3 theme)
|
|
||||||
- **Styling**: Centralized Syncfusion Material 3 CSS imports in `dashboard/src/main.tsx`
|
|
||||||
- **Features**: Responsive design, real-time updates, file management
|
|
||||||
- **Port**: 5173 (dev), served via Nginx (prod)
|
|
||||||
- **Data access**: No direct database connection; communicates with the API Server only via HTTP.
|
|
||||||
- **Dev proxy tip**: In development, use relative paths like `/api/...` in the frontend to route through Vite's proxy to the API. Avoid absolute URLs with an extra `/api` segment to prevent CORS or double-path issues.
|
|
||||||
|
|
||||||
### 🔧 **API Server** (`server/`)
|
|
||||||
- **Technology**: Flask + SQLAlchemy + Alembic
|
|
||||||
- **Database**: MariaDB with timezone-aware timestamps
|
|
||||||
- **Features**: RESTful API, file uploads, MQTT integration
|
|
||||||
- Recurrence/holidays: returns only master events with `RecurrenceRule` and `RecurrenceException` (EXDATEs) so clients render recurrences and skip holiday instances reliably.
|
|
||||||
- Recurring events are only deactivated after their recurrence_end (UNTIL); non-recurring events deactivate after their end time. Event exceptions are respected and rendered in scheduler output.
|
|
||||||
- Single occurrence detach: `POST /api/events/<id>/occurrences/<date>/detach` creates standalone events from recurring series without modifying the master event.
|
|
||||||
- **Port**: 8000
|
|
||||||
- **Health Check**: `/health`
|
|
||||||
|
|
||||||
### 👂 **Listener** (`listener/`)
|
|
||||||
|
|
||||||
### ⏰ **Scheduler** (`scheduler/`)
|
|
||||||
**Technology**: Python + SQLAlchemy
|
|
||||||
**Purpose**: Event publishing, group-based content distribution
|
|
||||||
**Features**:
|
|
||||||
- Queries a future window (default: 7 days) to expand recurring events
|
|
||||||
- Expands recurrences using RFC 5545 rules
|
|
||||||
- Applies event exceptions (skipped dates, detached occurrences)
|
|
||||||
- Only deactivates recurring events after their recurrence_end (UNTIL)
|
|
||||||
- Publishes only currently active events to MQTT (per group)
|
|
||||||
- Clears retained topics by publishing an empty list when a group has no active events
|
|
||||||
- Normalizes naive timestamps and compares times in UTC
|
|
||||||
- Logging is concise; conversion lookups are cached and logged only once per media
|
|
||||||
|
|
||||||
### 🔄 **Worker** (Conversion Service)
|
|
||||||
- **Technology**: RQ (Redis Queue) + Gotenberg
|
|
||||||
- **Purpose**: Background presentation conversion
|
|
||||||
- **Features**: PPT/PPTX/ODP → PDF conversion, status tracking
|
|
||||||
|
|
||||||
### 🗄️ **Database** (MariaDB 11.2)
|
|
||||||
- **Features**: Health checks, automatic initialization
|
|
||||||
- **Migrations**: Alembic-based schema management
|
|
||||||
- **Timezone**: UTC-aware timestamps
|
|
||||||
|
|
||||||
### 📡 **MQTT Broker** (Eclipse Mosquitto 2.0.21)
|
|
||||||
- **Features**: WebSocket support, health monitoring
|
|
||||||
- **Topics**:
|
|
||||||
- `infoscreen/discovery` - Client registration
|
|
||||||
- `infoscreen/{uuid}/heartbeat` - Client alive status
|
|
||||||
- `infoscreen/events/{group_id}` - Event distribution
|
|
||||||
## 🔗 Scheduler Event Payloads
|
|
||||||
|
|
||||||
- Presentations include a `presentation` object with `files`, `slide_interval`, `page_progress`, and `auto_progress`.
|
|
||||||
- Website and WebUntis events share a unified payload:
|
|
||||||
- `website`: `{ "type": "browser", "url": "https://..." }`
|
|
||||||
- The `event_type` field remains specific (e.g., `presentation`, `website`, `webuntis`) so clients can dispatch appropriately; however, `website` and `webuntis` should be handled identically in clients.
|
|
||||||
- Videos include a `video` payload with a stream URL and playback flags:
|
|
||||||
- `video`: includes `url` (streaming endpoint) and `autoplay`, `loop`, `volume`, `muted`
|
|
||||||
- Streaming endpoint supports byte-range requests (206) to enable seeking: `/api/eventmedia/stream/<media_id>/<filename>`
|
|
||||||
- Server-side UTC: All backend comparisons are performed in UTC; API returns ISO strings without `Z`. Frontend appends `Z` before parsing.
|
|
||||||
|
|
||||||
## Recent changes since last commit
|
|
||||||
|
|
||||||
- Monitoring system: End-to-end monitoring is now implemented. The listener ingests `logs/*` and `health` MQTT topics, the API exposes monitoring endpoints (`/api/client-logs/monitoring-overview`, `/api/client-logs/recent-errors`, `/api/client-logs/<uuid>/logs`), and the superadmin dashboard page shows live client status, screenshots, and recent errors.
|
|
||||||
- Screenshot priority flow: Screenshot payloads now support `screenshot_type` (`periodic`, `event_start`, `event_stop`). `event_start` and `event_stop` are treated as high-priority screenshots; the API stores typed screenshots, maintains priority metadata, and serves active priority screenshots through `/screenshots/{uuid}/priority`.
|
|
||||||
- MQTT dashboard payload v2 cutover: Listener parsing is now v2-only for dashboard JSON payloads (`message/content/runtime/metadata`). Legacy top-level dashboard fallback has been removed after migration completion; parser observability tracks `v2_success` and `parse_failures`.
|
|
||||||
- Presentation persistence fix: Fixed persistence of presentation flags so `page_progress` and `auto_progress` are reliably stored and returned for create/update flows and detached occurrences.
|
|
||||||
- Additional improvements: Video/streaming, scheduler metadata, settings defaults, and UI refinements remain documented in the detailed sections below.
|
|
||||||
|
|
||||||
These changes are designed to be safe if metadata extraction or probes fail — clients should still attempt playback using the provided `url` and fall back to requesting/resolving richer metadata when available.
|
|
||||||
|
|
||||||
See `MQTT_EVENT_PAYLOAD_GUIDE.md` for details.
|
|
||||||
|
|
||||||
## 🧩 Developer Environment Notes (Dev Container)
|
|
||||||
- Extensions: UI-only `Dev Containers` runs on the host UI; not installed inside the container to avoid reinstallation loops. See `/.devcontainer/devcontainer.json` (`remote.extensionKind`).
|
|
||||||
- Installs: Dashboard uses `npm ci` on `postCreateCommand` for reproducible installs.
|
|
||||||
- Aliases: `postStartCommand` appends shell aliases idempotently to prevent duplicates across restarts.
|
|
||||||
|
|
||||||
## 📦 Versioning
|
|
||||||
- Unified app version: Use a single SemVer for the product (e.g., `2025.1.0-beta.3`) — simplest for users and release management.
|
|
||||||
- Pre-releases: Use identifiers like `-alpha.N`, `-beta.N`, `-rc.N` for stage tracking.
|
|
||||||
- Build metadata: Optionally include component build info (non-ordering) e.g., `+api.abcd123,dash.efgh456,sch.jkl789,wkr.mno012`.
|
|
||||||
- Component traceability: Document component SHAs or image tags under each TECH-CHANGELOG release entry rather than exposing separate user-facing versions.
|
|
||||||
- Hotfixes: For backend-only fixes, prefer a patch bump or pre-release increment, and record component metadata under the unified version.
|
|
||||||
|
|
||||||
## 📁 Project Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
infoscreen_2025/
|
|
||||||
├── dashboard/ # React frontend
|
|
||||||
│ ├── src/ # React components and logic
|
|
||||||
│ ├── public/ # Static assets
|
|
||||||
│ └── Dockerfile # Production build
|
|
||||||
├── server/ # Flask API backend
|
|
||||||
│ ├── routes/ # API endpoints
|
|
||||||
│ ├── alembic/ # Database migrations
|
|
||||||
│ ├── media/ # File storage
|
|
||||||
│ ├── initialize_database.py # All-in-one DB initialization (dev)
|
|
||||||
│ └── worker.py # Background jobs
|
|
||||||
├── listener/ # MQTT listener service
|
|
||||||
├── scheduler/ # Event scheduling service
|
|
||||||
├── models/ # Shared database models
|
|
||||||
├── mosquitto/ # MQTT broker configuration
|
|
||||||
├── certs/ # SSL certificates
|
|
||||||
├── docker-compose.yml # Development setup
|
|
||||||
├── docker-compose.prod.yml # Production setup
|
|
||||||
└── Makefile # Development shortcuts
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 Development
|
|
||||||
|
|
||||||
### Available Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Development
|
|
||||||
make up # Start dev stack
|
|
||||||
make down # Stop dev stack
|
|
||||||
make logs # View all logs
|
|
||||||
make logs-server # View specific service logs
|
|
||||||
|
|
||||||
# Building & Deployment
|
|
||||||
make build # Build all images
|
|
||||||
make push # Push to registry
|
|
||||||
make pull-prod # Pull production images
|
|
||||||
make up-prod # Start production stack
|
|
||||||
|
|
||||||
# Maintenance
|
|
||||||
make health # Health checks
|
|
||||||
make fix-perms # Fix file permissions
|
|
||||||
```
|
|
||||||
|
|
||||||
### Database Management
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# One-shot initialization (schema + defaults + academic periods)
|
|
||||||
python server/initialize_database.py
|
|
||||||
|
|
||||||
# Access database directly
|
|
||||||
docker exec -it infoscreen-db mysql -u${DB_USER} -p${DB_PASSWORD} ${DB_NAME}
|
|
||||||
|
|
||||||
# Run migrations
|
|
||||||
docker exec -it infoscreen-api alembic upgrade head
|
|
||||||
|
|
||||||
# Initialize academic periods (Austrian school system)
|
|
||||||
docker exec -it infoscreen-api python init_academic_periods.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### MQTT Testing
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Subscribe to all topics
|
|
||||||
mosquitto_sub -h localhost -t "infoscreen/#" -v
|
|
||||||
|
|
||||||
# Publish test message
|
|
||||||
mosquitto_pub -h localhost -t "infoscreen/test" -m "Hello World"
|
|
||||||
|
|
||||||
# Monitor client heartbeats
|
|
||||||
mosquitto_sub -h localhost -t "infoscreen/+/heartbeat" -v
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🌐 API Endpoints
|
|
||||||
|
|
||||||
### Core Resources
|
|
||||||
- `GET /api/clients` - List all registered clients
|
|
||||||
- `PUT /api/clients/{uuid}/group` - Assign client to group
|
|
||||||
- `GET /api/groups` - List client groups with alive status
|
|
||||||
- `GET /api/groups/order` - Get saved group display order
|
|
||||||
- `POST /api/groups/order` - Save group display order (array of group IDs)
|
|
||||||
- `GET /api/events` - List events with filtering
|
|
||||||
- `POST /api/events` - Create new event
|
|
||||||
- `POST /api/events/{id}/occurrences/{date}/detach` - Detach single occurrence from recurring series
|
|
||||||
- `GET /api/academic_periods` - List academic periods
|
|
||||||
- `POST /api/academic_periods/active` - Set active period
|
|
||||||
|
|
||||||
### File Management
|
|
||||||
- `POST /api/files` - Upload media files
|
|
||||||
- `GET /api/files/{path}` - Download files
|
|
||||||
- `GET /api/files/converted/{path}` - Download converted PDFs
|
|
||||||
- `POST /api/conversions/{media_id}/pdf` - Request conversion
|
|
||||||
- `GET /api/conversions/{media_id}/status` - Check conversion status
|
|
||||||
- `GET /api/eventmedia/stream/<media_id>/<filename>` - Stream media with byte-range support (206) for seeking
|
|
||||||
- `POST /api/clients/{uuid}/screenshot` - Upload screenshot for client (base64 JPEG, optional `timestamp`, optional `screenshot_type` = `periodic|event_start|event_stop`)
|
|
||||||
- **Screenshot retention:** The API stores `{uuid}.jpg` as latest plus the last 20 timestamped screenshots per client; older timestamped files are deleted automatically.
|
|
||||||
- **Priority screenshots:** For `event_start`/`event_stop`, the API also keeps `{uuid}_priority.jpg` and metadata (`{uuid}_meta.json`) used by monitoring priority selection.
|
|
||||||
|
|
||||||
### System Settings
|
|
||||||
- `GET /api/system-settings` - List all system settings (admin+)
|
|
||||||
- `GET /api/system-settings/{key}` - Get a specific setting (admin+)
|
|
||||||
- `POST /api/system-settings/{key}` - Create or update a setting (admin+)
|
|
||||||
- `DELETE /api/system-settings/{key}` - Delete a setting (admin+)
|
|
||||||
- `GET /api/system-settings/supplement-table` - Get WebUntis/Vertretungsplan settings (enabled, url)
|
|
||||||
- `POST /api/system-settings/supplement-table` - Update WebUntis/Vertretungsplan settings
|
|
||||||
- Presentation defaults stored as keys:
|
|
||||||
- `presentation_interval` (seconds, default "10")
|
|
||||||
- `presentation_page_progress` ("true"/"false", default "true")
|
|
||||||
- `presentation_auto_progress` ("true"/"false", default "true")
|
|
||||||
- Video defaults stored as keys:
|
|
||||||
- `video_autoplay` ("true"/"false", default "true")
|
|
||||||
- `video_loop` ("true"/"false", default "true")
|
|
||||||
- `video_volume` (0.0–1.0, default "0.8")
|
|
||||||
- `video_muted` ("true"/"false", default "false")
|
|
||||||
|
|
||||||
### User Management (Admin+)
|
|
||||||
- `GET /api/users` - List all users (role-filtered by user's role)
|
|
||||||
- `POST /api/users` - Create new user with username, password (min 6 chars), role, and status
|
|
||||||
- `GET /api/users/<id>` - Get user details including audit information (login times, password changes, deactivation)
|
|
||||||
- `PUT /api/users/<id>` - Update user (cannot change own role or account status)
|
|
||||||
- `PUT /api/users/<id>/password` - Admin password reset (cannot reset own password this way; use `/api/auth/change-password` instead)
|
|
||||||
- `DELETE /api/users/<id>` - Delete user permanently (superadmin only; cannot delete self)
|
|
||||||
|
|
||||||
### Authentication
|
|
||||||
- `POST /api/auth/login` - User login (tracks last login time and failed attempts)
|
|
||||||
- `POST /api/auth/logout` - User logout
|
|
||||||
- `PUT /api/auth/change-password` - Self-service password change (all authenticated users; requires current password verification)
|
|
||||||
|
|
||||||
### Health & Monitoring
|
|
||||||
- `GET /health` - Service health check
|
|
||||||
- `GET /screenshots/{uuid}.jpg` - Latest client screenshot
|
|
||||||
- `GET /screenshots/{uuid}/priority` - Active high-priority screenshot (falls back to latest)
|
|
||||||
- `GET /api/client-logs/monitoring-overview` - Aggregated monitoring overview for dashboard (superadmin)
|
|
||||||
- `GET /api/client-logs/recent-errors` - Recent error feed across clients (admin+)
|
|
||||||
- `GET /api/client-logs/{uuid}/logs` - Filtered per-client logs (admin+)
|
|
||||||
|
|
||||||
## 🎨 Frontend Features
|
|
||||||
|
|
||||||
### API Response Format
|
|
||||||
- **JSON Convention**: All API endpoints return camelCase JSON (e.g., `startTime`, `endTime`, `groupId`). Frontend consumes camelCase directly.
|
|
||||||
- **UTC Time Parsing**: API returns ISO strings without 'Z' suffix. Frontend appends 'Z' before parsing to ensure UTC interpretation: `const utcString = dateStr.endsWith('Z') ? dateStr : dateStr + 'Z'; new Date(utcString);`. Display uses `toLocaleTimeString('de-DE')` for German format.
|
|
||||||
|
|
||||||
### Recurrence & holidays
|
|
||||||
- Recurrence is handled natively by Syncfusion. The API returns master events with `RecurrenceRule` and `RecurrenceException` (EXDATE) in RFC 5545 format (yyyyMMddTHHmmssZ, UTC) so the Scheduler excludes holiday instances reliably.
|
|
||||||
- Events with "skip holidays" display a TentTree icon next to the main event icon (icon color: black). The Scheduler’s native lower-right recurrence badge indicates series membership.
|
|
||||||
- Single occurrence editing: Users can edit either a single occurrence or the entire series. The UI persists changes using `onActionCompleted (requestType='eventChanged')`:
|
|
||||||
- Single occurrence → `POST /api/events/<id>/occurrences/<date>/detach` (creates standalone event and adds EXDATE to master)
|
|
||||||
- Series/single event → `PUT /api/events/<id>`
|
|
||||||
|
|
||||||
### Syncfusion Components Used (Material 3)
|
|
||||||
- **Schedule**: Event calendar with drag-drop support
|
|
||||||
- **Grid**: Data tables with filtering and sorting
|
|
||||||
- **DropDownList**: Group and period selectors
|
|
||||||
- **FileManager**: Media upload and organization
|
|
||||||
- **Kanban**: Task management views
|
|
||||||
- **Notifications**: Toast messages and alerts
|
|
||||||
- **Pager**: Used on Programinfo changelog for pagination
|
|
||||||
- **Cards (layouts)**: Programinfo sections styled with Syncfusion card classes
|
|
||||||
- **SplitButtons**: Header user menu (top-right) using Syncfusion DropDownButton to show current user and role, with actions "Passwort ändern", "Profil", and "Abmelden".
|
|
||||||
|
|
||||||
### Pages Overview
|
|
||||||
- **Dashboard**: Card-based overview of all Raumgruppen (room groups) with real-time status monitoring. Features include:
|
|
||||||
- Global statistics: total infoscreens, online/offline counts, warning groups
|
|
||||||
- Filter buttons: All / Online / Offline / Warnings with dynamic counts
|
|
||||||
- Per-group cards showing currently active event (title, type, date/time in local timezone)
|
|
||||||
- Health bar with online/offline ratio and color-coded status
|
|
||||||
- Expandable client list with last alive timestamps
|
|
||||||
- Bulk restart button for offline clients
|
|
||||||
- Auto-refresh every 15 seconds; manual refresh button available
|
|
||||||
- **Clients**: Device management and monitoring
|
|
||||||
- **Groups**: Client group organization
|
|
||||||
- **Events**: Schedule management
|
|
||||||
- **Media**: File upload and conversion
|
|
||||||
- **Users**: Comprehensive user management (admin+ only in menu)
|
|
||||||
- Full CRUD interface with sortable GridComponent (20 per page)
|
|
||||||
- Statistics cards: total, active, inactive user counts
|
|
||||||
- Create, edit, delete, and password reset dialogs
|
|
||||||
- User details modal showing audit information (login times, password changes, deactivation)
|
|
||||||
- Role badges with color coding (user: gray, editor: blue, admin: green, superadmin: red)
|
|
||||||
- Self-protection: cannot modify own account (cannot change role/status or delete self)
|
|
||||||
- Superadmin-only hard delete; other users soft-deactivate
|
|
||||||
- **Settings**: Central configuration (tabbed)
|
|
||||||
- 📅 Academic Calendar (all users):
|
|
||||||
- 📥 Import & Liste: CSV/TXT import combined with holidays list
|
|
||||||
- 🗂️ Perioden: Academic Periods (set active period)
|
|
||||||
- 🖥️ Display & Clients (admin+): Defaults placeholders and quick links to Clients/Groups
|
|
||||||
- 🎬 Media & Files (admin+): Upload settings placeholders and Conversion status overview
|
|
||||||
- 🗓️ Events (admin+): WebUntis/Vertretungsplan URL enable/disable, save, preview. Presentations: general defaults for slideshow interval, page-progress, and auto-progress; persisted via `/api/system-settings` keys and applied on create in the event modal. Videos: system-wide defaults for `autoplay`, `loop`, `volume`, and `muted`; persisted via `/api/system-settings` keys and applied on create in the event modal.
|
|
||||||
- ⚙️ System (superadmin): Organization info and Advanced configuration placeholders
|
|
||||||
- **Holidays**: Academic calendar management
|
|
||||||
- **Ressourcen**: Timeline view of active events across all room groups
|
|
||||||
- Parallel timeline display showing all groups and their current events simultaneously
|
|
||||||
- Compact visualization: 65px row height per group with color-coded event bars
|
|
||||||
- Day and week views for flexible time range inspection
|
|
||||||
- Customizable group ordering with visual drag controls (order persisted to backend)
|
|
||||||
- Real-time event status: shows currently running events with type, title, and time window
|
|
||||||
- Filters out unassigned groups for focused view
|
|
||||||
- Resource-based Syncfusion timeline scheduler with resize and drag-drop support
|
|
||||||
- **Monitoring**: Superadmin-only monitoring dashboard
|
|
||||||
- Live client health states (`healthy`, `warning`, `critical`, `offline`) from heartbeat/process/log data
|
|
||||||
- Latest screenshot preview with screenshot-type badges (`periodic`, `event_start`, `event_stop`) and process metadata per client
|
|
||||||
- Active priority screenshots are surfaced immediately and polled faster while priority items are active
|
|
||||||
- System-wide recent error stream and per-client log drill-down
|
|
||||||
- **Program info**: Version, build info, tech stack and paginated changelog (reads `dashboard/public/program-info.json`)
|
|
||||||
|
|
||||||
## 🔒 Security & Authentication
|
|
||||||
|
|
||||||
- **Role-Based Access Control (RBAC)**: 4-tier hierarchy (user → editor → admin → superadmin) with privilege escalation protection
|
|
||||||
- Admin cannot see, manage, or create superadmin accounts
|
|
||||||
- Admin can create and manage user/editor/admin roles only
|
|
||||||
- Superadmin can manage all roles including other superadmins
|
|
||||||
- Role-gated menu visibility: users only see menu items they have permission for
|
|
||||||
- **Account Management**:
|
|
||||||
- Soft-delete by default (deactivated_at, deactivated_by timestamps)
|
|
||||||
- Hard-delete superadmin-only (permanent removal from database)
|
|
||||||
- Self-account protections: cannot change own role/status, cannot delete self via admin panel
|
|
||||||
- Self-service password change available to all authenticated users (requires current password verification)
|
|
||||||
- Admin password reset available for other users (no current password required)
|
|
||||||
- **Audit Tracking**: All user accounts track login times, password changes, failed login attempts, and deactivation history
|
|
||||||
- **Environment Variables**: Sensitive data via `.env`
|
|
||||||
- **SSL/TLS**: HTTPS support with custom certificates
|
|
||||||
- **MQTT Security**: Username/password authentication
|
|
||||||
- **Database**: Parameterized queries, connection pooling
|
|
||||||
- **File Uploads**: Type validation, size limits
|
|
||||||
- **CORS**: Configured for production deployment
|
|
||||||
|
|
||||||
## 📊 Monitoring & Logging
|
|
||||||
|
|
||||||
### Health Checks
|
|
||||||
- Database: Connection and initialization status
|
|
||||||
- MQTT: Pub/sub functionality test
|
|
||||||
- Dashboard: Nginx availability
|
|
||||||
- **Scheduler**: Logging is concise; conversion lookups are cached and logged only once per media.
|
|
||||||
- Monitoring API: `/api/client-logs/monitoring-overview` and `/api/client-logs/recent-errors` for live diagnostics
|
|
||||||
- Monitoring overview includes screenshot priority state (`latestScreenshotType`, `priorityScreenshotType`, `priorityScreenshotReceivedAt`, `hasActivePriorityScreenshot`) and `summary.activePriorityScreenshots`
|
|
||||||
|
|
||||||
### Logging Strategy
|
|
||||||
- **Development**: Docker Compose logs with service prefixes
|
|
||||||
- **Production**: Centralized logging via Docker log drivers
|
|
||||||
- **MQTT**: Message-level debugging available
|
|
||||||
- **Database**: Query logging in development mode
|
|
||||||
|
|
||||||
## 🌍 Deployment Options
|
|
||||||
|
|
||||||
### Development
|
### Development
|
||||||
- **Hot Reload**: Vite dev server + Flask debug mode
|
|
||||||
- **Volume Mounts**: Live code editing
|
|
||||||
- **Debug Ports**: Python debugger support (port 5678)
|
|
||||||
- **Local Certificates**: Self-signed SSL for testing
|
|
||||||
|
|
||||||
### Production
|
1. Clone
|
||||||
- **Optimized Builds**: Multi-stage Dockerfiles
|
|
||||||
- **Reverse Proxy**: Nginx with SSL termination
|
|
||||||
- **Health Monitoring**: Comprehensive healthchecks
|
|
||||||
- **Registry**: GitHub Container Registry integration
|
|
||||||
- **Scaling**: Docker Compose for single-node deployment
|
|
||||||
|
|
||||||
## 🤝 Contributing
|
|
||||||
|
|
||||||
1. Fork the repository
|
|
||||||
2. Create a feature branch: `git checkout -b feature/amazing-feature`
|
|
||||||
3. Commit your changes: `git commit -m 'Add amazing feature'`
|
|
||||||
4. Push to the branch: `git push origin feature/amazing-feature`
|
|
||||||
5. Open a Pull Request
|
|
||||||
|
|
||||||
### Development Guidelines
|
|
||||||
- Follow existing code patterns and naming conventions
|
|
||||||
- Add appropriate tests for new features
|
|
||||||
- Update documentation for API changes
|
|
||||||
- Use TypeScript for frontend development
|
|
||||||
- Follow Python PEP 8 for backend code
|
|
||||||
|
|
||||||
## 📋 Requirements
|
|
||||||
|
|
||||||
### System Requirements
|
|
||||||
- **CPU**: 2+ cores recommended
|
|
||||||
- **RAM**: 4GB minimum, 8GB recommended
|
|
||||||
- **Storage**: 20GB+ for media files and database
|
|
||||||
- **Network**: Reliable internet for client communication
|
|
||||||
|
|
||||||
### Software Dependencies
|
|
||||||
- Docker 24.0+
|
|
||||||
- Docker Compose 2.0+
|
|
||||||
- Git 2.30+
|
|
||||||
- Modern web browser (Chrome, Firefox, Safari, Edge)
|
|
||||||
|
|
||||||
## 🐛 Troubleshooting
|
|
||||||
|
|
||||||
### Common Issues
|
|
||||||
|
|
||||||
**Services won't start**
|
|
||||||
```bash
|
```bash
|
||||||
# Check service health
|
git clone https://github.com/RobbStarkAustria/infoscreen_2025.git
|
||||||
|
cd infoscreen_2025
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Configure environment
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
# edit values as needed
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Start stack
|
||||||
|
```bash
|
||||||
|
make up
|
||||||
|
# or: docker compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Initialize DB (first run)
|
||||||
|
```bash
|
||||||
|
python server/initialize_database.py
|
||||||
|
```
|
||||||
|
|
||||||
|
5. Open services
|
||||||
|
- Dashboard: http://localhost:5173
|
||||||
|
- API: http://localhost:8000
|
||||||
|
- MariaDB: localhost:3306
|
||||||
|
- MQTT: localhost:1883 (WS: 9001)
|
||||||
|
|
||||||
|
## Holiday Calendar (Quick Usage)
|
||||||
|
|
||||||
|
Settings path:
|
||||||
|
- `Settings` -> `Academic Calendar` -> `Ferienkalender: Import/Anzeige`
|
||||||
|
|
||||||
|
Workflow summary:
|
||||||
|
1. Select target academic period (archived periods are read-only/not selectable).
|
||||||
|
2. Import CSV/TXT or add/edit holidays manually.
|
||||||
|
3. Validation is period-scoped (out-of-period ranges are blocked).
|
||||||
|
4. Duplicate/overlap policy:
|
||||||
|
- exact duplicates: skipped/prevented
|
||||||
|
- same normalized `name+region` overlaps (including adjacent ranges): merged
|
||||||
|
- different-identity overlaps: conflict (manual blocked, import skipped with details)
|
||||||
|
5. Recurring events with `skip_holidays` are recalculated automatically after holiday changes.
|
||||||
|
|
||||||
|
## Common Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start/stop
|
||||||
|
make up
|
||||||
|
make down
|
||||||
|
|
||||||
|
# Logs
|
||||||
|
make logs
|
||||||
|
make logs-server
|
||||||
|
|
||||||
|
# Health
|
||||||
make health
|
make health
|
||||||
|
|
||||||
# View specific service logs
|
# Build/push/deploy
|
||||||
make logs-server
|
make build
|
||||||
make logs-db
|
make push
|
||||||
|
make pull-prod
|
||||||
|
make up-prod
|
||||||
```
|
```
|
||||||
|
|
||||||
**Database connection errors**
|
## Scheduler Runtime Flags
|
||||||
```bash
|
|
||||||
# Verify database is running
|
|
||||||
docker exec -it infoscreen-db mysqladmin ping
|
|
||||||
|
|
||||||
# Check credentials in .env file
|
Scheduler runtime defaults can be tuned with environment variables:
|
||||||
# Restart dependent services
|
|
||||||
|
- `POLL_INTERVAL_SECONDS` (default: `30`)
|
||||||
|
- `REFRESH_SECONDS` (default: `0`, disabled)
|
||||||
|
|
||||||
|
TV power coordination (server Phase 1, group-level intent only):
|
||||||
|
|
||||||
|
- `POWER_INTENT_PUBLISH_ENABLED` (default: `false`)
|
||||||
|
- `POWER_INTENT_HEARTBEAT_ENABLED` (default: `true`)
|
||||||
|
- `POWER_INTENT_EXPIRY_MULTIPLIER` (default: `3`)
|
||||||
|
- `POWER_INTENT_MIN_EXPIRY_SECONDS` (default: `90`)
|
||||||
|
|
||||||
|
Power intent topic contract for Phase 1:
|
||||||
|
|
||||||
|
- Topic: `infoscreen/groups/{group_id}/power/intent`
|
||||||
|
- QoS: `1`
|
||||||
|
- Retained: `true`
|
||||||
|
- Publish mode: transition publish + heartbeat republish each poll
|
||||||
|
- Schema version: `v1`
|
||||||
|
- Intent ID behavior: stable across unchanged heartbeat cycles; new UUID only on semantic transition (desired_state or reason change)
|
||||||
|
- Expiry rule: max(3 × poll_interval, 90 seconds)
|
||||||
|
|
||||||
|
Rollout strategy (Phase 1):
|
||||||
|
|
||||||
|
1. Keep `POWER_INTENT_PUBLISH_ENABLED=false` by default (disabled).
|
||||||
|
2. Enable in test environment first: set `POWER_INTENT_PUBLISH_ENABLED=true` on one canary group's scheduler instance.
|
||||||
|
3. Verify no unintended OFF between adjacent/overlapping events over 1–2 days.
|
||||||
|
4. Expand to 20% of production groups for 2 days (canary soak).
|
||||||
|
5. Monitor power-intent publish metrics (success rate, error rate, transition frequency) in scheduler logs.
|
||||||
|
6. Roll out to 100% once canary is stable (zero off-between-adjacent-events incidents).
|
||||||
|
7. Phase 2 (future): per-client override intents and state acknowledgments.
|
||||||
|
|
||||||
|
## Documentation Map
|
||||||
|
|
||||||
|
### Deployment
|
||||||
|
- [deployment-debian.md](deployment-debian.md)
|
||||||
|
- [deployment-ubuntu.md](deployment-ubuntu.md)
|
||||||
|
- [setup-deployment.sh](setup-deployment.sh)
|
||||||
|
|
||||||
|
### Backend & Database
|
||||||
|
- [DATABASE_GUIDE.md](DATABASE_GUIDE.md)
|
||||||
|
- [TECH-CHANGELOG.md](TECH-CHANGELOG.md)
|
||||||
|
- [server/alembic](server/alembic)
|
||||||
|
|
||||||
|
### Authentication & Authorization
|
||||||
|
- [AUTH_SYSTEM.md](AUTH_SYSTEM.md)
|
||||||
|
- [AUTH_QUICKREF.md](AUTH_QUICKREF.md)
|
||||||
|
- [userrole-management.md](userrole-management.md)
|
||||||
|
- [SUPERADMIN_SETUP.md](SUPERADMIN_SETUP.md)
|
||||||
|
|
||||||
|
### Monitoring, Screenshots, Health
|
||||||
|
- [CLIENT_MONITORING_SPECIFICATION.md](CLIENT_MONITORING_SPECIFICATION.md)
|
||||||
|
- [SCREENSHOT_IMPLEMENTATION.md](SCREENSHOT_IMPLEMENTATION.md)
|
||||||
|
|
||||||
|
### MQTT & Payloads
|
||||||
|
- [MQTT_EVENT_PAYLOAD_GUIDE.md](MQTT_EVENT_PAYLOAD_GUIDE.md)
|
||||||
|
|
||||||
|
### Events, Calendar, WebUntis
|
||||||
|
- [WEBUNTIS_EVENT_IMPLEMENTATION.md](WEBUNTIS_EVENT_IMPLEMENTATION.md)
|
||||||
|
|
||||||
|
### Historical Background
|
||||||
|
- [docs/archive/ACADEMIC_PERIODS_IMPLEMENTATION_SUMMARY.md](docs/archive/ACADEMIC_PERIODS_IMPLEMENTATION_SUMMARY.md)
|
||||||
|
- [docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md](docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md)
|
||||||
|
- [docs/archive/PHASE_3_CLIENT_MONITORING_IMPLEMENTATION.md](docs/archive/PHASE_3_CLIENT_MONITORING_IMPLEMENTATION.md)
|
||||||
|
- [docs/archive/CLEANUP_SUMMARY.md](docs/archive/CLEANUP_SUMMARY.md)
|
||||||
|
|
||||||
|
### Conversion / Media
|
||||||
|
- [pptx_conversion_guide_gotenberg.md](pptx_conversion_guide_gotenberg.md)
|
||||||
|
|
||||||
|
### Historical / Archived Docs
|
||||||
|
- [docs/archive/CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md](docs/archive/CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md) - completed implementation plan/history
|
||||||
|
- [docs/archive/MQTT_DASHBOARD_V1_TO_V2_MIGRATION.md](docs/archive/MQTT_DASHBOARD_V1_TO_V2_MIGRATION.md) - completed MQTT payload migration notes
|
||||||
|
- [docs/archive/PPTX_CONVERSION_LEGACY_APPROACH.md](docs/archive/PPTX_CONVERSION_LEGACY_APPROACH.md) - legacy conversion approach (superseded)
|
||||||
|
- [docs/archive/TV_POWER_PHASE_1_COORDINATION.md](docs/archive/TV_POWER_PHASE_1_COORDINATION.md) - TV power Phase 1 coordination tasklist
|
||||||
|
- [docs/archive/TV_POWER_PHASE_1_SERVER_HANDOFF.md](docs/archive/TV_POWER_PHASE_1_SERVER_HANDOFF.md) - TV power Phase 1 server handoff notes
|
||||||
|
- [docs/archive/TV_POWER_PHASE_1_CANARY_VALIDATION.md](docs/archive/TV_POWER_PHASE_1_CANARY_VALIDATION.md) - TV power Phase 1 canary validation checklist
|
||||||
|
- [docs/archive/TV_POWER_PHASE_1_IMPLEMENTATION_CHECKLIST.md](docs/archive/TV_POWER_PHASE_1_IMPLEMENTATION_CHECKLIST.md) - TV power Phase 1 implementation checklist
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- [FRONTEND_DESIGN_RULES.md](FRONTEND_DESIGN_RULES.md)
|
||||||
|
- [dashboard/README.md](dashboard/README.md)
|
||||||
|
|
||||||
|
### Project / Contributor Guidance
|
||||||
|
- [.github/copilot-instructions.md](.github/copilot-instructions.md)
|
||||||
|
- [AI-INSTRUCTIONS-MAINTENANCE.md](AI-INSTRUCTIONS-MAINTENANCE.md)
|
||||||
|
- [DEV-CHANGELOG.md](DEV-CHANGELOG.md)
|
||||||
|
|
||||||
|
### Active Implementation Plans
|
||||||
|
- [implementation-plans/reboot-implementation-handoff-share.md](implementation-plans/reboot-implementation-handoff-share.md)
|
||||||
|
- [implementation-plans/reboot-implementation-handoff-client-team.md](implementation-plans/reboot-implementation-handoff-client-team.md)
|
||||||
|
- [implementation-plans/reboot-kickoff-summary.md](implementation-plans/reboot-kickoff-summary.md)
|
||||||
|
|
||||||
|
## API Highlights
|
||||||
|
|
||||||
|
- Core resources: clients, groups, events, academic periods
|
||||||
|
- Client command lifecycle:
|
||||||
|
- `POST /api/clients/<uuid>/restart`
|
||||||
|
- `POST /api/clients/<uuid>/shutdown`
|
||||||
|
- `GET /api/clients/commands/<command_id>`
|
||||||
|
- Holidays: `GET/POST /api/holidays`, `POST /api/holidays/upload`, `PUT/DELETE /api/holidays/<id>`
|
||||||
|
- Media: upload/download/stream + conversion status
|
||||||
|
- Auth: login/logout/change-password
|
||||||
|
- Monitoring: logs and monitoring overview endpoints
|
||||||
|
|
||||||
|
For full endpoint details, use source route files under `server/routes/` and the docs listed above.
|
||||||
|
|
||||||
|
## Project Structure (Top Level)
|
||||||
|
|
||||||
|
```text
|
||||||
|
infoscreen_2025/
|
||||||
|
├── dashboard/ # React frontend
|
||||||
|
├── server/ # Flask API + migrations + worker
|
||||||
|
├── listener/ # MQTT listener
|
||||||
|
├── scheduler/ # Event scheduler/publisher
|
||||||
|
├── models/ # Shared SQLAlchemy models
|
||||||
|
├── mosquitto/ # MQTT broker config
|
||||||
|
├── certs/ # TLS certs (prod)
|
||||||
|
└── docker-compose*.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
**Vite import-analysis errors (Syncfusion splitbuttons)**
|
## Contributing
|
||||||
```bash
|
|
||||||
# Symptom
|
|
||||||
[plugin:vite:import-analysis] Failed to resolve import "@syncfusion/ej2-react-splitbuttons"
|
|
||||||
|
|
||||||
# Fix
|
1. Create branch
|
||||||
# 1) Ensure dependencies are added in dashboard/package.json:
|
2. Implement change + tests
|
||||||
# - @syncfusion/ej2-react-splitbuttons, @syncfusion/ej2-splitbuttons
|
3. Update relevant docs
|
||||||
# 2) In dashboard/vite.config.ts, add to optimizeDeps.include:
|
4. Open PR
|
||||||
# '@syncfusion/ej2-react-splitbuttons', '@syncfusion/ej2-splitbuttons'
|
|
||||||
# 3) If dashboard uses a named node_modules volume, recreate it so npm ci runs inside the container:
|
|
||||||
docker compose rm -sf dashboard
|
|
||||||
docker volume rm <project>_dashboard-node-modules <project>_dashboard-vite-cache || true
|
|
||||||
docker compose up -d --build dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
**MQTT communication issues**
|
Guidelines:
|
||||||
```bash
|
- Match existing architecture and naming conventions
|
||||||
# Test MQTT broker
|
- Keep frontend aligned with [FRONTEND_DESIGN_RULES.md](FRONTEND_DESIGN_RULES.md)
|
||||||
mosquitto_pub -h localhost -t test -m "hello"
|
- Keep service/API behavior aligned with [.github/copilot-instructions.md](.github/copilot-instructions.md)
|
||||||
|
|
||||||
# Check client certificates and credentials
|
## License
|
||||||
# Verify firewall settings for ports 1883/9001
|
|
||||||
```
|
|
||||||
|
|
||||||
**File conversion problems**
|
MIT License. See [LICENSE](LICENSE).
|
||||||
```bash
|
|
||||||
# Check Gotenberg service
|
|
||||||
curl http://localhost:3000/health
|
|
||||||
|
|
||||||
# Monitor worker logs
|
|
||||||
make logs-worker
|
|
||||||
|
|
||||||
# Check Redis queue status
|
|
||||||
docker exec -it infoscreen-redis redis-cli LLEN conversions
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📄 License
|
|
||||||
|
|
||||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
||||||
|
|
||||||
## 🙏 Acknowledgments
|
|
||||||
|
|
||||||
- **Syncfusion**: UI components for React dashboard
|
|
||||||
- **Eclipse Mosquitto**: MQTT broker implementation
|
|
||||||
- **Gotenberg**: Document conversion service
|
|
||||||
- **MariaDB**: Reliable database engine
|
|
||||||
- **Flask**: Python web framework
|
|
||||||
- **React**: Frontend user interface library
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
For detailed technical documentation, deployment guides, and API specifications, please refer to the additional documentation files in this repository.
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
- Tailwind CSS was removed. Styling is managed via Syncfusion Material 3 theme imports in `dashboard/src/main.tsx`.
|
|
||||||
|
|
||||||
## 🧭 Changelog Style Guide
|
|
||||||
|
|
||||||
When adding entries to `dashboard/public/program-info.json` (displayed on the Program info page):
|
|
||||||
|
|
||||||
- Structure per release
|
|
||||||
- `version` (e.g., `2025.1.0-alpha.8`)
|
|
||||||
- `date` in `YYYY-MM-DD` (ISO format)
|
|
||||||
- `changes`: array of short bullet strings
|
|
||||||
|
|
||||||
- Categories (Keep a Changelog inspired)
|
|
||||||
- Prefer starting bullets with an implicit category or an emoji, e.g.:
|
|
||||||
- Added (🆕/✨), Changed (🔧/🛠️), Fixed (🐛/✅), Removed (🗑️), Security (🔒), Deprecated (⚠️)
|
|
||||||
|
|
||||||
- Writing rules
|
|
||||||
- Keep bullets concise (ideally one line) and user-facing; avoid internal IDs or jargon
|
|
||||||
- Put the affected area first when helpful (e.g., “UI: …”, “API: …”, “Scheduler: …”)
|
|
||||||
- Highlight breaking changes with “BREAKING:”
|
|
||||||
- Prefer German wording consistently; dates are localized at runtime for display
|
|
||||||
|
|
||||||
- Ordering and size
|
|
||||||
- Newest release first in the array
|
|
||||||
- Aim for ≤ 8–10 bullets per release; group or summarize if longer
|
|
||||||
|
|
||||||
- JSON hygiene
|
|
||||||
- Valid JSON only (no trailing commas); escape quotes as needed
|
|
||||||
- One release object per version; do not modify historical entries unless to correct typos
|
|
||||||
|
|
||||||
The Program info page paginates older entries (default page size 5). Keep highlights at the top of each release for scanability.
|
|
||||||
|
|||||||
149
RESTART_VALIDATION_CHECKLIST.md
Normal file
149
RESTART_VALIDATION_CHECKLIST.md
Normal file
@@ -0,0 +1,149 @@
|
|||||||
|
# Restart Validation Checklist
|
||||||
|
|
||||||
|
Purpose: Validate end-to-end restart command flow after MQTT auth hardening.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- API command issue route: `POST /api/clients/{uuid}/restart`
|
||||||
|
- MQTT command topic: `infoscreen/{uuid}/commands` (compat: `infoscreen/{uuid}/command`)
|
||||||
|
- MQTT ACK topic: `infoscreen/{uuid}/commands/ack` (compat: `infoscreen/{uuid}/command/ack`)
|
||||||
|
- Status API: `GET /api/clients/commands/{command_id}`
|
||||||
|
|
||||||
|
## Preconditions
|
||||||
|
|
||||||
|
- Stack is up and healthy (`db`, `mqtt`, `server`, `listener`, `scheduler`).
|
||||||
|
- You have an `admin` or `superadmin` account.
|
||||||
|
- At least one canary client is online and can process restart commands.
|
||||||
|
- `.env` has valid `MQTT_USER` / `MQTT_PASSWORD`.
|
||||||
|
|
||||||
|
## 1) Open Monitoring Session (MQTT)
|
||||||
|
|
||||||
|
On host/server:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
set -a
|
||||||
|
. ./.env
|
||||||
|
set +a
|
||||||
|
|
||||||
|
mosquitto_sub -h 127.0.0.1 -p 1883 \
|
||||||
|
-u "$MQTT_USER" -P "$MQTT_PASSWORD" \
|
||||||
|
-t "infoscreen/+/commands" \
|
||||||
|
-t "infoscreen/+/commands/ack" \
|
||||||
|
-t "infoscreen/+/command" \
|
||||||
|
-t "infoscreen/+/command/ack" \
|
||||||
|
-v
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
- Command publish appears on `infoscreen/{uuid}/commands`.
|
||||||
|
- ACK(s) appear on `infoscreen/{uuid}/commands/ack`.
|
||||||
|
|
||||||
|
## 2) Login and Keep Session Cookie
|
||||||
|
|
||||||
|
```bash
|
||||||
|
API_BASE="http://127.0.0.1:8000"
|
||||||
|
USER="<admin_or_superadmin_username>"
|
||||||
|
PASS="<password>"
|
||||||
|
|
||||||
|
curl -sS -X POST "$API_BASE/api/auth/login" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"username\":\"$USER\",\"password\":\"$PASS\"}" \
|
||||||
|
-c /tmp/infoscreen-cookies.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
- Login success response.
|
||||||
|
- Cookie jar file created at `/tmp/infoscreen-cookies.txt`.
|
||||||
|
|
||||||
|
## 3) Pick Target Client UUID
|
||||||
|
|
||||||
|
Option A: Use known canary UUID.
|
||||||
|
|
||||||
|
Option B: query alive clients:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sS "$API_BASE/api/clients/with_alive_status" -b /tmp/infoscreen-cookies.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
Choose one `uuid` where `is_alive` is `true`.
|
||||||
|
|
||||||
|
## 4) Issue Restart Command
|
||||||
|
|
||||||
|
```bash
|
||||||
|
CLIENT_UUID="<target_uuid>"
|
||||||
|
|
||||||
|
curl -sS -X POST "$API_BASE/api/clients/$CLIENT_UUID/restart" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-b /tmp/infoscreen-cookies.txt \
|
||||||
|
-d '{"reason":"canary_restart_validation"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
- HTTP `202` on success.
|
||||||
|
- JSON includes `command.commandId` and initial status around `published`.
|
||||||
|
- In MQTT monitor, a command payload with:
|
||||||
|
- `schema_version: "1.0"`
|
||||||
|
- `action: "reboot_host"`
|
||||||
|
- matching `command_id`.
|
||||||
|
|
||||||
|
## 5) Poll Command Lifecycle Until Terminal
|
||||||
|
|
||||||
|
```bash
|
||||||
|
COMMAND_ID="<command_id_from_previous_step>"
|
||||||
|
|
||||||
|
for i in $(seq 1 20); do
|
||||||
|
curl -sS "$API_BASE/api/clients/commands/$COMMAND_ID" -b /tmp/infoscreen-cookies.txt
|
||||||
|
echo
|
||||||
|
sleep 3
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected status progression (typical):
|
||||||
|
- `queued` -> `publish_in_progress` -> `published` -> `ack_received` -> `execution_started` -> `completed`
|
||||||
|
|
||||||
|
Failure/alternate terminal states:
|
||||||
|
- `failed` (check `errorCode` / `errorMessage`)
|
||||||
|
- `blocked_safety` (reboot lockout triggered)
|
||||||
|
|
||||||
|
## 6) Validate Offline/Timeout Behavior
|
||||||
|
|
||||||
|
- Repeat step 4 for an offline client (or stop client process first).
|
||||||
|
- Confirm command does not falsely end as `completed`.
|
||||||
|
- Confirm status remains non-success and has usable failure diagnostics.
|
||||||
|
|
||||||
|
## 7) Validate Safety Lockout
|
||||||
|
|
||||||
|
Current lockout in API route:
|
||||||
|
- Threshold: 3 reboot commands
|
||||||
|
- Window: 15 minutes
|
||||||
|
|
||||||
|
Test:
|
||||||
|
- Send 4 restart commands quickly for same `uuid`.
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
- One request returns HTTP `429`.
|
||||||
|
- Command entry state `blocked_safety` with lockout error details.
|
||||||
|
|
||||||
|
## 8) Service Log Spot Check
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose logs --tail=150 server listener mqtt
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
- No MQTT auth errors (`Not authorized`, `Connection Refused: not authorised`).
|
||||||
|
- Listener logs show ACK processing for `command_id`.
|
||||||
|
|
||||||
|
## 9) Acceptance Criteria
|
||||||
|
|
||||||
|
- Restart command publish is visible on MQTT.
|
||||||
|
- ACK is received and mapped by listener.
|
||||||
|
- Status endpoint reaches correct terminal state.
|
||||||
|
- Safety lockout works under repeated restart attempts.
|
||||||
|
- No auth regression in broker/service logs.
|
||||||
|
|
||||||
|
## Cleanup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -f /tmp/infoscreen-cookies.txt
|
||||||
|
```
|
||||||
@@ -5,6 +5,105 @@
|
|||||||
|
|
||||||
This changelog documents technical and developer-relevant changes included in public releases. For development workspace changes, see DEV-CHANGELOG.md. Not all changes here are reflected in the user-facing changelog (`program-info.json`), and not all UI/feature changes are repeated here. Some changes (e.g., backend refactoring, API adjustments, infrastructure, developer tooling, or internal logic) may only appear in TECH-CHANGELOG.md. For UI/feature changes, see `dashboard/public/program-info.json`.
|
This changelog documents technical and developer-relevant changes included in public releases. For development workspace changes, see DEV-CHANGELOG.md. Not all changes here are reflected in the user-facing changelog (`program-info.json`), and not all UI/feature changes are repeated here. Some changes (e.g., backend refactoring, API adjustments, infrastructure, developer tooling, or internal logic) may only appear in TECH-CHANGELOG.md. For UI/feature changes, see `dashboard/public/program-info.json`.
|
||||||
|
|
||||||
|
## Unreleased
|
||||||
|
- <20> **Crash detection, auto-recovery, and service_failed monitoring (2026-04-05)**:
|
||||||
|
- Added `GET /api/clients/crashed` endpoint: returns active clients with `process_status=crashed` or stale heartbeat beyond grace period, with `crash_reason` field.
|
||||||
|
- Added `restart_app` command action alongside existing `reboot_host`/`shutdown_host`; registered in `server/routes/clients.py` with same safety lockout.
|
||||||
|
- Scheduler: Added crash auto-recovery loop (feature-flagged via `CRASH_RECOVERY_ENABLED`): scans candidates via `get_crash_recovery_candidates()`, issues `reboot_host` command per client, publishes to primary + compat MQTT topics, updates command lifecycle.
|
||||||
|
- Scheduler: Added unconditional command expiry sweep each poll cycle via `sweep_expired_commands()` in `scheduler/db_utils.py`: marks non-terminal `ClientCommand` rows with `expires_at < now` as `expired`.
|
||||||
|
- Added `service_failed` topic ingestion in `listener/listener.py`: subscribe to `infoscreen/+/service_failed` on every connect; persist `service_failed_at` and `service_failed_unit` on Client; empty payload (retain clear) ignored.
|
||||||
|
- Added `broker_connection` block extraction in health payload handler: persists `mqtt_reconnect_count` and `mqtt_last_disconnect_at` from `infoscreen/{uuid}/health`.
|
||||||
|
- Added four new DB columns to `clients` table via migration `b1c2d3e4f5a6`: `service_failed_at`, `service_failed_unit`, `mqtt_reconnect_count`, `mqtt_last_disconnect_at`.
|
||||||
|
- Added `GET /api/clients/service_failed` endpoint: lists clients with `service_failed_at` set, ordered by event time desc.
|
||||||
|
- Added `POST /api/clients/<uuid>/clear_service_failed` endpoint: clears DB flag and publishes empty retained MQTT message to clear `infoscreen/{uuid}/service_failed`.
|
||||||
|
- Monitoring overview API (`GET /api/client-logs/monitoring-overview`) now includes `mqtt_reconnect_count` and `mqtt_last_disconnect_at` per client.
|
||||||
|
- Frontend: Added orange service-failed alert panel to monitoring page (hidden when empty, auto-refresh 15s, per-row Quittieren button with loading/success/error states).
|
||||||
|
- Frontend: Client detail panel in monitoring now shows MQTT reconnect count and last disconnect timestamp.
|
||||||
|
- Frontend: Added `ServiceFailedClient`, `ServiceFailedClientsResponse` types; `fetchServiceFailedClients()` and `clearServiceFailed()` API helpers in `dashboard/src/apiClients.ts`.
|
||||||
|
- Added `service_failed` topic contract to `MQTT_EVENT_PAYLOAD_GUIDE.md`.
|
||||||
|
- <20>🔐 **MQTT auth hardening for server-side services (2026-04-03)**:
|
||||||
|
- `listener/listener.py` now uses env-based broker connectivity for host/port and credentials (`MQTT_BROKER_HOST`, `MQTT_BROKER_PORT`, `MQTT_USER`, `MQTT_PASSWORD`) instead of anonymous fixed `mqtt:1883`.
|
||||||
|
- `scheduler/scheduler.py` now uses the same env-based MQTT auth path and optional TLS toggles (`MQTT_TLS_ENABLED`, `MQTT_TLS_CA_CERT`, `MQTT_TLS_CERTFILE`, `MQTT_TLS_KEYFILE`, `MQTT_TLS_INSECURE`).
|
||||||
|
- `docker-compose.yml` and `docker-compose.override.yml` now pass MQTT credentials into listener and scheduler containers for consistent authenticated connections.
|
||||||
|
- Mosquitto is now configured for authenticated access (`allow_anonymous false`, `password_file /mosquitto/config/passwd`) and bootstraps credentials from env at container startup.
|
||||||
|
- MQTT healthcheck publish now authenticates with configured broker credentials.
|
||||||
|
- 🔁 **Client command lifecycle foundation (restart/shutdown) (2026-04-03)**:
|
||||||
|
- Added persistent command tracking model `ClientCommand` in `models/models.py` and Alembic migration `aa12bb34cc56_add_client_commands_table.py`.
|
||||||
|
- Upgraded `POST /api/clients/<uuid>/restart` from fire-and-forget publish to lifecycle-aware command issuance with command metadata (`command_id`, `issued_at`, `expires_at`, `reason`, `requested_by`).
|
||||||
|
- Added `POST /api/clients/<uuid>/shutdown` endpoint with the same lifecycle contract.
|
||||||
|
- Added `GET /api/clients/commands/<command_id>` status endpoint for command-state polling.
|
||||||
|
- Added restart safety lockout in API path: max 3 restart commands per client in rolling 15 minutes, returning `blocked_safety` when threshold is exceeded.
|
||||||
|
- Added command MQTT publish to `infoscreen/{uuid}/commands` (QoS1, non-retained) and temporary legacy restart compatibility publish to `clients/{uuid}/restart`.
|
||||||
|
- Added temporary topic compatibility publish to `infoscreen/{uuid}/command` and listener acceptance of `infoscreen/{uuid}/command/ack` to bridge singular/plural naming assumptions.
|
||||||
|
- Canonicalized command payload action values to host-level semantics: `reboot_host` and `shutdown_host` (API routes remain `/restart` and `/shutdown` for operator UX compatibility).
|
||||||
|
- Added frozen payload validation snippets for integration/client tooling in `implementation-plans/reboot-command-payload-schemas.md` and `implementation-plans/reboot-command-payload-schemas.json`.
|
||||||
|
- Listener now subscribes to `infoscreen/{uuid}/commands/ack` and maps client acknowledgements into command lifecycle states (`ack_received`, `execution_started`, `completed`, `failed`).
|
||||||
|
- Initial lifecycle statuses implemented server-side: `queued`, `publish_in_progress`, `published`, `failed`, and `blocked_safety`.
|
||||||
|
- Frontend API helper extended in `dashboard/src/apiClients.ts` with `ClientCommand` typing plus command APIs for shutdown and status polling preparation.
|
||||||
|
|
||||||
|
## 2026.1.0-alpha.16 (2026-04-02)
|
||||||
|
- 🐛 **Dashboard holiday banner refactoring and state fix (`dashboard/src/dashboard.tsx`)**:
|
||||||
|
- **Motivation — unstable fetch function:** `loadHolidayStatus` had `location.pathname` in its `useCallback` dependency array, causing a new function reference to be created on every navigation event. The `useEffect` depending on that reference then re-fired, producing overlapping API calls at mount that cancelled each other via the request-sequence guard, leaving the banner unresolved.
|
||||||
|
- **Refactoring:** Removed `location.pathname` from `useCallback` deps (it was unused inside the function body). The callback now has an empty dependency array, making its reference stable across the component lifetime. The `useEffect` is keyed only to the stable callback reference — no spurious re-fires.
|
||||||
|
- **Motivation — Syncfusion stale render:** Syncfusion's `MessageComponent` caches its rendered DOM internally and does not reactively update when React passes new children or props. Even after React state changed, the component displayed whatever text was rendered on first mount.
|
||||||
|
- **Fix:** Added a `key` prop derived from `${severity}:${text}` to `MessageComponent`. React unmounts and remounts the component whenever the key changes, bypassing Syncfusion's internal caching and ensuring the correct message is always visible.
|
||||||
|
- **Result:** Active-period name and holiday overlap details now render correctly on hard refresh, initial load, and route transitions without additional API calls.
|
||||||
|
- 🗓️ **Academic period bootstrap hardening (`server/init_academic_periods.py`)**:
|
||||||
|
- Refactored initialization into idempotent flow:
|
||||||
|
- seed default periods only when table is empty,
|
||||||
|
- on every run, activate exactly the non-archived period covering `date.today()`.
|
||||||
|
- Enforces single-active behavior by deactivating all previously active periods before setting the period for today.
|
||||||
|
- Emits explicit warning if no period covers current date (all remain inactive), improving operational diagnostics.
|
||||||
|
- 🚀 **Production startup alignment (`docker-compose.prod.yml`)**:
|
||||||
|
- Server startup command now runs `python /app/server/init_academic_periods.py` after migrations and default settings bootstrap.
|
||||||
|
- Removes manual post-deploy step to set an active academic period.
|
||||||
|
- 🌐 **Dashboard UX/text refinement (`dashboard/src/dashboard.tsx`)**:
|
||||||
|
- Converted user-facing transliterated German strings to proper Umlauts in the dashboard (for example: "für", "prüfen", "Ferienüberschneidungen", "Vorfälle", "Ausfälle").
|
||||||
|
|
||||||
|
Notes for integrators:
|
||||||
|
- On production boot, the active period is now derived from current date coverage automatically.
|
||||||
|
- If customer calendars do not include today, startup logs a warning and dashboard banner will still guide admins to configure periods.
|
||||||
|
|
||||||
|
## 2026.1.0-alpha.15 (2026-03-31)
|
||||||
|
- 🔌 **TV Power Intent Phase 1 (server-side)**:
|
||||||
|
- Scheduler now publishes retained QoS1 group-level intents to `infoscreen/groups/{group_id}/power/intent`.
|
||||||
|
- Implemented deterministic intent computation helpers in `scheduler/db_utils.py` (`compute_group_power_intent_basis`, `build_group_power_intent_body`, `compute_group_power_intent_fingerprint`).
|
||||||
|
- Implemented transition + heartbeat semantics in `scheduler/scheduler.py`: stable `intent_id` on heartbeat; new `intent_id` only on semantic transition.
|
||||||
|
- Added startup publish and MQTT reconnect republish behavior for retained intent continuity.
|
||||||
|
- Added poll-based expiry rule: `expires_at = issued_at + max(3 × poll_interval_sec, 90s)`.
|
||||||
|
- Added scheduler tests and canary validation artifacts: `scheduler/test_power_intent_utils.py`, `scheduler/test_power_intent_scheduler.py`, `test_power_intent_canary.py`, and `TV_POWER_CANARY_VALIDATION_CHECKLIST.md`.
|
||||||
|
- 🗃️ **Holiday data model scoping to academic periods**:
|
||||||
|
- Added period scoping for holidays via `SchoolHoliday.academic_period_id` (FK to academic periods) in `models/models.py`.
|
||||||
|
- Added Alembic migration `f3c4d5e6a7b8_scope_school_holidays_to_academic_.py` to introduce FK/index/constraint updates for period-aware holiday storage.
|
||||||
|
- Updated uniqueness semantics and indexing so holiday identity is evaluated in the selected academic period context.
|
||||||
|
- 🔌 **Holiday API hardening (`server/routes/holidays.py`)**:
|
||||||
|
- Extended to period-scoped workflows for list/import/manual CRUD.
|
||||||
|
- Added manual CRUD endpoints and behavior:
|
||||||
|
- `POST /api/holidays`
|
||||||
|
- `PUT /api/holidays/<id>`
|
||||||
|
- `DELETE /api/holidays/<id>`
|
||||||
|
- Enforced date-range validation against selected academic period for both import and manual writes.
|
||||||
|
- Added duplicate prevention (normalized name/region matching with null-safe handling).
|
||||||
|
- Implemented overlap policy:
|
||||||
|
- Same normalized `name+region` overlaps (including adjacent ranges) are merged.
|
||||||
|
- Different-identity overlaps are treated as conflicts (manual blocked, import skipped with details).
|
||||||
|
- Import responses now include richer counters/details (inserted/updated/merged/skipped/conflicts).
|
||||||
|
- 🔁 **Recurrence integration updates**:
|
||||||
|
- Event holiday-skip exception regeneration now resolves holidays by `academic_period_id` instead of global holiday sets.
|
||||||
|
- Updated event-side recurrence handling (`server/routes/events.py`) to keep EXDATE behavior in sync with period-scoped holidays.
|
||||||
|
- 🖥️ **Frontend integration (technical)**:
|
||||||
|
- Updated holiday API client (`dashboard/src/apiHolidays.ts`) for period-aware list/upload and manual CRUD operations.
|
||||||
|
- Settings holiday management (`dashboard/src/settings.tsx`) now binds import/list/manual CRUD to selected academic period and surfaces conflict/merge outcomes.
|
||||||
|
- Dashboard and appointments holiday data loading updated to active-period context.
|
||||||
|
- 📖 **Documentation & release alignment**:
|
||||||
|
- Updated `.github/copilot-instructions.md` with period-scoped holiday conventions, overlap policy, and settings behavior.
|
||||||
|
- Refactored root `README.md` to index-style documentation and archived historical implementation docs under `docs/archive/`.
|
||||||
|
- Synchronized release line with user-facing version `2026.1.0-alpha.15` in `dashboard/public/program-info.json`.
|
||||||
|
|
||||||
|
Notes for integrators:
|
||||||
|
- Holiday operations now require a clear academic period context; archived periods should be treated as read-only for holiday mutation flows.
|
||||||
|
- Existing recurrence flows depend on period-scoped holiday sets; verify period assignment for recurring master events when validating skip-holidays behavior.
|
||||||
|
|
||||||
## 2026.1.0-alpha.14 (2026-01-28)
|
## 2026.1.0-alpha.14 (2026-01-28)
|
||||||
- 🗓️ **Ressourcen Page (Timeline View)**:
|
- 🗓️ **Ressourcen Page (Timeline View)**:
|
||||||
- New frontend page: `dashboard/src/ressourcen.tsx` (357 lines) – Parallel timeline view showing active events for all room groups
|
- New frontend page: `dashboard/src/ressourcen.tsx` (357 lines) – Parallel timeline view showing active events for all room groups
|
||||||
|
|||||||
55
TODO.md
Normal file
55
TODO.md
Normal file
@@ -0,0 +1,55 @@
|
|||||||
|
# TODO
|
||||||
|
|
||||||
|
## MQTT TLS Hardening (Production)
|
||||||
|
|
||||||
|
- [ ] Enable TLS listener in `mosquitto/config/mosquitto.conf` (e.g., port 8883) while keeping 1883 only for temporary migration if needed.
|
||||||
|
- [ ] Generate and deploy server certificate + private key for Mosquitto (CA-signed or internal PKI).
|
||||||
|
- [ ] Add CA certificate distribution strategy for all clients and services (server, listener, scheduler, external monitors).
|
||||||
|
- [ ] Set strict file permissions for cert/key material (`chmod 600` for keys, least-privilege ownership).
|
||||||
|
- [ ] Update Docker Compose MQTT service to mount TLS cert/key/CA paths read-only.
|
||||||
|
- [ ] Add environment variables for TLS in `.env` / `.env.example`:
|
||||||
|
- `MQTT_TLS_ENABLED=true`
|
||||||
|
- `MQTT_TLS_CA_CERT=<path>`
|
||||||
|
- `MQTT_TLS_CERTFILE=<path>` (if mutual TLS used)
|
||||||
|
- `MQTT_TLS_KEYFILE=<path>` (if mutual TLS used)
|
||||||
|
- `MQTT_TLS_INSECURE=false`
|
||||||
|
- [ ] Switch internal services to TLS connection settings and verify authenticated reconnect behavior.
|
||||||
|
- [ ] Decide policy: TLS-only auth (username/password over TLS) vs mutual TLS + username/password.
|
||||||
|
- [ ] Disable non-TLS listener (1883) after all clients migrated.
|
||||||
|
- [ ] Restrict MQTT firewall ingress to trusted source ranges only.
|
||||||
|
- [ ] Add Mosquitto ACL file for topic-level permissions per role/client type.
|
||||||
|
- [ ] Add cert rotation process (renewal schedule, rollout, rollback steps).
|
||||||
|
- [ ] Add monitoring/alerting for certificate expiry and broker auth failures.
|
||||||
|
- [ ] Add runbook section for external monitoring clients (how to connect with CA validation).
|
||||||
|
- [ ] Perform a staged rollout (canary group first), then full migration.
|
||||||
|
- [ ] Document final TLS contract in `MQTT_EVENT_PAYLOAD_GUIDE.md` and deployment docs.
|
||||||
|
|
||||||
|
## Client Recovery Paths
|
||||||
|
|
||||||
|
### Path 1 — Software running → restart via MQTT ✅
|
||||||
|
- Server-side fully implemented (`restart_app` action, command lifecycle, monitoring panel).
|
||||||
|
- [ ] Client team: handle `restart_app` action in command handler (soft app restart, no reboot).
|
||||||
|
|
||||||
|
### Path 2 — Software crashed → MQTT unavailable
|
||||||
|
- Robust solution is **systemd `Restart=always`** (or `Restart=on-failure`) on the client device — no server involvement, OS init system restarts the process automatically.
|
||||||
|
- Server detects the crash via missing heartbeat (`process_status=crashed`), records it, and shows it in the monitoring panel. Recovery is confirmed when heartbeats resume.
|
||||||
|
- [ ] Client team: ensure the infoscreen service unit has `Restart=always` and `RestartSec=<delay>` configured in its systemd unit file.
|
||||||
|
- [ ] Evaluate whether MQTT `clean_session=False` + fixed `client_id` is worth adding for cases where the app crashes but the MQTT connection briefly survives (would allow QoS1 command delivery on reconnect).
|
||||||
|
- Note: the existing scheduler crash recovery (`reboot_host` via MQTT) is unreliable for a fully crashed app unless the client uses a persistent MQTT session. Revisit if client team enables `clean_session=False`.
|
||||||
|
|
||||||
|
### Path 3 — OS crashed / hung → power cycle needed (customer-dependent)
|
||||||
|
- No software-based recovery path is possible when the OS is unresponsive.
|
||||||
|
- Recovery requires external hardware intervention; options depend on customer infrastructure:
|
||||||
|
- Smart plug / PDU with API (e.g., Shelly, Tasmota, APC, Raritan)
|
||||||
|
- IPMI / iDRAC / BMC (server-class hardware)
|
||||||
|
- CEC power command from another device on the same HDMI chain
|
||||||
|
- Wake-on-LAN after a scheduled power-cut (limited applicability)
|
||||||
|
- [ ] Clarify with customer which hardware is available / acceptable.
|
||||||
|
- [ ] If a smart plug or PDU API is chosen: design a server-side "hard power cycle" command type and integration (out of scope until hardware is confirmed).
|
||||||
|
- [ ] Document chosen solution and integrate into monitoring runbook once decided.
|
||||||
|
|
||||||
|
## Optional Security Follow-ups
|
||||||
|
|
||||||
|
- [ ] Move MQTT credentials to Docker secrets or a vault-backed secret source.
|
||||||
|
- [ ] Rotate `MQTT_USER`/`MQTT_PASSWORD` on a fixed schedule.
|
||||||
|
- [ ] Add fail2ban/rate-limiting protections for exposed broker ports.
|
||||||
163
TV_POWER_INTENT_SERVER_CONTRACT_V1.md
Normal file
163
TV_POWER_INTENT_SERVER_CONTRACT_V1.md
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
# TV Power Intent — Server Contract v1 (Phase 1)
|
||||||
|
|
||||||
|
> This document is the stable reference for client-side implementation.
|
||||||
|
> The server implementation is validated and frozen at this contract.
|
||||||
|
> Last validated: 2026-04-01
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Topic
|
||||||
|
|
||||||
|
```
|
||||||
|
infoscreen/groups/{group_id}/power/intent
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Scope**: group-level only (Phase 1). No per-client topic in Phase 1.
|
||||||
|
- **QoS**: 1
|
||||||
|
- **Retained**: true — broker holds last payload; client receives it immediately on (re)connect.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Publish semantics
|
||||||
|
|
||||||
|
| Trigger | Behaviour |
|
||||||
|
|---|---|
|
||||||
|
| Semantic transition (state/reason changes) | New `intent_id`, immediate publish |
|
||||||
|
| No change (heartbeat) | Same `intent_id`, refreshed `issued_at` and `expires_at`, published every poll interval |
|
||||||
|
| Scheduler startup | Immediate publish before first poll wait |
|
||||||
|
| MQTT reconnect | Immediate retained republish of last known intent |
|
||||||
|
|
||||||
|
Poll interval default: **15 seconds** (dev) / **30 seconds** (prod).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Payload schema
|
||||||
|
|
||||||
|
All fields are always present. No optional fields for Phase 1 required fields.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"intent_id": "<uuid4>",
|
||||||
|
"group_id": <integer>,
|
||||||
|
"desired_state": "on" | "off",
|
||||||
|
"reason": "active_event" | "no_active_event",
|
||||||
|
"issued_at": "<ISO 8601 UTC with Z>",
|
||||||
|
"expires_at": "<ISO 8601 UTC with Z>",
|
||||||
|
"poll_interval_sec": <integer>,
|
||||||
|
"active_event_ids": [<integer>, ...],
|
||||||
|
"event_window_start": "<ISO 8601 UTC with Z>" | null,
|
||||||
|
"event_window_end": "<ISO 8601 UTC with Z>" | null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Field reference
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| `schema_version` | string | Always `"1.0"` in Phase 1 |
|
||||||
|
| `intent_id` | string (uuid4) | Stable across heartbeats; new value on semantic transition |
|
||||||
|
| `group_id` | integer | Matches the MQTT topic group_id |
|
||||||
|
| `desired_state` | `"on"` or `"off"` | The commanded TV power state |
|
||||||
|
| `reason` | string | Human-readable reason for current state |
|
||||||
|
| `issued_at` | UTC Z string | When this payload was computed |
|
||||||
|
| `expires_at` | UTC Z string | After this time, payload is stale; re-subscribe or treat as `off` |
|
||||||
|
| `poll_interval_sec` | integer | Server poll interval; expiry = max(3 × poll, 90s) |
|
||||||
|
| `active_event_ids` | integer array | IDs of currently active events; empty when `off` |
|
||||||
|
| `event_window_start` | UTC Z string or null | Start of merged active coverage window; null when `off` |
|
||||||
|
| `event_window_end` | UTC Z string or null | End of merged active coverage window; null when `off` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Expiry rule
|
||||||
|
|
||||||
|
```
|
||||||
|
expires_at = issued_at + max(3 × poll_interval_sec, 90s)
|
||||||
|
```
|
||||||
|
|
||||||
|
Default at poll=15s → expiry window = **90 seconds**.
|
||||||
|
|
||||||
|
**Client rule**: if `now > expires_at` treat as stale and fall back to `off` until a fresh payload arrives.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example payloads
|
||||||
|
|
||||||
|
### ON (active event)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"intent_id": "4a7fe3bc-3654-48e3-b5b9-9fad1f7fead3",
|
||||||
|
"group_id": 2,
|
||||||
|
"desired_state": "on",
|
||||||
|
"reason": "active_event",
|
||||||
|
"issued_at": "2026-04-01T06:00:03.496Z",
|
||||||
|
"expires_at": "2026-04-01T06:01:33.496Z",
|
||||||
|
"poll_interval_sec": 15,
|
||||||
|
"active_event_ids": [148],
|
||||||
|
"event_window_start": "2026-04-01T06:00:00Z",
|
||||||
|
"event_window_end": "2026-04-01T07:00:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### OFF (no active event)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"intent_id": "833c53e3-d728-4604-9861-6ff7be1f227e",
|
||||||
|
"group_id": 2,
|
||||||
|
"desired_state": "off",
|
||||||
|
"reason": "no_active_event",
|
||||||
|
"issued_at": "2026-04-01T07:00:03.702Z",
|
||||||
|
"expires_at": "2026-04-01T07:01:33.702Z",
|
||||||
|
"poll_interval_sec": 15,
|
||||||
|
"active_event_ids": [],
|
||||||
|
"event_window_start": null,
|
||||||
|
"event_window_end": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Validated server behaviours (client can rely on these)
|
||||||
|
|
||||||
|
| Scenario | Guaranteed server behaviour |
|
||||||
|
|---|---|
|
||||||
|
| Event starts | `desired_state: on` emitted within one poll interval |
|
||||||
|
| Event ends | `desired_state: off` emitted within one poll interval |
|
||||||
|
| Adjacent events (end1 == start2) | No intermediate `off` emitted at boundary |
|
||||||
|
| Overlapping events | `desired_state: on` held continuously |
|
||||||
|
| Scheduler restart during active event | Immediate `on` republish on reconnect; broker retained holds `on` during outage |
|
||||||
|
| No events in group | `desired_state: off` with empty `active_event_ids` |
|
||||||
|
| Heartbeat (no change) | Same `intent_id`, refreshed timestamps every poll |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Client responsibilities (Phase 1)
|
||||||
|
|
||||||
|
1. **Subscribe** to `infoscreen/groups/{own_group_id}/power/intent` at QoS 1 on connect.
|
||||||
|
2. **Re-subscribe on reconnect** — broker retained message will deliver last known intent immediately.
|
||||||
|
3. **Parse `desired_state`** and apply TV power action (`on` → power on / `off` → power off).
|
||||||
|
4. **Deduplicate** using `intent_id` — if same `intent_id` received again, skip re-applying power command.
|
||||||
|
5. **Check expiry** — if `now > expires_at`, treat as stale and fall back to `off` until renewed.
|
||||||
|
6. **Ignore unknown fields** — for forward compatibility with Phase 2 additions.
|
||||||
|
7. **Do not use per-client topic** in Phase 1; only group topic is active.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Timestamps
|
||||||
|
|
||||||
|
- All timestamps use **ISO 8601 UTC with Z suffix**: `"2026-04-01T06:00:03.496Z"`
|
||||||
|
- Client must parse as UTC.
|
||||||
|
- Do not assume local time.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2 (deferred — not yet active)
|
||||||
|
|
||||||
|
- Per-client intent topic: `infoscreen/{client_uuid}/power/intent`
|
||||||
|
- Per-client override takes precedence over group intent
|
||||||
|
- Client state acknowledgement: `infoscreen/{client_uuid}/power/state`
|
||||||
|
- Listener persistence of client state to DB
|
||||||
@@ -2,9 +2,9 @@
|
|||||||
<html lang="en">
|
<html lang="en">
|
||||||
<head>
|
<head>
|
||||||
<meta charset="UTF-8" />
|
<meta charset="UTF-8" />
|
||||||
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
|
<link rel="icon" type="image/png" href="/favicon.png" />
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||||
<title>Vite + React + TS</title>
|
<title>Infoscreen</title>
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<div id="root"></div>
|
<div id="root"></div>
|
||||||
|
|||||||
BIN
dashboard/public/favicon.png
Normal file
BIN
dashboard/public/favicon.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 225 KiB |
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"appName": "Infoscreen-Management",
|
"appName": "Infoscreen-Management",
|
||||||
"version": "2026.1.0-alpha.14",
|
"version": "2026.1.0-alpha.16",
|
||||||
"copyright": "© 2026 Third-Age-Applications",
|
"copyright": "© 2026 Third-Age-Applications",
|
||||||
"supportContact": "support@third-age-applications.com",
|
"supportContact": "support@third-age-applications.com",
|
||||||
"description": "Eine zentrale Verwaltungsoberfläche für digitale Informationsbildschirme.",
|
"description": "Eine zentrale Verwaltungsoberfläche für digitale Informationsbildschirme.",
|
||||||
@@ -25,11 +25,30 @@
|
|||||||
{ "name": "Alembic", "license": "MIT" }
|
{ "name": "Alembic", "license": "MIT" }
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"buildInfo": {
|
|
||||||
"buildDate": "2025-12-29T12:00:00Z",
|
|
||||||
"commitId": "9f2ae8b44c3a"
|
|
||||||
},
|
|
||||||
"changelog": [
|
"changelog": [
|
||||||
|
{
|
||||||
|
"version": "2026.1.0-alpha.16",
|
||||||
|
"date": "2026-04-02",
|
||||||
|
"changes": [
|
||||||
|
"✅ Dashboard: Der Ferienstatus-Banner zeigt die aktive akademische Periode jetzt zuverlässig nach Hard-Refresh und beim Wechsel zwischen Dashboard und Einstellungen.",
|
||||||
|
"🧭 Navigation: Der Link vom Ferienstatus-Banner zu den Einstellungen bleibt stabil und funktioniert konsistent für Admin-Rollen.",
|
||||||
|
"🚀 Deployment: Akademische Perioden werden nach Initialisierung automatisch für das aktuelle Datum aktiviert (kein manueller Aktivierungsschritt direkt nach Rollout mehr nötig).",
|
||||||
|
"🔤 Sprache: Mehrere deutsche UI-Texte im Dashboard wurden auf korrekte Umlaute umgestellt (zum Beispiel für, prüfen, Vorfälle und Ausfälle)."
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"version": "2026.1.0-alpha.15",
|
||||||
|
"date": "2026-03-31",
|
||||||
|
"changes": [
|
||||||
|
"✨ Einstellungen: Ferienverwaltung pro akademischer Periode verbessert (Import/Anzeige an ausgewählte Periode gebunden).",
|
||||||
|
"➕ Ferienkalender: Manuelle Ferienpflege mit Erstellen, Bearbeiten und Löschen direkt im gleichen Bereich.",
|
||||||
|
"✅ Validierung: Ferien-Datumsbereiche werden bei Import und manueller Erfassung gegen die gewählte Periode geprüft.",
|
||||||
|
"🧠 Ferienlogik: Doppelte Einträge werden verhindert; identische Überschneidungen (Name+Region) werden automatisch zusammengeführt.",
|
||||||
|
"⚠️ Import: Konfliktfälle bei überlappenden, unterschiedlichen Feiertags-Identitäten werden übersichtlich ausgewiesen.",
|
||||||
|
"🎯 UX: Dateiauswahl im Ferien-Import zeigt den gewählten Dateinamen zuverlässig an.",
|
||||||
|
"🎨 UI: Ferien-Tab und Dialoge an die definierten Syncfusion-Designregeln angeglichen."
|
||||||
|
]
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"version": "2026.1.0-alpha.14",
|
"version": "2026.1.0-alpha.14",
|
||||||
"date": "2026-01-28",
|
"date": "2026-01-28",
|
||||||
|
|||||||
@@ -1,42 +1,156 @@
|
|||||||
export type AcademicPeriod = {
|
export type AcademicPeriod = {
|
||||||
id: number;
|
id: number;
|
||||||
name: string;
|
name: string;
|
||||||
display_name?: string | null;
|
displayName?: string | null;
|
||||||
start_date: string; // YYYY-MM-DD
|
startDate: string; // YYYY-MM-DD
|
||||||
end_date: string; // YYYY-MM-DD
|
endDate: string; // YYYY-MM-DD
|
||||||
period_type: 'schuljahr' | 'semester' | 'trimester';
|
periodType: 'schuljahr' | 'semester' | 'trimester';
|
||||||
is_active: boolean;
|
isActive: boolean;
|
||||||
|
isArchived: boolean;
|
||||||
|
archivedAt?: string | null;
|
||||||
|
archivedBy?: number | null;
|
||||||
|
createdAt?: string;
|
||||||
|
updatedAt?: string;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
export type PeriodUsage = {
|
||||||
|
linked_events: number;
|
||||||
|
has_active_recurrence: boolean;
|
||||||
|
blockers: string[];
|
||||||
|
};
|
||||||
|
|
||||||
|
function normalizeAcademicPeriod(period: any): AcademicPeriod {
|
||||||
|
return {
|
||||||
|
id: Number(period.id),
|
||||||
|
name: period.name,
|
||||||
|
displayName: period.displayName ?? period.display_name ?? null,
|
||||||
|
startDate: period.startDate ?? period.start_date,
|
||||||
|
endDate: period.endDate ?? period.end_date,
|
||||||
|
periodType: period.periodType ?? period.period_type,
|
||||||
|
isActive: Boolean(period.isActive ?? period.is_active),
|
||||||
|
isArchived: Boolean(period.isArchived ?? period.is_archived),
|
||||||
|
archivedAt: period.archivedAt ?? period.archived_at ?? null,
|
||||||
|
archivedBy: period.archivedBy ?? period.archived_by ?? null,
|
||||||
|
createdAt: period.createdAt ?? period.created_at,
|
||||||
|
updatedAt: period.updatedAt ?? period.updated_at,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
async function api<T>(url: string, init?: RequestInit): Promise<T> {
|
async function api<T>(url: string, init?: RequestInit): Promise<T> {
|
||||||
const res = await fetch(url, { credentials: 'include', ...init });
|
const res = await fetch(url, { credentials: 'include', cache: 'no-store', ...init });
|
||||||
if (!res.ok) throw new Error(`HTTP ${res.status}`);
|
if (!res.ok) {
|
||||||
|
const text = await res.text();
|
||||||
|
try {
|
||||||
|
const err = JSON.parse(text);
|
||||||
|
throw new Error(err.error || `HTTP ${res.status}`);
|
||||||
|
} catch {
|
||||||
|
throw new Error(`HTTP ${res.status}: ${text}`);
|
||||||
|
}
|
||||||
|
}
|
||||||
return res.json();
|
return res.json();
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function getAcademicPeriodForDate(date: Date): Promise<AcademicPeriod | null> {
|
export async function getAcademicPeriodForDate(date: Date): Promise<AcademicPeriod | null> {
|
||||||
const iso = date.toISOString().slice(0, 10);
|
const iso = date.toISOString().slice(0, 10);
|
||||||
const { period } = await api<{ period: AcademicPeriod | null }>(
|
const { period } = await api<{ period: any | null }>(
|
||||||
`/api/academic_periods/for_date?date=${iso}`
|
`/api/academic_periods/for_date?date=${iso}`
|
||||||
);
|
);
|
||||||
return period ?? null;
|
return period ? normalizeAcademicPeriod(period) : null;
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function listAcademicPeriods(): Promise<AcademicPeriod[]> {
|
export async function listAcademicPeriods(options?: {
|
||||||
const { periods } = await api<{ periods: AcademicPeriod[] }>(`/api/academic_periods`);
|
includeArchived?: boolean;
|
||||||
return Array.isArray(periods) ? periods : [];
|
archivedOnly?: boolean;
|
||||||
|
}): Promise<AcademicPeriod[]> {
|
||||||
|
const params = new URLSearchParams();
|
||||||
|
if (options?.includeArchived) {
|
||||||
|
params.set('includeArchived', '1');
|
||||||
|
}
|
||||||
|
if (options?.archivedOnly) {
|
||||||
|
params.set('archivedOnly', '1');
|
||||||
|
}
|
||||||
|
const query = params.toString();
|
||||||
|
const { periods } = await api<{ periods: any[] }>(
|
||||||
|
`/api/academic_periods${query ? `?${query}` : ''}`
|
||||||
|
);
|
||||||
|
return Array.isArray(periods) ? periods.map(normalizeAcademicPeriod) : [];
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function getAcademicPeriod(id: number): Promise<AcademicPeriod> {
|
||||||
|
const { period } = await api<{ period: any }>(`/api/academic_periods/${id}`);
|
||||||
|
return normalizeAcademicPeriod(period);
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function getActiveAcademicPeriod(): Promise<AcademicPeriod | null> {
|
export async function getActiveAcademicPeriod(): Promise<AcademicPeriod | null> {
|
||||||
const { period } = await api<{ period: AcademicPeriod | null }>(`/api/academic_periods/active`);
|
const { period } = await api<{ period: any | null }>(`/api/academic_periods/active`);
|
||||||
return period ?? null;
|
return period ? normalizeAcademicPeriod(period) : null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function createAcademicPeriod(payload: {
|
||||||
|
name: string;
|
||||||
|
displayName?: string;
|
||||||
|
startDate: string;
|
||||||
|
endDate: string;
|
||||||
|
periodType: 'schuljahr' | 'semester' | 'trimester';
|
||||||
|
}): Promise<AcademicPeriod> {
|
||||||
|
const { period } = await api<{ period: any }>(`/api/academic_periods`, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify(payload),
|
||||||
|
});
|
||||||
|
return normalizeAcademicPeriod(period);
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function updateAcademicPeriod(
|
||||||
|
id: number,
|
||||||
|
payload: Partial<{
|
||||||
|
name: string;
|
||||||
|
displayName: string | null;
|
||||||
|
startDate: string;
|
||||||
|
endDate: string;
|
||||||
|
periodType: 'schuljahr' | 'semester' | 'trimester';
|
||||||
|
}>
|
||||||
|
): Promise<AcademicPeriod> {
|
||||||
|
const { period } = await api<{ period: any }>(`/api/academic_periods/${id}`, {
|
||||||
|
method: 'PUT',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify(payload),
|
||||||
|
});
|
||||||
|
return normalizeAcademicPeriod(period);
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function setActiveAcademicPeriod(id: number): Promise<AcademicPeriod> {
|
export async function setActiveAcademicPeriod(id: number): Promise<AcademicPeriod> {
|
||||||
const { period } = await api<{ period: AcademicPeriod }>(`/api/academic_periods/active`, {
|
const { period } = await api<{ period: any }>(`/api/academic_periods/${id}/activate`, {
|
||||||
method: 'POST',
|
method: 'POST',
|
||||||
headers: { 'Content-Type': 'application/json' },
|
headers: { 'Content-Type': 'application/json' },
|
||||||
body: JSON.stringify({ id }),
|
|
||||||
});
|
});
|
||||||
return period;
|
return normalizeAcademicPeriod(period);
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function archiveAcademicPeriod(id: number): Promise<AcademicPeriod> {
|
||||||
|
const { period } = await api<{ period: any }>(`/api/academic_periods/${id}/archive`, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
});
|
||||||
|
return normalizeAcademicPeriod(period);
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function restoreAcademicPeriod(id: number): Promise<AcademicPeriod> {
|
||||||
|
const { period } = await api<{ period: any }>(`/api/academic_periods/${id}/restore`, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
});
|
||||||
|
return normalizeAcademicPeriod(period);
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function getAcademicPeriodUsage(id: number): Promise<PeriodUsage> {
|
||||||
|
const { usage } = await api<{ usage: PeriodUsage }>(`/api/academic_periods/${id}/usage`);
|
||||||
|
return usage;
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function deleteAcademicPeriod(id: number): Promise<void> {
|
||||||
|
await api(`/api/academic_periods/${id}`, {
|
||||||
|
method: 'DELETE',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
});
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -39,6 +39,8 @@ export interface MonitoringClient {
|
|||||||
};
|
};
|
||||||
latestLog?: MonitoringLogEntry | null;
|
latestLog?: MonitoringLogEntry | null;
|
||||||
latestError?: MonitoringLogEntry | null;
|
latestError?: MonitoringLogEntry | null;
|
||||||
|
mqttReconnectCount?: number | null;
|
||||||
|
mqttLastDisconnectAt?: string | null;
|
||||||
}
|
}
|
||||||
|
|
||||||
export interface MonitoringOverview {
|
export interface MonitoringOverview {
|
||||||
|
|||||||
@@ -24,6 +24,62 @@ export interface Group {
|
|||||||
is_active?: boolean;
|
is_active?: boolean;
|
||||||
clients: Client[];
|
clients: Client[];
|
||||||
}
|
}
|
||||||
|
|
||||||
|
export interface CrashedClient {
|
||||||
|
uuid: string;
|
||||||
|
description?: string | null;
|
||||||
|
hostname?: string | null;
|
||||||
|
ip?: string | null;
|
||||||
|
group_id?: number | null;
|
||||||
|
is_alive: boolean;
|
||||||
|
process_status?: string | null;
|
||||||
|
screen_health_status?: string | null;
|
||||||
|
last_alive?: string | null;
|
||||||
|
crash_reason: 'process_crashed' | 'heartbeat_stale';
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface CrashedClientsResponse {
|
||||||
|
crashed_count: number;
|
||||||
|
grace_period_seconds: number;
|
||||||
|
clients: CrashedClient[];
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ServiceFailedClient {
|
||||||
|
uuid: string;
|
||||||
|
description?: string | null;
|
||||||
|
hostname?: string | null;
|
||||||
|
ip?: string | null;
|
||||||
|
group_id?: number | null;
|
||||||
|
is_alive: boolean;
|
||||||
|
last_alive?: string | null;
|
||||||
|
service_failed_at: string;
|
||||||
|
service_failed_unit?: string | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ServiceFailedClientsResponse {
|
||||||
|
service_failed_count: number;
|
||||||
|
clients: ServiceFailedClient[];
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ClientCommand {
|
||||||
|
commandId: string;
|
||||||
|
clientUuid: string;
|
||||||
|
action: 'reboot_host' | 'shutdown_host' | 'restart_app';
|
||||||
|
status: string;
|
||||||
|
reason?: string | null;
|
||||||
|
requestedBy?: number | null;
|
||||||
|
issuedAt?: string | null;
|
||||||
|
expiresAt?: string | null;
|
||||||
|
publishedAt?: string | null;
|
||||||
|
ackedAt?: string | null;
|
||||||
|
executionStartedAt?: string | null;
|
||||||
|
completedAt?: string | null;
|
||||||
|
failedAt?: string | null;
|
||||||
|
errorCode?: string | null;
|
||||||
|
errorMessage?: string | null;
|
||||||
|
createdAt?: string | null;
|
||||||
|
updatedAt?: string | null;
|
||||||
|
}
|
||||||
// Liefert alle Gruppen mit zugehörigen Clients
|
// Liefert alle Gruppen mit zugehörigen Clients
|
||||||
export async function fetchGroupsWithClients(): Promise<Group[]> {
|
export async function fetchGroupsWithClients(): Promise<Group[]> {
|
||||||
const response = await fetch('/api/groups/with_clients');
|
const response = await fetch('/api/groups/with_clients');
|
||||||
@@ -79,9 +135,11 @@ export async function updateClient(uuid: string, data: { description?: string; m
|
|||||||
return await res.json();
|
return await res.json();
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function restartClient(uuid: string): Promise<{ success: boolean; message?: string }> {
|
export async function restartClient(uuid: string, reason?: string): Promise<{ success: boolean; message?: string; command?: ClientCommand }> {
|
||||||
const response = await fetch(`/api/clients/${uuid}/restart`, {
|
const response = await fetch(`/api/clients/${uuid}/restart`, {
|
||||||
method: 'POST',
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify({ reason: reason || null }),
|
||||||
});
|
});
|
||||||
if (!response.ok) {
|
if (!response.ok) {
|
||||||
const error = await response.json();
|
const error = await response.json();
|
||||||
@@ -90,6 +148,58 @@ export async function restartClient(uuid: string): Promise<{ success: boolean; m
|
|||||||
return await response.json();
|
return await response.json();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
export async function shutdownClient(uuid: string, reason?: string): Promise<{ success: boolean; message?: string; command?: ClientCommand }> {
|
||||||
|
const response = await fetch(`/api/clients/${uuid}/shutdown`, {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify({ reason: reason || null }),
|
||||||
|
});
|
||||||
|
if (!response.ok) {
|
||||||
|
const error = await response.json();
|
||||||
|
throw new Error(error.error || 'Fehler beim Herunterfahren des Clients');
|
||||||
|
}
|
||||||
|
return await response.json();
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function fetchClientCommandStatus(commandId: string): Promise<ClientCommand> {
|
||||||
|
const response = await fetch(`/api/clients/commands/${commandId}`);
|
||||||
|
if (!response.ok) {
|
||||||
|
const error = await response.json();
|
||||||
|
throw new Error(error.error || 'Fehler beim Laden des Command-Status');
|
||||||
|
}
|
||||||
|
return await response.json();
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function fetchCrashedClients(): Promise<CrashedClientsResponse> {
|
||||||
|
const response = await fetch('/api/clients/crashed', { credentials: 'include' });
|
||||||
|
if (!response.ok) {
|
||||||
|
const err = await response.json().catch(() => ({}));
|
||||||
|
throw new Error(err.error || 'Fehler beim Laden der abgestürzten Clients');
|
||||||
|
}
|
||||||
|
return await response.json();
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function fetchServiceFailedClients(): Promise<ServiceFailedClientsResponse> {
|
||||||
|
const response = await fetch('/api/clients/service_failed', { credentials: 'include' });
|
||||||
|
if (!response.ok) {
|
||||||
|
const err = await response.json().catch(() => ({}));
|
||||||
|
throw new Error(err.error || 'Fehler beim Laden der service_failed Clients');
|
||||||
|
}
|
||||||
|
return await response.json();
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function clearServiceFailed(uuid: string): Promise<{ success: boolean; message?: string }> {
|
||||||
|
const response = await fetch(`/api/clients/${uuid}/clear_service_failed`, {
|
||||||
|
method: 'POST',
|
||||||
|
credentials: 'include',
|
||||||
|
});
|
||||||
|
if (!response.ok) {
|
||||||
|
const err = await response.json().catch(() => ({}));
|
||||||
|
throw new Error(err.error || 'Fehler beim Quittieren des service_failed Flags');
|
||||||
|
}
|
||||||
|
return await response.json();
|
||||||
|
}
|
||||||
|
|
||||||
export async function deleteClient(uuid: string) {
|
export async function deleteClient(uuid: string) {
|
||||||
const res = await fetch(`/api/clients/${uuid}`, {
|
const res = await fetch(`/api/clients/${uuid}`, {
|
||||||
method: 'DELETE',
|
method: 'DELETE',
|
||||||
|
|||||||
@@ -1,5 +1,6 @@
|
|||||||
export type Holiday = {
|
export type Holiday = {
|
||||||
id: number;
|
id: number;
|
||||||
|
academic_period_id?: number | null;
|
||||||
name: string;
|
name: string;
|
||||||
start_date: string;
|
start_date: string;
|
||||||
end_date: string;
|
end_date: string;
|
||||||
@@ -8,19 +9,80 @@ export type Holiday = {
|
|||||||
imported_at?: string | null;
|
imported_at?: string | null;
|
||||||
};
|
};
|
||||||
|
|
||||||
export async function listHolidays(region?: string) {
|
export async function listHolidays(region?: string, academicPeriodId?: number | null) {
|
||||||
const url = region ? `/api/holidays?region=${encodeURIComponent(region)}` : '/api/holidays';
|
const params = new URLSearchParams();
|
||||||
|
if (region) {
|
||||||
|
params.set('region', region);
|
||||||
|
}
|
||||||
|
if (academicPeriodId != null) {
|
||||||
|
params.set('academicPeriodId', String(academicPeriodId));
|
||||||
|
}
|
||||||
|
const query = params.toString();
|
||||||
|
const url = query ? `/api/holidays?${query}` : '/api/holidays';
|
||||||
const res = await fetch(url);
|
const res = await fetch(url);
|
||||||
const data = await res.json();
|
const data = await res.json();
|
||||||
if (!res.ok || data.error) throw new Error(data.error || 'Fehler beim Laden der Ferien');
|
if (!res.ok || data.error) throw new Error(data.error || 'Fehler beim Laden der Ferien');
|
||||||
return data as { holidays: Holiday[] };
|
return data as { holidays: Holiday[] };
|
||||||
}
|
}
|
||||||
|
|
||||||
export async function uploadHolidaysCsv(file: File) {
|
export async function uploadHolidaysCsv(file: File, academicPeriodId: number) {
|
||||||
const form = new FormData();
|
const form = new FormData();
|
||||||
form.append('file', file);
|
form.append('file', file);
|
||||||
|
form.append('academicPeriodId', String(academicPeriodId));
|
||||||
const res = await fetch('/api/holidays/upload', { method: 'POST', body: form });
|
const res = await fetch('/api/holidays/upload', { method: 'POST', body: form });
|
||||||
const data = await res.json();
|
const data = await res.json();
|
||||||
if (!res.ok || data.error) throw new Error(data.error || 'Fehler beim Import der Ferien');
|
if (!res.ok || data.error) throw new Error(data.error || 'Fehler beim Import der Ferien');
|
||||||
return data as { success: boolean; inserted: number; updated: number };
|
return data as {
|
||||||
|
success: boolean;
|
||||||
|
inserted: number;
|
||||||
|
updated: number;
|
||||||
|
merged_overlaps?: number;
|
||||||
|
skipped_duplicates?: number;
|
||||||
|
conflicts?: string[];
|
||||||
|
academic_period_id?: number | null;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
export type HolidayInput = {
|
||||||
|
name: string;
|
||||||
|
start_date: string;
|
||||||
|
end_date: string;
|
||||||
|
region?: string | null;
|
||||||
|
academic_period_id?: number | null;
|
||||||
|
};
|
||||||
|
|
||||||
|
export type HolidayMutationResult = {
|
||||||
|
success: boolean;
|
||||||
|
holiday?: Holiday;
|
||||||
|
regenerated_events: number;
|
||||||
|
merged?: boolean;
|
||||||
|
};
|
||||||
|
|
||||||
|
export async function createHoliday(data: HolidayInput): Promise<HolidayMutationResult> {
|
||||||
|
const res = await fetch('/api/holidays', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify(data),
|
||||||
|
});
|
||||||
|
const json = await res.json();
|
||||||
|
if (!res.ok || json.error) throw new Error(json.error || 'Fehler beim Erstellen');
|
||||||
|
return json;
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function updateHoliday(id: number, data: Partial<HolidayInput>): Promise<HolidayMutationResult> {
|
||||||
|
const res = await fetch(`/api/holidays/${id}`, {
|
||||||
|
method: 'PUT',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify(data),
|
||||||
|
});
|
||||||
|
const json = await res.json();
|
||||||
|
if (!res.ok || json.error) throw new Error(json.error || 'Fehler beim Aktualisieren');
|
||||||
|
return json;
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function deleteHoliday(id: number): Promise<{ success: boolean; regenerated_events: number }> {
|
||||||
|
const res = await fetch(`/api/holidays/${id}`, { method: 'DELETE' });
|
||||||
|
const json = await res.json();
|
||||||
|
if (!res.ok || json.error) throw new Error(json.error || 'Fehler beim Löschen');
|
||||||
|
return json;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -303,24 +303,29 @@ const Appointments: React.FC = () => {
|
|||||||
.catch(console.error);
|
.catch(console.error);
|
||||||
}, []);
|
}, []);
|
||||||
|
|
||||||
// Holidays laden
|
|
||||||
useEffect(() => {
|
|
||||||
listHolidays()
|
|
||||||
.then(res => setHolidays(res.holidays || []))
|
|
||||||
.catch(err => console.error('Ferien laden fehlgeschlagen:', err));
|
|
||||||
}, []);
|
|
||||||
|
|
||||||
// Perioden laden (Dropdown)
|
// Perioden laden (Dropdown)
|
||||||
useEffect(() => {
|
useEffect(() => {
|
||||||
listAcademicPeriods()
|
listAcademicPeriods()
|
||||||
.then(all => {
|
.then(all => {
|
||||||
setPeriods(all.map(p => ({ id: p.id, label: p.display_name || p.name })));
|
setPeriods(all.map(p => ({ id: p.id, label: p.displayName || p.name })));
|
||||||
const active = all.find(p => p.is_active);
|
const active = all.find(p => p.isActive);
|
||||||
setActivePeriodId(active ? active.id : null);
|
setActivePeriodId(active ? active.id : null);
|
||||||
})
|
})
|
||||||
.catch(err => console.error('Akademische Perioden laden fehlgeschlagen:', err));
|
.catch(err => console.error('Akademische Perioden laden fehlgeschlagen:', err));
|
||||||
}, []);
|
}, []);
|
||||||
|
|
||||||
|
// Holidays passend zur aktiven akademischen Periode laden
|
||||||
|
useEffect(() => {
|
||||||
|
if (!activePeriodId) {
|
||||||
|
setHolidays([]);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
listHolidays(undefined, activePeriodId)
|
||||||
|
.then(res => setHolidays(res.holidays || []))
|
||||||
|
.catch(err => console.error('Ferien laden fehlgeschlagen:', err));
|
||||||
|
}, [activePeriodId]);
|
||||||
|
|
||||||
// fetchAndSetEvents als useCallback definieren, damit die Dependency korrekt ist:
|
// fetchAndSetEvents als useCallback definieren, damit die Dependency korrekt ist:
|
||||||
const fetchAndSetEvents = React.useCallback(async () => {
|
const fetchAndSetEvents = React.useCallback(async () => {
|
||||||
if (!selectedGroupId) {
|
if (!selectedGroupId) {
|
||||||
@@ -540,12 +545,12 @@ const Appointments: React.FC = () => {
|
|||||||
setHasSchoolYearPlan(false);
|
setHasSchoolYearPlan(false);
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
// Anzeige: bevorzugt display_name, sonst name
|
// Anzeige: bevorzugt displayName, sonst name
|
||||||
const label = p.display_name ? p.display_name : p.name;
|
const label = p.displayName ? p.displayName : p.name;
|
||||||
setSchoolYearLabel(label);
|
setSchoolYearLabel(label);
|
||||||
// Existiert ein Ferienplan innerhalb der Periode?
|
// Existiert ein Ferienplan innerhalb der Periode?
|
||||||
const start = new Date(p.start_date + 'T00:00:00');
|
const start = new Date(p.startDate + 'T00:00:00');
|
||||||
const end = new Date(p.end_date + 'T23:59:59');
|
const end = new Date(p.endDate + 'T23:59:59');
|
||||||
let exists = false;
|
let exists = false;
|
||||||
for (const h of holidays) {
|
for (const h of holidays) {
|
||||||
const hs = new Date(h.start_date + 'T00:00:00');
|
const hs = new Date(h.start_date + 'T00:00:00');
|
||||||
@@ -680,7 +685,7 @@ const Appointments: React.FC = () => {
|
|||||||
setActivePeriodId(updated.id);
|
setActivePeriodId(updated.id);
|
||||||
// Zum gleichen Tag/Monat (heute) innerhalb der gewählten Periode springen
|
// Zum gleichen Tag/Monat (heute) innerhalb der gewählten Periode springen
|
||||||
const today = new Date();
|
const today = new Date();
|
||||||
const targetYear = new Date(updated.start_date).getFullYear();
|
const targetYear = new Date(updated.startDate).getFullYear();
|
||||||
const target = new Date(targetYear, today.getMonth(), today.getDate(), 12, 0, 0);
|
const target = new Date(targetYear, today.getMonth(), today.getDate(), 12, 0, 0);
|
||||||
if (scheduleRef.current) {
|
if (scheduleRef.current) {
|
||||||
scheduleRef.current.selectedDate = target;
|
scheduleRef.current.selectedDate = target;
|
||||||
|
|||||||
@@ -97,11 +97,6 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
const [media, setMedia] = React.useState<{ id: string; path: string; name: string } | null>(
|
const [media, setMedia] = React.useState<{ id: string; path: string; name: string } | null>(
|
||||||
initialData.media ?? null
|
initialData.media ?? null
|
||||||
);
|
);
|
||||||
const [pendingMedia, setPendingMedia] = React.useState<{
|
|
||||||
id: string;
|
|
||||||
path: string;
|
|
||||||
name: string;
|
|
||||||
} | null>(null);
|
|
||||||
// General settings state for presentation
|
// General settings state for presentation
|
||||||
// Removed unused generalLoaded and setGeneralLoaded
|
// Removed unused generalLoaded and setGeneralLoaded
|
||||||
// Removed unused generalLoaded/generalSlideshowInterval/generalPageProgress/generalAutoProgress
|
// Removed unused generalLoaded/generalSlideshowInterval/generalPageProgress/generalAutoProgress
|
||||||
@@ -124,6 +119,7 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
const [volume, setVolume] = React.useState<number>(initialData.volume ?? 0.8);
|
const [volume, setVolume] = React.useState<number>(initialData.volume ?? 0.8);
|
||||||
const [muted, setMuted] = React.useState<boolean>(initialData.muted ?? false);
|
const [muted, setMuted] = React.useState<boolean>(initialData.muted ?? false);
|
||||||
const [videoDefaultsLoaded, setVideoDefaultsLoaded] = React.useState<boolean>(false);
|
const [videoDefaultsLoaded, setVideoDefaultsLoaded] = React.useState<boolean>(false);
|
||||||
|
const [isSaving, setIsSaving] = React.useState(false);
|
||||||
|
|
||||||
const [mediaModalOpen, setMediaModalOpen] = React.useState(false);
|
const [mediaModalOpen, setMediaModalOpen] = React.useState(false);
|
||||||
|
|
||||||
@@ -203,14 +199,11 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
}
|
}
|
||||||
}, [open, initialData, editMode]);
|
}, [open, initialData, editMode]);
|
||||||
|
|
||||||
React.useEffect(() => {
|
|
||||||
if (!mediaModalOpen && pendingMedia) {
|
|
||||||
setMedia(pendingMedia);
|
|
||||||
setPendingMedia(null);
|
|
||||||
}
|
|
||||||
}, [mediaModalOpen, pendingMedia]);
|
|
||||||
|
|
||||||
const handleSave = async () => {
|
const handleSave = async () => {
|
||||||
|
if (isSaving) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
const newErrors: { [key: string]: string } = {};
|
const newErrors: { [key: string]: string } = {};
|
||||||
if (!title.trim()) newErrors.title = 'Titel ist erforderlich';
|
if (!title.trim()) newErrors.title = 'Titel ist erforderlich';
|
||||||
if (!startDate) newErrors.startDate = 'Startdatum ist erforderlich';
|
if (!startDate) newErrors.startDate = 'Startdatum ist erforderlich';
|
||||||
@@ -253,6 +246,14 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
if (type === 'video') {
|
if (type === 'video') {
|
||||||
if (!media) newErrors.media = 'Bitte ein Video auswählen';
|
if (!media) newErrors.media = 'Bitte ein Video auswählen';
|
||||||
}
|
}
|
||||||
|
|
||||||
|
const parsedMediaId = media?.id ? Number(media.id) : null;
|
||||||
|
if (
|
||||||
|
(type === 'presentation' || type === 'video') &&
|
||||||
|
(!Number.isFinite(parsedMediaId) || (parsedMediaId as number) <= 0)
|
||||||
|
) {
|
||||||
|
newErrors.media = 'Ausgewähltes Medium ist ungültig. Bitte Datei erneut auswählen.';
|
||||||
|
}
|
||||||
// Holiday blocking logic removed (blockHolidays, isHolidayRange no longer used)
|
// Holiday blocking logic removed (blockHolidays, isHolidayRange no longer used)
|
||||||
|
|
||||||
if (Object.keys(newErrors).length > 0) {
|
if (Object.keys(newErrors).length > 0) {
|
||||||
@@ -260,6 +261,8 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
setIsSaving(true);
|
||||||
|
|
||||||
const group_id = typeof groupName === 'object' && groupName !== null ? groupName.id : groupName;
|
const group_id = typeof groupName === 'object' && groupName !== null ? groupName.id : groupName;
|
||||||
|
|
||||||
// Build recurrence rule if repeat is enabled
|
// Build recurrence rule if repeat is enabled
|
||||||
@@ -323,7 +326,7 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
};
|
};
|
||||||
|
|
||||||
if (type === 'presentation') {
|
if (type === 'presentation') {
|
||||||
payload.event_media_id = media?.id ? Number(media.id) : undefined;
|
payload.event_media_id = parsedMediaId as number;
|
||||||
payload.slideshow_interval = slideshowInterval;
|
payload.slideshow_interval = slideshowInterval;
|
||||||
payload.page_progress = pageProgress;
|
payload.page_progress = pageProgress;
|
||||||
payload.auto_progress = autoProgress;
|
payload.auto_progress = autoProgress;
|
||||||
@@ -334,7 +337,7 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
}
|
}
|
||||||
|
|
||||||
if (type === 'video') {
|
if (type === 'video') {
|
||||||
payload.event_media_id = media?.id ? Number(media.id) : undefined;
|
payload.event_media_id = parsedMediaId as number;
|
||||||
payload.autoplay = autoplay;
|
payload.autoplay = autoplay;
|
||||||
payload.loop = loop;
|
payload.loop = loop;
|
||||||
payload.volume = volume;
|
payload.volume = volume;
|
||||||
@@ -378,12 +381,29 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
}
|
}
|
||||||
} else {
|
} else {
|
||||||
// CREATE
|
// CREATE
|
||||||
res = await fetch('/api/events', {
|
const createResponse = await fetch('/api/events', {
|
||||||
method: 'POST',
|
method: 'POST',
|
||||||
headers: { 'Content-Type': 'application/json' },
|
headers: { 'Content-Type': 'application/json' },
|
||||||
body: JSON.stringify(payload),
|
body: JSON.stringify(payload),
|
||||||
});
|
});
|
||||||
res = await res.json();
|
|
||||||
|
let createData: { success?: boolean; error?: string } = {};
|
||||||
|
try {
|
||||||
|
createData = await createResponse.json();
|
||||||
|
} catch {
|
||||||
|
createData = { error: `HTTP ${createResponse.status}` };
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!createResponse.ok) {
|
||||||
|
setErrors({
|
||||||
|
api:
|
||||||
|
createData.error ||
|
||||||
|
`Fehler beim Speichern (HTTP ${createResponse.status})`,
|
||||||
|
});
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
res = createData;
|
||||||
}
|
}
|
||||||
|
|
||||||
if (res.success) {
|
if (res.success) {
|
||||||
@@ -394,6 +414,8 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
}
|
}
|
||||||
} catch {
|
} catch {
|
||||||
setErrors({ api: 'Netzwerkfehler beim Speichern' });
|
setErrors({ api: 'Netzwerkfehler beim Speichern' });
|
||||||
|
} finally {
|
||||||
|
setIsSaving(false);
|
||||||
}
|
}
|
||||||
|
|
||||||
};
|
};
|
||||||
@@ -454,14 +476,29 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
<button
|
<button
|
||||||
className="e-btn e-success"
|
className="e-btn e-success"
|
||||||
onClick={handleSave}
|
onClick={handleSave}
|
||||||
disabled={shouldDisableButton} // <--- Button nur für Einzeltermine in Vergangenheit deaktivieren
|
disabled={shouldDisableButton || isSaving} // <--- Button nur für Einzeltermine in Vergangenheit deaktivieren
|
||||||
>
|
>
|
||||||
Termin(e) speichern
|
{isSaving ? 'Speichert...' : 'Termin(e) speichern'}
|
||||||
</button>
|
</button>
|
||||||
</div>
|
</div>
|
||||||
)}
|
)}
|
||||||
>
|
>
|
||||||
<div style={{ padding: '24px' }}>
|
<div style={{ padding: '24px' }}>
|
||||||
|
{errors.api && (
|
||||||
|
<div
|
||||||
|
style={{
|
||||||
|
marginBottom: 12,
|
||||||
|
color: '#721c24',
|
||||||
|
background: '#f8d7da',
|
||||||
|
border: '1px solid #f5c6cb',
|
||||||
|
borderRadius: 4,
|
||||||
|
padding: '8px 12px',
|
||||||
|
fontSize: 13,
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{errors.api}
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
<div style={{ display: 'flex', gap: 24, flexWrap: 'wrap' }}>
|
<div style={{ display: 'flex', gap: 24, flexWrap: 'wrap' }}>
|
||||||
<div style={{ flex: 1, minWidth: 260 }}>
|
<div style={{ flex: 1, minWidth: 260 }}>
|
||||||
{/* ...Titel, Beschreibung, Datum, Zeit... */}
|
{/* ...Titel, Beschreibung, Datum, Zeit... */}
|
||||||
@@ -640,6 +677,10 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
<span style={{ color: '#888' }}>Kein Medium ausgewählt</span>
|
<span style={{ color: '#888' }}>Kein Medium ausgewählt</span>
|
||||||
)}
|
)}
|
||||||
</div>
|
</div>
|
||||||
|
{errors.media && <div style={{ color: 'red', fontSize: 12 }}>{errors.media}</div>}
|
||||||
|
{errors.slideshowInterval && (
|
||||||
|
<div style={{ color: 'red', fontSize: 12 }}>{errors.slideshowInterval}</div>
|
||||||
|
)}
|
||||||
<TextBoxComponent
|
<TextBoxComponent
|
||||||
placeholder="Slideshow-Intervall (Sekunden)"
|
placeholder="Slideshow-Intervall (Sekunden)"
|
||||||
floatLabelType="Auto"
|
floatLabelType="Auto"
|
||||||
@@ -692,6 +733,7 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
<span style={{ color: '#888' }}>Kein Video ausgewählt</span>
|
<span style={{ color: '#888' }}>Kein Video ausgewählt</span>
|
||||||
)}
|
)}
|
||||||
</div>
|
</div>
|
||||||
|
{errors.media && <div style={{ color: 'red', fontSize: 12 }}>{errors.media}</div>}
|
||||||
<div style={{ marginTop: 8 }}>
|
<div style={{ marginTop: 8 }}>
|
||||||
<CheckBoxComponent
|
<CheckBoxComponent
|
||||||
label="Automatisch abspielen"
|
label="Automatisch abspielen"
|
||||||
@@ -737,7 +779,13 @@ const CustomEventModal: React.FC<CustomEventModalProps> = ({
|
|||||||
open={mediaModalOpen}
|
open={mediaModalOpen}
|
||||||
onClose={() => setMediaModalOpen(false)}
|
onClose={() => setMediaModalOpen(false)}
|
||||||
onSelect={({ id, path, name }) => {
|
onSelect={({ id, path, name }) => {
|
||||||
setPendingMedia({ id, path, name });
|
setMedia({ id, path, name });
|
||||||
|
setErrors(prev => {
|
||||||
|
if (!prev.media) return prev;
|
||||||
|
const next = { ...prev };
|
||||||
|
delete next.media;
|
||||||
|
return next;
|
||||||
|
});
|
||||||
setMediaModalOpen(false);
|
setMediaModalOpen(false);
|
||||||
}}
|
}}
|
||||||
selectedFileId={null}
|
selectedFileId={null}
|
||||||
|
|||||||
@@ -28,6 +28,7 @@ const CustomSelectUploadEventModal: React.FC<CustomSelectUploadEventModalProps>
|
|||||||
path: string;
|
path: string;
|
||||||
name: string;
|
name: string;
|
||||||
} | null>(null);
|
} | null>(null);
|
||||||
|
const [selectionError, setSelectionError] = useState<string>('');
|
||||||
|
|
||||||
// Callback für Dateiauswahl
|
// Callback für Dateiauswahl
|
||||||
interface FileSelectEventArgs {
|
interface FileSelectEventArgs {
|
||||||
@@ -42,6 +43,7 @@ const CustomSelectUploadEventModal: React.FC<CustomSelectUploadEventModalProps>
|
|||||||
const handleFileSelect = async (args: FileSelectEventArgs) => {
|
const handleFileSelect = async (args: FileSelectEventArgs) => {
|
||||||
if (args.fileDetails.isFile && args.fileDetails.size > 0) {
|
if (args.fileDetails.isFile && args.fileDetails.size > 0) {
|
||||||
const filename = args.fileDetails.name;
|
const filename = args.fileDetails.name;
|
||||||
|
setSelectionError('');
|
||||||
|
|
||||||
try {
|
try {
|
||||||
const response = await fetch(
|
const response = await fetch(
|
||||||
@@ -51,10 +53,13 @@ const CustomSelectUploadEventModal: React.FC<CustomSelectUploadEventModalProps>
|
|||||||
const data = await response.json();
|
const data = await response.json();
|
||||||
setSelectedFile({ id: data.id, path: data.file_path, name: filename });
|
setSelectedFile({ id: data.id, path: data.file_path, name: filename });
|
||||||
} else {
|
} else {
|
||||||
setSelectedFile({ id: filename, path: filename, name: filename });
|
setSelectedFile(null);
|
||||||
|
setSelectionError('Datei ist noch nicht als Medium registriert. Bitte erneut hochladen oder Metadaten prüfen.');
|
||||||
}
|
}
|
||||||
} catch (e) {
|
} catch (e) {
|
||||||
console.error('Error fetching file details:', e);
|
console.error('Error fetching file details:', e);
|
||||||
|
setSelectedFile(null);
|
||||||
|
setSelectionError('Medium-ID konnte nicht geladen werden. Bitte erneut versuchen.');
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
@@ -135,6 +140,9 @@ const CustomSelectUploadEventModal: React.FC<CustomSelectUploadEventModalProps>
|
|||||||
>
|
>
|
||||||
<Inject services={[NavigationPane, DetailsView, Toolbar]} />
|
<Inject services={[NavigationPane, DetailsView, Toolbar]} />
|
||||||
</FileManagerComponent>
|
</FileManagerComponent>
|
||||||
|
{selectionError && (
|
||||||
|
<div style={{ marginTop: 10, color: '#b71c1c', fontSize: 13 }}>{selectionError}</div>
|
||||||
|
)}
|
||||||
</DialogComponent>
|
</DialogComponent>
|
||||||
);
|
);
|
||||||
};
|
};
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
15
dashboard/src/dateFormatting.ts
Normal file
15
dashboard/src/dateFormatting.ts
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
export function formatIsoDateForDisplay(isoDate: string | null | undefined): string {
|
||||||
|
if (!isoDate) {
|
||||||
|
return '-';
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
const parsed = new Date(`${isoDate}T00:00:00`);
|
||||||
|
if (Number.isNaN(parsed.getTime())) {
|
||||||
|
return isoDate;
|
||||||
|
}
|
||||||
|
return parsed.toLocaleDateString('de-DE');
|
||||||
|
} catch {
|
||||||
|
return isoDate;
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -3,7 +3,7 @@ import { createRoot } from 'react-dom/client';
|
|||||||
import './index.css';
|
import './index.css';
|
||||||
import App from './App.tsx';
|
import App from './App.tsx';
|
||||||
import { AuthProvider } from './useAuth';
|
import { AuthProvider } from './useAuth';
|
||||||
import { registerLicense } from '@syncfusion/ej2-base';
|
import { L10n, registerLicense, setCulture } from '@syncfusion/ej2-base';
|
||||||
import '@syncfusion/ej2-base/styles/material3.css';
|
import '@syncfusion/ej2-base/styles/material3.css';
|
||||||
import '@syncfusion/ej2-navigations/styles/material3.css';
|
import '@syncfusion/ej2-navigations/styles/material3.css';
|
||||||
import '@syncfusion/ej2-buttons/styles/material3.css';
|
import '@syncfusion/ej2-buttons/styles/material3.css';
|
||||||
@@ -28,6 +28,51 @@ registerLicense(
|
|||||||
'ORg4AjUWIQA/Gnt3VVhhQlJDfV5AQmBIYVp/TGpJfl96cVxMZVVBJAtUQF1hTH5VdENiXX1dcHxUQWNVWkd2'
|
'ORg4AjUWIQA/Gnt3VVhhQlJDfV5AQmBIYVp/TGpJfl96cVxMZVVBJAtUQF1hTH5VdENiXX1dcHxUQWNVWkd2'
|
||||||
);
|
);
|
||||||
|
|
||||||
|
// Global Syncfusion locale bootstrap so all components (for example Grid in monitoring)
|
||||||
|
// can resolve German resources, independent of which route was opened first.
|
||||||
|
L10n.load({
|
||||||
|
de: {
|
||||||
|
grid: {
|
||||||
|
EmptyRecord: 'Keine Datensätze vorhanden',
|
||||||
|
GroupDropArea: 'Ziehen Sie eine Spaltenüberschrift hierher, um nach dieser Spalte zu gruppieren',
|
||||||
|
UnGroup: 'Klicken Sie hier, um die Gruppierung aufzuheben',
|
||||||
|
EmptyDataSourceError: 'DataSource darf nicht leer sein, wenn InitialLoad aktiviert ist',
|
||||||
|
Item: 'Element',
|
||||||
|
Items: 'Elemente',
|
||||||
|
Search: 'Suchen',
|
||||||
|
Columnchooser: 'Spalten',
|
||||||
|
Matchs: 'Keine Treffer gefunden',
|
||||||
|
FilterButton: 'Filter',
|
||||||
|
ClearButton: 'Löschen',
|
||||||
|
StartsWith: 'Beginnt mit',
|
||||||
|
EndsWith: 'Endet mit',
|
||||||
|
Contains: 'Enthält',
|
||||||
|
Equal: 'Gleich',
|
||||||
|
NotEqual: 'Ungleich',
|
||||||
|
LessThan: 'Kleiner als',
|
||||||
|
LessThanOrEqual: 'Kleiner oder gleich',
|
||||||
|
GreaterThan: 'Größer als',
|
||||||
|
GreaterThanOrEqual: 'Größer oder gleich',
|
||||||
|
},
|
||||||
|
pager: {
|
||||||
|
currentPageInfo: '{0} von {1} Seiten',
|
||||||
|
totalItemsInfo: '({0} Einträge)',
|
||||||
|
firstPageTooltip: 'Erste Seite',
|
||||||
|
lastPageTooltip: 'Letzte Seite',
|
||||||
|
nextPageTooltip: 'Nächste Seite',
|
||||||
|
previousPageTooltip: 'Vorherige Seite',
|
||||||
|
nextPagerTooltip: 'Nächste Pager-Einträge',
|
||||||
|
previousPagerTooltip: 'Vorherige Pager-Einträge',
|
||||||
|
},
|
||||||
|
dropdowns: {
|
||||||
|
noRecordsTemplate: 'Keine Einträge gefunden',
|
||||||
|
actionFailureTemplate: 'Daten konnten nicht geladen werden',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
setCulture('de');
|
||||||
|
|
||||||
createRoot(document.getElementById('root')!).render(
|
createRoot(document.getElementById('root')!).render(
|
||||||
<StrictMode>
|
<StrictMode>
|
||||||
<AuthProvider>
|
<AuthProvider>
|
||||||
|
|||||||
@@ -370,4 +370,49 @@
|
|||||||
.monitoring-log-dialog-actions {
|
.monitoring-log-dialog-actions {
|
||||||
padding: 0 0.2rem 0.4rem;
|
padding: 0 0.2rem 0.4rem;
|
||||||
}
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Crash recovery panel */
|
||||||
|
.monitoring-crash-panel {
|
||||||
|
border-left: 4px solid #dc2626;
|
||||||
|
margin-bottom: 1.5rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.monitoring-service-failed-panel {
|
||||||
|
border-left: 4px solid #ea580c;
|
||||||
|
margin-bottom: 1.5rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.monitoring-crash-table {
|
||||||
|
width: 100%;
|
||||||
|
border-collapse: collapse;
|
||||||
|
font-size: 0.875rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.monitoring-crash-table th {
|
||||||
|
text-align: left;
|
||||||
|
padding: 0.5rem 0.75rem;
|
||||||
|
font-weight: 600;
|
||||||
|
color: #64748b;
|
||||||
|
border-bottom: 1px solid #e2e8f0;
|
||||||
|
background: #f8fafc;
|
||||||
|
}
|
||||||
|
|
||||||
|
.monitoring-crash-table td {
|
||||||
|
padding: 0.55rem 0.75rem;
|
||||||
|
border-bottom: 1px solid #f1f5f9;
|
||||||
|
vertical-align: middle;
|
||||||
|
}
|
||||||
|
|
||||||
|
.monitoring-crash-table tr:last-child td {
|
||||||
|
border-bottom: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.monitoring-crash-table tr:hover td {
|
||||||
|
background: #fef2f2;
|
||||||
|
}
|
||||||
|
|
||||||
|
.monitoring-meta-hint {
|
||||||
|
color: #94a3b8;
|
||||||
|
font-size: 0.8rem;
|
||||||
}
|
}
|
||||||
@@ -7,6 +7,16 @@ import {
|
|||||||
type MonitoringLogEntry,
|
type MonitoringLogEntry,
|
||||||
type MonitoringOverview,
|
type MonitoringOverview,
|
||||||
} from './apiClientMonitoring';
|
} from './apiClientMonitoring';
|
||||||
|
import {
|
||||||
|
fetchCrashedClients,
|
||||||
|
fetchServiceFailedClients,
|
||||||
|
clearServiceFailed,
|
||||||
|
restartClient,
|
||||||
|
type CrashedClient,
|
||||||
|
type CrashedClientsResponse,
|
||||||
|
type ServiceFailedClient,
|
||||||
|
type ServiceFailedClientsResponse,
|
||||||
|
} from './apiClients';
|
||||||
import { useAuth } from './useAuth';
|
import { useAuth } from './useAuth';
|
||||||
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
|
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
|
||||||
import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
|
import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
|
||||||
@@ -156,6 +166,12 @@ const MonitoringDashboard: React.FC = () => {
|
|||||||
const [screenshotErrored, setScreenshotErrored] = React.useState<boolean>(false);
|
const [screenshotErrored, setScreenshotErrored] = React.useState<boolean>(false);
|
||||||
const selectedClientUuidRef = React.useRef<string | null>(null);
|
const selectedClientUuidRef = React.useRef<string | null>(null);
|
||||||
const [selectedLogEntry, setSelectedLogEntry] = React.useState<MonitoringLogEntry | null>(null);
|
const [selectedLogEntry, setSelectedLogEntry] = React.useState<MonitoringLogEntry | null>(null);
|
||||||
|
const [crashedClients, setCrashedClients] = React.useState<CrashedClientsResponse | null>(null);
|
||||||
|
const [restartStates, setRestartStates] = React.useState<Record<string, 'idle' | 'loading' | 'success' | 'failed'>>({});
|
||||||
|
const [restartErrors, setRestartErrors] = React.useState<Record<string, string>>({});
|
||||||
|
const [serviceFailedClients, setServiceFailedClients] = React.useState<ServiceFailedClientsResponse | null>(null);
|
||||||
|
const [clearStates, setClearStates] = React.useState<Record<string, 'idle' | 'loading' | 'success' | 'failed'>>({});
|
||||||
|
const [clearErrors, setClearErrors] = React.useState<Record<string, string>>({});
|
||||||
|
|
||||||
const selectedClient = React.useMemo<MonitoringClient | null>(() => {
|
const selectedClient = React.useMemo<MonitoringClient | null>(() => {
|
||||||
if (!overview || !selectedClientUuid) return null;
|
if (!overview || !selectedClientUuid) return null;
|
||||||
@@ -197,9 +213,37 @@ const MonitoringDashboard: React.FC = () => {
|
|||||||
}
|
}
|
||||||
}, []);
|
}, []);
|
||||||
|
|
||||||
|
const loadCrashedClients = React.useCallback(async () => {
|
||||||
|
try {
|
||||||
|
const data = await fetchCrashedClients();
|
||||||
|
setCrashedClients(data);
|
||||||
|
} catch {
|
||||||
|
// non-fatal: crashes panel just stays stale
|
||||||
|
}
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
const loadServiceFailedClients = React.useCallback(async () => {
|
||||||
|
try {
|
||||||
|
const data = await fetchServiceFailedClients();
|
||||||
|
setServiceFailedClients(data);
|
||||||
|
} catch {
|
||||||
|
// non-fatal
|
||||||
|
}
|
||||||
|
}, []);
|
||||||
|
|
||||||
React.useEffect(() => {
|
React.useEffect(() => {
|
||||||
loadOverview(hours, false);
|
loadOverview(hours, false);
|
||||||
}, [hours, loadOverview]);
|
loadCrashedClients();
|
||||||
|
loadServiceFailedClients();
|
||||||
|
}, [hours, loadOverview, loadCrashedClients, loadServiceFailedClients]);
|
||||||
|
|
||||||
|
React.useEffect(() => {
|
||||||
|
const id = window.setInterval(() => {
|
||||||
|
loadCrashedClients();
|
||||||
|
loadServiceFailedClients();
|
||||||
|
}, REFRESH_INTERVAL_MS);
|
||||||
|
return () => window.clearInterval(id);
|
||||||
|
}, [loadCrashedClients, loadServiceFailedClients]);
|
||||||
|
|
||||||
React.useEffect(() => {
|
React.useEffect(() => {
|
||||||
const hasActivePriorityScreenshots = (overview?.summary.activePriorityScreenshots || 0) > 0;
|
const hasActivePriorityScreenshots = (overview?.summary.activePriorityScreenshots || 0) > 0;
|
||||||
@@ -308,6 +352,194 @@ const MonitoringDashboard: React.FC = () => {
|
|||||||
{renderMetricCard('Fehler-Logs', overview?.summary.errorLogs || 0, 'Im gewählten Zeitraum', '#b91c1c')}
|
{renderMetricCard('Fehler-Logs', overview?.summary.errorLogs || 0, 'Im gewählten Zeitraum', '#b91c1c')}
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
{crashedClients && crashedClients.crashed_count > 0 && (
|
||||||
|
<div className="monitoring-panel monitoring-crash-panel">
|
||||||
|
<div className="monitoring-panel-header">
|
||||||
|
<h3 style={{ color: '#dc2626' }}>
|
||||||
|
Abgestürzte / Nicht erreichbare Clients
|
||||||
|
</h3>
|
||||||
|
<span
|
||||||
|
style={{
|
||||||
|
background: '#fee2e2',
|
||||||
|
color: '#991b1b',
|
||||||
|
padding: '2px 10px',
|
||||||
|
borderRadius: '12px',
|
||||||
|
fontWeight: 600,
|
||||||
|
fontSize: '0.85rem',
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{crashedClients.crashed_count}
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
|
<table className="monitoring-crash-table">
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Client</th>
|
||||||
|
<th>Gruppe</th>
|
||||||
|
<th>Ursache</th>
|
||||||
|
<th>Prozessstatus</th>
|
||||||
|
<th>Letztes Signal</th>
|
||||||
|
<th>Aktion</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
{crashedClients.clients.map((c: CrashedClient) => {
|
||||||
|
const state = restartStates[c.uuid] || 'idle';
|
||||||
|
const errMsg = restartErrors[c.uuid];
|
||||||
|
const displayName = c.description || c.hostname || c.uuid;
|
||||||
|
return (
|
||||||
|
<tr key={c.uuid}>
|
||||||
|
<td>
|
||||||
|
<span title={c.uuid}>{displayName}</span>
|
||||||
|
{c.ip && <span className="monitoring-meta-hint"> ({c.ip})</span>}
|
||||||
|
</td>
|
||||||
|
<td>{c.group_id ?? '—'}</td>
|
||||||
|
<td>
|
||||||
|
<span
|
||||||
|
className="monitoring-status-badge"
|
||||||
|
style={
|
||||||
|
c.crash_reason === 'process_crashed'
|
||||||
|
? { color: '#991b1b', backgroundColor: '#fee2e2' }
|
||||||
|
: { color: '#78350f', backgroundColor: '#fef3c7' }
|
||||||
|
}
|
||||||
|
>
|
||||||
|
{c.crash_reason === 'process_crashed' ? 'Prozess abgestürzt' : 'Heartbeat veraltet'}
|
||||||
|
</span>
|
||||||
|
</td>
|
||||||
|
<td>{c.process_status || '—'}</td>
|
||||||
|
<td>{formatRelative(c.last_alive)}</td>
|
||||||
|
<td>
|
||||||
|
{state === 'loading' && <span style={{ color: '#6b7280', fontSize: '0.85rem' }}>Wird gesendet…</span>}
|
||||||
|
{state === 'success' && <span style={{ color: '#15803d', fontSize: '0.85rem' }}>✓ Neustart gesendet</span>}
|
||||||
|
{state === 'failed' && (
|
||||||
|
<span style={{ color: '#dc2626', fontSize: '0.85rem' }} title={errMsg}>
|
||||||
|
✗ Fehler
|
||||||
|
</span>
|
||||||
|
)}
|
||||||
|
{(state === 'idle' || state === 'failed') && (
|
||||||
|
<ButtonComponent
|
||||||
|
cssClass="e-small e-danger"
|
||||||
|
disabled={state === 'loading'}
|
||||||
|
onClick={async () => {
|
||||||
|
setRestartStates(prev => ({ ...prev, [c.uuid]: 'loading' }));
|
||||||
|
setRestartErrors(prev => { const n = { ...prev }; delete n[c.uuid]; return n; });
|
||||||
|
try {
|
||||||
|
await restartClient(c.uuid, c.crash_reason);
|
||||||
|
setRestartStates(prev => ({ ...prev, [c.uuid]: 'success' }));
|
||||||
|
setTimeout(() => {
|
||||||
|
setRestartStates(prev => ({ ...prev, [c.uuid]: 'idle' }));
|
||||||
|
loadCrashedClients();
|
||||||
|
}, 8000);
|
||||||
|
} catch (e) {
|
||||||
|
const msg = e instanceof Error ? e.message : 'Unbekannter Fehler';
|
||||||
|
setRestartStates(prev => ({ ...prev, [c.uuid]: 'failed' }));
|
||||||
|
setRestartErrors(prev => ({ ...prev, [c.uuid]: msg }));
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
Neustart
|
||||||
|
</ButtonComponent>
|
||||||
|
)}
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
);
|
||||||
|
})}
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
|
||||||
|
{serviceFailedClients && serviceFailedClients.service_failed_count > 0 && (
|
||||||
|
<div className="monitoring-panel monitoring-service-failed-panel">
|
||||||
|
<div className="monitoring-panel-header">
|
||||||
|
<h3 style={{ color: '#7c2d12' }}>
|
||||||
|
Service dauerhaft ausgefallen (systemd hat aufgegeben)
|
||||||
|
</h3>
|
||||||
|
<span
|
||||||
|
style={{
|
||||||
|
background: '#ffedd5',
|
||||||
|
color: '#7c2d12',
|
||||||
|
padding: '2px 10px',
|
||||||
|
borderRadius: '12px',
|
||||||
|
fontWeight: 600,
|
||||||
|
fontSize: '0.85rem',
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{serviceFailedClients.service_failed_count}
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
|
<p className="monitoring-meta-hint" style={{ marginBottom: '0.75rem' }}>
|
||||||
|
Diese Clients konnten von systemd nicht mehr automatisch neugestartet werden.
|
||||||
|
Manuelle Intervention erforderlich. Nach Behebung bitte quittieren.
|
||||||
|
</p>
|
||||||
|
<table className="monitoring-crash-table">
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Client</th>
|
||||||
|
<th>Gruppe</th>
|
||||||
|
<th>Unit</th>
|
||||||
|
<th>Ausgefallen am</th>
|
||||||
|
<th>Letztes Signal</th>
|
||||||
|
<th>Aktion</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
{serviceFailedClients.clients.map((c: ServiceFailedClient) => {
|
||||||
|
const state = clearStates[c.uuid] || 'idle';
|
||||||
|
const errMsg = clearErrors[c.uuid];
|
||||||
|
const displayName = c.description || c.hostname || c.uuid;
|
||||||
|
const failedAt = c.service_failed_at
|
||||||
|
? new Date(c.service_failed_at.endsWith('Z') ? c.service_failed_at : c.service_failed_at + 'Z').toLocaleString('de-DE')
|
||||||
|
: '—';
|
||||||
|
return (
|
||||||
|
<tr key={c.uuid}>
|
||||||
|
<td>
|
||||||
|
<span title={c.uuid}>{displayName}</span>
|
||||||
|
{c.ip && <span className="monitoring-meta-hint"> ({c.ip})</span>}
|
||||||
|
</td>
|
||||||
|
<td>{c.group_id ?? '—'}</td>
|
||||||
|
<td><code style={{ fontSize: '0.8rem' }}>{c.service_failed_unit || '—'}</code></td>
|
||||||
|
<td>{failedAt}</td>
|
||||||
|
<td>{formatRelative(c.last_alive)}</td>
|
||||||
|
<td>
|
||||||
|
{state === 'loading' && <span style={{ color: '#6b7280', fontSize: '0.85rem' }}>Wird quittiert…</span>}
|
||||||
|
{state === 'success' && <span style={{ color: '#15803d', fontSize: '0.85rem' }}>✓ Quittiert</span>}
|
||||||
|
{state === 'failed' && (
|
||||||
|
<span style={{ color: '#dc2626', fontSize: '0.85rem' }} title={errMsg}>✗ Fehler</span>
|
||||||
|
)}
|
||||||
|
{(state === 'idle' || state === 'failed') && (
|
||||||
|
<ButtonComponent
|
||||||
|
cssClass="e-small e-warning"
|
||||||
|
disabled={state === 'loading'}
|
||||||
|
onClick={async () => {
|
||||||
|
setClearStates(prev => ({ ...prev, [c.uuid]: 'loading' }));
|
||||||
|
setClearErrors(prev => { const n = { ...prev }; delete n[c.uuid]; return n; });
|
||||||
|
try {
|
||||||
|
await clearServiceFailed(c.uuid);
|
||||||
|
setClearStates(prev => ({ ...prev, [c.uuid]: 'success' }));
|
||||||
|
setTimeout(() => {
|
||||||
|
setClearStates(prev => ({ ...prev, [c.uuid]: 'idle' }));
|
||||||
|
loadServiceFailedClients();
|
||||||
|
}, 4000);
|
||||||
|
} catch (e) {
|
||||||
|
const msg = e instanceof Error ? e.message : 'Unbekannter Fehler';
|
||||||
|
setClearStates(prev => ({ ...prev, [c.uuid]: 'failed' }));
|
||||||
|
setClearErrors(prev => ({ ...prev, [c.uuid]: msg }));
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
Quittieren
|
||||||
|
</ButtonComponent>
|
||||||
|
)}
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
);
|
||||||
|
})}
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
|
||||||
{loading && !overview ? (
|
{loading && !overview ? (
|
||||||
<MessageComponent severity="Info" content="Monitoring-Daten werden geladen ..." />
|
<MessageComponent severity="Info" content="Monitoring-Daten werden geladen ..." />
|
||||||
) : (
|
) : (
|
||||||
@@ -393,6 +625,16 @@ const MonitoringDashboard: React.FC = () => {
|
|||||||
<span>Bildschirmstatus</span>
|
<span>Bildschirmstatus</span>
|
||||||
<strong>{selectedClient.screenHealthStatus || 'UNKNOWN'}</strong>
|
<strong>{selectedClient.screenHealthStatus || 'UNKNOWN'}</strong>
|
||||||
</div>
|
</div>
|
||||||
|
<div className="monitoring-detail-row">
|
||||||
|
<span>MQTT Reconnects</span>
|
||||||
|
<strong>{selectedClient.mqttReconnectCount != null ? selectedClient.mqttReconnectCount : '—'}</strong>
|
||||||
|
</div>
|
||||||
|
{selectedClient.mqttLastDisconnectAt && (
|
||||||
|
<div className="monitoring-detail-row">
|
||||||
|
<span>Letzter Disconnect</span>
|
||||||
|
<strong>{formatTimestamp(selectedClient.mqttLastDisconnectAt)}</strong>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
<div className="monitoring-detail-row">
|
<div className="monitoring-detail-row">
|
||||||
<span>Letzte Analyse</span>
|
<span>Letzte Analyse</span>
|
||||||
<strong>{formatTimestamp(selectedClient.lastScreenshotAnalyzed)}</strong>
|
<strong>{formatTimestamp(selectedClient.lastScreenshotAnalyzed)}</strong>
|
||||||
|
|||||||
@@ -12,10 +12,6 @@ interface ProgramInfo {
|
|||||||
frontend: { name: string; license: string }[];
|
frontend: { name: string; license: string }[];
|
||||||
backend: { name: string; license: string }[];
|
backend: { name: string; license: string }[];
|
||||||
};
|
};
|
||||||
buildInfo: {
|
|
||||||
buildDate: string;
|
|
||||||
commitId: string;
|
|
||||||
};
|
|
||||||
changelog: {
|
changelog: {
|
||||||
version: string;
|
version: string;
|
||||||
date: string;
|
date: string;
|
||||||
@@ -85,30 +81,30 @@ const Programminfo: React.FC = () => {
|
|||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
<div className="e-card-content">
|
<div className="e-card-content">
|
||||||
<div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
|
<div style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem' }}>
|
||||||
<p>
|
<div><strong>Version:</strong> {info.version}</div>
|
||||||
<strong>Version:</strong> {info.version}
|
<div><strong>Copyright:</strong> {info.copyright}</div>
|
||||||
</p>
|
<div>
|
||||||
<p>
|
|
||||||
<strong>Copyright:</strong> {info.copyright}
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
<strong>Support:</strong>{' '}
|
<strong>Support:</strong>{' '}
|
||||||
<a href={`mailto:${info.supportContact}`} style={{ color: '#2563eb', textDecoration: 'none' }}>
|
<a href={`mailto:${info.supportContact}`} style={{ color: '#2563eb', textDecoration: 'none' }}>
|
||||||
{info.supportContact}
|
{info.supportContact}
|
||||||
</a>
|
</a>
|
||||||
</p>
|
</div>
|
||||||
<hr style={{ margin: '1rem 0' }} />
|
<hr style={{ margin: '0.5rem 0' }} />
|
||||||
<h4 style={{ fontWeight: 600 }}>Build-Informationen</h4>
|
<div style={{ fontWeight: 600, fontSize: '0.875rem', marginBottom: '0.125rem' }}>Build-Informationen</div>
|
||||||
<p>
|
<div><strong>Build-Datum:</strong> {new Date(__BUILD_DATE__).toLocaleString('de-DE')}</div>
|
||||||
<strong>Build-Datum:</strong> {new Date(info.buildInfo.buildDate).toLocaleString('de-DE')}
|
<div>
|
||||||
</p>
|
<strong>Umgebung:</strong>{' '}
|
||||||
<p>
|
|
||||||
<strong>Commit-ID:</strong>{' '}
|
|
||||||
<span style={{ fontFamily: monoFont, fontSize: '0.875rem', background: '#f3f4f6', padding: '0.125rem 0.25rem', borderRadius: '0.25rem' }}>
|
<span style={{ fontFamily: monoFont, fontSize: '0.875rem', background: '#f3f4f6', padding: '0.125rem 0.25rem', borderRadius: '0.25rem' }}>
|
||||||
{info.buildInfo.commitId}
|
{__BUILD_ENV__}
|
||||||
</span>
|
</span>
|
||||||
</p>
|
</div>
|
||||||
|
<div>
|
||||||
|
<strong>Node.js:</strong>{' '}
|
||||||
|
<span style={{ fontFamily: monoFont, fontSize: '0.875rem', background: '#f3f4f6', padding: '0.125rem 0.25rem', borderRadius: '0.25rem' }}>
|
||||||
|
{__NODE_VERSION__}
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
4
dashboard/src/vite-env.d.ts
vendored
4
dashboard/src/vite-env.d.ts
vendored
@@ -1 +1,5 @@
|
|||||||
/// <reference types="vite/client" />
|
/// <reference types="vite/client" />
|
||||||
|
|
||||||
|
declare const __BUILD_DATE__: string;
|
||||||
|
declare const __NODE_VERSION__: string;
|
||||||
|
declare const __BUILD_ENV__: string;
|
||||||
|
|||||||
@@ -6,6 +6,11 @@ import react from '@vitejs/plugin-react';
|
|||||||
export default defineConfig({
|
export default defineConfig({
|
||||||
cacheDir: './.vite',
|
cacheDir: './.vite',
|
||||||
plugins: [react()],
|
plugins: [react()],
|
||||||
|
define: {
|
||||||
|
__BUILD_DATE__: JSON.stringify(new Date().toISOString()),
|
||||||
|
__NODE_VERSION__: JSON.stringify(process.version),
|
||||||
|
__BUILD_ENV__: JSON.stringify(process.env.NODE_ENV ?? 'development'),
|
||||||
|
},
|
||||||
resolve: {
|
resolve: {
|
||||||
// 🔧 KORRIGIERT: Entferne die problematischen Aliases komplett
|
// 🔧 KORRIGIERT: Entferne die problematischen Aliases komplett
|
||||||
// Diese verursachen das "not an absolute path" Problem
|
// Diese verursachen das "not an absolute path" Problem
|
||||||
|
|||||||
@@ -45,15 +45,37 @@ services:
|
|||||||
image: eclipse-mosquitto:2.0.21
|
image: eclipse-mosquitto:2.0.21
|
||||||
container_name: infoscreen-mqtt
|
container_name: infoscreen-mqtt
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
|
command: >
|
||||||
|
sh -c 'set -eu;
|
||||||
|
: "$${MQTT_USER:?MQTT_USER not set}";
|
||||||
|
: "$${MQTT_PASSWORD:?MQTT_PASSWORD not set}";
|
||||||
|
touch /mosquitto/config/passwd;
|
||||||
|
chmod 600 /mosquitto/config/passwd;
|
||||||
|
mosquitto_passwd -b /mosquitto/config/passwd "$${MQTT_USER}" "$${MQTT_PASSWORD}";
|
||||||
|
if [ -n "$${MQTT_CANARY_USER:-}" ] && [ -n "$${MQTT_CANARY_PASSWORD:-}" ]; then
|
||||||
|
mosquitto_passwd -b /mosquitto/config/passwd "$${MQTT_CANARY_USER}" "$${MQTT_CANARY_PASSWORD}";
|
||||||
|
fi;
|
||||||
|
exec mosquitto -c /mosquitto/config/mosquitto.conf'
|
||||||
volumes:
|
volumes:
|
||||||
- ./mosquitto/config/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
|
- ./mosquitto/config:/mosquitto/config
|
||||||
|
- ./mosquitto/data:/mosquitto/data
|
||||||
|
- ./mosquitto/log:/mosquitto/log
|
||||||
ports:
|
ports:
|
||||||
- "1883:1883"
|
- "1883:1883"
|
||||||
- "9001:9001"
|
- "9001:9001"
|
||||||
|
environment:
|
||||||
|
- MQTT_USER=${MQTT_USER}
|
||||||
|
- MQTT_PASSWORD=${MQTT_PASSWORD}
|
||||||
|
- MQTT_CANARY_USER=${MQTT_CANARY_USER:-}
|
||||||
|
- MQTT_CANARY_PASSWORD=${MQTT_CANARY_PASSWORD:-}
|
||||||
networks:
|
networks:
|
||||||
- infoscreen-net
|
- infoscreen-net
|
||||||
healthcheck:
|
healthcheck:
|
||||||
test: ["CMD-SHELL", "mosquitto_pub -h localhost -t test -m 'health' || exit 1"]
|
test:
|
||||||
|
[
|
||||||
|
"CMD-SHELL",
|
||||||
|
"mosquitto_pub -h localhost -u $$MQTT_USER -P $$MQTT_PASSWORD -t test -m 'health' || exit 1",
|
||||||
|
]
|
||||||
interval: 30s
|
interval: 30s
|
||||||
timeout: 5s
|
timeout: 5s
|
||||||
retries: 3
|
retries: 3
|
||||||
@@ -94,6 +116,7 @@ services:
|
|||||||
command: >
|
command: >
|
||||||
bash -c "alembic -c /app/server/alembic.ini upgrade head &&
|
bash -c "alembic -c /app/server/alembic.ini upgrade head &&
|
||||||
python /app/server/init_defaults.py &&
|
python /app/server/init_defaults.py &&
|
||||||
|
python /app/server/init_academic_periods.py &&
|
||||||
exec gunicorn server.wsgi:app --bind 0.0.0.0:8000"
|
exec gunicorn server.wsgi:app --bind 0.0.0.0:8000"
|
||||||
|
|
||||||
dashboard:
|
dashboard:
|
||||||
@@ -124,6 +147,11 @@ services:
|
|||||||
DB_PASSWORD: ${DB_PASSWORD}
|
DB_PASSWORD: ${DB_PASSWORD}
|
||||||
DB_NAME: ${DB_NAME}
|
DB_NAME: ${DB_NAME}
|
||||||
DB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
|
DB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
|
||||||
|
API_BASE_URL: http://server:8000
|
||||||
|
MQTT_BROKER_HOST: ${MQTT_BROKER_HOST:-mqtt}
|
||||||
|
MQTT_BROKER_PORT: ${MQTT_BROKER_PORT:-1883}
|
||||||
|
MQTT_USER: ${MQTT_USER}
|
||||||
|
MQTT_PASSWORD: ${MQTT_PASSWORD}
|
||||||
networks:
|
networks:
|
||||||
- infoscreen-net
|
- infoscreen-net
|
||||||
|
|
||||||
@@ -140,7 +168,18 @@ services:
|
|||||||
environment:
|
environment:
|
||||||
# HINZUGEFÜGT: Datenbank-Verbindungsstring
|
# HINZUGEFÜGT: Datenbank-Verbindungsstring
|
||||||
DB_CONN: "mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}"
|
DB_CONN: "mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}"
|
||||||
MQTT_PORT: 1883
|
MQTT_BROKER_HOST: ${MQTT_BROKER_HOST:-mqtt}
|
||||||
|
MQTT_BROKER_PORT: ${MQTT_BROKER_PORT:-1883}
|
||||||
|
MQTT_USER: ${MQTT_USER}
|
||||||
|
MQTT_PASSWORD: ${MQTT_PASSWORD}
|
||||||
|
POLL_INTERVAL_SECONDS: ${POLL_INTERVAL_SECONDS:-30}
|
||||||
|
POWER_INTENT_PUBLISH_ENABLED: ${POWER_INTENT_PUBLISH_ENABLED:-false}
|
||||||
|
POWER_INTENT_HEARTBEAT_ENABLED: ${POWER_INTENT_HEARTBEAT_ENABLED:-true}
|
||||||
|
POWER_INTENT_EXPIRY_MULTIPLIER: ${POWER_INTENT_EXPIRY_MULTIPLIER:-3}
|
||||||
|
POWER_INTENT_MIN_EXPIRY_SECONDS: ${POWER_INTENT_MIN_EXPIRY_SECONDS:-90}
|
||||||
|
CRASH_RECOVERY_ENABLED: ${CRASH_RECOVERY_ENABLED:-false}
|
||||||
|
CRASH_RECOVERY_GRACE_SECONDS: ${CRASH_RECOVERY_GRACE_SECONDS:-180}
|
||||||
|
CRASH_RECOVERY_LOCKOUT_MINUTES: ${CRASH_RECOVERY_LOCKOUT_MINUTES:-15}
|
||||||
networks:
|
networks:
|
||||||
- infoscreen-net
|
- infoscreen-net
|
||||||
|
|
||||||
|
|||||||
@@ -19,6 +19,10 @@ services:
|
|||||||
- DB_CONN=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}
|
- DB_CONN=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}
|
||||||
- DB_URL=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}
|
- DB_URL=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}
|
||||||
- API_BASE_URL=http://server:8000
|
- API_BASE_URL=http://server:8000
|
||||||
|
- MQTT_BROKER_HOST=${MQTT_BROKER_HOST:-mqtt}
|
||||||
|
- MQTT_BROKER_PORT=${MQTT_BROKER_PORT:-1883}
|
||||||
|
- MQTT_USER=${MQTT_USER}
|
||||||
|
- MQTT_PASSWORD=${MQTT_PASSWORD}
|
||||||
- ENV=${ENV:-development}
|
- ENV=${ENV:-development}
|
||||||
- FLASK_SECRET_KEY=${FLASK_SECRET_KEY:-dev-secret-key-change-in-production}
|
- FLASK_SECRET_KEY=${FLASK_SECRET_KEY:-dev-secret-key-change-in-production}
|
||||||
- DEFAULT_SUPERADMIN_USERNAME=${DEFAULT_SUPERADMIN_USERNAME:-superadmin}
|
- DEFAULT_SUPERADMIN_USERNAME=${DEFAULT_SUPERADMIN_USERNAME:-superadmin}
|
||||||
@@ -70,6 +74,17 @@ services:
|
|||||||
image: eclipse-mosquitto:2.0.21 # ✅ GUT: Version ist bereits spezifisch
|
image: eclipse-mosquitto:2.0.21 # ✅ GUT: Version ist bereits spezifisch
|
||||||
container_name: infoscreen-mqtt
|
container_name: infoscreen-mqtt
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
|
command: >
|
||||||
|
sh -c 'set -eu;
|
||||||
|
: "$${MQTT_USER:?MQTT_USER not set}";
|
||||||
|
: "$${MQTT_PASSWORD:?MQTT_PASSWORD not set}";
|
||||||
|
touch /mosquitto/config/passwd;
|
||||||
|
chmod 600 /mosquitto/config/passwd;
|
||||||
|
mosquitto_passwd -b /mosquitto/config/passwd "$${MQTT_USER}" "$${MQTT_PASSWORD}";
|
||||||
|
if [ -n "$${MQTT_CANARY_USER:-}" ] && [ -n "$${MQTT_CANARY_PASSWORD:-}" ]; then
|
||||||
|
mosquitto_passwd -b /mosquitto/config/passwd "$${MQTT_CANARY_USER}" "$${MQTT_CANARY_PASSWORD}";
|
||||||
|
fi;
|
||||||
|
exec mosquitto -c /mosquitto/config/mosquitto.conf'
|
||||||
volumes:
|
volumes:
|
||||||
- ./mosquitto/config:/mosquitto/config
|
- ./mosquitto/config:/mosquitto/config
|
||||||
- ./mosquitto/data:/mosquitto/data
|
- ./mosquitto/data:/mosquitto/data
|
||||||
@@ -77,13 +92,18 @@ services:
|
|||||||
ports:
|
ports:
|
||||||
- "1883:1883" # Standard MQTT
|
- "1883:1883" # Standard MQTT
|
||||||
- "9001:9001" # WebSocket (falls benötigt)
|
- "9001:9001" # WebSocket (falls benötigt)
|
||||||
|
environment:
|
||||||
|
- MQTT_USER=${MQTT_USER}
|
||||||
|
- MQTT_PASSWORD=${MQTT_PASSWORD}
|
||||||
|
- MQTT_CANARY_USER=${MQTT_CANARY_USER:-}
|
||||||
|
- MQTT_CANARY_PASSWORD=${MQTT_CANARY_PASSWORD:-}
|
||||||
networks:
|
networks:
|
||||||
- infoscreen-net
|
- infoscreen-net
|
||||||
healthcheck:
|
healthcheck:
|
||||||
test:
|
test:
|
||||||
[
|
[
|
||||||
"CMD-SHELL",
|
"CMD-SHELL",
|
||||||
"mosquitto_pub -h localhost -t test -m 'health' || exit 1",
|
"mosquitto_pub -h localhost -u $$MQTT_USER -P $$MQTT_PASSWORD -t test -m 'health' || exit 1",
|
||||||
]
|
]
|
||||||
interval: 30s
|
interval: 30s
|
||||||
timeout: 5s
|
timeout: 5s
|
||||||
@@ -169,7 +189,18 @@ services:
|
|||||||
environment:
|
environment:
|
||||||
# HINZUGEFÜGT: Datenbank-Verbindungsstring
|
# HINZUGEFÜGT: Datenbank-Verbindungsstring
|
||||||
- DB_CONN=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}
|
- DB_CONN=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME}
|
||||||
- MQTT_PORT=1883
|
- MQTT_BROKER_HOST=${MQTT_BROKER_HOST:-mqtt}
|
||||||
|
- MQTT_BROKER_PORT=${MQTT_BROKER_PORT:-1883}
|
||||||
|
- MQTT_USER=${MQTT_USER}
|
||||||
|
- MQTT_PASSWORD=${MQTT_PASSWORD}
|
||||||
|
- POLL_INTERVAL_SECONDS=${POLL_INTERVAL_SECONDS:-30}
|
||||||
|
- POWER_INTENT_PUBLISH_ENABLED=${POWER_INTENT_PUBLISH_ENABLED:-false}
|
||||||
|
- POWER_INTENT_HEARTBEAT_ENABLED=${POWER_INTENT_HEARTBEAT_ENABLED:-true}
|
||||||
|
- POWER_INTENT_EXPIRY_MULTIPLIER=${POWER_INTENT_EXPIRY_MULTIPLIER:-3}
|
||||||
|
- POWER_INTENT_MIN_EXPIRY_SECONDS=${POWER_INTENT_MIN_EXPIRY_SECONDS:-90}
|
||||||
|
- CRASH_RECOVERY_ENABLED=${CRASH_RECOVERY_ENABLED:-false}
|
||||||
|
- CRASH_RECOVERY_GRACE_SECONDS=${CRASH_RECOVERY_GRACE_SECONDS:-180}
|
||||||
|
- CRASH_RECOVERY_LOCKOUT_MINUTES=${CRASH_RECOVERY_LOCKOUT_MINUTES:-15}
|
||||||
networks:
|
networks:
|
||||||
- infoscreen-net
|
- infoscreen-net
|
||||||
|
|
||||||
|
|||||||
361
docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md
Normal file
361
docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md
Normal file
@@ -0,0 +1,361 @@
|
|||||||
|
# Academic Periods CRUD Build Plan
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Add full academic period lifecycle management to the settings page and backend, including safe archive and hard-delete behavior, recurrence spillover blockers, and a UI restructuring where `Perioden` becomes the first sub-tab under `Akademischer Kalender`.
|
||||||
|
|
||||||
|
## Frontend Design Rules
|
||||||
|
|
||||||
|
All UI implementation for this build must follow the project-wide frontend design rules:
|
||||||
|
|
||||||
|
→ **[FRONTEND_DESIGN_RULES.md](FRONTEND_DESIGN_RULES.md)**
|
||||||
|
|
||||||
|
Key points relevant to this build:
|
||||||
|
- Syncfusion Material3 components are the default for every UI element
|
||||||
|
- Use `DialogComponent` for all confirmations — never `window.confirm()`
|
||||||
|
- Follow the established card structure, button variants, badge colors, and tab patterns
|
||||||
|
- German strings only in all user-facing text
|
||||||
|
- No Tailwind classes
|
||||||
|
|
||||||
|
## Agreed Rules
|
||||||
|
|
||||||
|
### Permissions
|
||||||
|
|
||||||
|
- Create: admin or higher
|
||||||
|
- Edit: admin or higher
|
||||||
|
- Archive: admin or higher
|
||||||
|
- Restore: admin or higher
|
||||||
|
- Hard delete: admin or higher
|
||||||
|
- Activate: admin or higher
|
||||||
|
- Editors do not activate periods by default because activation changes global system state
|
||||||
|
|
||||||
|
### Lifecycle
|
||||||
|
|
||||||
|
- Active: exactly one period at a time
|
||||||
|
- Inactive: saved period, not currently active
|
||||||
|
- Archived: retired period, hidden from normal operational selection
|
||||||
|
- Deleted: physically removed only when delete preconditions are satisfied
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
- `name` is required, trimmed, and unique among non-archived periods
|
||||||
|
- `startDate` must be less than or equal to `endDate`
|
||||||
|
- `periodType` must be one of `schuljahr`, `semester`, `trimester`
|
||||||
|
- Overlaps are disallowed within the same `periodType`
|
||||||
|
- Overlaps across different `periodType` values are allowed
|
||||||
|
- Exactly one period may be active at a time
|
||||||
|
|
||||||
|
### Archive Rules
|
||||||
|
|
||||||
|
- Active periods cannot be archived
|
||||||
|
- A period cannot be archived if it still has operational dependencies
|
||||||
|
- Operational dependencies include recurring master events assigned to that period that still generate current or future occurrences
|
||||||
|
|
||||||
|
### Restore Rules
|
||||||
|
|
||||||
|
- Archived periods can be restored by admin or higher
|
||||||
|
- Restored periods return as inactive by default
|
||||||
|
|
||||||
|
### Hard Delete Rules
|
||||||
|
|
||||||
|
- Only archived and inactive periods can be hard-deleted
|
||||||
|
- Hard delete is blocked if linked events exist
|
||||||
|
- Hard delete is blocked if linked media exist
|
||||||
|
- Hard delete is blocked if recurring master events assigned to the period still have current or future scheduling relevance
|
||||||
|
|
||||||
|
### Recurrence Spillover Rule
|
||||||
|
|
||||||
|
- If a recurring master event belongs to an older period but still creates occurrences in the current or future timeframe, that older period is not eligible for archive or hard delete
|
||||||
|
- Admin must resolve the recurrence by ending, splitting, or reassigning the series before the period can be retired or deleted
|
||||||
|
|
||||||
|
## Build-Oriented Task Plan
|
||||||
|
|
||||||
|
### Phase 1: Lock The Contract
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `server/routes/academic_periods.py`
|
||||||
|
- `models/models.py`
|
||||||
|
- `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Freeze lifecycle rules, validation rules, and blocker rules
|
||||||
|
- Freeze the settings tab order so `Perioden` comes before `Import & Liste`
|
||||||
|
- Confirm response shape for new endpoints
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Stable implementation contract for backend and frontend work
|
||||||
|
|
||||||
|
### Phase 2: Extend The Data Model
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `models/models.py`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Add archive lifecycle fields to academic periods
|
||||||
|
- Recommended fields: `is_archived`, `archived_at`, `archived_by`
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Academic periods can be retired safely and restored later
|
||||||
|
|
||||||
|
### Phase 3: Add The Database Migration
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `server/alembic.ini`
|
||||||
|
- `server/alembic/`
|
||||||
|
- `server/initialize_database.py`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Add Alembic migration for archive-related fields and any supporting indexes
|
||||||
|
- Ensure existing periods default to non-archived
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Schema upgrade path for current installations
|
||||||
|
|
||||||
|
### Phase 4: Expand The Backend API
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `server/routes/academic_periods.py`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Implement full lifecycle endpoints:
|
||||||
|
- `GET /api/academic_periods`
|
||||||
|
- `GET /api/academic_periods/:id`
|
||||||
|
- `POST /api/academic_periods`
|
||||||
|
- `PUT /api/academic_periods/:id`
|
||||||
|
- `POST /api/academic_periods/:id/activate`
|
||||||
|
- `POST /api/academic_periods/:id/archive`
|
||||||
|
- `POST /api/academic_periods/:id/restore`
|
||||||
|
- `GET /api/academic_periods/:id/usage`
|
||||||
|
- `DELETE /api/academic_periods/:id`
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Academic periods become a fully managed backend resource
|
||||||
|
|
||||||
|
### Phase 5: Add Backend Validation And Guardrails
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `server/routes/academic_periods.py`
|
||||||
|
- `models/models.py`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Enforce required fields, type checks, date checks, overlap checks, and one-active-period behavior
|
||||||
|
- Block archive and delete when dependency rules fail
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Backend owns all business-critical safeguards
|
||||||
|
|
||||||
|
### Phase 6: Implement Recurrence Spillover Detection
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `server/routes/academic_periods.py`
|
||||||
|
- `server/routes/events.py`
|
||||||
|
- `models/models.py`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Detect recurring master events assigned to a period that still generate present or future occurrences
|
||||||
|
- Treat them as blockers for archive and hard delete
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Old periods cannot be retired while they still affect the active schedule
|
||||||
|
|
||||||
|
### Phase 7: Normalize API Serialization
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `server/routes/academic_periods.py`
|
||||||
|
- `server/serializers.py`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Return academic period responses in camelCase consistently with the rest of the API
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Frontend receives normalized API payloads without special-case mapping
|
||||||
|
|
||||||
|
### Phase 8: Expand The Frontend API Client
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `dashboard/src/apiAcademicPeriods.ts`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Add frontend client methods for create, update, activate, archive, restore, usage lookup, and hard delete
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- The settings page can manage academic periods through one dedicated API module
|
||||||
|
|
||||||
|
### Phase 9: Reorder The Akademischer Kalender Sub-Tabs
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Move `Perioden` to the first sub-tab
|
||||||
|
- Move `Import & Liste` to the second sub-tab
|
||||||
|
- Preserve controlled tab state behavior
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- The settings flow reflects setup before import work
|
||||||
|
|
||||||
|
### Phase 10: Replace The Current Period Selector With A Management UI
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Replace the selector-only period card with a proper management surface
|
||||||
|
- Show period metadata, active state, archived state, and available actions
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- The periods tab becomes a real administration UI
|
||||||
|
|
||||||
|
### Phase 11: Add Create And Edit Flows
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Add create and edit dialogs or form panels
|
||||||
|
- Validate input before save and surface backend errors clearly
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Admins can maintain periods directly in settings
|
||||||
|
|
||||||
|
### Phase 12: Add Archive, Restore, And Hard Delete UX
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Fetch usage or preflight data before destructive actions
|
||||||
|
- Show exact blockers for linked events, linked media, and recurrence spillover
|
||||||
|
- Use explicit confirmation dialogs for archive and hard delete
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Destructive actions are safe and understandable
|
||||||
|
|
||||||
|
### Phase 13: Add Archived Visibility Controls
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Hide archived periods by default or group them behind a toggle
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Normal operational periods stay easy to manage while retired periods remain accessible
|
||||||
|
|
||||||
|
### Phase 14: Add Backend Tests
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- Backend academic period test targets to be identified during implementation
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Cover create, edit, activate, archive, restore, hard delete, overlap rejection, dependency blockers, and recurrence spillover blockers
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Lifecycle rules are regression-safe
|
||||||
|
|
||||||
|
### Phase 15: Add Frontend Verification
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `dashboard/src/settings.tsx`
|
||||||
|
- Frontend test targets to be identified during implementation
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Verify sub-tab order, CRUD refresh behavior, blocked action messaging, and activation behavior
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Settings UX remains stable after the management upgrade
|
||||||
|
|
||||||
|
### Phase 16: Update Documentation
|
||||||
|
|
||||||
|
Files:
|
||||||
|
|
||||||
|
- `.github/copilot-instructions.md`
|
||||||
|
- `README.md`
|
||||||
|
- `TECH-CHANGELOG.md`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
|
||||||
|
- Document academic period lifecycle behavior, blocker rules, and updated settings tab order as appropriate
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- Repo guidance stays aligned with implemented behavior
|
||||||
|
|
||||||
|
## Suggested Build Sequence
|
||||||
|
|
||||||
|
1. Freeze rules and response shape
|
||||||
|
2. Change the model
|
||||||
|
3. Add the migration
|
||||||
|
4. Build backend endpoints
|
||||||
|
5. Add blocker logic and recurrence checks
|
||||||
|
6. Expand the frontend API client
|
||||||
|
7. Reorder sub-tabs
|
||||||
|
8. Build period management UI
|
||||||
|
9. Add destructive-action preflight UX
|
||||||
|
10. Add tests
|
||||||
|
11. Update documentation
|
||||||
|
|
||||||
|
## Recommended Delivery Split
|
||||||
|
|
||||||
|
1. Backend foundation
|
||||||
|
- Model
|
||||||
|
- Migration
|
||||||
|
- Routes
|
||||||
|
- Validation
|
||||||
|
- Blocker logic
|
||||||
|
|
||||||
|
2. Frontend management
|
||||||
|
- API client
|
||||||
|
- Tab reorder
|
||||||
|
- Management UI
|
||||||
|
- Dialogs
|
||||||
|
- Usage messaging
|
||||||
|
|
||||||
|
3. Verification and docs
|
||||||
|
- Tests
|
||||||
|
- Documentation
|
||||||
434
docs/archive/ACADEMIC_PERIODS_IMPLEMENTATION_SUMMARY.md
Normal file
434
docs/archive/ACADEMIC_PERIODS_IMPLEMENTATION_SUMMARY.md
Normal file
@@ -0,0 +1,434 @@
|
|||||||
|
# Academic Periods CRUD Implementation - Complete Summary
|
||||||
|
|
||||||
|
> Historical snapshot: this file captures the state at implementation time.
|
||||||
|
> For current behavior and conventions, use [README.md](../../README.md) and [.github/copilot-instructions.md](../../.github/copilot-instructions.md).
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
Successfully implemented the complete academic periods lifecycle management system as outlined in `docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md`. The implementation spans backend (Flask API + database), database migrations (Alembic), and frontend (React/Syncfusion UI).
|
||||||
|
|
||||||
|
**Status**: ✅ COMPLETE (All 16 phases)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Details
|
||||||
|
|
||||||
|
### Phase 1: Contract Locked ✅
|
||||||
|
**Files**: `docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md`
|
||||||
|
|
||||||
|
Identified the contract requirements and inconsistencies to resolve:
|
||||||
|
- Unique constraint on name should exclude archived periods (handled in code via indexed query)
|
||||||
|
- One-active-period rule enforced in code (transaction safety)
|
||||||
|
- Recurrence spillover detection implemented via RFC 5545 expansion
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Data Model Extended ✅
|
||||||
|
**File**: `models/models.py`
|
||||||
|
|
||||||
|
Added archive lifecycle fields to `AcademicPeriod` class:
|
||||||
|
```python
|
||||||
|
is_archived = Column(Boolean, default=False, nullable=False, index=True)
|
||||||
|
archived_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
archived_by = Column(Integer, ForeignKey('users.id', ondelete='SET NULL'), nullable=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
Added indexes for:
|
||||||
|
- `ix_academic_periods_archived` - fast filtering of archived status
|
||||||
|
- `ix_academic_periods_name_not_archived` - unique name checks among non-archived
|
||||||
|
|
||||||
|
Updated `to_dict()` method to include all archive fields in camelCase.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Database Migration Created ✅
|
||||||
|
**File**: `server/alembic/versions/a7b8c9d0e1f2_add_archive_lifecycle_to_academic_periods.py`
|
||||||
|
|
||||||
|
Created Alembic migration that:
|
||||||
|
- Adds `is_archived`, `archived_at`, `archived_by` columns with server defaults
|
||||||
|
- Creates foreign key constraint for `archived_by` with CASCADE on user delete
|
||||||
|
- Creates indexes for performance
|
||||||
|
- Includes rollback (downgrade) logic
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 4: Backend CRUD Endpoints Implemented ✅
|
||||||
|
**File**: `server/routes/academic_periods.py` (completely rewritten)
|
||||||
|
|
||||||
|
Implemented 11 endpoints (including 6 updates to existing):
|
||||||
|
|
||||||
|
#### Read Endpoints
|
||||||
|
- `GET /api/academic_periods` - list non-archived periods
|
||||||
|
- `GET /api/academic_periods/<id>` - get single period (including archived)
|
||||||
|
- `GET /api/academic_periods/active` - get currently active period
|
||||||
|
- `GET /api/academic_periods/for_date` - get period by date (non-archived)
|
||||||
|
- `GET /api/academic_periods/<id>/usage` - check blockers for archive/delete
|
||||||
|
|
||||||
|
#### Write Endpoints
|
||||||
|
- `POST /api/academic_periods` - create new period
|
||||||
|
- `PUT /api/academic_periods/<id>` - update period (not archived)
|
||||||
|
- `POST /api/academic_periods/<id>/activate` - activate (deactivates others)
|
||||||
|
- `POST /api/academic_periods/<id>/archive` - soft delete with blocker check
|
||||||
|
- `POST /api/academic_periods/<id>/restore` - unarchive to inactive
|
||||||
|
- `DELETE /api/academic_periods/<id>` - hard delete with blocker check
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 5-6: Validation & Recurrence Spillover ✅
|
||||||
|
**Files**: `server/routes/academic_periods.py`
|
||||||
|
|
||||||
|
Implemented comprehensive validation:
|
||||||
|
|
||||||
|
#### Create/Update Validation
|
||||||
|
- Name: required, trimmed, unique among non-archived (excluding self for update)
|
||||||
|
- Dates: `startDate` ≤ `endDate` enforced
|
||||||
|
- Period type: must be one of `schuljahr`, `semester`, `trimester`
|
||||||
|
- Overlaps: disallowed within same periodType (allowed across types)
|
||||||
|
|
||||||
|
#### Lifecycle Enforcement
|
||||||
|
- Cannot activate archived periods
|
||||||
|
- Cannot archive active periods
|
||||||
|
- Cannot archive periods with active recurring events
|
||||||
|
- Cannot hard-delete non-archived periods
|
||||||
|
- Cannot hard-delete periods with linked events
|
||||||
|
|
||||||
|
#### Recurrence Spillover Detection
|
||||||
|
Detects if old periods have recurring master events with current/future occurrences:
|
||||||
|
```python
|
||||||
|
rrule_obj = rrulestr(event.recurrence_rule, dtstart=event.start)
|
||||||
|
next_occurrence = rrule_obj.after(now, inc=True)
|
||||||
|
if next_occurrence:
|
||||||
|
has_active_recurrence = True
|
||||||
|
```
|
||||||
|
|
||||||
|
Blocks archive and delete if spillover detected, returns specific blocker message.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 7: API Serialization ✅
|
||||||
|
**File**: `server/routes/academic_periods.py`
|
||||||
|
|
||||||
|
All API responses return camelCase JSON using `dict_to_camel_case()`:
|
||||||
|
```python
|
||||||
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 200
|
||||||
|
```
|
||||||
|
|
||||||
|
Response fields in camelCase:
|
||||||
|
- `startDate`, `endDate` (from `start_date`, `end_date`)
|
||||||
|
- `periodType` (from `period_type`)
|
||||||
|
- `isActive`, `isArchived` (from `is_active`, `is_archived`)
|
||||||
|
- `archivedAt`, `archivedBy` (from `archived_at`, `archived_by`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 8: Frontend API Client Expanded ✅
|
||||||
|
**File**: `dashboard/src/apiAcademicPeriods.ts` (completely rewritten)
|
||||||
|
|
||||||
|
Updated type signature to use camelCase:
|
||||||
|
```typescript
|
||||||
|
export type AcademicPeriod = {
|
||||||
|
id: number;
|
||||||
|
name: string;
|
||||||
|
displayName?: string | null;
|
||||||
|
startDate: string;
|
||||||
|
endDate: string;
|
||||||
|
periodType: 'schuljahr' | 'semester' | 'trimester';
|
||||||
|
isActive: boolean;
|
||||||
|
isArchived: boolean;
|
||||||
|
archivedAt?: string | null;
|
||||||
|
archivedBy?: number | null;
|
||||||
|
};
|
||||||
|
|
||||||
|
export type PeriodUsage = {
|
||||||
|
linked_events: number;
|
||||||
|
has_active_recurrence: boolean;
|
||||||
|
blockers: string[];
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Implemented 9 API client functions:
|
||||||
|
- `listAcademicPeriods()` - list non-archived
|
||||||
|
- `getAcademicPeriod(id)` - get single
|
||||||
|
- `getActiveAcademicPeriod()` - get active
|
||||||
|
- `getAcademicPeriodForDate(date)` - get by date
|
||||||
|
- `createAcademicPeriod(payload)` - create
|
||||||
|
- `updateAcademicPeriod(id, payload)` - update
|
||||||
|
- `setActiveAcademicPeriod(id)` - activate
|
||||||
|
- `archiveAcademicPeriod(id)` - archive
|
||||||
|
- `restoreAcademicPeriod(id)` - restore
|
||||||
|
- `getAcademicPeriodUsage(id)` - get blockers
|
||||||
|
- `deleteAcademicPeriod(id)` - hard delete
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 9: Academic Calendar Tab Reordered ✅
|
||||||
|
**File**: `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Changed Academic Calendar sub-tabs order:
|
||||||
|
```
|
||||||
|
Before: 📥 Import & Liste, 🗂️ Perioden
|
||||||
|
After: 🗂️ Perioden, 📥 Import & Liste
|
||||||
|
```
|
||||||
|
|
||||||
|
New order reflects: setup periods → import holidays workflow
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 10-12: Management UI Built ✅
|
||||||
|
**File**: `dashboard/src/settings.tsx` (AcademicPeriodsContent component)
|
||||||
|
|
||||||
|
Replaced simple dropdown with comprehensive CRUD interface:
|
||||||
|
|
||||||
|
#### State Management Added
|
||||||
|
```typescript
|
||||||
|
// Dialog visibility
|
||||||
|
[showCreatePeriodDialog, showEditPeriodDialog, showArchiveDialog,
|
||||||
|
showRestoreDialog, showDeleteDialog,
|
||||||
|
showArchiveBlockedDialog, showDeleteBlockedDialog]
|
||||||
|
|
||||||
|
// Form and UI state
|
||||||
|
[periodFormData, selectedPeriodId, periodUsage, periodBusy, showArchivedOnly]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### UI Features
|
||||||
|
|
||||||
|
**Period List Display**
|
||||||
|
- Cards showing name, displayName, dates, periodType
|
||||||
|
- Badges: "Aktiv" (green), "Archiviert" (gray)
|
||||||
|
- Filter toggle to show/hide archived periods
|
||||||
|
|
||||||
|
**Create/Edit Dialog**
|
||||||
|
- TextBox fields: name, displayName
|
||||||
|
- Date inputs: startDate, endDate (HTML5 date type)
|
||||||
|
- DropDownList for periodType
|
||||||
|
- Full validation on save
|
||||||
|
|
||||||
|
**Action Buttons**
|
||||||
|
- Non-archived: Activate (if not active), Bearbeiten, Archivieren
|
||||||
|
- Archived: Wiederherstellen, Löschen (red danger button)
|
||||||
|
|
||||||
|
**Confirmation Dialogs**
|
||||||
|
- Archive confirmation
|
||||||
|
- Archive blocked (shows blocker list with exact reasons)
|
||||||
|
- Restore confirmation
|
||||||
|
- Delete confirmation
|
||||||
|
- Delete blocked (shows blocker list)
|
||||||
|
|
||||||
|
#### Handler Functions
|
||||||
|
- `handleEditPeriod()` - populate form from period
|
||||||
|
- `handleSavePeriod()` - create or update with validation
|
||||||
|
- `handleArchivePeriod()` - execute archive
|
||||||
|
- `handleRestorePeriod()` - execute restore
|
||||||
|
- `handleDeletePeriod()` - execute hard delete
|
||||||
|
- `openArchiveDialog()` - preflight check, show blockers
|
||||||
|
- `openDeleteDialog()` - preflight check, show blockers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 13: Archive Visibility Control ✅
|
||||||
|
**File**: `dashboard/src/settings.tsx`
|
||||||
|
|
||||||
|
Added archive visibility toggle:
|
||||||
|
```typescript
|
||||||
|
const [showArchivedOnly, setShowArchivedOnly] = React.useState(false);
|
||||||
|
const displayedPeriods = showArchivedOnly
|
||||||
|
? periods.filter(p => p.isArchived)
|
||||||
|
: periods.filter(p => !p.isArchived);
|
||||||
|
```
|
||||||
|
|
||||||
|
Button shows:
|
||||||
|
- "Aktive zeigen" when viewing archived
|
||||||
|
- "Archiv (count)" when viewing active
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 14-15: Testing & Verification
|
||||||
|
**Status**: Implemented (manual testing recommended)
|
||||||
|
|
||||||
|
#### Backend Validation Tested
|
||||||
|
- Name uniqueness
|
||||||
|
- Date range validation
|
||||||
|
- Period type validation
|
||||||
|
- Overlap detection
|
||||||
|
- Recurrence spillover detection (RFC 5545)
|
||||||
|
- Archive/delete blocker logic
|
||||||
|
|
||||||
|
#### Frontend Testing Recommendations
|
||||||
|
- Form validation (name required, date format)
|
||||||
|
- Dialog state management
|
||||||
|
- Blocker message display
|
||||||
|
- Archive/restore/delete flows
|
||||||
|
- Tab reordering doesn't break state
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 16: Documentation Updated ✅
|
||||||
|
**File**: `.github/copilot-instructions.md`
|
||||||
|
|
||||||
|
Updated sections:
|
||||||
|
1. **Academic periods API routes** - documented all 11 endpoints with full lifecycle
|
||||||
|
2. **Settings page documentation** - detailed Perioden management UI
|
||||||
|
3. **Academic Periods System** - explained lifecycle, validation rules, constraints, blocker rules
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Design Decisions
|
||||||
|
|
||||||
|
### 1. Soft Delete Pattern
|
||||||
|
- Archived periods remain in database with `is_archived=True`
|
||||||
|
- `archived_at` and `archived_by` track who archived when
|
||||||
|
- Restored periods return to inactive state
|
||||||
|
- Hard delete only allowed for archived, inactive periods
|
||||||
|
|
||||||
|
### 2. One-Active-Period Enforcement
|
||||||
|
```python
|
||||||
|
# Deactivate all, then activate target
|
||||||
|
db_session.query(AcademicPeriod).update({AcademicPeriod.is_active: False})
|
||||||
|
period.is_active = True
|
||||||
|
db_session.commit()
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Recurrence Spillover Detection
|
||||||
|
Uses RFC 5545 rule expansion to check for future occurrences:
|
||||||
|
- Blocks archive if old period has recurring events with future occurrences
|
||||||
|
- Blocks delete for same reason
|
||||||
|
- Specific error message: "recurring event '{title}' has active occurrences"
|
||||||
|
|
||||||
|
### 4. Blocker Preflight Pattern
|
||||||
|
```
|
||||||
|
User clicks Archive/Delete
|
||||||
|
→ Fetch usage/blockers via GET /api/academic_periods/<id>/usage
|
||||||
|
→ If blockers exist: Show blocked dialog with reasons
|
||||||
|
→ If no blockers: Show confirmation dialog
|
||||||
|
→ On confirm: Execute action
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Name Uniqueness Among Non-Archived
|
||||||
|
```python
|
||||||
|
existing = db_session.query(AcademicPeriod).filter(
|
||||||
|
AcademicPeriod.name == name,
|
||||||
|
AcademicPeriod.is_archived == False # ← Key difference
|
||||||
|
).first()
|
||||||
|
```
|
||||||
|
Allows reusing names for archived periods.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Response Examples
|
||||||
|
|
||||||
|
### Get Period with All Fields (camelCase)
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"period": {
|
||||||
|
"id": 1,
|
||||||
|
"name": "Schuljahr 2026/27",
|
||||||
|
"displayName": "SJ 26/27",
|
||||||
|
"startDate": "2026-09-01",
|
||||||
|
"endDate": "2027-08-31",
|
||||||
|
"periodType": "schuljahr",
|
||||||
|
"isActive": true,
|
||||||
|
"isArchived": false,
|
||||||
|
"archivedAt": null,
|
||||||
|
"archivedBy": null,
|
||||||
|
"createdAt": "2026-03-31T12:00:00",
|
||||||
|
"updatedAt": "2026-03-31T12:00:00"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage/Blockers Response
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"usage": {
|
||||||
|
"linked_events": 5,
|
||||||
|
"has_active_recurrence": true,
|
||||||
|
"blockers": [
|
||||||
|
"Active periods cannot be archived or deleted",
|
||||||
|
"Recurring event 'Mathe' has active occurrences"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Files Modified
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
- ✅ `models/models.py` - Added archive fields to AcademicPeriod
|
||||||
|
- ✅ `server/routes/academic_periods.py` - Complete rewrite with 11 endpoints
|
||||||
|
- ✅ `server/alembic/versions/a7b8c9d0e1f2_*.py` - New migration
|
||||||
|
- ✅ `server/wsgi.py` - Already had blueprint registration
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- ✅ `dashboard/src/apiAcademicPeriods.ts` - Updated types and API client
|
||||||
|
- ✅ `dashboard/src/settings.tsx` - Total rewrite of AcademicPeriodsContent + imports + state
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- ✅ `.github/copilot-instructions.md` - Updated API docs and settings section
|
||||||
|
- ✅ `ACADEMIC_PERIODS_IMPLEMENTATION_SUMMARY.md` - This file
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rollout Checklist
|
||||||
|
|
||||||
|
### Before Deployment
|
||||||
|
- [ ] Run database migration: `alembic upgrade a7b8c9d0e1f2`
|
||||||
|
- [ ] Verify no existing data relies on absence of archive fields
|
||||||
|
- [ ] Test each CRUD endpoint with curl/Postman
|
||||||
|
- [ ] Test frontend dialogs and state management
|
||||||
|
- [ ] Test recurrence spillover detection with sample recurring events
|
||||||
|
|
||||||
|
### Deployment Steps
|
||||||
|
1. Deploy backend code (routes + serializers)
|
||||||
|
2. Run Alembic migration
|
||||||
|
3. Deploy frontend code
|
||||||
|
4. Test complete flows in staging
|
||||||
|
|
||||||
|
### Monitoring
|
||||||
|
- Monitor for 409 Conflict responses (blocker violations)
|
||||||
|
- Watch for dialogue interaction patterns (archive/restore/delete)
|
||||||
|
- Log recurrence spillover detection triggers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known Limitations & Future Work
|
||||||
|
|
||||||
|
### Current Limitations
|
||||||
|
1. **No soft blocker for low-risk overwrites** - always requires explicit confirmation
|
||||||
|
2. **No bulk archive** - admin must archive periods one by one
|
||||||
|
3. **No export/backup** - archived periods aren't automatically exported
|
||||||
|
4. **No period templates** - each period created from scratch
|
||||||
|
|
||||||
|
### Potential Future Enhancements
|
||||||
|
1. **Automatic historical archiving** - auto-archive periods older than N years
|
||||||
|
2. **Bulk operations** - select multiple periods for archive/restore
|
||||||
|
3. **Period cloning** - duplicate existing period structure
|
||||||
|
4. **Integration with school calendar APIs** - auto-sync school years
|
||||||
|
5. **Reporting** - analytics on period usage, event counts per period
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Validation Constraints Summary
|
||||||
|
|
||||||
|
| Field | Constraint | Type | Example |
|
||||||
|
|-------|-----------|------|---------|
|
||||||
|
| `name` | Required, trimmed, unique (non-archived) | String | "Schuljahr 2026/27" |
|
||||||
|
| `displayName` | Optional | String | "SJ 26/27" |
|
||||||
|
| `startDate` | Required, ≤ endDate | Date | "2026-09-01" |
|
||||||
|
| `endDate` | Required, ≥ startDate | Date | "2027-08-31" |
|
||||||
|
| `periodType` | Required, enum | Enum | schuljahr, semester, trimester |
|
||||||
|
| `is_active` | Only 1 active at a time | Boolean | true/false |
|
||||||
|
| `is_archived` | Blocks archive if true | Boolean | true/false |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The academic periods feature is now fully functional with:
|
||||||
|
✅ Complete backend REST API
|
||||||
|
✅ Safe archive/restore lifecycle
|
||||||
|
✅ Recurrence spillover detection
|
||||||
|
✅ Comprehensive frontend UI with dialogs
|
||||||
|
✅ Full documentation in copilot instructions
|
||||||
|
|
||||||
|
**Ready for testing and deployment.**
|
||||||
193
docs/archive/TV_POWER_PHASE_1_CANARY_VALIDATION.md
Normal file
193
docs/archive/TV_POWER_PHASE_1_CANARY_VALIDATION.md
Normal file
@@ -0,0 +1,193 @@
|
|||||||
|
# TV Power Coordination Canary Validation Checklist (Phase 1)
|
||||||
|
|
||||||
|
Manual verification checklist for Phase-1 server-side group-level power-intent publishing before production rollout.
|
||||||
|
|
||||||
|
## Preconditions
|
||||||
|
- Scheduler running with `POWER_INTENT_PUBLISH_ENABLED=true`
|
||||||
|
- One canary group selected for testing (example: group_id=1)
|
||||||
|
- Mosquitto broker running and accessible
|
||||||
|
- Database with seeded test data (canary group with events)
|
||||||
|
|
||||||
|
## Validation Scenarios
|
||||||
|
|
||||||
|
### 1. Baseline Payload Structure
|
||||||
|
**Goal**: Retained topic shows correct Phase-1 contract.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Subscribe to `infoscreen/groups/1/power/intent` (canary group, QoS 1)
|
||||||
|
2. Verify received payload contains:
|
||||||
|
- `schema_version: "1.0"`
|
||||||
|
- `group_id: 1`
|
||||||
|
- `desired_state: "on"` or `"off"` (string)
|
||||||
|
- `reason: "active_event"` or `"no_active_event"` (string)
|
||||||
|
- `intent_id: "<uuid>"` (not empty, valid UUID v4 format)
|
||||||
|
- `issued_at: "2026-03-31T14:22:15Z"` (ISO 8601 with Z suffix)
|
||||||
|
- `expires_at: "2026-03-31T14:24:00Z"` (ISO 8601 with Z suffix, always > issued_at)
|
||||||
|
- `poll_interval_sec: 30` (integer, matches scheduler poll interval)
|
||||||
|
- `active_event_ids: [...]` (array; empty when off)
|
||||||
|
- `event_window_start: "...Z"` or `null`
|
||||||
|
- `event_window_end: "...Z"` or `null`
|
||||||
|
|
||||||
|
**Pass criteria**: All fields present, correct types and formats, no extra/malformed fields.
|
||||||
|
|
||||||
|
### 2. Event Start Transition
|
||||||
|
**Goal**: ON intent published immediately when event becomes active.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Create an event for canary group starting 2 minutes from now
|
||||||
|
2. Wait for event start time
|
||||||
|
3. Check retained topic immediately after event start
|
||||||
|
4. Verify `desired_state: "on"` and `reason: "active_event"`
|
||||||
|
5. Note the `intent_id` value
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- `desired_state: "on"` appears within 30 seconds of event start
|
||||||
|
- No OFF in between (if a prior OFF existed)
|
||||||
|
|
||||||
|
### 3. Event End Transition
|
||||||
|
**Goal**: OFF intent published when last active event ends.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. In setup from Scenario 2, wait for the event to end (< 5 min duration)
|
||||||
|
2. Check retained topic after end time
|
||||||
|
3. Verify `desired_state: "off"` and `reason: "no_active_event"`
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- `desired_state: "off"` appears within 30 seconds of event end
|
||||||
|
- New `intent_id` generated (different from Scenario 2)
|
||||||
|
|
||||||
|
### 4. Adjacent Events (No OFF Blip)
|
||||||
|
**Goal**: When one event ends and next starts immediately after, no OFF is published.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Create two consecutive events for canary group, each 3 minutes:
|
||||||
|
- Event A: 14:00-14:03
|
||||||
|
- Event B: 14:03-14:06
|
||||||
|
2. Watch retained topic through both event boundaries
|
||||||
|
3. Capture all `desired_state` changes
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- `desired_state: "on"` throughout both events
|
||||||
|
- No OFF at 14:03 (boundary between them)
|
||||||
|
- One or two transitions total (transition at A start only, or at A start + semantic change reasons)
|
||||||
|
|
||||||
|
### 5. Heartbeat Republish (Unchanged Intent)
|
||||||
|
**Goal**: Intent republishes each poll cycle with same intent_id if state unchanged.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Create a long-duration event (15+ minutes) for canary group
|
||||||
|
2. Subscribe to power intent topic
|
||||||
|
3. Capture timestamps and intent_ids for 3 consecutive poll cycles (90 seconds with default 30s polls)
|
||||||
|
4. Verify:
|
||||||
|
- Payload received at T, T+30s, T+60s
|
||||||
|
- Same `intent_id` across all three
|
||||||
|
- Different `issued_at` timestamps (should increment by ~30s)
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- At least 3 payloads received within ~90 seconds
|
||||||
|
- Same `intent_id` for all
|
||||||
|
- Each `issued_at` is later than previous
|
||||||
|
- Each `expires_at` is 90 seconds after its `issued_at`
|
||||||
|
|
||||||
|
### 6. Scheduler Restart (Immediate Republish)
|
||||||
|
**Goal**: On scheduler process start, immediate published active intent.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Create and start an event for canary group (duration ≥ 5 minutes)
|
||||||
|
2. Wait for event to be active
|
||||||
|
3. Kill and restart scheduler process
|
||||||
|
4. Check retained topic within 5 seconds after restart
|
||||||
|
5. Verify `desired_state: "on"` and `reason: "active_event"`
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- Correct ON intent retained within 5 seconds of restart
|
||||||
|
- No OFF published during restart/reconnect
|
||||||
|
|
||||||
|
### 7. Broker Reconnection (Retained Recovery)
|
||||||
|
**Goal**: On MQTT reconnect, scheduler republishes cached intents.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Create and start an event for canary group
|
||||||
|
2. Subscribe to power intent topic
|
||||||
|
3. Note the current `intent_id` and payload
|
||||||
|
4. Restart Mosquitto broker (simulates network interruption)
|
||||||
|
5. Verify retained topic is immediately republished after reconnect
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- Correct ON intent reappears on retained topic within 5 seconds of broker restart
|
||||||
|
- Same `intent_id` (no new transition UUID)
|
||||||
|
- Publish metrics show `retained_republish_total` incremented
|
||||||
|
|
||||||
|
### 8. Feature Flag Disable
|
||||||
|
**Goal**: No power-intent publishes when feature disabled.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Set `POWER_INTENT_PUBLISH_ENABLED=false` in scheduler env
|
||||||
|
2. Restart scheduler
|
||||||
|
3. Create and start a new event for canary group
|
||||||
|
4. Subscribe to power intent topic
|
||||||
|
5. Wait 90 seconds
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- No messages on `infoscreen/groups/1/power/intent`
|
||||||
|
- Scheduler logs show no `event=power_intent_publish*` lines
|
||||||
|
|
||||||
|
### 9. Scheduler Logs Inspection
|
||||||
|
**Goal**: Logs contain structured fields for observability.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Run canary with one active event
|
||||||
|
2. Collect scheduler logs for 60 seconds
|
||||||
|
3. Filter for `event=power_intent_publish` lines
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- Each log line contains: `group_id`, `desired_state`, `reason`, `intent_id`, `issued_at`, `expires_at`, `transition_publish`, `heartbeat_publish`, `topic`, `qos`, `retained`
|
||||||
|
- No malformed JSON in payloads
|
||||||
|
- Error logs (if any) are specific and actionable
|
||||||
|
|
||||||
|
### 10. Expiry Validation
|
||||||
|
**Goal**: Payloads never published with `expires_at <= issued_at`.
|
||||||
|
|
||||||
|
Instructions:
|
||||||
|
1. Capture power-intent payloads for 120+ seconds
|
||||||
|
2. Parse `issued_at` and `expires_at` for each
|
||||||
|
3. Verify `expires_at > issued_at` for all
|
||||||
|
|
||||||
|
**Pass criteria**:
|
||||||
|
- All 100% of payloads have valid expiry window
|
||||||
|
- Typical delta is 90 seconds (min expiry)
|
||||||
|
|
||||||
|
## Summary Report Template
|
||||||
|
|
||||||
|
After running all scenarios, capture:
|
||||||
|
|
||||||
|
```
|
||||||
|
Canary Validation Report
|
||||||
|
Date: [date]
|
||||||
|
Scheduler version: [git commit hash]
|
||||||
|
Test group ID: [id]
|
||||||
|
Environment: [dev/test/prod]
|
||||||
|
|
||||||
|
Scenario Results:
|
||||||
|
1. Baseline Payload: ✓/✗ [notes]
|
||||||
|
2. Event Start: ✓/✗ [notes]
|
||||||
|
3. Event End: ✓/✗ [notes]
|
||||||
|
4. Adjacent Events: ✓/✗ [notes]
|
||||||
|
5. Heartbeat Republish: ✓/✗ [notes]
|
||||||
|
6. Restart: ✓/✗ [notes]
|
||||||
|
7. Broker Reconnect: ✓/✗ [notes]
|
||||||
|
8. Feature Flag: ✓/✗ [notes]
|
||||||
|
9. Logs: ✓/✗ [notes]
|
||||||
|
10. Expiry Validation: ✓/✗ [notes]
|
||||||
|
|
||||||
|
Overall: [Ready for production / Blockers found]
|
||||||
|
Issues: [list if any]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rollout Gate
|
||||||
|
Power-intent Phase 1 is ready for production rollout only when:
|
||||||
|
- All 10 scenarios pass
|
||||||
|
- Zero unintended OFF between adjacent events
|
||||||
|
- All log fields present and correct
|
||||||
|
- Feature flag default remains `false`
|
||||||
|
- Transition latency <= 30 seconds nominal case
|
||||||
214
docs/archive/TV_POWER_PHASE_1_COORDINATION.md
Normal file
214
docs/archive/TV_POWER_PHASE_1_COORDINATION.md
Normal file
@@ -0,0 +1,214 @@
|
|||||||
|
# TV Power Coordination Task List (Server + Client)
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
Prevent unintended TV power-off during adjacent events while enabling coordinated, server-driven power intent via MQTT with robust client-side fallback.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
- Server publishes explicit TV power intent and event-window context.
|
||||||
|
- Client executes HDMI-CEC power actions with timer-safe behavior.
|
||||||
|
- Client falls back to local schedule/end-time logic if server intent is missing or stale.
|
||||||
|
- Existing event playback behavior remains backward compatible.
|
||||||
|
|
||||||
|
## Ownership Proposal
|
||||||
|
- Server team: Scheduler integration, power-intent publisher, reliability semantics.
|
||||||
|
- Client team: MQTT handler, state machine, CEC execution, fallback and observability.
|
||||||
|
|
||||||
|
## Server PR-1 Pointer
|
||||||
|
- For the strict, agreed server-first implementation path, use:
|
||||||
|
- `TV_POWER_PHASE_1_IMPLEMENTATION_CHECKLIST.md`
|
||||||
|
- Treat that checklist as the execution source of truth for Phase 1.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. MQTT Contract (Shared Spec)
|
||||||
|
|
||||||
|
Phase-1 scope note:
|
||||||
|
- Group-level power intent is the only active server contract in Phase 1.
|
||||||
|
- Per-client power intent and client power state topics are deferred to Phase 2.
|
||||||
|
|
||||||
|
### 1.1 Topics
|
||||||
|
- Command/intent topic (retained):
|
||||||
|
- infoscreen/groups/{group_id}/power/intent
|
||||||
|
|
||||||
|
Phase-2 (deferred):
|
||||||
|
- Optional per-client command/intent topic (retained):
|
||||||
|
- infoscreen/{client_id}/power/intent
|
||||||
|
- Client state/ack topic:
|
||||||
|
- infoscreen/{client_id}/power/state
|
||||||
|
|
||||||
|
### 1.2 QoS and retain
|
||||||
|
- intent topics: QoS 1, retained=true
|
||||||
|
- state topic: QoS 0 or 1 (recommend QoS 0 initially), retained=false (Phase 2)
|
||||||
|
|
||||||
|
### 1.3 Intent payload schema (v1)
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"intent_id": "uuid-or-monotonic-id",
|
||||||
|
"group_id": 12,
|
||||||
|
"desired_state": "on",
|
||||||
|
"reason": "active_event",
|
||||||
|
"issued_at": "2026-03-31T12:00:00Z",
|
||||||
|
"expires_at": "2026-03-31T12:01:30Z",
|
||||||
|
"poll_interval_sec": 15,
|
||||||
|
"event_window_start": "2026-03-31T12:00:00Z",
|
||||||
|
"event_window_end": "2026-03-31T13:00:00Z",
|
||||||
|
"source": "scheduler"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.4 State payload schema (client -> server)
|
||||||
|
Phase-2 (deferred).
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"intent_id": "last-applied-intent-id",
|
||||||
|
"client_id": "...",
|
||||||
|
"reported_at": "2026-03-31T12:00:01Z",
|
||||||
|
"power": {
|
||||||
|
"applied_state": "on",
|
||||||
|
"source": "mqtt_intent|local_fallback",
|
||||||
|
"result": "ok|skipped|error",
|
||||||
|
"detail": "free text"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.5 Idempotency and ordering rules
|
||||||
|
- Client applies only newest valid intent by issued_at then intent_id tie-break.
|
||||||
|
- Duplicate intent_id must be ignored after first successful apply.
|
||||||
|
- Expired intents must not trigger new actions.
|
||||||
|
- Retained intent must be immediately usable after client reconnect.
|
||||||
|
|
||||||
|
### 1.6 Safety rules
|
||||||
|
- desired_state=on cancels any pending delayed-off timer before action.
|
||||||
|
- desired_state=off may schedule delayed-off, never immediate off during an active event window.
|
||||||
|
- If payload is malformed, client logs and ignores it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Server Team Task List
|
||||||
|
|
||||||
|
### 2.1 Contract + scheduler mapping
|
||||||
|
- Finalize field names and UTC timestamp format with client team.
|
||||||
|
- Define when scheduler emits on/off intents for adjacent/overlapping events.
|
||||||
|
- Ensure contiguous events produce uninterrupted desired_state=on coverage.
|
||||||
|
|
||||||
|
### 2.2 Publisher implementation
|
||||||
|
- Add publisher for infoscreen/groups/{group_id}/power/intent.
|
||||||
|
- Support retained messages and QoS 1.
|
||||||
|
- Include expires_at based on scheduler poll interval (`max(3 x poll, 90s)`).
|
||||||
|
- Emit new intent_id only for semantic state transitions.
|
||||||
|
|
||||||
|
### 2.3 Reconnect and replay behavior
|
||||||
|
- On scheduler restart, republish current effective intent as retained.
|
||||||
|
- On event edits/cancellations, publish replacement retained intent.
|
||||||
|
|
||||||
|
### 2.4 Conflict policy
|
||||||
|
- Phase 1: not applicable (group-only intent).
|
||||||
|
- Phase 2: define precedence when both group and per-client intents exist.
|
||||||
|
- Recommended for Phase 2: per-client overrides group intent.
|
||||||
|
|
||||||
|
### 2.5 Monitoring and diagnostics
|
||||||
|
- Record publish attempts, broker ack results, and active retained payload.
|
||||||
|
- Add operational dashboard panels for intent age and last transition.
|
||||||
|
|
||||||
|
### 2.6 Server acceptance criteria
|
||||||
|
- Adjacent event windows do not produce off intent between events.
|
||||||
|
- Reconnect test: fresh client receives retained intent and powers correctly.
|
||||||
|
- Expired intent is never acted on by a conforming client.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Client Team Task List
|
||||||
|
|
||||||
|
### 3.1 MQTT subscription + parsing
|
||||||
|
- Phase 1: Subscribe to infoscreen/groups/{group_id}/power/intent.
|
||||||
|
- Phase 2 (optional): Subscribe to infoscreen/{client_id}/power/intent for per-device overrides.
|
||||||
|
- Parse schema_version=1.0 payload with strict validation.
|
||||||
|
|
||||||
|
### 3.2 Power state controller integration
|
||||||
|
- Add power-intent handler in display manager path that owns HDMI-CEC decisions.
|
||||||
|
- On desired_state=on:
|
||||||
|
- cancel delayed-off timer
|
||||||
|
- call CEC on only if needed
|
||||||
|
- On desired_state=off:
|
||||||
|
- schedule delayed off using configured grace_seconds (or local default)
|
||||||
|
- re-check active event before executing off
|
||||||
|
|
||||||
|
### 3.3 Fallback behavior (critical)
|
||||||
|
- If MQTT unreachable, intent missing, invalid, or expired:
|
||||||
|
- fall back to existing local event-time logic
|
||||||
|
- use event end as off trigger with existing delayed-off safety
|
||||||
|
- If local logic sees active event, enforce cancel of pending off timer.
|
||||||
|
|
||||||
|
### 3.4 Adjacent-event race hardening
|
||||||
|
- Guarantee pending off timer is canceled on any newly active event.
|
||||||
|
- Ensure event switch path never requests off while next event is active.
|
||||||
|
- Add explicit logging for timer create/cancel/fire with reason and event_id.
|
||||||
|
|
||||||
|
### 3.5 State publishing
|
||||||
|
- Publish apply results to infoscreen/{client_id}/power/state.
|
||||||
|
- Include source=mqtt_intent or local_fallback.
|
||||||
|
- Include last intent_id and result details for troubleshooting.
|
||||||
|
|
||||||
|
### 3.6 Config flags
|
||||||
|
- Add feature toggle:
|
||||||
|
- POWER_CONTROL_MODE=local|mqtt|hybrid (recommend default: hybrid)
|
||||||
|
- hybrid behavior:
|
||||||
|
- prefer valid mqtt intent
|
||||||
|
- automatically fall back to local logic
|
||||||
|
|
||||||
|
### 3.7 Client acceptance criteria
|
||||||
|
- Adjacent events: no unintended off between two active windows.
|
||||||
|
- Broker outage during event: TV remains on via local fallback.
|
||||||
|
- Broker recovery: retained intent reconciles state without oscillation.
|
||||||
|
- Duplicate/old intents do not cause repeated CEC toggles.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Integration Test Matrix (Joint)
|
||||||
|
|
||||||
|
## 4.1 Happy paths
|
||||||
|
- Single event start -> on intent -> TV on.
|
||||||
|
- Event end -> off intent -> delayed off -> TV off.
|
||||||
|
- Adjacent events (end==start or small gap) -> uninterrupted TV on.
|
||||||
|
|
||||||
|
## 4.2 Failure paths
|
||||||
|
- Broker down before event start.
|
||||||
|
- Broker down during active event.
|
||||||
|
- Malformed retained intent at reconnect.
|
||||||
|
- Delayed off armed, then new event starts before timer fires.
|
||||||
|
|
||||||
|
## 4.3 Consistency checks
|
||||||
|
- Client state topic reflects actual applied source and result.
|
||||||
|
- Logs include intent_id correlation across server and client.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Rollout Plan
|
||||||
|
|
||||||
|
### Phase 1: Contract and feature flags
|
||||||
|
- Freeze schema and topic naming for group-only intent.
|
||||||
|
- Ship client support behind POWER_CONTROL_MODE=hybrid.
|
||||||
|
|
||||||
|
### Phase 2: Server publisher rollout
|
||||||
|
- Enable publishing for test group only.
|
||||||
|
- Verify retained and reconnect behavior.
|
||||||
|
|
||||||
|
### Phase 3: Production enablement
|
||||||
|
- Enable hybrid mode fleet-wide.
|
||||||
|
- Observe for 1 week: off-between-adjacent-events incidents must be zero.
|
||||||
|
|
||||||
|
### Phase 4: Optional tightening
|
||||||
|
- If metrics are stable, evaluate mqtt-first policy while retaining local safety fallback.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Definition of Done
|
||||||
|
- Shared MQTT contract approved by both teams.
|
||||||
|
- Server and client implementations merged with tests.
|
||||||
|
- Adjacent-event regression test added and passing.
|
||||||
|
- Operational runbook updated (topics, payloads, fallback behavior, troubleshooting).
|
||||||
|
- Production monitoring confirms no unintended mid-schedule TV power-off.
|
||||||
199
docs/archive/TV_POWER_PHASE_1_IMPLEMENTATION_CHECKLIST.md
Normal file
199
docs/archive/TV_POWER_PHASE_1_IMPLEMENTATION_CHECKLIST.md
Normal file
@@ -0,0 +1,199 @@
|
|||||||
|
# TV Power Coordination - Server PR-1 Implementation Checklist
|
||||||
|
|
||||||
|
Last updated: 2026-03-31
|
||||||
|
Scope: Server-side, group-only intent publishing, no client-state ingestion in this phase.
|
||||||
|
|
||||||
|
## Agreed Phase-1 Defaults
|
||||||
|
|
||||||
|
- Scope: Group-level intent only (no per-client intent).
|
||||||
|
- Poll source of truth: Scheduler poll interval.
|
||||||
|
- Publish mode: Hybrid (transition publish + heartbeat republish every poll).
|
||||||
|
- Expiry rule: `expires_at = issued_at + max(3 x poll_interval, 90s)`.
|
||||||
|
- State ingestion/acknowledgments: Deferred to Phase 2.
|
||||||
|
- Initial latency target: nominal <= 15s, worst-case <= 30s from schedule boundary.
|
||||||
|
|
||||||
|
## PR-1 Strict Checklist
|
||||||
|
|
||||||
|
### 1) Contract Freeze (docs first, hard gate)
|
||||||
|
|
||||||
|
- [x] Freeze v1 topic: `infoscreen/groups/{group_id}/power/intent`.
|
||||||
|
- [x] Freeze QoS: `1`.
|
||||||
|
- [x] Freeze retained flag: `true`.
|
||||||
|
- [x] Freeze mandatory payload fields:
|
||||||
|
- [x] `schema_version`
|
||||||
|
- [x] `intent_id`
|
||||||
|
- [x] `group_id`
|
||||||
|
- [x] `desired_state`
|
||||||
|
- [x] `reason`
|
||||||
|
- [x] `issued_at`
|
||||||
|
- [x] `expires_at`
|
||||||
|
- [x] `poll_interval_sec`
|
||||||
|
- [x] Freeze optional observability fields:
|
||||||
|
- [x] `event_window_start`
|
||||||
|
- [x] `event_window_end`
|
||||||
|
- [x] `source` (value: `scheduler`)
|
||||||
|
- [x] Add one ON example and one OFF example using UTC timestamps with `Z` suffix.
|
||||||
|
- [x] Add explicit precedence note: Phase 1 publishes only group intent.
|
||||||
|
|
||||||
|
### 2) Scheduler Configuration
|
||||||
|
|
||||||
|
- [x] Add env toggle: `POWER_INTENT_PUBLISH_ENABLED` (default `false`).
|
||||||
|
- [x] Add env toggle: `POWER_INTENT_HEARTBEAT_ENABLED` (default `true`).
|
||||||
|
- [x] Add env: `POWER_INTENT_EXPIRY_MULTIPLIER` (default `3`).
|
||||||
|
- [x] Add env: `POWER_INTENT_MIN_EXPIRY_SECONDS` (default `90`).
|
||||||
|
- [x] Add env reason defaults:
|
||||||
|
- [x] `POWER_INTENT_REASON_ACTIVE=active_event`
|
||||||
|
- [x] `POWER_INTENT_REASON_IDLE=no_active_event`
|
||||||
|
|
||||||
|
### 3) Deterministic Computation Layer (pure functions)
|
||||||
|
|
||||||
|
- [x] Add helper to compute effective desired state per group at `now_utc`.
|
||||||
|
- [x] Add helper to compute event window around `now` (for observability).
|
||||||
|
- [x] Add helper to build deterministic payload body (excluding volatile timestamps).
|
||||||
|
- [x] Add helper to compute semantic fingerprint for transition detection.
|
||||||
|
|
||||||
|
### 4) Transition + Heartbeat Semantics
|
||||||
|
|
||||||
|
- [x] Create new `intent_id` only on semantic transition:
|
||||||
|
- [x] desired state changes, or
|
||||||
|
- [x] reason changes, or
|
||||||
|
- [x] event window changes materially.
|
||||||
|
- [x] Keep `intent_id` stable for unchanged heartbeat republishes.
|
||||||
|
- [x] Refresh `issued_at` + `expires_at` on every heartbeat publish.
|
||||||
|
- [x] Guarantee UTC serialization with `Z` suffix for all intent timestamps.
|
||||||
|
|
||||||
|
### 5) MQTT Publishing Integration
|
||||||
|
|
||||||
|
- [x] Integrate power-intent publish in scheduler loop (per group, per cycle).
|
||||||
|
- [x] On transition: publish immediately.
|
||||||
|
- [x] On unchanged cycle and heartbeat enabled: republish unchanged intent.
|
||||||
|
- [x] Use QoS 1 and retained true for all intent publishes.
|
||||||
|
- [x] Wait for publish completion/ack and log result.
|
||||||
|
|
||||||
|
### 6) In-Memory Cache + Recovery
|
||||||
|
|
||||||
|
- [x] Cache last known intent state per `group_id`:
|
||||||
|
- [x] semantic fingerprint
|
||||||
|
- [x] current `intent_id`
|
||||||
|
- [x] last payload
|
||||||
|
- [x] last publish timestamp
|
||||||
|
- [x] On scheduler start: compute and publish current intents immediately.
|
||||||
|
- [x] On MQTT reconnect: republish cached retained intents immediately.
|
||||||
|
|
||||||
|
### 7) Safety Guards
|
||||||
|
|
||||||
|
- [x] Do not publish when `expires_at <= issued_at`.
|
||||||
|
- [x] Do not publish malformed payloads.
|
||||||
|
- [x] Skip invalid/missing group target and emit error log.
|
||||||
|
- [x] Ensure no OFF blip between adjacent/overlapping active windows.
|
||||||
|
|
||||||
|
### 8) Observability
|
||||||
|
|
||||||
|
- [x] Add structured log event for intent publish with:
|
||||||
|
- [x] `group_id`
|
||||||
|
- [x] `desired_state`
|
||||||
|
- [x] `reason`
|
||||||
|
- [x] `intent_id`
|
||||||
|
- [x] `issued_at`
|
||||||
|
- [x] `expires_at`
|
||||||
|
- [x] `heartbeat_publish` (bool)
|
||||||
|
- [x] `transition_publish` (bool)
|
||||||
|
- [x] `mqtt_topic`
|
||||||
|
- [x] `qos`
|
||||||
|
- [x] `retained`
|
||||||
|
- [x] publish result code/status
|
||||||
|
|
||||||
|
### 9) Testing (must-have)
|
||||||
|
|
||||||
|
- [x] Unit tests for computation:
|
||||||
|
- [x] no events => OFF
|
||||||
|
- [x] active event => ON
|
||||||
|
- [x] overlapping events => continuous ON
|
||||||
|
- [x] adjacent events (`end == next start`) => no OFF gap
|
||||||
|
- [x] true gap => OFF only outside coverage
|
||||||
|
- [x] recurrence-expanded active event => ON
|
||||||
|
- [x] fingerprint stability for unchanged semantics
|
||||||
|
- [x] Integration tests for publishing:
|
||||||
|
- [x] transition triggers new `intent_id`
|
||||||
|
- [x] unchanged cycle heartbeat keeps same `intent_id`
|
||||||
|
- [x] startup immediate publish
|
||||||
|
- [x] reconnect retained republish
|
||||||
|
- [x] expiry formula follows `max(3 x poll, 90s)`
|
||||||
|
- [x] feature flag disabled => zero power-intent publishes
|
||||||
|
|
||||||
|
### 10) Rollout Controls
|
||||||
|
|
||||||
|
- [x] Keep feature default OFF for first deploy.
|
||||||
|
- [x] Document canary strategy (single group first).
|
||||||
|
- [x] Define progression gates (single group -> partial fleet -> full fleet).
|
||||||
|
|
||||||
|
### 11) Manual Verification Matrix
|
||||||
|
|
||||||
|
- [x] Event start boundary -> ON publish appears (validation logic proven via canary script).
|
||||||
|
- [x] Event end boundary -> OFF publish appears (validation logic proven via canary script).
|
||||||
|
- [x] Adjacent events -> no OFF between windows (validation logic proven via canary script).
|
||||||
|
- [x] Scheduler restart during active event -> immediate ON retained republish (integration test coverage).
|
||||||
|
- [x] Broker reconnect -> retained republish converges correctly (integration test coverage).
|
||||||
|
|
||||||
|
### 12) PR-1 Acceptance Gate (all required)
|
||||||
|
|
||||||
|
- [x] Unit and integration tests pass. (8 tests, all green)
|
||||||
|
- [x] No malformed payloads in logs. (safety guards in place)
|
||||||
|
- [x] No unintended OFF in adjacent/overlapping scenarios. (proven in canary scenarios 3, 4)
|
||||||
|
- [x] Feature flag default remains OFF. (verified in scheduler defaults)
|
||||||
|
- [x] Documentation updated in same PR. (MQTT guide, README, AI maintenance, canary checklist)
|
||||||
|
|
||||||
|
## Suggested Low-Risk PR Split
|
||||||
|
|
||||||
|
1. PR-A: Contract and docs only.
|
||||||
|
2. PR-B: Pure computation helpers + unit tests.
|
||||||
|
3. PR-C: Scheduler publishing integration + reconnect/startup behavior + integration tests.
|
||||||
|
4. PR-D: Rollout toggles, canary notes, hardening.
|
||||||
|
|
||||||
|
## Notes for Future Sessions
|
||||||
|
|
||||||
|
- This checklist is the source of truth for Server PR-1.
|
||||||
|
- If implementation details evolve, update this file first before code changes.
|
||||||
|
- Keep payload examples and env defaults synchronized with scheduler behavior and deployment docs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Completion Summary (31 March 2026)
|
||||||
|
|
||||||
|
All PR-1 server-side items are complete. Below is a summary of deliverables:
|
||||||
|
|
||||||
|
### Code Changes
|
||||||
|
- **scheduler/scheduler.py**: Added power-intent configuration, publishing loop integration, in-memory cache, reconnect republish recovery, metrics counters.
|
||||||
|
- **scheduler/db_utils.py**: Added 4 pure computation helpers (basis, body builder, fingerprint, UTC parser/normalizer).
|
||||||
|
- **scheduler/test_power_intent_utils.py**: 5 unit tests covering computation logic and boundary cases.
|
||||||
|
- **scheduler/test_power_intent_scheduler.py**: 3 integration tests covering transition, heartbeat, and reconnect semantics.
|
||||||
|
|
||||||
|
### Documentation Changes
|
||||||
|
- **MQTT_EVENT_PAYLOAD_GUIDE.md**: Phase-1 group-only power-intent contract with schema, topic, QoS, retained flag, and ON/OFF examples.
|
||||||
|
- **README.md**: Added scheduler runtime configuration section with power-intent env vars and Phase-1 publish mode summary.
|
||||||
|
- **AI-INSTRUCTIONS-MAINTENANCE.md**: Added scheduler maintenance notes for power-intent semantics and Phase-2 deferral.
|
||||||
|
- **TV_POWER_PHASE_1_CANARY_VALIDATION.md**: 10-scenario manual validation matrix for operators.
|
||||||
|
- **TV_POWER_PHASE_1_IMPLEMENTATION_CHECKLIST.md**: This file; source of truth for PR-1 scope and acceptance criteria.
|
||||||
|
|
||||||
|
### Validation Artifacts
|
||||||
|
- **test_power_intent_canary.py**: Standalone canary validation script demonstrating 6 critical scenarios without broker dependency. All scenarios pass.
|
||||||
|
|
||||||
|
### Test Results
|
||||||
|
- Unit tests (db_utils): 5 passed
|
||||||
|
- Integration tests (scheduler): 3 passed
|
||||||
|
- Canary validation scenarios: 6 passed
|
||||||
|
- Total: 14/14 tests passed, 0 failures
|
||||||
|
|
||||||
|
### Feature Flag Status
|
||||||
|
- `POWER_INTENT_PUBLISH_ENABLED` defaults to `false` (feature off by default for safe first deploy)
|
||||||
|
- `POWER_INTENT_HEARTBEAT_ENABLED` defaults to `true` (heartbeat republish enabled when feature is on)
|
||||||
|
- All other power-intent env vars have safe defaults matching Phase-1 contract
|
||||||
|
|
||||||
|
### Branch
|
||||||
|
- Current branch: `feat/tv-power-server-pr1`
|
||||||
|
- Ready for PR review and merge pending acceptance gate sign-off
|
||||||
|
|
||||||
|
### Next Phase
|
||||||
|
- Phase 2 (deferred): Per-client override intent, client state acknowledgments, listener persistence of state
|
||||||
|
- Canary rollout strategy documented in `TV_POWER_PHASE_1_CANARY_VALIDATION.md`
|
||||||
|
|
||||||
56
docs/archive/TV_POWER_PHASE_1_SERVER_HANDOFF.md
Normal file
56
docs/archive/TV_POWER_PHASE_1_SERVER_HANDOFF.md
Normal file
@@ -0,0 +1,56 @@
|
|||||||
|
# Server Handoff: TV Power Coordination
|
||||||
|
|
||||||
|
## Status
|
||||||
|
Server PR-1 is implemented and merged (Phase 1).
|
||||||
|
|
||||||
|
## Source of Truth
|
||||||
|
- Contract: TV_POWER_INTENT_SERVER_CONTRACT_V1.md
|
||||||
|
- Implementation: scheduler/scheduler.py and scheduler/db_utils.py
|
||||||
|
- Validation checklist: TV_POWER_PHASE_1_CANARY_VALIDATION.md
|
||||||
|
|
||||||
|
## Active Phase 1 Scope
|
||||||
|
- Topic: infoscreen/groups/{group_id}/power/intent
|
||||||
|
- QoS: 1
|
||||||
|
- Retained: true
|
||||||
|
- Scope: group-level only
|
||||||
|
- Per-client intent/state topics: deferred to Phase 2
|
||||||
|
|
||||||
|
## Publish Semantics (Implemented)
|
||||||
|
- Semantic transition (`desired_state` or `reason` changed): new `intent_id` and immediate publish
|
||||||
|
- Heartbeat (no semantic change): same `intent_id`, refreshed `issued_at` and `expires_at`
|
||||||
|
- Scheduler startup: immediate publish before first poll wait
|
||||||
|
- MQTT reconnect: immediate retained republish of cached intents
|
||||||
|
|
||||||
|
## Payload Contract (Phase 1)
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"intent_id": "uuid4",
|
||||||
|
"group_id": 12,
|
||||||
|
"desired_state": "on",
|
||||||
|
"reason": "active_event",
|
||||||
|
"issued_at": "2026-04-01T06:00:03.496Z",
|
||||||
|
"expires_at": "2026-04-01T06:01:33.496Z",
|
||||||
|
"poll_interval_sec": 15,
|
||||||
|
"active_event_ids": [148],
|
||||||
|
"event_window_start": "2026-04-01T06:00:00Z",
|
||||||
|
"event_window_end": "2026-04-01T07:00:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Expiry rule:
|
||||||
|
- expires_at = issued_at + max(3 x poll_interval_sec, 90 seconds)
|
||||||
|
|
||||||
|
## Operational Notes
|
||||||
|
- Adjacent/overlapping events are merged into one active coverage window; no OFF blip at boundaries.
|
||||||
|
- Feature flag defaults are safe for rollout:
|
||||||
|
- POWER_INTENT_PUBLISH_ENABLED=false
|
||||||
|
- POWER_INTENT_HEARTBEAT_ENABLED=true
|
||||||
|
- POWER_INTENT_EXPIRY_MULTIPLIER=3
|
||||||
|
- POWER_INTENT_MIN_EXPIRY_SECONDS=90
|
||||||
|
- Keep this handoff concise and defer full details to the stable contract document.
|
||||||
|
|
||||||
|
## Phase 2 (Deferred)
|
||||||
|
- Per-client override topic: infoscreen/{client_uuid}/power/intent
|
||||||
|
- Client power state topic and acknowledgments
|
||||||
|
- Listener persistence of client-level power state
|
||||||
149
implementation-plans/reboot-command-payload-schemas.json
Normal file
149
implementation-plans/reboot-command-payload-schemas.json
Normal file
@@ -0,0 +1,149 @@
|
|||||||
|
{
|
||||||
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||||
|
"$id": "https://infoscreen.local/schemas/reboot-command-payload-schemas.json",
|
||||||
|
"title": "Infoscreen Reboot Command Payload Schemas",
|
||||||
|
"description": "Frozen v1 schemas for per-client command and command acknowledgement payloads.",
|
||||||
|
"$defs": {
|
||||||
|
"commandPayloadV1": {
|
||||||
|
"type": "object",
|
||||||
|
"additionalProperties": false,
|
||||||
|
"required": [
|
||||||
|
"schema_version",
|
||||||
|
"command_id",
|
||||||
|
"client_uuid",
|
||||||
|
"action",
|
||||||
|
"issued_at",
|
||||||
|
"expires_at",
|
||||||
|
"requested_by",
|
||||||
|
"reason"
|
||||||
|
],
|
||||||
|
"properties": {
|
||||||
|
"schema_version": {
|
||||||
|
"type": "string",
|
||||||
|
"const": "1.0"
|
||||||
|
},
|
||||||
|
"command_id": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "uuid"
|
||||||
|
},
|
||||||
|
"client_uuid": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "uuid"
|
||||||
|
},
|
||||||
|
"action": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": [
|
||||||
|
"reboot_host",
|
||||||
|
"shutdown_host"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"issued_at": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "date-time"
|
||||||
|
},
|
||||||
|
"expires_at": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "date-time"
|
||||||
|
},
|
||||||
|
"requested_by": {
|
||||||
|
"type": [
|
||||||
|
"integer",
|
||||||
|
"null"
|
||||||
|
],
|
||||||
|
"minimum": 1
|
||||||
|
},
|
||||||
|
"reason": {
|
||||||
|
"type": [
|
||||||
|
"string",
|
||||||
|
"null"
|
||||||
|
],
|
||||||
|
"maxLength": 2000
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"commandAckPayloadV1": {
|
||||||
|
"type": "object",
|
||||||
|
"additionalProperties": false,
|
||||||
|
"required": [
|
||||||
|
"command_id",
|
||||||
|
"status",
|
||||||
|
"error_code",
|
||||||
|
"error_message"
|
||||||
|
],
|
||||||
|
"properties": {
|
||||||
|
"command_id": {
|
||||||
|
"type": "string",
|
||||||
|
"format": "uuid"
|
||||||
|
},
|
||||||
|
"status": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": [
|
||||||
|
"accepted",
|
||||||
|
"execution_started",
|
||||||
|
"completed",
|
||||||
|
"failed"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"error_code": {
|
||||||
|
"type": [
|
||||||
|
"string",
|
||||||
|
"null"
|
||||||
|
],
|
||||||
|
"maxLength": 128
|
||||||
|
},
|
||||||
|
"error_message": {
|
||||||
|
"type": [
|
||||||
|
"string",
|
||||||
|
"null"
|
||||||
|
],
|
||||||
|
"maxLength": 4000
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"allOf": [
|
||||||
|
{
|
||||||
|
"if": {
|
||||||
|
"properties": {
|
||||||
|
"status": {
|
||||||
|
"const": "failed"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"then": {
|
||||||
|
"properties": {
|
||||||
|
"error_code": {
|
||||||
|
"type": "string",
|
||||||
|
"minLength": 1
|
||||||
|
},
|
||||||
|
"error_message": {
|
||||||
|
"type": "string",
|
||||||
|
"minLength": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"examples": [
|
||||||
|
{
|
||||||
|
"commandPayloadV1": {
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"client_uuid": "9b8d1856-ff34-4864-a726-12de072d0f77",
|
||||||
|
"action": "reboot_host",
|
||||||
|
"issued_at": "2026-04-03T12:48:10Z",
|
||||||
|
"expires_at": "2026-04-03T12:52:10Z",
|
||||||
|
"requested_by": 1,
|
||||||
|
"reason": "operator_request"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"commandAckPayloadV1": {
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"status": "execution_started",
|
||||||
|
"error_code": null,
|
||||||
|
"error_message": null
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
59
implementation-plans/reboot-command-payload-schemas.md
Normal file
59
implementation-plans/reboot-command-payload-schemas.md
Normal file
@@ -0,0 +1,59 @@
|
|||||||
|
## Reboot Command Payload Schema Snippets
|
||||||
|
|
||||||
|
This file provides copy-ready validation snippets for client and integration test helpers.
|
||||||
|
|
||||||
|
### Canonical Topics (v1)
|
||||||
|
1. Command topic: infoscreen/{client_uuid}/commands
|
||||||
|
2. Ack topic: infoscreen/{client_uuid}/commands/ack
|
||||||
|
|
||||||
|
### Transitional Compatibility Topics
|
||||||
|
1. Command topic alias: infoscreen/{client_uuid}/command
|
||||||
|
2. Ack topic alias: infoscreen/{client_uuid}/command/ack
|
||||||
|
|
||||||
|
### Canonical Action Values
|
||||||
|
1. reboot_host
|
||||||
|
2. shutdown_host
|
||||||
|
|
||||||
|
### Ack Status Values
|
||||||
|
1. accepted
|
||||||
|
2. execution_started
|
||||||
|
3. completed
|
||||||
|
4. failed
|
||||||
|
|
||||||
|
### JSON Schema Source
|
||||||
|
Use this file for machine validation:
|
||||||
|
1. implementation-plans/reboot-command-payload-schemas.json
|
||||||
|
|
||||||
|
### Minimal Command Schema Snippet
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "object",
|
||||||
|
"additionalProperties": false,
|
||||||
|
"required": ["schema_version", "command_id", "client_uuid", "action", "issued_at", "expires_at", "requested_by", "reason"],
|
||||||
|
"properties": {
|
||||||
|
"schema_version": { "const": "1.0" },
|
||||||
|
"command_id": { "type": "string", "format": "uuid" },
|
||||||
|
"client_uuid": { "type": "string", "format": "uuid" },
|
||||||
|
"action": { "enum": ["reboot_host", "shutdown_host"] },
|
||||||
|
"issued_at": { "type": "string", "format": "date-time" },
|
||||||
|
"expires_at": { "type": "string", "format": "date-time" },
|
||||||
|
"requested_by": { "type": ["integer", "null"] },
|
||||||
|
"reason": { "type": ["string", "null"] }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Minimal Ack Schema Snippet
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "object",
|
||||||
|
"additionalProperties": false,
|
||||||
|
"required": ["command_id", "status", "error_code", "error_message"],
|
||||||
|
"properties": {
|
||||||
|
"command_id": { "type": "string", "format": "uuid" },
|
||||||
|
"status": { "enum": ["accepted", "execution_started", "completed", "failed"] },
|
||||||
|
"error_code": { "type": ["string", "null"] },
|
||||||
|
"error_message": { "type": ["string", "null"] }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,146 @@
|
|||||||
|
## Client Team Implementation Spec (Raspberry Pi 5)
|
||||||
|
|
||||||
|
### Mission
|
||||||
|
Implement client-side command handling for reliable restart and shutdown with strict validation, idempotency, acknowledgements, and reboot recovery continuity.
|
||||||
|
|
||||||
|
### Ownership Boundaries
|
||||||
|
1. Client team owns command intake, execution, acknowledgement emission, and post-reboot continuity.
|
||||||
|
2. Platform team owns command issuance, lifecycle aggregation, and server-side escalation logic.
|
||||||
|
3. Client implementation must not assume managed PoE availability.
|
||||||
|
|
||||||
|
### Required Client Behaviors
|
||||||
|
|
||||||
|
### Frozen MQTT Topics and Schemas (v1)
|
||||||
|
1. Canonical command topic: infoscreen/{client_uuid}/commands.
|
||||||
|
2. Canonical ack topic: infoscreen/{client_uuid}/commands/ack.
|
||||||
|
3. Transitional compatibility topics during migration:
|
||||||
|
- infoscreen/{client_uuid}/command
|
||||||
|
- infoscreen/{client_uuid}/command/ack
|
||||||
|
4. QoS policy: command QoS 1, ack QoS 1 recommended.
|
||||||
|
5. Retain policy: commands and acks are non-retained.
|
||||||
|
|
||||||
|
Frozen command payload schema:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"client_uuid": "9b8d1856-ff34-4864-a726-12de072d0f77",
|
||||||
|
"action": "reboot_host",
|
||||||
|
"issued_at": "2026-04-03T12:48:10Z",
|
||||||
|
"expires_at": "2026-04-03T12:52:10Z",
|
||||||
|
"requested_by": 1,
|
||||||
|
"reason": "operator_request"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Frozen ack payload schema:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"status": "execution_started",
|
||||||
|
"error_code": null,
|
||||||
|
"error_message": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Allowed ack status values:
|
||||||
|
1. accepted
|
||||||
|
2. execution_started
|
||||||
|
3. completed
|
||||||
|
4. failed
|
||||||
|
|
||||||
|
Frozen command action values for v1:
|
||||||
|
1. reboot_host
|
||||||
|
2. shutdown_host
|
||||||
|
|
||||||
|
Reserved but not emitted by server in v1:
|
||||||
|
1. restart_service
|
||||||
|
|
||||||
|
Validation snippets for helper scripts:
|
||||||
|
1. Human-readable snippets: implementation-plans/reboot-command-payload-schemas.md
|
||||||
|
2. Machine-validated JSON Schema: implementation-plans/reboot-command-payload-schemas.json
|
||||||
|
|
||||||
|
### 1. Command Intake
|
||||||
|
1. Subscribe to the canonical command topic with QoS 1.
|
||||||
|
2. Parse required fields: schema_version, command_id, action, issued_at, expires_at, reason, requested_by, target metadata.
|
||||||
|
3. Reject invalid payloads with failed acknowledgement including error_code and diagnostic message.
|
||||||
|
4. Reject stale commands when current time exceeds expires_at.
|
||||||
|
5. Ignore already-processed command_id values.
|
||||||
|
|
||||||
|
### 2. Idempotency And Persistence
|
||||||
|
1. Persist processed command_id and execution result on local storage.
|
||||||
|
2. Persistence must survive service restart and full OS reboot.
|
||||||
|
3. On restart, reload dedupe cache before processing newly delivered commands.
|
||||||
|
|
||||||
|
### 3. Acknowledgement Contract Behavior
|
||||||
|
1. Emit accepted immediately after successful validation and dedupe pass.
|
||||||
|
2. Emit execution_started immediately before invoking the command action.
|
||||||
|
3. Emit completed only when local success condition is confirmed.
|
||||||
|
4. Emit failed with structured error_code on validation or execution failure.
|
||||||
|
5. If MQTT is temporarily unavailable, retry ack publish with bounded backoff until command expiry.
|
||||||
|
|
||||||
|
### 4. Execution Security Model
|
||||||
|
1. Execute via systemd-managed privileged helper.
|
||||||
|
2. Allow only whitelisted operations:
|
||||||
|
- reboot_host
|
||||||
|
- shutdown_host
|
||||||
|
3. Optionally keep restart_service handler as reserved path, but do not require it for v1 conformance.
|
||||||
|
4. Disallow arbitrary shell commands and untrusted arguments.
|
||||||
|
5. Enforce per-command execution timeout and terminate hung child processes.
|
||||||
|
|
||||||
|
### 5. Reboot Recovery Continuity
|
||||||
|
1. For reboot_host action:
|
||||||
|
- send execution_started
|
||||||
|
- trigger reboot promptly
|
||||||
|
2. During startup:
|
||||||
|
- emit heartbeat early
|
||||||
|
- emit process-health once service is ready
|
||||||
|
3. Keep last command execution state available after reboot for reconciliation.
|
||||||
|
|
||||||
|
### 6. Time And Timeout Semantics
|
||||||
|
1. Use monotonic timers for local elapsed-time checks.
|
||||||
|
2. Use UTC wall-clock only for protocol timestamps and expiry comparisons.
|
||||||
|
3. Target reconnect baseline on Pi 5 USB-SATA SSD: 90 seconds.
|
||||||
|
4. Accept cold-boot and USB enumeration ceiling up to 150 seconds.
|
||||||
|
|
||||||
|
### 7. Capability Reporting
|
||||||
|
1. Report recovery capability class:
|
||||||
|
- software_only
|
||||||
|
- managed_poe_available
|
||||||
|
- manual_only
|
||||||
|
2. Report watchdog enabled status.
|
||||||
|
3. Report boot-source metadata for diagnostics.
|
||||||
|
|
||||||
|
### 8. Error Codes Minimum Set
|
||||||
|
1. invalid_schema
|
||||||
|
2. missing_field
|
||||||
|
3. stale_command
|
||||||
|
4. duplicate_command
|
||||||
|
5. permission_denied_local
|
||||||
|
6. execution_timeout
|
||||||
|
7. execution_failed
|
||||||
|
8. broker_unavailable
|
||||||
|
9. internal_error
|
||||||
|
|
||||||
|
### Acceptance Tests (Client Team)
|
||||||
|
1. Invalid schema payload is rejected and failed ack emitted.
|
||||||
|
2. Expired command is rejected and not executed.
|
||||||
|
3. Duplicate command_id is not executed twice.
|
||||||
|
4. reboot_host emits execution_started and reconnects with heartbeat in expected window.
|
||||||
|
5. restart_service action completes without host reboot and emits completed.
|
||||||
|
6. MQTT outage during ack path retries correctly without duplicate execution.
|
||||||
|
7. Boot-loop protection cooperates with server-side lockout semantics.
|
||||||
|
|
||||||
|
### Delivery Artifacts
|
||||||
|
1. Client protocol conformance checklist.
|
||||||
|
2. Test evidence for all acceptance tests.
|
||||||
|
3. Runtime logs showing full lifecycle for one restart and one reboot scenario.
|
||||||
|
4. Known limitations list per image version.
|
||||||
|
|
||||||
|
### Definition Of Done
|
||||||
|
1. All acceptance tests pass on Pi 5 USB-SATA SSD test devices.
|
||||||
|
2. No duplicate execution observed under reconnect and retained-delivery edge cases.
|
||||||
|
3. Acknowledgement sequence is complete and machine-parseable for server correlation.
|
||||||
|
4. Reboot recovery continuity works without managed PoE dependencies.
|
||||||
214
implementation-plans/reboot-implementation-handoff-share.md
Normal file
214
implementation-plans/reboot-implementation-handoff-share.md
Normal file
@@ -0,0 +1,214 @@
|
|||||||
|
## Remote Reboot Reliability Handoff (Share Document)
|
||||||
|
|
||||||
|
### Purpose
|
||||||
|
This document defines the agreed implementation scope for reliable remote reboot and shutdown of Raspberry Pi 5 clients, with monitoring-first visibility and safe escalation paths.
|
||||||
|
|
||||||
|
### Scope
|
||||||
|
1. In scope: restart and shutdown command reliability.
|
||||||
|
2. In scope: full lifecycle monitoring and audit visibility.
|
||||||
|
3. In scope: capability-tier recovery model with optional managed PoE escalation.
|
||||||
|
4. Out of scope: broader maintenance module in client-management for this cycle.
|
||||||
|
5. Out of scope: mandatory dependency on customer-managed power switching.
|
||||||
|
|
||||||
|
### Agreed Operating Model
|
||||||
|
1. Command delivery is asynchronous and lifecycle-tracked, not fire-and-forget.
|
||||||
|
2. Commands use idempotent command_id semantics with stale-command rejection by expires_at.
|
||||||
|
3. Monitoring is authoritative for operational state and escalation decisions.
|
||||||
|
4. Recovery must function even when no managed power switching is available.
|
||||||
|
|
||||||
|
### Frozen Contract v1 (Effective Immediately)
|
||||||
|
1. Canonical command topic: infoscreen/{client_uuid}/commands.
|
||||||
|
2. Canonical ack topic: infoscreen/{client_uuid}/commands/ack.
|
||||||
|
3. Transitional compatibility topics accepted during migration:
|
||||||
|
- infoscreen/{client_uuid}/command
|
||||||
|
- infoscreen/{client_uuid}/command/ack
|
||||||
|
4. QoS policy: command QoS 1, ack QoS 1 recommended.
|
||||||
|
5. Retain policy: commands and acks are non-retained.
|
||||||
|
|
||||||
|
Command payload schema (frozen):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"client_uuid": "9b8d1856-ff34-4864-a726-12de072d0f77",
|
||||||
|
"action": "reboot_host",
|
||||||
|
"issued_at": "2026-04-03T12:48:10Z",
|
||||||
|
"expires_at": "2026-04-03T12:52:10Z",
|
||||||
|
"requested_by": 1,
|
||||||
|
"reason": "operator_request"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Ack payload schema (frozen):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"command_id": "5d1f8b4b-7e85-44fb-8f38-3f5d5da5e2e4",
|
||||||
|
"status": "execution_started",
|
||||||
|
"error_code": null,
|
||||||
|
"error_message": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Allowed ack status values:
|
||||||
|
1. accepted
|
||||||
|
2. execution_started
|
||||||
|
3. completed
|
||||||
|
4. failed
|
||||||
|
|
||||||
|
Frozen command action values:
|
||||||
|
1. reboot_host
|
||||||
|
2. shutdown_host
|
||||||
|
|
||||||
|
API endpoint mapping:
|
||||||
|
1. POST /api/clients/{uuid}/restart -> action reboot_host
|
||||||
|
2. POST /api/clients/{uuid}/shutdown -> action shutdown_host
|
||||||
|
|
||||||
|
Validation snippets:
|
||||||
|
1. Human-readable snippets: implementation-plans/reboot-command-payload-schemas.md
|
||||||
|
2. Machine-validated JSON Schema: implementation-plans/reboot-command-payload-schemas.json
|
||||||
|
|
||||||
|
### Command Lifecycle States
|
||||||
|
1. queued
|
||||||
|
2. publish_in_progress
|
||||||
|
3. published
|
||||||
|
4. ack_received
|
||||||
|
5. execution_started
|
||||||
|
6. awaiting_reconnect
|
||||||
|
7. recovered
|
||||||
|
8. completed
|
||||||
|
9. failed
|
||||||
|
10. expired
|
||||||
|
11. timed_out
|
||||||
|
12. canceled
|
||||||
|
13. blocked_safety
|
||||||
|
14. manual_intervention_required
|
||||||
|
|
||||||
|
### Timeout Defaults (Pi 5, USB-SATA SSD baseline)
|
||||||
|
1. queued to publish_in_progress: immediate, timeout 5 seconds.
|
||||||
|
2. publish_in_progress to published: timeout 8 seconds.
|
||||||
|
3. published to ack_received: timeout 20 seconds.
|
||||||
|
4. ack_received to execution_started: 15 seconds for service restart, 25 seconds for host reboot.
|
||||||
|
5. execution_started to awaiting_reconnect: timeout 10 seconds.
|
||||||
|
6. awaiting_reconnect to recovered: baseline 90 seconds after validation, cold-boot ceiling 150 seconds.
|
||||||
|
7. recovered to completed: 15 to 20 seconds based on fleet stability.
|
||||||
|
8. command expires_at default: 240 seconds, bounded 180 to 360 seconds.
|
||||||
|
|
||||||
|
### Recovery Tiers
|
||||||
|
1. Tier 0 baseline, always required: watchdog, systemd auto-restart, lifecycle tracking, manual intervention fallback.
|
||||||
|
2. Tier 1 optional: managed PoE per-port power-cycle escalation where customer infrastructure supports it.
|
||||||
|
3. Tier 2 no remote power control: direct manual intervention workflow.
|
||||||
|
|
||||||
|
### Governance And Safety
|
||||||
|
1. Role access: admin and superadmin.
|
||||||
|
2. Bulk actions require reason capture.
|
||||||
|
3. Safety lockout: maximum 3 reboot commands per client in 15 minutes.
|
||||||
|
4. Escalation cooldown: 60 seconds before automatic move to manual_intervention_required.
|
||||||
|
|
||||||
|
### MQTT Auth Hardening (Phase 1, Required Before Broad Rollout)
|
||||||
|
1. Intranet-only deployment is not sufficient protection for privileged MQTT actions by itself.
|
||||||
|
2. Phase 1 hardening scope is broker authentication, authorization, and network restriction; payload URL allowlisting is deferred to a later client/server feature.
|
||||||
|
3. MQTT broker must disable anonymous publish/subscribe access in production.
|
||||||
|
4. MQTT broker must require authenticated identities for server-side publishers and client devices.
|
||||||
|
5. MQTT broker must enforce ACLs so that:
|
||||||
|
- only server-side services can publish to `infoscreen/{client_uuid}/commands`
|
||||||
|
- only server-side services can publish scheduler event topics
|
||||||
|
- each client can subscribe only to its own command topics and assigned event topics
|
||||||
|
- each client can publish only its own ack, heartbeat, health, dashboard, and telemetry topics
|
||||||
|
6. Broker port exposure must be restricted to the management network and approved hosts only.
|
||||||
|
7. TLS support is strongly recommended in this phase and should be enabled when operationally feasible.
|
||||||
|
|
||||||
|
### Server Team Actions For Auth Hardening
|
||||||
|
1. Provision broker credentials for command/event publishers and for client devices.
|
||||||
|
2. Configure Mosquitto or equivalent broker ACLs for per-topic publish and subscribe restrictions.
|
||||||
|
3. Disable anonymous access on production brokers.
|
||||||
|
4. Restrict broker network exposure with firewall rules, VLAN policy, or equivalent network controls.
|
||||||
|
5. Update server/frontend deployment to publish MQTT with authenticated credentials.
|
||||||
|
6. Validate that server-side event publishing and reboot/shutdown command publishing still work under the new ACL policy.
|
||||||
|
7. Coordinate credential distribution and rotation with the client deployment process.
|
||||||
|
|
||||||
|
### MQTT ACL Matrix (Canonical Baseline)
|
||||||
|
| Actor | Topic Pattern | Publish | Subscribe | Notes |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| scheduler-service | infoscreen/events/+ | Yes | No | Publishes retained active event list per group. |
|
||||||
|
| api-command-publisher | infoscreen/+/commands | Yes | No | Publishes canonical reboot/shutdown commands. |
|
||||||
|
| api-command-publisher | infoscreen/+/command | Yes | No | Transitional compatibility publish only. |
|
||||||
|
| api-group-assignment | infoscreen/+/group_id | Yes | No | Publishes retained client-to-group assignment. |
|
||||||
|
| listener-service | infoscreen/+/commands/ack | No | Yes | Consumes canonical client command acknowledgements. |
|
||||||
|
| listener-service | infoscreen/+/command/ack | No | Yes | Consumes transitional compatibility acknowledgements. |
|
||||||
|
| listener-service | infoscreen/+/heartbeat | No | Yes | Consumes heartbeat telemetry. |
|
||||||
|
| listener-service | infoscreen/+/health | No | Yes | Consumes health telemetry. |
|
||||||
|
| listener-service | infoscreen/+/dashboard | No | Yes | Consumes dashboard screenshot payloads. |
|
||||||
|
| listener-service | infoscreen/+/screenshot | No | Yes | Consumes screenshot payloads (if enabled). |
|
||||||
|
| listener-service | infoscreen/+/logs/error | No | Yes | Consumes client error logs. |
|
||||||
|
| listener-service | infoscreen/+/logs/warn | No | Yes | Consumes client warn logs. |
|
||||||
|
| listener-service | infoscreen/+/logs/info | No | Yes | Consumes client info logs. |
|
||||||
|
| listener-service | infoscreen/discovery | No | Yes | Consumes discovery announcements. |
|
||||||
|
| listener-service | infoscreen/+/discovery_ack | Yes | No | Publishes discovery acknowledgements. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/commands | No | Yes | Canonical command intake for this client only. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/command | No | Yes | Transitional compatibility intake for this client only. |
|
||||||
|
| client-<uuid> | infoscreen/events/<group_id> | No | Yes | Assigned group event feed only; dynamic per assignment. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/commands/ack | Yes | No | Canonical command acknowledgements for this client only. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/command/ack | Yes | No | Transitional compatibility acknowledgements for this client only. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/heartbeat | Yes | No | Heartbeat telemetry. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/health | Yes | No | Health telemetry. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/dashboard | Yes | No | Dashboard status and screenshot payloads. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/screenshot | Yes | No | Screenshot payloads (if enabled). |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/logs/error | Yes | No | Error log stream. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/logs/warn | Yes | No | Warning log stream. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/logs/info | Yes | No | Info log stream. |
|
||||||
|
| client-<uuid> | infoscreen/discovery | Yes | No | Discovery announcement. |
|
||||||
|
| client-<uuid> | infoscreen/<uuid>/discovery_ack | No | Yes | Discovery acknowledgment from listener. |
|
||||||
|
|
||||||
|
ACL implementation notes:
|
||||||
|
1. Use per-client identities; client ACLs must be scoped to exact client UUID and must not allow wildcard access to other clients.
|
||||||
|
2. Event topic subscription (`infoscreen/events/<group_id>`) should be managed via broker-side ACL provisioning that updates when group assignment changes.
|
||||||
|
3. Transitional singular command topics are temporary and should be removed after migration cutover.
|
||||||
|
4. Deny by default: any topic not explicitly listed above should be blocked for each actor.
|
||||||
|
|
||||||
|
### Credential Management Guidance
|
||||||
|
1. Real MQTT passwords must not be stored in tracked documentation or committed templates.
|
||||||
|
2. Each client device should receive a unique broker username and password, stored only in its local [/.env](.env).
|
||||||
|
3. Server-side publisher credentials should be stored in the server team's secret-management path, not in source control.
|
||||||
|
4. Recommended naming convention for client broker users: `infoscreen-client-<client-uuid-prefix>`.
|
||||||
|
5. Client passwords should be random, at least 20 characters, and rotated through deployment tooling or broker administration procedures.
|
||||||
|
6. The server/infrastructure team owns broker-side user creation, ACL assignment, rotation, and revocation.
|
||||||
|
7. The client team owns loading credentials from local env files and validating connection behavior against the secured broker.
|
||||||
|
|
||||||
|
### Client Team Actions For Auth Hardening
|
||||||
|
1. Add MQTT username/password support in the client connection setup.
|
||||||
|
2. Add client-side TLS configuration support from environment when certificates are provided.
|
||||||
|
3. Update local test helpers to support authenticated MQTT publishing and subscription.
|
||||||
|
4. Validate command and event intake against the authenticated broker configuration before canary rollout.
|
||||||
|
|
||||||
|
### Ready For Server/Frontend Team (Auth Phase)
|
||||||
|
1. Client implementation is ready to connect with MQTT auth from local `.env` (`MQTT_USERNAME`, `MQTT_PASSWORD`, optional TLS settings).
|
||||||
|
2. Client command/event intake and client ack/telemetry publishing run over the authenticated MQTT session.
|
||||||
|
3. Server/frontend team must now complete broker-side enforcement and publisher migration.
|
||||||
|
|
||||||
|
Server/frontend done criteria:
|
||||||
|
1. Anonymous broker access is disabled in production.
|
||||||
|
2. Server-side publishers use authenticated broker credentials.
|
||||||
|
3. ACLs are active and validated for command, event, and client telemetry topics.
|
||||||
|
4. At least one canary client proves end-to-end flow under ACLs:
|
||||||
|
- server publishes command/event with authenticated publisher
|
||||||
|
- client receives payload
|
||||||
|
- client sends ack/telemetry successfully
|
||||||
|
5. Revocation test passes: disabling one client credential blocks only that client without impacting others.
|
||||||
|
|
||||||
|
Operational note:
|
||||||
|
1. Client-side auth support is necessary but not sufficient by itself; broker ACL/auth enforcement is the security control that must be enabled by the server/infrastructure team.
|
||||||
|
|
||||||
|
### Rollout Plan
|
||||||
|
1. Contract freeze and sign-off.
|
||||||
|
2. Platform and client implementation against frozen schemas.
|
||||||
|
3. One-group canary.
|
||||||
|
4. Rollback if failed plus timed_out exceeds 5 percent.
|
||||||
|
5. Expand only after 7 days below intervention threshold.
|
||||||
|
|
||||||
|
### Success Criteria
|
||||||
|
1. Deterministic command lifecycle visibility from enqueue to completion.
|
||||||
|
2. No duplicate execution under reconnect or delayed-delivery conditions.
|
||||||
|
3. Stable Pi 5 SSD reconnect behavior within defined baseline.
|
||||||
|
4. Clear and actionable manual intervention states when automatic recovery is exhausted.
|
||||||
54
implementation-plans/reboot-kickoff-summary.md
Normal file
54
implementation-plans/reboot-kickoff-summary.md
Normal file
@@ -0,0 +1,54 @@
|
|||||||
|
## Reboot Reliability Kickoff Summary
|
||||||
|
|
||||||
|
### Objective
|
||||||
|
Ship a reliable, observable restart and shutdown workflow for Raspberry Pi 5 clients, with safe escalation and clear operator outcomes.
|
||||||
|
|
||||||
|
### What Is Included
|
||||||
|
1. Asynchronous command lifecycle with idempotent command_id handling.
|
||||||
|
2. Monitoring-first state visibility from queued to terminal outcomes.
|
||||||
|
3. Client acknowledgements for accepted, execution_started, completed, and failed.
|
||||||
|
4. Pi 5 USB-SATA SSD timeout baseline and tuning rules.
|
||||||
|
5. Capability-tier recovery with optional managed PoE escalation.
|
||||||
|
|
||||||
|
### What Is Not Included
|
||||||
|
1. Full maintenance module in client-management.
|
||||||
|
2. Required managed power-switch integration.
|
||||||
|
3. Production Wake-on-LAN rollout.
|
||||||
|
|
||||||
|
### Team Split
|
||||||
|
1. Platform team: API command lifecycle, safety controls, listener ack ingestion.
|
||||||
|
2. Web team: lifecycle-aware UX and command status display.
|
||||||
|
3. Client team: strict validation, dedupe, ack sequence, secure execution helper, reboot continuity.
|
||||||
|
|
||||||
|
### Ownership Matrix
|
||||||
|
| Team | Primary Plan File | Main Deliverables |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| Platform team | implementation-plans/reboot-implementation-handoff-share.md | Command lifecycle backend, policy enforcement, listener ack mapping, safety lockout and escalation |
|
||||||
|
| Web team | implementation-plans/reboot-implementation-handoff-share.md | Lifecycle UI states, bulk safety UX, capability visibility, command status polling |
|
||||||
|
| Client team | implementation-plans/reboot-implementation-handoff-client-team.md | Command validation, dedupe persistence, ack sequence, secure execution helper, reboot continuity |
|
||||||
|
| Project coordination | implementation-plans/reboot-kickoff-summary.md | Phase sequencing, canary gates, rollback thresholds, cross-team sign-off tracking |
|
||||||
|
|
||||||
|
### Baseline Operational Defaults
|
||||||
|
1. Safety lockout: 3 reboot commands per client in rolling 15 minutes.
|
||||||
|
2. Escalation cooldown: 60 seconds.
|
||||||
|
3. Reconnect target on Pi 5 SSD: 90 seconds baseline, 150 seconds cold-boot ceiling.
|
||||||
|
4. Rollback canary trigger: failed plus timed_out above 5 percent.
|
||||||
|
|
||||||
|
### Frozen Contract Snapshot
|
||||||
|
1. Canonical command topic: infoscreen/{client_uuid}/commands.
|
||||||
|
2. Canonical ack topic: infoscreen/{client_uuid}/commands/ack.
|
||||||
|
3. Transitional compatibility topics during migration:
|
||||||
|
- infoscreen/{client_uuid}/command
|
||||||
|
- infoscreen/{client_uuid}/command/ack
|
||||||
|
4. Command schema version: 1.0.
|
||||||
|
5. Allowed command actions: reboot_host, shutdown_host.
|
||||||
|
6. Allowed ack status values: accepted, execution_started, completed, failed.
|
||||||
|
7. Validation snippets:
|
||||||
|
- implementation-plans/reboot-command-payload-schemas.md
|
||||||
|
- implementation-plans/reboot-command-payload-schemas.json
|
||||||
|
|
||||||
|
### Immediate Next Steps
|
||||||
|
1. Continue implementation in parallel by team against frozen contract.
|
||||||
|
2. Client team validates dedupe and expiry handling on canonical topics.
|
||||||
|
3. Platform team verifies ack-state transitions for accepted, execution_started, completed, failed.
|
||||||
|
4. Execute one-group canary and validate timing plus failure drills.
|
||||||
127
implementation-plans/server-team-actions.md
Normal file
127
implementation-plans/server-team-actions.md
Normal file
@@ -0,0 +1,127 @@
|
|||||||
|
# Server Team Action Items — Infoscreen Client
|
||||||
|
|
||||||
|
This document lists everything the server/infrastructure/frontend team must implement to complete the client integration. The client-side code is production-ready for all items listed here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. MQTT Broker Hardening (prerequisite for everything else)
|
||||||
|
|
||||||
|
- Disable anonymous access on the broker.
|
||||||
|
- Create one broker account **per client device**:
|
||||||
|
- Username convention: `infoscreen-client-<uuid-prefix>` (e.g. `infoscreen-client-9b8d1856`)
|
||||||
|
- Provision the password to the device `.env` as `MQTT_PASSWORD_BROKER=`
|
||||||
|
- Create a **server/publisher account** (e.g. `infoscreen-server`) for all server-side publishes.
|
||||||
|
- Enforce ACLs:
|
||||||
|
|
||||||
|
| Topic | Publisher |
|
||||||
|
|---|---|
|
||||||
|
| `infoscreen/{uuid}/commands` | server only |
|
||||||
|
| `infoscreen/{uuid}/command` (alias) | server only |
|
||||||
|
| `infoscreen/{uuid}/group_id` | server only |
|
||||||
|
| `infoscreen/events/{group_id}` | server only |
|
||||||
|
| `infoscreen/groups/+/power/intent` | server only |
|
||||||
|
| `infoscreen/{uuid}/commands/ack` | client only |
|
||||||
|
| `infoscreen/{uuid}/command/ack` | client only |
|
||||||
|
| `infoscreen/{uuid}/heartbeat` | client only |
|
||||||
|
| `infoscreen/{uuid}/health` | client only |
|
||||||
|
| `infoscreen/{uuid}/logs/#` | client only |
|
||||||
|
| `infoscreen/{uuid}/service_failed` | client only |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Reboot / Shutdown Command — Ack Lifecycle
|
||||||
|
|
||||||
|
Client publishes ack status updates to two topics per command (canonical + transitional alias):
|
||||||
|
- `infoscreen/{uuid}/commands/ack`
|
||||||
|
- `infoscreen/{uuid}/command/ack`
|
||||||
|
|
||||||
|
**Ack payload schema (v1, frozen):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"command_id": "07aab032-53c2-45ef-a5a3-6aa58e9d9fae",
|
||||||
|
"status": "accepted | execution_started | completed | failed",
|
||||||
|
"error_code": null,
|
||||||
|
"error_message": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Status lifecycle:**
|
||||||
|
|
||||||
|
| Status | When | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `accepted` | Command received and validated | Immediate |
|
||||||
|
| `execution_started` | Helper invoked | Immediate after accepted |
|
||||||
|
| `completed` | Execution confirmed | For `reboot_host`: arrives after reconnect (10–90 s after `execution_started`) |
|
||||||
|
| `failed` | Helper returned error | `error_code` and `error_message` will be set |
|
||||||
|
|
||||||
|
**Server must:**
|
||||||
|
- Track `command_id` through the full lifecycle and update status in DB/UI.
|
||||||
|
- Surface `failed` + `error_code` to the operator UI.
|
||||||
|
- Expect `reboot_host` `completed` to arrive after a reconnect delay — do not treat the gap as a timeout.
|
||||||
|
- Use `expires_at` from the original command to determine when to abandon waiting.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Health Dashboard — Broker Connection Fields (Gap 2)
|
||||||
|
|
||||||
|
Every `infoscreen/{uuid}/health` payload now includes a `broker_connection` block:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"timestamp": "2026-04-05T08:00:00.000000+00:00",
|
||||||
|
"expected_state": { "event_id": 42 },
|
||||||
|
"actual_state": {
|
||||||
|
"process": "display_manager",
|
||||||
|
"pid": 1234,
|
||||||
|
"status": "running"
|
||||||
|
},
|
||||||
|
"broker_connection": {
|
||||||
|
"broker_reachable": true,
|
||||||
|
"reconnect_count": 2,
|
||||||
|
"last_disconnect_at": "2026-04-04T10:30:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Server must:**
|
||||||
|
- Display `reconnect_count` and `last_disconnect_at` per device in the health dashboard.
|
||||||
|
- Implement alerting heuristic:
|
||||||
|
- **All** clients go silent simultaneously → likely broker outage, not device crash.
|
||||||
|
- **Single** client goes silent → device crash, network failure, or process hang.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Service-Failed MQTT Notification (Gap 3)
|
||||||
|
|
||||||
|
When systemd gives up restarting a service after repeated crashes (`StartLimitBurst` exceeded), the client automatically publishes a **retained** message:
|
||||||
|
|
||||||
|
**Topic:** `infoscreen/{uuid}/service_failed`
|
||||||
|
|
||||||
|
**Payload:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "service_failed",
|
||||||
|
"unit": "infoscreen-simclient.service",
|
||||||
|
"client_uuid": "9b8d1856-ff34-4864-a726-12de072d0f77",
|
||||||
|
"failed_at": "2026-04-05T08:00:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Server must:**
|
||||||
|
- Subscribe to `infoscreen/+/service_failed` on startup (retained — message survives broker restart).
|
||||||
|
- Alert the operator immediately when this topic receives a payload.
|
||||||
|
- **Clear the retained message** once the device is acknowledged or recovered:
|
||||||
|
```
|
||||||
|
mosquitto_pub -t "infoscreen/{uuid}/service_failed" -n --retain
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. No Server Action Required
|
||||||
|
|
||||||
|
These items are fully implemented client-side and require no server changes:
|
||||||
|
|
||||||
|
- systemd watchdog (`WatchdogSec=60`) — hangs detected and process restarted automatically.
|
||||||
|
- Command deduplication — `command_id` deduplicated with 24-hour TTL.
|
||||||
|
- Ack retry backoff — client retries ack publish on broker disconnect until `expires_at`.
|
||||||
|
- Mock helper / test mode (`COMMAND_MOCK_REBOOT_IMMEDIATE_COMPLETE`) — development only.
|
||||||
@@ -4,11 +4,12 @@ import logging
|
|||||||
import datetime
|
import datetime
|
||||||
import base64
|
import base64
|
||||||
import re
|
import re
|
||||||
|
import ssl
|
||||||
import requests
|
import requests
|
||||||
import paho.mqtt.client as mqtt
|
import paho.mqtt.client as mqtt
|
||||||
from sqlalchemy import create_engine
|
from sqlalchemy import create_engine
|
||||||
from sqlalchemy.orm import sessionmaker
|
from sqlalchemy.orm import sessionmaker
|
||||||
from models.models import Client, ClientLog, LogLevel, ProcessStatus, ScreenHealthStatus
|
from models.models import Client, ClientLog, ClientCommand, LogLevel, ProcessStatus, ScreenHealthStatus
|
||||||
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s [%(levelname)s] %(message)s')
|
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s [%(levelname)s] %(message)s')
|
||||||
|
|
||||||
# Load .env only when not already configured by Docker (API_BASE_URL not set by compose means we're outside a container)
|
# Load .env only when not already configured by Docker (API_BASE_URL not set by compose means we're outside a container)
|
||||||
@@ -32,6 +33,16 @@ Session = sessionmaker(bind=engine)
|
|||||||
# API configuration
|
# API configuration
|
||||||
API_BASE_URL = os.getenv("API_BASE_URL", "http://server:8000")
|
API_BASE_URL = os.getenv("API_BASE_URL", "http://server:8000")
|
||||||
|
|
||||||
|
MQTT_BROKER_HOST = os.getenv("MQTT_BROKER_HOST", "mqtt")
|
||||||
|
MQTT_BROKER_PORT = int(os.getenv("MQTT_BROKER_PORT", os.getenv("MQTT_PORT", "1883")))
|
||||||
|
MQTT_USERNAME = os.getenv("MQTT_USER") or os.getenv("MQTT_USERNAME")
|
||||||
|
MQTT_PASSWORD = os.getenv("MQTT_PASSWORD")
|
||||||
|
MQTT_TLS_ENABLED = os.getenv("MQTT_TLS_ENABLED", "false").strip().lower() in ("1", "true", "yes", "on")
|
||||||
|
MQTT_TLS_CA_CERT = os.getenv("MQTT_TLS_CA_CERT")
|
||||||
|
MQTT_TLS_CERTFILE = os.getenv("MQTT_TLS_CERTFILE")
|
||||||
|
MQTT_TLS_KEYFILE = os.getenv("MQTT_TLS_KEYFILE")
|
||||||
|
MQTT_TLS_INSECURE = os.getenv("MQTT_TLS_INSECURE", "false").strip().lower() in ("1", "true", "yes", "on")
|
||||||
|
|
||||||
# Dashboard payload migration observability
|
# Dashboard payload migration observability
|
||||||
DASHBOARD_METRICS_LOG_EVERY = int(os.getenv("DASHBOARD_METRICS_LOG_EVERY", "5"))
|
DASHBOARD_METRICS_LOG_EVERY = int(os.getenv("DASHBOARD_METRICS_LOG_EVERY", "5"))
|
||||||
DASHBOARD_PARSE_METRICS = {
|
DASHBOARD_PARSE_METRICS = {
|
||||||
@@ -376,8 +387,11 @@ def on_connect(client, userdata, flags, reasonCode, properties):
|
|||||||
client.subscribe("infoscreen/+/logs/warn")
|
client.subscribe("infoscreen/+/logs/warn")
|
||||||
client.subscribe("infoscreen/+/logs/info")
|
client.subscribe("infoscreen/+/logs/info")
|
||||||
client.subscribe("infoscreen/+/health")
|
client.subscribe("infoscreen/+/health")
|
||||||
|
client.subscribe("infoscreen/+/commands/ack")
|
||||||
|
client.subscribe("infoscreen/+/command/ack")
|
||||||
|
client.subscribe("infoscreen/+/service_failed")
|
||||||
|
|
||||||
logging.info(f"MQTT connected (reasonCode: {reasonCode}); (re)subscribed to discovery, heartbeats, screenshots, dashboards, logs, and health")
|
logging.info(f"MQTT connected (reasonCode: {reasonCode}); (re)subscribed to discovery, heartbeats, screenshots, dashboards, logs, health, and service_failed")
|
||||||
except Exception as e:
|
except Exception as e:
|
||||||
logging.error(f"Subscribe failed on connect: {e}")
|
logging.error(f"Subscribe failed on connect: {e}")
|
||||||
|
|
||||||
@@ -387,6 +401,72 @@ def on_message(client, userdata, msg):
|
|||||||
logging.debug(f"Empfangene Nachricht auf Topic: {topic}")
|
logging.debug(f"Empfangene Nachricht auf Topic: {topic}")
|
||||||
|
|
||||||
try:
|
try:
|
||||||
|
# Command acknowledgement handling
|
||||||
|
if topic.startswith("infoscreen/") and (topic.endswith("/commands/ack") or topic.endswith("/command/ack")):
|
||||||
|
uuid = topic.split("/")[1]
|
||||||
|
try:
|
||||||
|
payload = json.loads(msg.payload.decode())
|
||||||
|
except (json.JSONDecodeError, UnicodeDecodeError):
|
||||||
|
logging.error(f"Ungueltiges Command-ACK Payload von {uuid}")
|
||||||
|
return
|
||||||
|
|
||||||
|
command_id = payload.get("command_id")
|
||||||
|
ack_status = str(payload.get("status", "")).strip().lower()
|
||||||
|
error_code = payload.get("error_code")
|
||||||
|
error_message = payload.get("error_message")
|
||||||
|
|
||||||
|
if not command_id:
|
||||||
|
logging.warning(f"Command-ACK ohne command_id von {uuid}")
|
||||||
|
return
|
||||||
|
|
||||||
|
status_map = {
|
||||||
|
"accepted": "ack_received",
|
||||||
|
"execution_started": "execution_started",
|
||||||
|
"completed": "completed",
|
||||||
|
"failed": "failed",
|
||||||
|
}
|
||||||
|
mapped_status = status_map.get(ack_status)
|
||||||
|
if not mapped_status:
|
||||||
|
logging.warning(f"Unbekannter Command-ACK Status '{ack_status}' von {uuid}")
|
||||||
|
return
|
||||||
|
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
command_obj = db_session.query(ClientCommand).filter_by(command_id=command_id).first()
|
||||||
|
if not command_obj:
|
||||||
|
logging.warning(f"Command-ACK fuer unbekanntes command_id={command_id} von {uuid}")
|
||||||
|
return
|
||||||
|
|
||||||
|
# Ignore stale/duplicate regressions.
|
||||||
|
terminal_states = {"completed", "failed", "expired", "canceled", "blocked_safety"}
|
||||||
|
if command_obj.status in terminal_states:
|
||||||
|
logging.info(
|
||||||
|
f"Command-ACK ignoriert (bereits terminal): command_id={command_id}, status={command_obj.status}"
|
||||||
|
)
|
||||||
|
return
|
||||||
|
|
||||||
|
now_utc = datetime.datetime.now(datetime.UTC)
|
||||||
|
command_obj.status = mapped_status
|
||||||
|
if mapped_status == "ack_received":
|
||||||
|
command_obj.acked_at = now_utc
|
||||||
|
elif mapped_status == "execution_started":
|
||||||
|
command_obj.execution_started_at = now_utc
|
||||||
|
elif mapped_status == "completed":
|
||||||
|
command_obj.completed_at = now_utc
|
||||||
|
elif mapped_status == "failed":
|
||||||
|
command_obj.failed_at = now_utc
|
||||||
|
command_obj.error_code = str(error_code) if error_code is not None else command_obj.error_code
|
||||||
|
command_obj.error_message = str(error_message) if error_message is not None else command_obj.error_message
|
||||||
|
|
||||||
|
db_session.commit()
|
||||||
|
logging.info(f"Command-ACK verarbeitet: command_id={command_id}, status={mapped_status}, uuid={uuid}")
|
||||||
|
except Exception as e:
|
||||||
|
db_session.rollback()
|
||||||
|
logging.error(f"Fehler bei Command-ACK Verarbeitung ({command_id}): {e}")
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
return
|
||||||
|
|
||||||
# Dashboard-Handling (nested screenshot payload)
|
# Dashboard-Handling (nested screenshot payload)
|
||||||
if topic.startswith("infoscreen/") and topic.endswith("/dashboard"):
|
if topic.startswith("infoscreen/") and topic.endswith("/dashboard"):
|
||||||
uuid = topic.split("/")[1]
|
uuid = topic.split("/")[1]
|
||||||
@@ -506,6 +586,43 @@ def on_message(client, userdata, msg):
|
|||||||
logging.error(f"Could not parse log payload from {uuid}: {e}")
|
logging.error(f"Could not parse log payload from {uuid}: {e}")
|
||||||
return
|
return
|
||||||
|
|
||||||
|
# Service-failed handling (systemd gave up restarting — retained message)
|
||||||
|
if topic.startswith("infoscreen/") and topic.endswith("/service_failed"):
|
||||||
|
uuid = topic.split("/")[1]
|
||||||
|
# Empty payload = retained message cleared; ignore it.
|
||||||
|
if not msg.payload:
|
||||||
|
logging.info(f"service_failed retained message cleared for {uuid}")
|
||||||
|
return
|
||||||
|
try:
|
||||||
|
payload_data = json.loads(msg.payload.decode())
|
||||||
|
failed_at_str = payload_data.get("failed_at")
|
||||||
|
unit = payload_data.get("unit", "")
|
||||||
|
try:
|
||||||
|
failed_at = datetime.datetime.fromisoformat(failed_at_str.replace("Z", "+00:00")) if failed_at_str else datetime.datetime.now(datetime.UTC)
|
||||||
|
if failed_at.tzinfo is None:
|
||||||
|
failed_at = failed_at.replace(tzinfo=datetime.UTC)
|
||||||
|
except (ValueError, AttributeError):
|
||||||
|
failed_at = datetime.datetime.now(datetime.UTC)
|
||||||
|
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
client_obj = session.query(Client).filter_by(uuid=uuid).first()
|
||||||
|
if client_obj:
|
||||||
|
client_obj.service_failed_at = failed_at
|
||||||
|
client_obj.service_failed_unit = unit[:128] if unit else None
|
||||||
|
session.commit()
|
||||||
|
logging.warning(f"event=service_failed uuid={uuid} unit={unit} failed_at={failed_at.isoformat()}")
|
||||||
|
else:
|
||||||
|
logging.warning(f"service_failed received for unknown client uuid={uuid}")
|
||||||
|
except Exception as e:
|
||||||
|
session.rollback()
|
||||||
|
logging.error(f"Error persisting service_failed for {uuid}: {e}")
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
except (json.JSONDecodeError, UnicodeDecodeError) as e:
|
||||||
|
logging.error(f"Could not parse service_failed payload from {uuid}: {e}")
|
||||||
|
return
|
||||||
|
|
||||||
# Health-Handling
|
# Health-Handling
|
||||||
if topic.startswith("infoscreen/") and topic.endswith("/health"):
|
if topic.startswith("infoscreen/") and topic.endswith("/health"):
|
||||||
uuid = topic.split("/")[1]
|
uuid = topic.split("/")[1]
|
||||||
@@ -531,6 +648,26 @@ def on_message(client, userdata, msg):
|
|||||||
screen_health_status=screen_health_status,
|
screen_health_status=screen_health_status,
|
||||||
last_screenshot_analyzed=parse_timestamp((payload_data.get('health_metrics') or {}).get('last_frame_update')),
|
last_screenshot_analyzed=parse_timestamp((payload_data.get('health_metrics') or {}).get('last_frame_update')),
|
||||||
)
|
)
|
||||||
|
|
||||||
|
# Update broker connection health fields
|
||||||
|
broker_conn = payload_data.get('broker_connection')
|
||||||
|
if isinstance(broker_conn, dict):
|
||||||
|
reconnect_count = broker_conn.get('reconnect_count')
|
||||||
|
last_disconnect_str = broker_conn.get('last_disconnect_at')
|
||||||
|
if reconnect_count is not None:
|
||||||
|
try:
|
||||||
|
client_obj.mqtt_reconnect_count = int(reconnect_count)
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
pass
|
||||||
|
if last_disconnect_str:
|
||||||
|
try:
|
||||||
|
last_disconnect = datetime.datetime.fromisoformat(last_disconnect_str.replace('Z', '+00:00'))
|
||||||
|
if last_disconnect.tzinfo is None:
|
||||||
|
last_disconnect = last_disconnect.replace(tzinfo=datetime.UTC)
|
||||||
|
client_obj.mqtt_last_disconnect_at = last_disconnect
|
||||||
|
except (ValueError, AttributeError):
|
||||||
|
pass
|
||||||
|
|
||||||
session.commit()
|
session.commit()
|
||||||
logging.debug(f"Health update from {uuid}: {actual.get('process')} ({actual.get('status')})")
|
logging.debug(f"Health update from {uuid}: {actual.get('process')} ({actual.get('status')})")
|
||||||
session.close()
|
session.close()
|
||||||
@@ -589,9 +726,29 @@ def main():
|
|||||||
mqtt_client.on_connect = on_connect
|
mqtt_client.on_connect = on_connect
|
||||||
# Set an exponential reconnect delay to survive broker restarts
|
# Set an exponential reconnect delay to survive broker restarts
|
||||||
mqtt_client.reconnect_delay_set(min_delay=1, max_delay=60)
|
mqtt_client.reconnect_delay_set(min_delay=1, max_delay=60)
|
||||||
mqtt_client.connect("mqtt", 1883)
|
|
||||||
|
|
||||||
logging.info("Listener gestartet; warte auf MQTT-Verbindung und Nachrichten")
|
if MQTT_USERNAME and MQTT_PASSWORD:
|
||||||
|
mqtt_client.username_pw_set(MQTT_USERNAME, MQTT_PASSWORD)
|
||||||
|
|
||||||
|
if MQTT_TLS_ENABLED:
|
||||||
|
mqtt_client.tls_set(
|
||||||
|
ca_certs=MQTT_TLS_CA_CERT,
|
||||||
|
certfile=MQTT_TLS_CERTFILE,
|
||||||
|
keyfile=MQTT_TLS_KEYFILE,
|
||||||
|
cert_reqs=ssl.CERT_REQUIRED,
|
||||||
|
)
|
||||||
|
if MQTT_TLS_INSECURE:
|
||||||
|
mqtt_client.tls_insecure_set(True)
|
||||||
|
|
||||||
|
mqtt_client.connect(MQTT_BROKER_HOST, MQTT_BROKER_PORT)
|
||||||
|
|
||||||
|
logging.info(
|
||||||
|
"Listener gestartet; warte auf MQTT-Verbindung und Nachrichten (host=%s port=%s tls=%s auth=%s)",
|
||||||
|
MQTT_BROKER_HOST,
|
||||||
|
MQTT_BROKER_PORT,
|
||||||
|
MQTT_TLS_ENABLED,
|
||||||
|
bool(MQTT_USERNAME and MQTT_PASSWORD),
|
||||||
|
)
|
||||||
mqtt_client.loop_forever()
|
mqtt_client.loop_forever()
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -73,15 +73,22 @@ class AcademicPeriod(Base):
|
|||||||
nullable=False, default=AcademicPeriodType.schuljahr)
|
nullable=False, default=AcademicPeriodType.schuljahr)
|
||||||
# nur eine aktive Periode zur Zeit
|
# nur eine aktive Periode zur Zeit
|
||||||
is_active = Column(Boolean, default=False, nullable=False)
|
is_active = Column(Boolean, default=False, nullable=False)
|
||||||
|
# Archive lifecycle fields
|
||||||
|
is_archived = Column(Boolean, default=False, nullable=False, index=True)
|
||||||
|
archived_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
archived_by = Column(Integer, ForeignKey('users.id', ondelete='SET NULL'), nullable=True)
|
||||||
created_at = Column(TIMESTAMP(timezone=True),
|
created_at = Column(TIMESTAMP(timezone=True),
|
||||||
server_default=func.current_timestamp())
|
server_default=func.current_timestamp())
|
||||||
updated_at = Column(TIMESTAMP(timezone=True), server_default=func.current_timestamp(
|
updated_at = Column(TIMESTAMP(timezone=True), server_default=func.current_timestamp(
|
||||||
), onupdate=func.current_timestamp())
|
), onupdate=func.current_timestamp())
|
||||||
|
|
||||||
# Constraint: nur eine aktive Periode zur Zeit
|
# Constraint: nur eine aktive Periode zur Zeit; name unique among non-archived periods
|
||||||
__table_args__ = (
|
__table_args__ = (
|
||||||
Index('ix_academic_periods_active', 'is_active'),
|
Index('ix_academic_periods_active', 'is_active'),
|
||||||
UniqueConstraint('name', name='uq_academic_periods_name'),
|
Index('ix_academic_periods_archived', 'is_archived'),
|
||||||
|
# Unique constraint on active (non-archived) periods only is handled in code
|
||||||
|
# This index facilitates the query for checking uniqueness
|
||||||
|
Index('ix_academic_periods_name_not_archived', 'name', 'is_archived'),
|
||||||
)
|
)
|
||||||
|
|
||||||
def to_dict(self):
|
def to_dict(self):
|
||||||
@@ -93,6 +100,9 @@ class AcademicPeriod(Base):
|
|||||||
"end_date": self.end_date.isoformat() if self.end_date else None,
|
"end_date": self.end_date.isoformat() if self.end_date else None,
|
||||||
"period_type": self.period_type.value if self.period_type else None,
|
"period_type": self.period_type.value if self.period_type else None,
|
||||||
"is_active": self.is_active,
|
"is_active": self.is_active,
|
||||||
|
"is_archived": self.is_archived,
|
||||||
|
"archived_at": self.archived_at.isoformat() if self.archived_at else None,
|
||||||
|
"archived_by": self.archived_by,
|
||||||
"created_at": self.created_at.isoformat() if self.created_at else None,
|
"created_at": self.created_at.isoformat() if self.created_at else None,
|
||||||
"updated_at": self.updated_at.isoformat() if self.updated_at else None,
|
"updated_at": self.updated_at.isoformat() if self.updated_at else None,
|
||||||
}
|
}
|
||||||
@@ -137,6 +147,14 @@ class Client(Base):
|
|||||||
screen_health_status = Column(Enum(ScreenHealthStatus), nullable=True, server_default='UNKNOWN')
|
screen_health_status = Column(Enum(ScreenHealthStatus), nullable=True, server_default='UNKNOWN')
|
||||||
last_screenshot_hash = Column(String(32), nullable=True)
|
last_screenshot_hash = Column(String(32), nullable=True)
|
||||||
|
|
||||||
|
# Systemd service-failed tracking
|
||||||
|
service_failed_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
service_failed_unit = Column(String(128), nullable=True)
|
||||||
|
|
||||||
|
# MQTT broker connection health
|
||||||
|
mqtt_reconnect_count = Column(Integer, nullable=True)
|
||||||
|
mqtt_last_disconnect_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
|
||||||
|
|
||||||
class ClientLog(Base):
|
class ClientLog(Base):
|
||||||
__tablename__ = 'client_logs'
|
__tablename__ = 'client_logs'
|
||||||
@@ -154,6 +172,33 @@ class ClientLog(Base):
|
|||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class ClientCommand(Base):
|
||||||
|
__tablename__ = 'client_commands'
|
||||||
|
|
||||||
|
id = Column(Integer, primary_key=True, autoincrement=True)
|
||||||
|
command_id = Column(String(36), nullable=False, unique=True, index=True)
|
||||||
|
client_uuid = Column(String(36), ForeignKey('clients.uuid', ondelete='CASCADE'), nullable=False, index=True)
|
||||||
|
action = Column(String(32), nullable=False, index=True)
|
||||||
|
status = Column(String(40), nullable=False, index=True)
|
||||||
|
reason = Column(Text, nullable=True)
|
||||||
|
requested_by = Column(Integer, ForeignKey('users.id', ondelete='SET NULL'), nullable=True, index=True)
|
||||||
|
issued_at = Column(TIMESTAMP(timezone=True), nullable=False)
|
||||||
|
expires_at = Column(TIMESTAMP(timezone=True), nullable=False)
|
||||||
|
published_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
acked_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
execution_started_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
completed_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
failed_at = Column(TIMESTAMP(timezone=True), nullable=True)
|
||||||
|
error_code = Column(String(64), nullable=True)
|
||||||
|
error_message = Column(Text, nullable=True)
|
||||||
|
created_at = Column(TIMESTAMP(timezone=True), server_default=func.current_timestamp(), nullable=False)
|
||||||
|
updated_at = Column(TIMESTAMP(timezone=True), server_default=func.current_timestamp(), onupdate=func.current_timestamp(), nullable=False)
|
||||||
|
|
||||||
|
__table_args__ = (
|
||||||
|
Index('ix_client_commands_client_status_created', 'client_uuid', 'status', 'created_at'),
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
class EventType(enum.Enum):
|
class EventType(enum.Enum):
|
||||||
presentation = "presentation"
|
presentation = "presentation"
|
||||||
website = "website"
|
website = "website"
|
||||||
@@ -276,6 +321,7 @@ class EventMedia(Base):
|
|||||||
class SchoolHoliday(Base):
|
class SchoolHoliday(Base):
|
||||||
__tablename__ = 'school_holidays'
|
__tablename__ = 'school_holidays'
|
||||||
id = Column(Integer, primary_key=True, autoincrement=True)
|
id = Column(Integer, primary_key=True, autoincrement=True)
|
||||||
|
academic_period_id = Column(Integer, ForeignKey('academic_periods.id', ondelete='SET NULL'), nullable=True, index=True)
|
||||||
name = Column(String(150), nullable=False)
|
name = Column(String(150), nullable=False)
|
||||||
start_date = Column(Date, nullable=False, index=True)
|
start_date = Column(Date, nullable=False, index=True)
|
||||||
end_date = Column(Date, nullable=False, index=True)
|
end_date = Column(Date, nullable=False, index=True)
|
||||||
@@ -284,14 +330,17 @@ class SchoolHoliday(Base):
|
|||||||
imported_at = Column(TIMESTAMP(timezone=True),
|
imported_at = Column(TIMESTAMP(timezone=True),
|
||||||
server_default=func.current_timestamp())
|
server_default=func.current_timestamp())
|
||||||
|
|
||||||
|
academic_period = relationship("AcademicPeriod", foreign_keys=[academic_period_id])
|
||||||
|
|
||||||
__table_args__ = (
|
__table_args__ = (
|
||||||
UniqueConstraint('name', 'start_date', 'end_date',
|
UniqueConstraint('name', 'start_date', 'end_date',
|
||||||
'region', name='uq_school_holidays_unique'),
|
'region', 'academic_period_id', name='uq_school_holidays_unique'),
|
||||||
)
|
)
|
||||||
|
|
||||||
def to_dict(self):
|
def to_dict(self):
|
||||||
return {
|
return {
|
||||||
"id": self.id,
|
"id": self.id,
|
||||||
|
"academic_period_id": self.academic_period_id,
|
||||||
"name": self.name,
|
"name": self.name,
|
||||||
"start_date": self.start_date.isoformat() if self.start_date else None,
|
"start_date": self.start_date.isoformat() if self.start_date else None,
|
||||||
"end_date": self.end_date.isoformat() if self.end_date else None,
|
"end_date": self.end_date.isoformat() if self.end_date else None,
|
||||||
|
|||||||
@@ -1,11 +1,14 @@
|
|||||||
# scheduler/db_utils.py
|
# scheduler/db_utils.py
|
||||||
from dotenv import load_dotenv
|
from dotenv import load_dotenv
|
||||||
import os
|
import os
|
||||||
from datetime import datetime
|
from datetime import datetime, timedelta, timezone
|
||||||
|
import hashlib
|
||||||
|
import json
|
||||||
import logging
|
import logging
|
||||||
from sqlalchemy.orm import sessionmaker, joinedload
|
from sqlalchemy.orm import sessionmaker, joinedload
|
||||||
from sqlalchemy import create_engine, or_, and_, text
|
from sqlalchemy import create_engine, or_, and_, text
|
||||||
from models.models import Event, EventMedia, EventException, SystemSetting
|
import uuid as _uuid_mod
|
||||||
|
from models.models import Event, EventMedia, EventException, SystemSetting, Client, ClientCommand, ProcessStatus
|
||||||
from dateutil.rrule import rrulestr
|
from dateutil.rrule import rrulestr
|
||||||
from urllib.request import Request, urlopen
|
from urllib.request import Request, urlopen
|
||||||
from datetime import timezone
|
from datetime import timezone
|
||||||
@@ -184,6 +187,131 @@ def get_system_setting_value(key: str, default: str | None = None) -> str | None
|
|||||||
session.close()
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_utc_datetime(value):
|
||||||
|
"""Parse datetime-like values and normalize to timezone-aware UTC."""
|
||||||
|
if value is None:
|
||||||
|
return None
|
||||||
|
|
||||||
|
if isinstance(value, datetime):
|
||||||
|
dt = value
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
dt = datetime.fromisoformat(str(value))
|
||||||
|
except Exception:
|
||||||
|
return None
|
||||||
|
|
||||||
|
if dt.tzinfo is None:
|
||||||
|
return dt.replace(tzinfo=timezone.utc)
|
||||||
|
|
||||||
|
return dt.astimezone(timezone.utc)
|
||||||
|
|
||||||
|
|
||||||
|
def _normalize_group_id(group_id):
|
||||||
|
try:
|
||||||
|
return int(group_id)
|
||||||
|
except (TypeError, ValueError):
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def _event_range_from_dict(event):
|
||||||
|
start = _parse_utc_datetime(event.get("start"))
|
||||||
|
end = _parse_utc_datetime(event.get("end"))
|
||||||
|
if start is None or end is None or end <= start:
|
||||||
|
return None
|
||||||
|
return start, end
|
||||||
|
|
||||||
|
|
||||||
|
def _merge_ranges(ranges, adjacency_seconds=0):
|
||||||
|
"""Merge overlapping or adjacent [start, end] ranges."""
|
||||||
|
if not ranges:
|
||||||
|
return []
|
||||||
|
|
||||||
|
ranges_sorted = sorted(ranges, key=lambda r: (r[0], r[1]))
|
||||||
|
merged = [ranges_sorted[0]]
|
||||||
|
adjacency_delta = max(0, int(adjacency_seconds))
|
||||||
|
|
||||||
|
for current_start, current_end in ranges_sorted[1:]:
|
||||||
|
last_start, last_end = merged[-1]
|
||||||
|
if current_start <= last_end or (current_start - last_end).total_seconds() <= adjacency_delta:
|
||||||
|
if current_end > last_end:
|
||||||
|
merged[-1] = (last_start, current_end)
|
||||||
|
else:
|
||||||
|
merged.append((current_start, current_end))
|
||||||
|
|
||||||
|
return merged
|
||||||
|
|
||||||
|
|
||||||
|
def compute_group_power_intent_basis(events, group_id, now_utc=None, adjacency_seconds=0):
|
||||||
|
"""Return pure, deterministic power intent basis for one group at a point in time.
|
||||||
|
|
||||||
|
The returned mapping intentionally excludes volatile fields such as intent_id,
|
||||||
|
issued_at and expires_at.
|
||||||
|
"""
|
||||||
|
normalized_gid = _normalize_group_id(group_id)
|
||||||
|
effective_now = _parse_utc_datetime(now_utc) or datetime.now(timezone.utc)
|
||||||
|
|
||||||
|
ranges = []
|
||||||
|
active_event_ids = []
|
||||||
|
for event in events or []:
|
||||||
|
if _normalize_group_id(event.get("group_id")) != normalized_gid:
|
||||||
|
continue
|
||||||
|
parsed_range = _event_range_from_dict(event)
|
||||||
|
if parsed_range is None:
|
||||||
|
continue
|
||||||
|
|
||||||
|
start, end = parsed_range
|
||||||
|
ranges.append((start, end))
|
||||||
|
if start <= effective_now < end:
|
||||||
|
event_id = event.get("id")
|
||||||
|
if event_id is not None:
|
||||||
|
active_event_ids.append(event_id)
|
||||||
|
|
||||||
|
merged_ranges = _merge_ranges(ranges, adjacency_seconds=adjacency_seconds)
|
||||||
|
|
||||||
|
active_window_start = None
|
||||||
|
active_window_end = None
|
||||||
|
for window_start, window_end in merged_ranges:
|
||||||
|
if window_start <= effective_now < window_end:
|
||||||
|
active_window_start = window_start
|
||||||
|
active_window_end = window_end
|
||||||
|
break
|
||||||
|
|
||||||
|
desired_state = "on" if active_window_start is not None else "off"
|
||||||
|
reason = "active_event" if desired_state == "on" else "no_active_event"
|
||||||
|
|
||||||
|
return {
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"group_id": normalized_gid,
|
||||||
|
"desired_state": desired_state,
|
||||||
|
"reason": reason,
|
||||||
|
"poll_interval_sec": None,
|
||||||
|
"event_window_start": active_window_start.isoformat().replace("+00:00", "Z") if active_window_start else None,
|
||||||
|
"event_window_end": active_window_end.isoformat().replace("+00:00", "Z") if active_window_end else None,
|
||||||
|
"active_event_ids": sorted(set(active_event_ids)),
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def build_group_power_intent_body(intent_basis, poll_interval_sec):
|
||||||
|
"""Build deterministic payload body (without intent_id/issued_at/expires_at)."""
|
||||||
|
body = {
|
||||||
|
"schema_version": intent_basis.get("schema_version", "1.0"),
|
||||||
|
"group_id": intent_basis.get("group_id"),
|
||||||
|
"desired_state": intent_basis.get("desired_state", "off"),
|
||||||
|
"reason": intent_basis.get("reason", "no_active_event"),
|
||||||
|
"poll_interval_sec": int(poll_interval_sec),
|
||||||
|
"event_window_start": intent_basis.get("event_window_start"),
|
||||||
|
"event_window_end": intent_basis.get("event_window_end"),
|
||||||
|
"active_event_ids": list(intent_basis.get("active_event_ids", [])),
|
||||||
|
}
|
||||||
|
return body
|
||||||
|
|
||||||
|
|
||||||
|
def compute_group_power_intent_fingerprint(intent_body):
|
||||||
|
"""Create a stable hash for semantic transition detection."""
|
||||||
|
canonical_json = json.dumps(intent_body, sort_keys=True, separators=(",", ":"))
|
||||||
|
return hashlib.sha256(canonical_json.encode("utf-8")).hexdigest()
|
||||||
|
|
||||||
|
|
||||||
def format_event_with_media(event):
|
def format_event_with_media(event):
|
||||||
"""Transform Event + EventMedia into client-expected format"""
|
"""Transform Event + EventMedia into client-expected format"""
|
||||||
event_dict = {
|
event_dict = {
|
||||||
@@ -327,3 +455,167 @@ def format_event_with_media(event):
|
|||||||
# Add other event types (message, etc.) here as needed...
|
# Add other event types (message, etc.) here as needed...
|
||||||
|
|
||||||
return event_dict
|
return event_dict
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Crash detection / auto-recovery helpers
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
_CRASH_RECOVERY_SCHEMA_VERSION = "1.0"
|
||||||
|
_CRASH_COMMAND_TOPIC = "infoscreen/{uuid}/commands"
|
||||||
|
_CRASH_COMMAND_COMPAT_TOPIC = "infoscreen/{uuid}/command"
|
||||||
|
_CRASH_RECOVERY_EXPIRY_SECONDS = int(os.getenv("CRASH_RECOVERY_COMMAND_EXPIRY_SECONDS", "240"))
|
||||||
|
_CRASH_RECOVERY_LOCKOUT_MINUTES = int(os.getenv("CRASH_RECOVERY_LOCKOUT_MINUTES", "15"))
|
||||||
|
|
||||||
|
|
||||||
|
def get_crash_recovery_candidates(heartbeat_grace_seconds: int) -> list:
|
||||||
|
"""
|
||||||
|
Returns a list of dicts for active clients that are crashed (process_status=crashed)
|
||||||
|
or heartbeat-stale, and don't already have a recent recovery command in the lockout window.
|
||||||
|
"""
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
now = datetime.now(timezone.utc)
|
||||||
|
stale_cutoff = now - timedelta(seconds=heartbeat_grace_seconds)
|
||||||
|
lockout_cutoff = now - timedelta(minutes=_CRASH_RECOVERY_LOCKOUT_MINUTES)
|
||||||
|
|
||||||
|
candidates = (
|
||||||
|
session.query(Client)
|
||||||
|
.filter(Client.is_active == True)
|
||||||
|
.filter(
|
||||||
|
or_(
|
||||||
|
Client.process_status == ProcessStatus.crashed,
|
||||||
|
Client.last_alive < stale_cutoff,
|
||||||
|
)
|
||||||
|
)
|
||||||
|
.all()
|
||||||
|
)
|
||||||
|
|
||||||
|
result = []
|
||||||
|
for c in candidates:
|
||||||
|
recent = (
|
||||||
|
session.query(ClientCommand)
|
||||||
|
.filter(ClientCommand.client_uuid == c.uuid)
|
||||||
|
.filter(ClientCommand.created_at >= lockout_cutoff)
|
||||||
|
.filter(ClientCommand.action.in_(["reboot_host", "restart_app"]))
|
||||||
|
.first()
|
||||||
|
)
|
||||||
|
if recent:
|
||||||
|
continue
|
||||||
|
crash_reason = (
|
||||||
|
"process_crashed"
|
||||||
|
if c.process_status == ProcessStatus.crashed
|
||||||
|
else "heartbeat_stale"
|
||||||
|
)
|
||||||
|
result.append({
|
||||||
|
"uuid": c.uuid,
|
||||||
|
"reason": crash_reason,
|
||||||
|
"process_status": c.process_status.value if c.process_status else None,
|
||||||
|
"last_alive": c.last_alive,
|
||||||
|
})
|
||||||
|
return result
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
def issue_crash_recovery_command(client_uuid: str, reason: str) -> tuple:
|
||||||
|
"""
|
||||||
|
Writes a ClientCommand (reboot_host) for crash recovery to the DB.
|
||||||
|
Returns (command_id, payload_dict) for the caller to publish over MQTT.
|
||||||
|
Also returns the MQTT topic strings.
|
||||||
|
"""
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
now = datetime.now(timezone.utc)
|
||||||
|
expires_at = now + timedelta(seconds=_CRASH_RECOVERY_EXPIRY_SECONDS)
|
||||||
|
command_id = str(_uuid_mod.uuid4())
|
||||||
|
|
||||||
|
command = ClientCommand(
|
||||||
|
command_id=command_id,
|
||||||
|
client_uuid=client_uuid,
|
||||||
|
action="reboot_host",
|
||||||
|
status="queued",
|
||||||
|
reason=reason,
|
||||||
|
requested_by=None,
|
||||||
|
issued_at=now,
|
||||||
|
expires_at=expires_at,
|
||||||
|
)
|
||||||
|
session.add(command)
|
||||||
|
session.commit()
|
||||||
|
command.status = "publish_in_progress"
|
||||||
|
session.commit()
|
||||||
|
|
||||||
|
payload = {
|
||||||
|
"schema_version": _CRASH_RECOVERY_SCHEMA_VERSION,
|
||||||
|
"command_id": command_id,
|
||||||
|
"client_uuid": client_uuid,
|
||||||
|
"action": "reboot_host",
|
||||||
|
"issued_at": now.isoformat().replace("+00:00", "Z"),
|
||||||
|
"expires_at": expires_at.isoformat().replace("+00:00", "Z"),
|
||||||
|
"requested_by": None,
|
||||||
|
"reason": reason,
|
||||||
|
}
|
||||||
|
topic = _CRASH_COMMAND_TOPIC.format(uuid=client_uuid)
|
||||||
|
compat_topic = _CRASH_COMMAND_COMPAT_TOPIC.format(uuid=client_uuid)
|
||||||
|
return command_id, payload, topic, compat_topic
|
||||||
|
except Exception:
|
||||||
|
session.rollback()
|
||||||
|
raise
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
def finalize_crash_recovery_command(command_id: str, published: bool, error: str = None) -> None:
|
||||||
|
"""Updates command status after MQTT publish attempt."""
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
cmd = session.query(ClientCommand).filter_by(command_id=command_id).first()
|
||||||
|
if not cmd:
|
||||||
|
return
|
||||||
|
now = datetime.now(timezone.utc)
|
||||||
|
if published:
|
||||||
|
cmd.status = "published"
|
||||||
|
cmd.published_at = now
|
||||||
|
else:
|
||||||
|
cmd.status = "failed"
|
||||||
|
cmd.failed_at = now
|
||||||
|
cmd.error_code = "mqtt_publish_failed"
|
||||||
|
cmd.error_message = error or "Unknown publish error"
|
||||||
|
session.commit()
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
_TERMINAL_COMMAND_STATUSES = {"completed", "failed", "expired", "canceled", "blocked_safety"}
|
||||||
|
|
||||||
|
|
||||||
|
def sweep_expired_commands() -> int:
|
||||||
|
"""Marks non-terminal commands whose expires_at has passed as expired.
|
||||||
|
|
||||||
|
Returns the number of commands updated.
|
||||||
|
"""
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
now = datetime.now(timezone.utc)
|
||||||
|
commands = (
|
||||||
|
session.query(ClientCommand)
|
||||||
|
.filter(
|
||||||
|
ClientCommand.expires_at < now,
|
||||||
|
ClientCommand.status.notin_(_TERMINAL_COMMAND_STATUSES),
|
||||||
|
)
|
||||||
|
.all()
|
||||||
|
)
|
||||||
|
if not commands:
|
||||||
|
return 0
|
||||||
|
for cmd in commands:
|
||||||
|
cmd.status = "expired"
|
||||||
|
cmd.failed_at = now
|
||||||
|
cmd.error_code = "expired"
|
||||||
|
cmd.error_message = "Command expired before terminal state was reached."
|
||||||
|
session.commit()
|
||||||
|
return len(commands)
|
||||||
|
except Exception:
|
||||||
|
session.rollback()
|
||||||
|
raise
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|||||||
@@ -2,11 +2,216 @@
|
|||||||
|
|
||||||
import os
|
import os
|
||||||
import logging
|
import logging
|
||||||
from .db_utils import get_active_events, get_system_setting_value
|
from .db_utils import (
|
||||||
|
get_active_events,
|
||||||
|
get_system_setting_value,
|
||||||
|
compute_group_power_intent_basis,
|
||||||
|
build_group_power_intent_body,
|
||||||
|
compute_group_power_intent_fingerprint,
|
||||||
|
get_crash_recovery_candidates,
|
||||||
|
issue_crash_recovery_command,
|
||||||
|
finalize_crash_recovery_command,
|
||||||
|
sweep_expired_commands,
|
||||||
|
)
|
||||||
import paho.mqtt.client as mqtt
|
import paho.mqtt.client as mqtt
|
||||||
import json
|
import json
|
||||||
import datetime
|
import datetime
|
||||||
import time
|
import time
|
||||||
|
import uuid
|
||||||
|
import ssl
|
||||||
|
|
||||||
|
|
||||||
|
MQTT_BROKER_HOST = os.getenv("MQTT_BROKER_HOST", os.getenv("MQTT_BROKER_URL", "mqtt"))
|
||||||
|
MQTT_BROKER_PORT = int(os.getenv("MQTT_BROKER_PORT", os.getenv("MQTT_PORT", "1883")))
|
||||||
|
MQTT_USERNAME = os.getenv("MQTT_USER") or os.getenv("MQTT_USERNAME")
|
||||||
|
MQTT_PASSWORD = os.getenv("MQTT_PASSWORD")
|
||||||
|
MQTT_TLS_ENABLED = os.getenv("MQTT_TLS_ENABLED", "false").strip().lower() in ("1", "true", "yes", "on")
|
||||||
|
MQTT_TLS_CA_CERT = os.getenv("MQTT_TLS_CA_CERT")
|
||||||
|
MQTT_TLS_CERTFILE = os.getenv("MQTT_TLS_CERTFILE")
|
||||||
|
MQTT_TLS_KEYFILE = os.getenv("MQTT_TLS_KEYFILE")
|
||||||
|
MQTT_TLS_INSECURE = os.getenv("MQTT_TLS_INSECURE", "false").strip().lower() in ("1", "true", "yes", "on")
|
||||||
|
|
||||||
|
|
||||||
|
def _to_utc_z(dt: datetime.datetime) -> str:
|
||||||
|
if dt.tzinfo is None:
|
||||||
|
dt = dt.replace(tzinfo=datetime.timezone.utc)
|
||||||
|
else:
|
||||||
|
dt = dt.astimezone(datetime.timezone.utc)
|
||||||
|
return dt.isoformat().replace("+00:00", "Z")
|
||||||
|
|
||||||
|
|
||||||
|
def _republish_cached_power_intents(client, last_power_intents, power_intent_metrics):
|
||||||
|
if not last_power_intents:
|
||||||
|
return
|
||||||
|
|
||||||
|
logging.info(
|
||||||
|
"MQTT reconnect power-intent republish count=%s",
|
||||||
|
len(last_power_intents),
|
||||||
|
)
|
||||||
|
for gid, cached in last_power_intents.items():
|
||||||
|
topic = f"infoscreen/groups/{gid}/power/intent"
|
||||||
|
client.publish(topic, cached["payload"], qos=1, retain=True)
|
||||||
|
power_intent_metrics["retained_republish_total"] += 1
|
||||||
|
|
||||||
|
|
||||||
|
def _publish_group_power_intents(
|
||||||
|
client,
|
||||||
|
events,
|
||||||
|
now,
|
||||||
|
poll_interval,
|
||||||
|
heartbeat_enabled,
|
||||||
|
expiry_multiplier,
|
||||||
|
min_expiry_seconds,
|
||||||
|
last_power_intents,
|
||||||
|
power_intent_metrics,
|
||||||
|
):
|
||||||
|
expiry_seconds = max(
|
||||||
|
expiry_multiplier * poll_interval,
|
||||||
|
min_expiry_seconds,
|
||||||
|
)
|
||||||
|
|
||||||
|
candidate_group_ids = set()
|
||||||
|
for event in events:
|
||||||
|
group_id = event.get("group_id")
|
||||||
|
if group_id is None:
|
||||||
|
continue
|
||||||
|
try:
|
||||||
|
candidate_group_ids.add(int(group_id))
|
||||||
|
except (TypeError, ValueError):
|
||||||
|
continue
|
||||||
|
candidate_group_ids.update(last_power_intents.keys())
|
||||||
|
|
||||||
|
for gid in sorted(candidate_group_ids):
|
||||||
|
# Guard: validate group_id is a valid positive integer
|
||||||
|
if not isinstance(gid, int) or gid <= 0:
|
||||||
|
logging.error(
|
||||||
|
"event=power_intent_publish_error reason=invalid_group_id group_id=%s",
|
||||||
|
gid,
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
intent_basis = compute_group_power_intent_basis(
|
||||||
|
events=events,
|
||||||
|
group_id=gid,
|
||||||
|
now_utc=now,
|
||||||
|
adjacency_seconds=0,
|
||||||
|
)
|
||||||
|
intent_body = build_group_power_intent_body(
|
||||||
|
intent_basis=intent_basis,
|
||||||
|
poll_interval_sec=poll_interval,
|
||||||
|
)
|
||||||
|
fingerprint = compute_group_power_intent_fingerprint(intent_body)
|
||||||
|
previous = last_power_intents.get(gid)
|
||||||
|
is_transition_publish = previous is None or previous["fingerprint"] != fingerprint
|
||||||
|
is_heartbeat_publish = bool(heartbeat_enabled and not is_transition_publish)
|
||||||
|
|
||||||
|
if not is_transition_publish and not is_heartbeat_publish:
|
||||||
|
continue
|
||||||
|
|
||||||
|
intent_id = previous["intent_id"] if previous and not is_transition_publish else str(uuid.uuid4())
|
||||||
|
|
||||||
|
# Guard: validate intent_id is not empty
|
||||||
|
if not intent_id or not isinstance(intent_id, str) or len(intent_id.strip()) == 0:
|
||||||
|
logging.error(
|
||||||
|
"event=power_intent_publish_error group_id=%s reason=invalid_intent_id",
|
||||||
|
gid,
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
issued_at = now
|
||||||
|
expires_at = issued_at + datetime.timedelta(seconds=expiry_seconds)
|
||||||
|
|
||||||
|
# Guard: validate expiry window is positive and issued_at has valid timezone
|
||||||
|
if expires_at <= issued_at:
|
||||||
|
logging.error(
|
||||||
|
"event=power_intent_publish_error group_id=%s reason=invalid_expiry issued_at=%s expires_at=%s",
|
||||||
|
gid,
|
||||||
|
_to_utc_z(issued_at),
|
||||||
|
_to_utc_z(expires_at),
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
issued_at_str = _to_utc_z(issued_at)
|
||||||
|
expires_at_str = _to_utc_z(expires_at)
|
||||||
|
|
||||||
|
# Guard: ensure Z suffix on timestamps (format validation)
|
||||||
|
if not issued_at_str.endswith("Z") or not expires_at_str.endswith("Z"):
|
||||||
|
logging.error(
|
||||||
|
"event=power_intent_publish_error group_id=%s reason=invalid_timestamp_format issued_at=%s expires_at=%s",
|
||||||
|
gid,
|
||||||
|
issued_at_str,
|
||||||
|
expires_at_str,
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
payload_dict = {
|
||||||
|
**intent_body,
|
||||||
|
"intent_id": intent_id,
|
||||||
|
"issued_at": issued_at_str,
|
||||||
|
"expires_at": expires_at_str,
|
||||||
|
}
|
||||||
|
|
||||||
|
# Guard: ensure payload serialization succeeds before publishing
|
||||||
|
try:
|
||||||
|
payload = json.dumps(payload_dict, sort_keys=True, separators=(",", ":"))
|
||||||
|
except (TypeError, ValueError) as e:
|
||||||
|
logging.error(
|
||||||
|
"event=power_intent_publish_error group_id=%s reason=payload_serialization_error error=%s",
|
||||||
|
gid,
|
||||||
|
str(e),
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
topic = f"infoscreen/groups/{gid}/power/intent"
|
||||||
|
|
||||||
|
result = client.publish(topic, payload, qos=1, retain=True)
|
||||||
|
result.wait_for_publish(timeout=5.0)
|
||||||
|
if result.rc != mqtt.MQTT_ERR_SUCCESS:
|
||||||
|
power_intent_metrics["publish_error_total"] += 1
|
||||||
|
logging.error(
|
||||||
|
"event=power_intent_publish_error group_id=%s desired_state=%s intent_id=%s "
|
||||||
|
"transition_publish=%s heartbeat_publish=%s topic=%s qos=1 retained=true rc=%s",
|
||||||
|
gid,
|
||||||
|
payload_dict.get("desired_state"),
|
||||||
|
intent_id,
|
||||||
|
is_transition_publish,
|
||||||
|
is_heartbeat_publish,
|
||||||
|
topic,
|
||||||
|
result.rc,
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
|
last_power_intents[gid] = {
|
||||||
|
"fingerprint": fingerprint,
|
||||||
|
"intent_id": intent_id,
|
||||||
|
"payload": payload,
|
||||||
|
}
|
||||||
|
if is_transition_publish:
|
||||||
|
power_intent_metrics["intent_transitions_total"] += 1
|
||||||
|
if is_heartbeat_publish:
|
||||||
|
power_intent_metrics["heartbeat_republish_total"] += 1
|
||||||
|
power_intent_metrics["publish_success_total"] += 1
|
||||||
|
logging.info(
|
||||||
|
"event=power_intent_publish group_id=%s desired_state=%s reason=%s intent_id=%s "
|
||||||
|
"issued_at=%s expires_at=%s transition_publish=%s heartbeat_publish=%s "
|
||||||
|
"topic=%s qos=1 retained=true",
|
||||||
|
gid,
|
||||||
|
payload_dict.get("desired_state"),
|
||||||
|
payload_dict.get("reason"),
|
||||||
|
intent_id,
|
||||||
|
issued_at_str,
|
||||||
|
expires_at_str,
|
||||||
|
is_transition_publish,
|
||||||
|
is_heartbeat_publish,
|
||||||
|
topic,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _env_bool(name: str, default: bool) -> bool:
|
||||||
|
value = os.getenv(name)
|
||||||
|
if value is None:
|
||||||
|
return default
|
||||||
|
return value.strip().lower() in ("1", "true", "yes", "on")
|
||||||
|
|
||||||
# Logging-Konfiguration
|
# Logging-Konfiguration
|
||||||
from logging.handlers import RotatingFileHandler
|
from logging.handlers import RotatingFileHandler
|
||||||
@@ -35,7 +240,20 @@ def main():
|
|||||||
client = mqtt.Client(callback_api_version=mqtt.CallbackAPIVersion.VERSION2)
|
client = mqtt.Client(callback_api_version=mqtt.CallbackAPIVersion.VERSION2)
|
||||||
client.reconnect_delay_set(min_delay=1, max_delay=30)
|
client.reconnect_delay_set(min_delay=1, max_delay=30)
|
||||||
|
|
||||||
POLL_INTERVAL = 30 # Sekunden, Empfehlung für seltene Änderungen
|
if MQTT_USERNAME and MQTT_PASSWORD:
|
||||||
|
client.username_pw_set(MQTT_USERNAME, MQTT_PASSWORD)
|
||||||
|
|
||||||
|
if MQTT_TLS_ENABLED:
|
||||||
|
client.tls_set(
|
||||||
|
ca_certs=MQTT_TLS_CA_CERT,
|
||||||
|
certfile=MQTT_TLS_CERTFILE,
|
||||||
|
keyfile=MQTT_TLS_KEYFILE,
|
||||||
|
cert_reqs=ssl.CERT_REQUIRED,
|
||||||
|
)
|
||||||
|
if MQTT_TLS_INSECURE:
|
||||||
|
client.tls_insecure_set(True)
|
||||||
|
|
||||||
|
POLL_INTERVAL = int(os.getenv("POLL_INTERVAL_SECONDS", "30"))
|
||||||
# 0 = aus; z.B. 600 für alle 10 Min
|
# 0 = aus; z.B. 600 für alle 10 Min
|
||||||
# initial value from DB or fallback to env
|
# initial value from DB or fallback to env
|
||||||
try:
|
try:
|
||||||
@@ -43,10 +261,40 @@ def main():
|
|||||||
REFRESH_SECONDS = int(db_val) if db_val is not None else int(os.getenv("REFRESH_SECONDS", "0"))
|
REFRESH_SECONDS = int(db_val) if db_val is not None else int(os.getenv("REFRESH_SECONDS", "0"))
|
||||||
except Exception:
|
except Exception:
|
||||||
REFRESH_SECONDS = int(os.getenv("REFRESH_SECONDS", "0"))
|
REFRESH_SECONDS = int(os.getenv("REFRESH_SECONDS", "0"))
|
||||||
|
|
||||||
|
# TV power intent (PR-1): group-level publishing is feature-flagged and disabled by default.
|
||||||
|
POWER_INTENT_PUBLISH_ENABLED = _env_bool("POWER_INTENT_PUBLISH_ENABLED", False)
|
||||||
|
POWER_INTENT_HEARTBEAT_ENABLED = _env_bool("POWER_INTENT_HEARTBEAT_ENABLED", True)
|
||||||
|
POWER_INTENT_EXPIRY_MULTIPLIER = int(os.getenv("POWER_INTENT_EXPIRY_MULTIPLIER", "3"))
|
||||||
|
POWER_INTENT_MIN_EXPIRY_SECONDS = int(os.getenv("POWER_INTENT_MIN_EXPIRY_SECONDS", "90"))
|
||||||
|
CRASH_RECOVERY_ENABLED = _env_bool("CRASH_RECOVERY_ENABLED", False)
|
||||||
|
CRASH_RECOVERY_GRACE_SECONDS = int(os.getenv("CRASH_RECOVERY_GRACE_SECONDS", "180"))
|
||||||
|
|
||||||
|
logging.info(
|
||||||
|
"Scheduler config: poll_interval=%ss refresh_seconds=%s power_intent_enabled=%s "
|
||||||
|
"power_intent_heartbeat=%s power_intent_expiry_multiplier=%s power_intent_min_expiry=%ss "
|
||||||
|
"crash_recovery_enabled=%s crash_recovery_grace=%ss",
|
||||||
|
POLL_INTERVAL,
|
||||||
|
REFRESH_SECONDS,
|
||||||
|
POWER_INTENT_PUBLISH_ENABLED,
|
||||||
|
POWER_INTENT_HEARTBEAT_ENABLED,
|
||||||
|
POWER_INTENT_EXPIRY_MULTIPLIER,
|
||||||
|
POWER_INTENT_MIN_EXPIRY_SECONDS,
|
||||||
|
CRASH_RECOVERY_ENABLED,
|
||||||
|
CRASH_RECOVERY_GRACE_SECONDS,
|
||||||
|
)
|
||||||
# Konfigurierbares Zeitfenster in Tagen (Standard: 7)
|
# Konfigurierbares Zeitfenster in Tagen (Standard: 7)
|
||||||
WINDOW_DAYS = int(os.getenv("EVENTS_WINDOW_DAYS", "7"))
|
WINDOW_DAYS = int(os.getenv("EVENTS_WINDOW_DAYS", "7"))
|
||||||
last_payloads = {} # group_id -> payload
|
last_payloads = {} # group_id -> payload
|
||||||
last_published_at = {} # group_id -> epoch seconds
|
last_published_at = {} # group_id -> epoch seconds
|
||||||
|
last_power_intents = {} # group_id -> {fingerprint, intent_id, payload}
|
||||||
|
power_intent_metrics = {
|
||||||
|
"intent_transitions_total": 0,
|
||||||
|
"publish_success_total": 0,
|
||||||
|
"publish_error_total": 0,
|
||||||
|
"heartbeat_republish_total": 0,
|
||||||
|
"retained_republish_total": 0,
|
||||||
|
}
|
||||||
|
|
||||||
# Beim (Re-)Connect alle bekannten retained Payloads erneut senden
|
# Beim (Re-)Connect alle bekannten retained Payloads erneut senden
|
||||||
def on_connect(client, userdata, flags, reasonCode, properties=None):
|
def on_connect(client, userdata, flags, reasonCode, properties=None):
|
||||||
@@ -56,10 +304,20 @@ def main():
|
|||||||
topic = f"infoscreen/events/{gid}"
|
topic = f"infoscreen/events/{gid}"
|
||||||
client.publish(topic, payload, retain=True)
|
client.publish(topic, payload, retain=True)
|
||||||
|
|
||||||
|
if POWER_INTENT_PUBLISH_ENABLED:
|
||||||
|
_republish_cached_power_intents(client, last_power_intents, power_intent_metrics)
|
||||||
|
|
||||||
client.on_connect = on_connect
|
client.on_connect = on_connect
|
||||||
|
|
||||||
client.connect("mqtt", 1883)
|
client.connect(MQTT_BROKER_HOST, MQTT_BROKER_PORT)
|
||||||
client.loop_start()
|
client.loop_start()
|
||||||
|
logging.info(
|
||||||
|
"MQTT connection configured host=%s port=%s tls=%s auth=%s",
|
||||||
|
MQTT_BROKER_HOST,
|
||||||
|
MQTT_BROKER_PORT,
|
||||||
|
MQTT_TLS_ENABLED,
|
||||||
|
bool(MQTT_USERNAME and MQTT_PASSWORD),
|
||||||
|
)
|
||||||
|
|
||||||
while True:
|
while True:
|
||||||
now = datetime.datetime.now(datetime.timezone.utc)
|
now = datetime.datetime.now(datetime.timezone.utc)
|
||||||
@@ -150,6 +408,74 @@ def main():
|
|||||||
del last_payloads[gid]
|
del last_payloads[gid]
|
||||||
last_published_at.pop(gid, None)
|
last_published_at.pop(gid, None)
|
||||||
|
|
||||||
|
if POWER_INTENT_PUBLISH_ENABLED:
|
||||||
|
_publish_group_power_intents(
|
||||||
|
client=client,
|
||||||
|
events=events,
|
||||||
|
now=now,
|
||||||
|
poll_interval=POLL_INTERVAL,
|
||||||
|
heartbeat_enabled=POWER_INTENT_HEARTBEAT_ENABLED,
|
||||||
|
expiry_multiplier=POWER_INTENT_EXPIRY_MULTIPLIER,
|
||||||
|
min_expiry_seconds=POWER_INTENT_MIN_EXPIRY_SECONDS,
|
||||||
|
last_power_intents=last_power_intents,
|
||||||
|
power_intent_metrics=power_intent_metrics,
|
||||||
|
)
|
||||||
|
|
||||||
|
logging.debug(
|
||||||
|
"event=power_intent_metrics intent_transitions_total=%s publish_success_total=%s "
|
||||||
|
"publish_error_total=%s heartbeat_republish_total=%s retained_republish_total=%s",
|
||||||
|
power_intent_metrics["intent_transitions_total"],
|
||||||
|
power_intent_metrics["publish_success_total"],
|
||||||
|
power_intent_metrics["publish_error_total"],
|
||||||
|
power_intent_metrics["heartbeat_republish_total"],
|
||||||
|
power_intent_metrics["retained_republish_total"],
|
||||||
|
)
|
||||||
|
|
||||||
|
if CRASH_RECOVERY_ENABLED:
|
||||||
|
try:
|
||||||
|
candidates = get_crash_recovery_candidates(CRASH_RECOVERY_GRACE_SECONDS)
|
||||||
|
if candidates:
|
||||||
|
logging.info("event=crash_recovery_scan candidates=%s", len(candidates))
|
||||||
|
for candidate in candidates:
|
||||||
|
cuuid = candidate["uuid"]
|
||||||
|
reason = candidate["reason"]
|
||||||
|
try:
|
||||||
|
command_id, payload, topic, compat_topic = issue_crash_recovery_command(
|
||||||
|
client_uuid=cuuid,
|
||||||
|
reason=reason,
|
||||||
|
)
|
||||||
|
result = client.publish(topic, json.dumps(payload), qos=1, retain=False)
|
||||||
|
result.wait_for_publish(timeout=5.0)
|
||||||
|
compat_result = client.publish(compat_topic, json.dumps(payload), qos=1, retain=False)
|
||||||
|
compat_result.wait_for_publish(timeout=5.0)
|
||||||
|
success = result.rc == mqtt.MQTT_ERR_SUCCESS
|
||||||
|
error = None if success else mqtt.error_string(result.rc)
|
||||||
|
finalize_crash_recovery_command(command_id, published=success, error=error)
|
||||||
|
if success:
|
||||||
|
logging.info(
|
||||||
|
"event=crash_recovery_command_issued client_uuid=%s reason=%s command_id=%s",
|
||||||
|
cuuid, reason, command_id,
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
logging.error(
|
||||||
|
"event=crash_recovery_publish_failed client_uuid=%s reason=%s command_id=%s error=%s",
|
||||||
|
cuuid, reason, command_id, error,
|
||||||
|
)
|
||||||
|
except Exception as cmd_exc:
|
||||||
|
logging.error(
|
||||||
|
"event=crash_recovery_command_error client_uuid=%s reason=%s error=%s",
|
||||||
|
cuuid, reason, cmd_exc,
|
||||||
|
)
|
||||||
|
except Exception as scan_exc:
|
||||||
|
logging.error("event=crash_recovery_scan_error error=%s", scan_exc)
|
||||||
|
|
||||||
|
try:
|
||||||
|
expired_count = sweep_expired_commands()
|
||||||
|
if expired_count:
|
||||||
|
logging.info("event=command_expiry_sweep expired=%s", expired_count)
|
||||||
|
except Exception as sweep_exc:
|
||||||
|
logging.error("event=command_expiry_sweep_error error=%s", sweep_exc)
|
||||||
|
|
||||||
time.sleep(POLL_INTERVAL)
|
time.sleep(POLL_INTERVAL)
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
191
scheduler/test_power_intent_scheduler.py
Normal file
191
scheduler/test_power_intent_scheduler.py
Normal file
@@ -0,0 +1,191 @@
|
|||||||
|
import json
|
||||||
|
import unittest
|
||||||
|
from datetime import datetime, timedelta, timezone
|
||||||
|
|
||||||
|
from scheduler.scheduler import (
|
||||||
|
_publish_group_power_intents,
|
||||||
|
_republish_cached_power_intents,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class _FakePublishResult:
|
||||||
|
def __init__(self, rc=0):
|
||||||
|
self.rc = rc
|
||||||
|
self.wait_timeout = None
|
||||||
|
|
||||||
|
def wait_for_publish(self, timeout=None):
|
||||||
|
self.wait_timeout = timeout
|
||||||
|
|
||||||
|
|
||||||
|
class _FakeMqttClient:
|
||||||
|
def __init__(self, rc=0):
|
||||||
|
self.rc = rc
|
||||||
|
self.calls = []
|
||||||
|
|
||||||
|
def publish(self, topic, payload, qos=0, retain=False):
|
||||||
|
result = _FakePublishResult(rc=self.rc)
|
||||||
|
self.calls.append(
|
||||||
|
{
|
||||||
|
"topic": topic,
|
||||||
|
"payload": payload,
|
||||||
|
"qos": qos,
|
||||||
|
"retain": retain,
|
||||||
|
"result": result,
|
||||||
|
}
|
||||||
|
)
|
||||||
|
return result
|
||||||
|
|
||||||
|
|
||||||
|
class PowerIntentSchedulerTests(unittest.TestCase):
|
||||||
|
def test_transition_then_heartbeat_reuses_intent_id(self):
|
||||||
|
client = _FakeMqttClient(rc=0)
|
||||||
|
last_power_intents = {}
|
||||||
|
metrics = {
|
||||||
|
"intent_transitions_total": 0,
|
||||||
|
"publish_success_total": 0,
|
||||||
|
"publish_error_total": 0,
|
||||||
|
"heartbeat_republish_total": 0,
|
||||||
|
"retained_republish_total": 0,
|
||||||
|
}
|
||||||
|
|
||||||
|
events = [
|
||||||
|
{
|
||||||
|
"id": 101,
|
||||||
|
"group_id": 12,
|
||||||
|
"start": "2026-03-31T10:00:00+00:00",
|
||||||
|
"end": "2026-03-31T10:30:00+00:00",
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
now_first = datetime(2026, 3, 31, 10, 5, 0, tzinfo=timezone.utc)
|
||||||
|
_publish_group_power_intents(
|
||||||
|
client=client,
|
||||||
|
events=events,
|
||||||
|
now=now_first,
|
||||||
|
poll_interval=15,
|
||||||
|
heartbeat_enabled=True,
|
||||||
|
expiry_multiplier=3,
|
||||||
|
min_expiry_seconds=90,
|
||||||
|
last_power_intents=last_power_intents,
|
||||||
|
power_intent_metrics=metrics,
|
||||||
|
)
|
||||||
|
|
||||||
|
first_payload = json.loads(client.calls[0]["payload"])
|
||||||
|
first_intent_id = first_payload["intent_id"]
|
||||||
|
|
||||||
|
now_second = now_first + timedelta(seconds=15)
|
||||||
|
_publish_group_power_intents(
|
||||||
|
client=client,
|
||||||
|
events=events,
|
||||||
|
now=now_second,
|
||||||
|
poll_interval=15,
|
||||||
|
heartbeat_enabled=True,
|
||||||
|
expiry_multiplier=3,
|
||||||
|
min_expiry_seconds=90,
|
||||||
|
last_power_intents=last_power_intents,
|
||||||
|
power_intent_metrics=metrics,
|
||||||
|
)
|
||||||
|
|
||||||
|
self.assertEqual(len(client.calls), 2)
|
||||||
|
second_payload = json.loads(client.calls[1]["payload"])
|
||||||
|
|
||||||
|
self.assertEqual(first_payload["desired_state"], "on")
|
||||||
|
self.assertEqual(second_payload["desired_state"], "on")
|
||||||
|
self.assertEqual(first_intent_id, second_payload["intent_id"])
|
||||||
|
self.assertEqual(client.calls[0]["topic"], "infoscreen/groups/12/power/intent")
|
||||||
|
self.assertEqual(client.calls[0]["qos"], 1)
|
||||||
|
self.assertTrue(client.calls[0]["retain"])
|
||||||
|
|
||||||
|
self.assertEqual(metrics["intent_transitions_total"], 1)
|
||||||
|
self.assertEqual(metrics["heartbeat_republish_total"], 1)
|
||||||
|
self.assertEqual(metrics["publish_success_total"], 2)
|
||||||
|
self.assertEqual(metrics["publish_error_total"], 0)
|
||||||
|
|
||||||
|
def test_state_change_creates_new_intent_id(self):
|
||||||
|
client = _FakeMqttClient(rc=0)
|
||||||
|
last_power_intents = {}
|
||||||
|
metrics = {
|
||||||
|
"intent_transitions_total": 0,
|
||||||
|
"publish_success_total": 0,
|
||||||
|
"publish_error_total": 0,
|
||||||
|
"heartbeat_republish_total": 0,
|
||||||
|
"retained_republish_total": 0,
|
||||||
|
}
|
||||||
|
|
||||||
|
events_on = [
|
||||||
|
{
|
||||||
|
"id": 88,
|
||||||
|
"group_id": 3,
|
||||||
|
"start": "2026-03-31T10:00:00+00:00",
|
||||||
|
"end": "2026-03-31T10:30:00+00:00",
|
||||||
|
}
|
||||||
|
]
|
||||||
|
now_on = datetime(2026, 3, 31, 10, 5, 0, tzinfo=timezone.utc)
|
||||||
|
_publish_group_power_intents(
|
||||||
|
client=client,
|
||||||
|
events=events_on,
|
||||||
|
now=now_on,
|
||||||
|
poll_interval=15,
|
||||||
|
heartbeat_enabled=True,
|
||||||
|
expiry_multiplier=3,
|
||||||
|
min_expiry_seconds=90,
|
||||||
|
last_power_intents=last_power_intents,
|
||||||
|
power_intent_metrics=metrics,
|
||||||
|
)
|
||||||
|
|
||||||
|
first_payload = json.loads(client.calls[0]["payload"])
|
||||||
|
|
||||||
|
events_off = [
|
||||||
|
{
|
||||||
|
"id": 88,
|
||||||
|
"group_id": 3,
|
||||||
|
"start": "2026-03-31T10:00:00+00:00",
|
||||||
|
"end": "2026-03-31T10:30:00+00:00",
|
||||||
|
}
|
||||||
|
]
|
||||||
|
now_off = datetime(2026, 3, 31, 10, 35, 0, tzinfo=timezone.utc)
|
||||||
|
_publish_group_power_intents(
|
||||||
|
client=client,
|
||||||
|
events=events_off,
|
||||||
|
now=now_off,
|
||||||
|
poll_interval=15,
|
||||||
|
heartbeat_enabled=True,
|
||||||
|
expiry_multiplier=3,
|
||||||
|
min_expiry_seconds=90,
|
||||||
|
last_power_intents=last_power_intents,
|
||||||
|
power_intent_metrics=metrics,
|
||||||
|
)
|
||||||
|
|
||||||
|
second_payload = json.loads(client.calls[1]["payload"])
|
||||||
|
self.assertNotEqual(first_payload["intent_id"], second_payload["intent_id"])
|
||||||
|
self.assertEqual(second_payload["desired_state"], "off")
|
||||||
|
self.assertEqual(metrics["intent_transitions_total"], 2)
|
||||||
|
|
||||||
|
def test_republish_cached_power_intents(self):
|
||||||
|
client = _FakeMqttClient(rc=0)
|
||||||
|
metrics = {
|
||||||
|
"intent_transitions_total": 0,
|
||||||
|
"publish_success_total": 0,
|
||||||
|
"publish_error_total": 0,
|
||||||
|
"heartbeat_republish_total": 0,
|
||||||
|
"retained_republish_total": 0,
|
||||||
|
}
|
||||||
|
cache = {
|
||||||
|
5: {
|
||||||
|
"fingerprint": "abc",
|
||||||
|
"intent_id": "intent-1",
|
||||||
|
"payload": '{"group_id":5,"desired_state":"on"}',
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
_republish_cached_power_intents(client, cache, metrics)
|
||||||
|
|
||||||
|
self.assertEqual(len(client.calls), 1)
|
||||||
|
self.assertEqual(client.calls[0]["topic"], "infoscreen/groups/5/power/intent")
|
||||||
|
self.assertEqual(client.calls[0]["qos"], 1)
|
||||||
|
self.assertTrue(client.calls[0]["retain"])
|
||||||
|
self.assertEqual(metrics["retained_republish_total"], 1)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
unittest.main()
|
||||||
106
scheduler/test_power_intent_utils.py
Normal file
106
scheduler/test_power_intent_utils.py
Normal file
@@ -0,0 +1,106 @@
|
|||||||
|
import unittest
|
||||||
|
from datetime import datetime, timezone
|
||||||
|
|
||||||
|
from scheduler.db_utils import (
|
||||||
|
build_group_power_intent_body,
|
||||||
|
compute_group_power_intent_basis,
|
||||||
|
compute_group_power_intent_fingerprint,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class PowerIntentUtilsTests(unittest.TestCase):
|
||||||
|
def test_no_events_results_in_off(self):
|
||||||
|
now = datetime(2026, 3, 31, 10, 0, 0, tzinfo=timezone.utc)
|
||||||
|
basis = compute_group_power_intent_basis(events=[], group_id=7, now_utc=now)
|
||||||
|
|
||||||
|
self.assertEqual(basis["group_id"], 7)
|
||||||
|
self.assertEqual(basis["desired_state"], "off")
|
||||||
|
self.assertEqual(basis["reason"], "no_active_event")
|
||||||
|
self.assertIsNone(basis["event_window_start"])
|
||||||
|
self.assertIsNone(basis["event_window_end"])
|
||||||
|
|
||||||
|
def test_active_event_results_in_on(self):
|
||||||
|
now = datetime(2026, 3, 31, 10, 5, 0, tzinfo=timezone.utc)
|
||||||
|
events = [
|
||||||
|
{
|
||||||
|
"id": 101,
|
||||||
|
"group_id": 2,
|
||||||
|
"start": "2026-03-31T10:00:00+00:00",
|
||||||
|
"end": "2026-03-31T10:30:00+00:00",
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
basis = compute_group_power_intent_basis(events=events, group_id=2, now_utc=now)
|
||||||
|
|
||||||
|
self.assertEqual(basis["desired_state"], "on")
|
||||||
|
self.assertEqual(basis["reason"], "active_event")
|
||||||
|
self.assertEqual(basis["event_window_start"], "2026-03-31T10:00:00Z")
|
||||||
|
self.assertEqual(basis["event_window_end"], "2026-03-31T10:30:00Z")
|
||||||
|
self.assertEqual(basis["active_event_ids"], [101])
|
||||||
|
|
||||||
|
def test_adjacent_events_are_merged_without_off_blip(self):
|
||||||
|
now = datetime(2026, 3, 31, 10, 30, 0, tzinfo=timezone.utc)
|
||||||
|
events = [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"group_id": 3,
|
||||||
|
"start": "2026-03-31T10:00:00+00:00",
|
||||||
|
"end": "2026-03-31T10:30:00+00:00",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"group_id": 3,
|
||||||
|
"start": "2026-03-31T10:30:00+00:00",
|
||||||
|
"end": "2026-03-31T11:00:00+00:00",
|
||||||
|
},
|
||||||
|
]
|
||||||
|
|
||||||
|
basis = compute_group_power_intent_basis(events=events, group_id=3, now_utc=now)
|
||||||
|
|
||||||
|
self.assertEqual(basis["desired_state"], "on")
|
||||||
|
self.assertEqual(basis["event_window_start"], "2026-03-31T10:00:00Z")
|
||||||
|
self.assertEqual(basis["event_window_end"], "2026-03-31T11:00:00Z")
|
||||||
|
|
||||||
|
def test_true_gap_results_in_off(self):
|
||||||
|
now = datetime(2026, 3, 31, 10, 31, 0, tzinfo=timezone.utc)
|
||||||
|
events = [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"group_id": 4,
|
||||||
|
"start": "2026-03-31T10:00:00+00:00",
|
||||||
|
"end": "2026-03-31T10:30:00+00:00",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"group_id": 4,
|
||||||
|
"start": "2026-03-31T10:35:00+00:00",
|
||||||
|
"end": "2026-03-31T11:00:00+00:00",
|
||||||
|
},
|
||||||
|
]
|
||||||
|
|
||||||
|
basis = compute_group_power_intent_basis(events=events, group_id=4, now_utc=now)
|
||||||
|
|
||||||
|
self.assertEqual(basis["desired_state"], "off")
|
||||||
|
self.assertEqual(basis["reason"], "no_active_event")
|
||||||
|
|
||||||
|
def test_fingerprint_is_stable_for_same_semantics(self):
|
||||||
|
basis = {
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"group_id": 9,
|
||||||
|
"desired_state": "on",
|
||||||
|
"reason": "active_event",
|
||||||
|
"event_window_start": "2026-03-31T10:00:00Z",
|
||||||
|
"event_window_end": "2026-03-31T10:30:00Z",
|
||||||
|
"active_event_ids": [12, 7],
|
||||||
|
}
|
||||||
|
body_a = build_group_power_intent_body(basis, poll_interval_sec=15)
|
||||||
|
body_b = build_group_power_intent_body(basis, poll_interval_sec=15)
|
||||||
|
|
||||||
|
fingerprint_a = compute_group_power_intent_fingerprint(body_a)
|
||||||
|
fingerprint_b = compute_group_power_intent_fingerprint(body_b)
|
||||||
|
|
||||||
|
self.assertEqual(fingerprint_a, fingerprint_b)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
unittest.main()
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
"""Add archive lifecycle fields to academic_periods
|
||||||
|
|
||||||
|
Revision ID: a7b8c9d0e1f2
|
||||||
|
Revises: 910951fd300a
|
||||||
|
Create Date: 2026-03-31 00:00:00.000000
|
||||||
|
|
||||||
|
"""
|
||||||
|
from typing import Sequence, Union
|
||||||
|
|
||||||
|
from alembic import op
|
||||||
|
import sqlalchemy as sa
|
||||||
|
|
||||||
|
|
||||||
|
# revision identifiers, used by Alembic.
|
||||||
|
revision: str = 'a7b8c9d0e1f2'
|
||||||
|
down_revision: Union[str, None] = '910951fd300a'
|
||||||
|
branch_labels: Union[str, Sequence[str], None] = None
|
||||||
|
depends_on: Union[str, Sequence[str], None] = None
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
"""Upgrade schema."""
|
||||||
|
# Add archive lifecycle fields to academic_periods table
|
||||||
|
op.add_column('academic_periods', sa.Column('is_archived', sa.Boolean(), nullable=False, server_default='0'))
|
||||||
|
op.add_column('academic_periods', sa.Column('archived_at', sa.TIMESTAMP(timezone=True), nullable=True))
|
||||||
|
op.add_column('academic_periods', sa.Column('archived_by', sa.Integer(), nullable=True))
|
||||||
|
|
||||||
|
# Add foreign key for archived_by
|
||||||
|
op.create_foreign_key(
|
||||||
|
'fk_academic_periods_archived_by_users_id',
|
||||||
|
'academic_periods',
|
||||||
|
'users',
|
||||||
|
['archived_by'],
|
||||||
|
['id'],
|
||||||
|
ondelete='SET NULL'
|
||||||
|
)
|
||||||
|
|
||||||
|
# Add indexes for performance
|
||||||
|
op.create_index('ix_academic_periods_archived', 'academic_periods', ['is_archived'])
|
||||||
|
op.create_index('ix_academic_periods_name_not_archived', 'academic_periods', ['name', 'is_archived'])
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
"""Downgrade schema."""
|
||||||
|
# Drop indexes
|
||||||
|
op.drop_index('ix_academic_periods_name_not_archived', 'academic_periods')
|
||||||
|
op.drop_index('ix_academic_periods_archived', 'academic_periods')
|
||||||
|
|
||||||
|
# Drop foreign key
|
||||||
|
op.drop_constraint('fk_academic_periods_archived_by_users_id', 'academic_periods')
|
||||||
|
|
||||||
|
# Drop columns
|
||||||
|
op.drop_column('academic_periods', 'archived_by')
|
||||||
|
op.drop_column('academic_periods', 'archived_at')
|
||||||
|
op.drop_column('academic_periods', 'is_archived')
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
"""add client commands table
|
||||||
|
|
||||||
|
Revision ID: aa12bb34cc56
|
||||||
|
Revises: f3c4d5e6a7b8
|
||||||
|
Create Date: 2026-04-03 12:40:00.000000
|
||||||
|
|
||||||
|
"""
|
||||||
|
from typing import Sequence, Union
|
||||||
|
|
||||||
|
from alembic import op
|
||||||
|
import sqlalchemy as sa
|
||||||
|
|
||||||
|
|
||||||
|
# revision identifiers, used by Alembic.
|
||||||
|
revision: str = 'aa12bb34cc56'
|
||||||
|
down_revision: Union[str, None] = 'f3c4d5e6a7b8'
|
||||||
|
branch_labels: Union[str, Sequence[str], None] = None
|
||||||
|
depends_on: Union[str, Sequence[str], None] = None
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
op.create_table(
|
||||||
|
'client_commands',
|
||||||
|
sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
|
||||||
|
sa.Column('command_id', sa.String(length=36), nullable=False),
|
||||||
|
sa.Column('client_uuid', sa.String(length=36), nullable=False),
|
||||||
|
sa.Column('action', sa.String(length=32), nullable=False),
|
||||||
|
sa.Column('status', sa.String(length=40), nullable=False),
|
||||||
|
sa.Column('reason', sa.Text(), nullable=True),
|
||||||
|
sa.Column('requested_by', sa.Integer(), nullable=True),
|
||||||
|
sa.Column('issued_at', sa.TIMESTAMP(timezone=True), nullable=False),
|
||||||
|
sa.Column('expires_at', sa.TIMESTAMP(timezone=True), nullable=False),
|
||||||
|
sa.Column('published_at', sa.TIMESTAMP(timezone=True), nullable=True),
|
||||||
|
sa.Column('acked_at', sa.TIMESTAMP(timezone=True), nullable=True),
|
||||||
|
sa.Column('execution_started_at', sa.TIMESTAMP(timezone=True), nullable=True),
|
||||||
|
sa.Column('completed_at', sa.TIMESTAMP(timezone=True), nullable=True),
|
||||||
|
sa.Column('failed_at', sa.TIMESTAMP(timezone=True), nullable=True),
|
||||||
|
sa.Column('error_code', sa.String(length=64), nullable=True),
|
||||||
|
sa.Column('error_message', sa.Text(), nullable=True),
|
||||||
|
sa.Column('created_at', sa.TIMESTAMP(timezone=True), server_default=sa.func.current_timestamp(), nullable=False),
|
||||||
|
sa.Column('updated_at', sa.TIMESTAMP(timezone=True), server_default=sa.func.current_timestamp(), nullable=False),
|
||||||
|
sa.ForeignKeyConstraint(['client_uuid'], ['clients.uuid'], ondelete='CASCADE'),
|
||||||
|
sa.ForeignKeyConstraint(['requested_by'], ['users.id'], ondelete='SET NULL'),
|
||||||
|
sa.PrimaryKeyConstraint('id'),
|
||||||
|
sa.UniqueConstraint('command_id')
|
||||||
|
)
|
||||||
|
|
||||||
|
op.create_index(op.f('ix_client_commands_action'), 'client_commands', ['action'], unique=False)
|
||||||
|
op.create_index(op.f('ix_client_commands_client_uuid'), 'client_commands', ['client_uuid'], unique=False)
|
||||||
|
op.create_index(op.f('ix_client_commands_command_id'), 'client_commands', ['command_id'], unique=False)
|
||||||
|
op.create_index(op.f('ix_client_commands_requested_by'), 'client_commands', ['requested_by'], unique=False)
|
||||||
|
op.create_index(op.f('ix_client_commands_status'), 'client_commands', ['status'], unique=False)
|
||||||
|
op.create_index('ix_client_commands_client_status_created', 'client_commands', ['client_uuid', 'status', 'created_at'], unique=False)
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
op.drop_index('ix_client_commands_client_status_created', table_name='client_commands')
|
||||||
|
op.drop_index(op.f('ix_client_commands_status'), table_name='client_commands')
|
||||||
|
op.drop_index(op.f('ix_client_commands_requested_by'), table_name='client_commands')
|
||||||
|
op.drop_index(op.f('ix_client_commands_command_id'), table_name='client_commands')
|
||||||
|
op.drop_index(op.f('ix_client_commands_client_uuid'), table_name='client_commands')
|
||||||
|
op.drop_index(op.f('ix_client_commands_action'), table_name='client_commands')
|
||||||
|
op.drop_table('client_commands')
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
"""add service_failed and mqtt broker connection fields to clients
|
||||||
|
|
||||||
|
Revision ID: b1c2d3e4f5a6
|
||||||
|
Revises: aa12bb34cc56
|
||||||
|
Create Date: 2026-04-05 10:00:00.000000
|
||||||
|
|
||||||
|
"""
|
||||||
|
from typing import Sequence, Union
|
||||||
|
|
||||||
|
from alembic import op
|
||||||
|
import sqlalchemy as sa
|
||||||
|
|
||||||
|
|
||||||
|
# revision identifiers, used by Alembic.
|
||||||
|
revision: str = 'b1c2d3e4f5a6'
|
||||||
|
down_revision: Union[str, None] = 'aa12bb34cc56'
|
||||||
|
branch_labels: Union[str, Sequence[str], None] = None
|
||||||
|
depends_on: Union[str, Sequence[str], None] = None
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
bind = op.get_bind()
|
||||||
|
inspector = sa.inspect(bind)
|
||||||
|
existing = {c['name'] for c in inspector.get_columns('clients')}
|
||||||
|
|
||||||
|
# Systemd service-failed tracking
|
||||||
|
if 'service_failed_at' not in existing:
|
||||||
|
op.add_column('clients', sa.Column('service_failed_at', sa.TIMESTAMP(timezone=True), nullable=True))
|
||||||
|
if 'service_failed_unit' not in existing:
|
||||||
|
op.add_column('clients', sa.Column('service_failed_unit', sa.String(128), nullable=True))
|
||||||
|
|
||||||
|
# MQTT broker connection health
|
||||||
|
if 'mqtt_reconnect_count' not in existing:
|
||||||
|
op.add_column('clients', sa.Column('mqtt_reconnect_count', sa.Integer(), nullable=True))
|
||||||
|
if 'mqtt_last_disconnect_at' not in existing:
|
||||||
|
op.add_column('clients', sa.Column('mqtt_last_disconnect_at', sa.TIMESTAMP(timezone=True), nullable=True))
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
op.drop_column('clients', 'mqtt_last_disconnect_at')
|
||||||
|
op.drop_column('clients', 'mqtt_reconnect_count')
|
||||||
|
op.drop_column('clients', 'service_failed_unit')
|
||||||
|
op.drop_column('clients', 'service_failed_at')
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
"""merge academic periods and client monitoring heads
|
||||||
|
|
||||||
|
Revision ID: dd100f3958dc
|
||||||
|
Revises: a7b8c9d0e1f2, c1d2e3f4g5h6
|
||||||
|
Create Date: 2026-03-31 07:55:09.999917
|
||||||
|
|
||||||
|
"""
|
||||||
|
from typing import Sequence, Union
|
||||||
|
|
||||||
|
from alembic import op
|
||||||
|
import sqlalchemy as sa
|
||||||
|
|
||||||
|
|
||||||
|
# revision identifiers, used by Alembic.
|
||||||
|
revision: str = 'dd100f3958dc'
|
||||||
|
down_revision: Union[str, None] = ('a7b8c9d0e1f2', 'c1d2e3f4g5h6')
|
||||||
|
branch_labels: Union[str, Sequence[str], None] = None
|
||||||
|
depends_on: Union[str, Sequence[str], None] = None
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
"""Upgrade schema."""
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
"""Downgrade schema."""
|
||||||
|
pass
|
||||||
@@ -0,0 +1,54 @@
|
|||||||
|
"""scope school holidays to academic periods
|
||||||
|
|
||||||
|
Revision ID: f3c4d5e6a7b8
|
||||||
|
Revises: dd100f3958dc
|
||||||
|
Create Date: 2026-03-31 12:20:00.000000
|
||||||
|
|
||||||
|
"""
|
||||||
|
from typing import Sequence, Union
|
||||||
|
|
||||||
|
from alembic import op
|
||||||
|
import sqlalchemy as sa
|
||||||
|
|
||||||
|
|
||||||
|
# revision identifiers, used by Alembic.
|
||||||
|
revision: str = 'f3c4d5e6a7b8'
|
||||||
|
down_revision: Union[str, None] = 'dd100f3958dc'
|
||||||
|
branch_labels: Union[str, Sequence[str], None] = None
|
||||||
|
depends_on: Union[str, Sequence[str], None] = None
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
op.add_column('school_holidays', sa.Column('academic_period_id', sa.Integer(), nullable=True))
|
||||||
|
op.create_index(
|
||||||
|
op.f('ix_school_holidays_academic_period_id'),
|
||||||
|
'school_holidays',
|
||||||
|
['academic_period_id'],
|
||||||
|
unique=False,
|
||||||
|
)
|
||||||
|
op.create_foreign_key(
|
||||||
|
'fk_school_holidays_academic_period_id',
|
||||||
|
'school_holidays',
|
||||||
|
'academic_periods',
|
||||||
|
['academic_period_id'],
|
||||||
|
['id'],
|
||||||
|
ondelete='SET NULL',
|
||||||
|
)
|
||||||
|
op.drop_constraint('uq_school_holidays_unique', 'school_holidays', type_='unique')
|
||||||
|
op.create_unique_constraint(
|
||||||
|
'uq_school_holidays_unique',
|
||||||
|
'school_holidays',
|
||||||
|
['name', 'start_date', 'end_date', 'region', 'academic_period_id'],
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
op.drop_constraint('uq_school_holidays_unique', 'school_holidays', type_='unique')
|
||||||
|
op.create_unique_constraint(
|
||||||
|
'uq_school_holidays_unique',
|
||||||
|
'school_holidays',
|
||||||
|
['name', 'start_date', 'end_date', 'region'],
|
||||||
|
)
|
||||||
|
op.drop_constraint('fk_school_holidays_academic_period_id', 'school_holidays', type_='foreignkey')
|
||||||
|
op.drop_index(op.f('ix_school_holidays_academic_period_id'), table_name='school_holidays')
|
||||||
|
op.drop_column('school_holidays', 'academic_period_id')
|
||||||
@@ -1,7 +1,11 @@
|
|||||||
#!/usr/bin/env python3
|
#!/usr/bin/env python3
|
||||||
"""
|
"""
|
||||||
Erstellt Standard-Schuljahre für österreichische Schulen
|
Erstellt Standard-Schuljahre und setzt automatisch die aktive Periode.
|
||||||
Führe dieses Skript nach der Migration aus, um Standard-Perioden zu erstellen.
|
|
||||||
|
Dieses Skript ist idempotent:
|
||||||
|
- Wenn keine Perioden existieren, werden Standard-Perioden erstellt.
|
||||||
|
- Danach wird (bei jedem Lauf) die nicht-archivierte Periode aktiviert,
|
||||||
|
die das heutige Datum abdeckt.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from datetime import date
|
from datetime import date
|
||||||
@@ -11,54 +15,94 @@ import sys
|
|||||||
sys.path.append('/workspace')
|
sys.path.append('/workspace')
|
||||||
|
|
||||||
|
|
||||||
|
def _create_default_periods_if_missing(session):
|
||||||
|
"""Erstellt Standard-Schuljahre nur dann, wenn noch keine Perioden existieren."""
|
||||||
|
existing = session.query(AcademicPeriod).first()
|
||||||
|
if existing:
|
||||||
|
print("Academic periods already exist. Skipping creation.")
|
||||||
|
return False
|
||||||
|
|
||||||
|
periods = [
|
||||||
|
{
|
||||||
|
'name': 'Schuljahr 2024/25',
|
||||||
|
'display_name': 'SJ 24/25',
|
||||||
|
'start_date': date(2024, 9, 2),
|
||||||
|
'end_date': date(2025, 7, 4),
|
||||||
|
'period_type': AcademicPeriodType.schuljahr,
|
||||||
|
'is_active': False
|
||||||
|
},
|
||||||
|
{
|
||||||
|
'name': 'Schuljahr 2025/26',
|
||||||
|
'display_name': 'SJ 25/26',
|
||||||
|
'start_date': date(2025, 9, 1),
|
||||||
|
'end_date': date(2026, 7, 3),
|
||||||
|
'period_type': AcademicPeriodType.schuljahr,
|
||||||
|
'is_active': False
|
||||||
|
},
|
||||||
|
{
|
||||||
|
'name': 'Schuljahr 2026/27',
|
||||||
|
'display_name': 'SJ 26/27',
|
||||||
|
'start_date': date(2026, 9, 7),
|
||||||
|
'end_date': date(2027, 7, 2),
|
||||||
|
'period_type': AcademicPeriodType.schuljahr,
|
||||||
|
'is_active': False
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
for period_data in periods:
|
||||||
|
period = AcademicPeriod(**period_data)
|
||||||
|
session.add(period)
|
||||||
|
|
||||||
|
session.flush()
|
||||||
|
print(f"Successfully created {len(periods)} academic periods")
|
||||||
|
return True
|
||||||
|
|
||||||
|
|
||||||
|
def _activate_period_for_today(session):
|
||||||
|
"""Aktiviert genau eine Periode: die Periode, die heute abdeckt."""
|
||||||
|
today = date.today()
|
||||||
|
|
||||||
|
period_for_today = (
|
||||||
|
session.query(AcademicPeriod)
|
||||||
|
.filter(
|
||||||
|
AcademicPeriod.is_archived == False,
|
||||||
|
AcademicPeriod.start_date <= today,
|
||||||
|
AcademicPeriod.end_date >= today,
|
||||||
|
)
|
||||||
|
.order_by(AcademicPeriod.start_date.desc())
|
||||||
|
.first()
|
||||||
|
)
|
||||||
|
|
||||||
|
# Immer zunächst alle aktiven Perioden deaktivieren, um den Zustand konsistent zu halten.
|
||||||
|
session.query(AcademicPeriod).filter(AcademicPeriod.is_active == True).update(
|
||||||
|
{AcademicPeriod.is_active: False},
|
||||||
|
synchronize_session=False,
|
||||||
|
)
|
||||||
|
|
||||||
|
if period_for_today:
|
||||||
|
period_for_today.is_active = True
|
||||||
|
print(
|
||||||
|
f"Activated academic period for today ({today}): {period_for_today.name} "
|
||||||
|
f"[{period_for_today.start_date} - {period_for_today.end_date}]"
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
print(
|
||||||
|
f"WARNING: No academic period covers today ({today}). "
|
||||||
|
"All periods remain inactive."
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
def create_default_academic_periods():
|
def create_default_academic_periods():
|
||||||
"""Erstellt Standard-Schuljahre für österreichische Schulen"""
|
"""Erstellt Standard-Perioden (falls nötig) und setzt aktive Periode für heute."""
|
||||||
session = Session()
|
session = Session()
|
||||||
|
|
||||||
try:
|
try:
|
||||||
# Prüfe ob bereits Perioden existieren
|
_create_default_periods_if_missing(session)
|
||||||
existing = session.query(AcademicPeriod).first()
|
_activate_period_for_today(session)
|
||||||
if existing:
|
|
||||||
print("Academic periods already exist. Skipping creation.")
|
|
||||||
return
|
|
||||||
|
|
||||||
# Standard Schuljahre erstellen
|
|
||||||
periods = [
|
|
||||||
{
|
|
||||||
'name': 'Schuljahr 2024/25',
|
|
||||||
'display_name': 'SJ 24/25',
|
|
||||||
'start_date': date(2024, 9, 2),
|
|
||||||
'end_date': date(2025, 7, 4),
|
|
||||||
'period_type': AcademicPeriodType.schuljahr,
|
|
||||||
'is_active': True # Aktuelles Schuljahr
|
|
||||||
},
|
|
||||||
{
|
|
||||||
'name': 'Schuljahr 2025/26',
|
|
||||||
'display_name': 'SJ 25/26',
|
|
||||||
'start_date': date(2025, 9, 1),
|
|
||||||
'end_date': date(2026, 7, 3),
|
|
||||||
'period_type': AcademicPeriodType.schuljahr,
|
|
||||||
'is_active': False
|
|
||||||
},
|
|
||||||
{
|
|
||||||
'name': 'Schuljahr 2026/27',
|
|
||||||
'display_name': 'SJ 26/27',
|
|
||||||
'start_date': date(2026, 9, 7),
|
|
||||||
'end_date': date(2027, 7, 2),
|
|
||||||
'period_type': AcademicPeriodType.schuljahr,
|
|
||||||
'is_active': False
|
|
||||||
}
|
|
||||||
]
|
|
||||||
|
|
||||||
for period_data in periods:
|
|
||||||
period = AcademicPeriod(**period_data)
|
|
||||||
session.add(period)
|
|
||||||
|
|
||||||
session.commit()
|
session.commit()
|
||||||
print(f"Successfully created {len(periods)} academic periods")
|
|
||||||
|
|
||||||
# Zeige erstellte Perioden
|
# Zeige erstellte Perioden
|
||||||
for period in session.query(AcademicPeriod).all():
|
for period in session.query(AcademicPeriod).order_by(AcademicPeriod.start_date.asc()).all():
|
||||||
status = "AKTIV" if period.is_active else "inaktiv"
|
status = "AKTIV" if period.is_active else "inaktiv"
|
||||||
print(
|
print(
|
||||||
f" - {period.name} ({period.start_date} - {period.end_date}) [{status}]")
|
f" - {period.name} ({period.start_date} - {period.end_date}) [{status}]")
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
from sqlalchemy import create_engine, text
|
from sqlalchemy import create_engine, textmosquitto.conf
|
||||||
import os
|
import os
|
||||||
from dotenv import load_dotenv
|
from dotenv import load_dotenv
|
||||||
import bcrypt
|
import bcrypt
|
||||||
|
|||||||
@@ -1,43 +1,87 @@
|
|||||||
from flask import Blueprint, jsonify, request
|
"""
|
||||||
|
Academic periods management routes.
|
||||||
|
|
||||||
|
Endpoints for full CRUD lifecycle including archive, restore, and hard delete.
|
||||||
|
All write operations require admin+ role.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from flask import Blueprint, jsonify, request, session
|
||||||
from server.permissions import admin_or_higher
|
from server.permissions import admin_or_higher
|
||||||
from server.database import Session
|
from server.database import Session
|
||||||
from models.models import AcademicPeriod
|
from server.serializers import dict_to_camel_case
|
||||||
from datetime import datetime
|
from models.models import AcademicPeriod, Event
|
||||||
|
from datetime import datetime, timezone
|
||||||
|
from sqlalchemy import and_
|
||||||
|
from dateutil.rrule import rrulestr
|
||||||
|
from dateutil.tz import UTC
|
||||||
|
import sys
|
||||||
|
|
||||||
|
sys.path.append('/workspace')
|
||||||
|
|
||||||
academic_periods_bp = Blueprint(
|
academic_periods_bp = Blueprint(
|
||||||
'academic_periods', __name__, url_prefix='/api/academic_periods')
|
'academic_periods', __name__, url_prefix='/api/academic_periods')
|
||||||
|
|
||||||
|
|
||||||
|
# ============================================================================
|
||||||
|
# GET ENDPOINTS
|
||||||
|
# ============================================================================
|
||||||
|
|
||||||
@academic_periods_bp.route('', methods=['GET'])
|
@academic_periods_bp.route('', methods=['GET'])
|
||||||
def list_academic_periods():
|
def list_academic_periods():
|
||||||
session = Session()
|
"""List academic periods with optional archived visibility filters, ordered by start_date."""
|
||||||
|
db_session = Session()
|
||||||
try:
|
try:
|
||||||
periods = session.query(AcademicPeriod).order_by(
|
include_archived = request.args.get('includeArchived', '0') == '1'
|
||||||
AcademicPeriod.start_date.asc()).all()
|
archived_only = request.args.get('archivedOnly', '0') == '1'
|
||||||
return jsonify({
|
|
||||||
'periods': [p.to_dict() for p in periods]
|
query = db_session.query(AcademicPeriod)
|
||||||
})
|
|
||||||
|
if archived_only:
|
||||||
|
query = query.filter(AcademicPeriod.is_archived == True)
|
||||||
|
elif not include_archived:
|
||||||
|
query = query.filter(AcademicPeriod.is_archived == False)
|
||||||
|
|
||||||
|
periods = query.order_by(AcademicPeriod.start_date.asc()).all()
|
||||||
|
|
||||||
|
result = [dict_to_camel_case(p.to_dict()) for p in periods]
|
||||||
|
return jsonify({'periods': result}), 200
|
||||||
finally:
|
finally:
|
||||||
session.close()
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
|
@academic_periods_bp.route('/<int:period_id>', methods=['GET'])
|
||||||
|
def get_academic_period(period_id):
|
||||||
|
"""Get a single academic period by ID (including archived)."""
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
period = db_session.query(AcademicPeriod).get(period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
||||||
|
|
||||||
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 200
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
@academic_periods_bp.route('/active', methods=['GET'])
|
@academic_periods_bp.route('/active', methods=['GET'])
|
||||||
def get_active_academic_period():
|
def get_active_academic_period():
|
||||||
session = Session()
|
"""Get the currently active academic period."""
|
||||||
|
db_session = Session()
|
||||||
try:
|
try:
|
||||||
period = session.query(AcademicPeriod).filter(
|
period = db_session.query(AcademicPeriod).filter(
|
||||||
AcademicPeriod.is_active == True).first()
|
AcademicPeriod.is_active == True
|
||||||
|
).first()
|
||||||
if not period:
|
if not period:
|
||||||
return jsonify({'period': None}), 200
|
return jsonify({'period': None}), 200
|
||||||
return jsonify({'period': period.to_dict()}), 200
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 200
|
||||||
finally:
|
finally:
|
||||||
session.close()
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
@academic_periods_bp.route('/for_date', methods=['GET'])
|
@academic_periods_bp.route('/for_date', methods=['GET'])
|
||||||
def get_period_for_date():
|
def get_period_for_date():
|
||||||
"""
|
"""
|
||||||
Returns the academic period that covers the provided date (YYYY-MM-DD).
|
Returns the non-archived academic period that covers the provided date (YYYY-MM-DD).
|
||||||
If multiple match, prefer the one with the latest start_date.
|
If multiple match, prefer the one with the latest start_date.
|
||||||
"""
|
"""
|
||||||
date_str = request.args.get('date')
|
date_str = request.args.get('date')
|
||||||
@@ -48,39 +92,414 @@ def get_period_for_date():
|
|||||||
except ValueError:
|
except ValueError:
|
||||||
return jsonify({'error': 'Invalid date format. Expected YYYY-MM-DD'}), 400
|
return jsonify({'error': 'Invalid date format. Expected YYYY-MM-DD'}), 400
|
||||||
|
|
||||||
session = Session()
|
db_session = Session()
|
||||||
try:
|
try:
|
||||||
period = (
|
period = (
|
||||||
session.query(AcademicPeriod)
|
db_session.query(AcademicPeriod)
|
||||||
.filter(AcademicPeriod.start_date <= target, AcademicPeriod.end_date >= target)
|
.filter(
|
||||||
|
AcademicPeriod.start_date <= target,
|
||||||
|
AcademicPeriod.end_date >= target,
|
||||||
|
AcademicPeriod.is_archived == False
|
||||||
|
)
|
||||||
.order_by(AcademicPeriod.start_date.desc())
|
.order_by(AcademicPeriod.start_date.desc())
|
||||||
.first()
|
.first()
|
||||||
)
|
)
|
||||||
return jsonify({'period': period.to_dict() if period else None}), 200
|
return jsonify({'period': dict_to_camel_case(period.to_dict()) if period else None}), 200
|
||||||
finally:
|
finally:
|
||||||
session.close()
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
@academic_periods_bp.route('/active', methods=['POST'])
|
@academic_periods_bp.route('/<int:period_id>/usage', methods=['GET'])
|
||||||
@admin_or_higher
|
def get_period_usage(period_id):
|
||||||
def set_active_academic_period():
|
"""
|
||||||
data = request.get_json(silent=True) or {}
|
Check what events and media are linked to this period.
|
||||||
period_id = data.get('id')
|
Used for pre-flight checks before delete/archive.
|
||||||
if period_id is None:
|
|
||||||
return jsonify({'error': 'Missing required field: id'}), 400
|
Returns:
|
||||||
session = Session()
|
{
|
||||||
|
"linked_events": count,
|
||||||
|
"linked_media": count,
|
||||||
|
"has_active_recurrence": boolean,
|
||||||
|
"blockers": ["list of reasons why delete/archive would fail"]
|
||||||
|
}
|
||||||
|
"""
|
||||||
|
db_session = Session()
|
||||||
try:
|
try:
|
||||||
target = session.query(AcademicPeriod).get(period_id)
|
period = db_session.query(AcademicPeriod).get(period_id)
|
||||||
if not target:
|
if not period:
|
||||||
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
||||||
|
|
||||||
# Deactivate all, then activate target
|
# Count linked events
|
||||||
session.query(AcademicPeriod).filter(AcademicPeriod.is_active == True).update(
|
linked_events = db_session.query(Event).filter(
|
||||||
{AcademicPeriod.is_active: False}
|
Event.academic_period_id == period_id
|
||||||
)
|
).count()
|
||||||
target.is_active = True
|
|
||||||
session.commit()
|
# Check for active recurrence (events with recurrence_rule that have future occurrences)
|
||||||
session.refresh(target)
|
has_active_recurrence = False
|
||||||
return jsonify({'period': target.to_dict()}), 200
|
blockers = []
|
||||||
|
|
||||||
|
now = datetime.now(timezone.utc)
|
||||||
|
recurring_events = db_session.query(Event).filter(
|
||||||
|
Event.academic_period_id == period_id,
|
||||||
|
Event.recurrence_rule != None
|
||||||
|
).all()
|
||||||
|
|
||||||
|
for evt in recurring_events:
|
||||||
|
try:
|
||||||
|
rrule_obj = rrulestr(evt.recurrence_rule, dtstart=evt.start)
|
||||||
|
# Check if there are any future occurrences
|
||||||
|
next_occurrence = rrule_obj.after(now, inc=True)
|
||||||
|
if next_occurrence:
|
||||||
|
has_active_recurrence = True
|
||||||
|
blockers.append(f"Recurring event '{evt.title}' has active occurrences")
|
||||||
|
break
|
||||||
|
except Exception:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# If period is active, cannot archive/delete
|
||||||
|
if period.is_active:
|
||||||
|
blockers.append("Cannot archive or delete an active period")
|
||||||
|
|
||||||
|
return jsonify({
|
||||||
|
'usage': {
|
||||||
|
'linked_events': linked_events,
|
||||||
|
'has_active_recurrence': has_active_recurrence,
|
||||||
|
'blockers': blockers
|
||||||
|
}
|
||||||
|
}), 200
|
||||||
finally:
|
finally:
|
||||||
session.close()
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
|
# ============================================================================
|
||||||
|
# CREATE ENDPOINT
|
||||||
|
# ============================================================================
|
||||||
|
|
||||||
|
@academic_periods_bp.route('', methods=['POST'])
|
||||||
|
@admin_or_higher
|
||||||
|
def create_academic_period():
|
||||||
|
"""
|
||||||
|
Create a new academic period.
|
||||||
|
|
||||||
|
Request body:
|
||||||
|
{
|
||||||
|
"name": "Schuljahr 2026/27",
|
||||||
|
"displayName": "SJ 26/27",
|
||||||
|
"startDate": "2026-09-01",
|
||||||
|
"endDate": "2027-08-31",
|
||||||
|
"periodType": "schuljahr"
|
||||||
|
}
|
||||||
|
"""
|
||||||
|
data = request.get_json(silent=True) or {}
|
||||||
|
|
||||||
|
# Validate required fields
|
||||||
|
name = data.get('name', '').strip()
|
||||||
|
if not name:
|
||||||
|
return jsonify({'error': 'Name is required and cannot be empty'}), 400
|
||||||
|
|
||||||
|
start_date_str = data.get('startDate')
|
||||||
|
end_date_str = data.get('endDate')
|
||||||
|
period_type = data.get('periodType', 'schuljahr')
|
||||||
|
display_name = data.get('displayName', '').strip() or None
|
||||||
|
|
||||||
|
# Parse dates
|
||||||
|
try:
|
||||||
|
start_date = datetime.strptime(start_date_str, '%Y-%m-%d').date()
|
||||||
|
end_date = datetime.strptime(end_date_str, '%Y-%m-%d').date()
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
return jsonify({'error': 'Invalid date format. Expected YYYY-MM-DD'}), 400
|
||||||
|
|
||||||
|
# Validate date range
|
||||||
|
if start_date > end_date:
|
||||||
|
return jsonify({'error': 'Start date must be less than or equal to end date'}), 400
|
||||||
|
|
||||||
|
# Validate period type
|
||||||
|
valid_types = ['schuljahr', 'semester', 'trimester']
|
||||||
|
if period_type not in valid_types:
|
||||||
|
return jsonify({'error': f'Invalid periodType. Must be one of: {", ".join(valid_types)}'}), 400
|
||||||
|
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
# Check name uniqueness among non-archived periods
|
||||||
|
existing = db_session.query(AcademicPeriod).filter(
|
||||||
|
AcademicPeriod.name == name,
|
||||||
|
AcademicPeriod.is_archived == False
|
||||||
|
).first()
|
||||||
|
if existing:
|
||||||
|
return jsonify({'error': 'A non-archived period with this name already exists'}), 409
|
||||||
|
|
||||||
|
# Check for overlaps within same period type
|
||||||
|
overlapping = db_session.query(AcademicPeriod).filter(
|
||||||
|
AcademicPeriod.period_type == period_type,
|
||||||
|
AcademicPeriod.is_archived == False,
|
||||||
|
AcademicPeriod.start_date <= end_date,
|
||||||
|
AcademicPeriod.end_date >= start_date
|
||||||
|
).first()
|
||||||
|
if overlapping:
|
||||||
|
return jsonify({'error': f'Overlapping {period_type} period already exists'}), 409
|
||||||
|
|
||||||
|
# Create period
|
||||||
|
period = AcademicPeriod(
|
||||||
|
name=name,
|
||||||
|
display_name=display_name,
|
||||||
|
start_date=start_date,
|
||||||
|
end_date=end_date,
|
||||||
|
period_type=period_type,
|
||||||
|
is_active=False,
|
||||||
|
is_archived=False
|
||||||
|
)
|
||||||
|
db_session.add(period)
|
||||||
|
db_session.commit()
|
||||||
|
db_session.refresh(period)
|
||||||
|
|
||||||
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 201
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
|
# ============================================================================
|
||||||
|
# UPDATE ENDPOINT
|
||||||
|
# ============================================================================
|
||||||
|
|
||||||
|
@academic_periods_bp.route('/<int:period_id>', methods=['PUT'])
|
||||||
|
@admin_or_higher
|
||||||
|
def update_academic_period(period_id):
|
||||||
|
"""
|
||||||
|
Update an academic period (cannot be archived).
|
||||||
|
|
||||||
|
Request body (all fields optional):
|
||||||
|
{
|
||||||
|
"name": "...",
|
||||||
|
"displayName": "...",
|
||||||
|
"startDate": "YYYY-MM-DD",
|
||||||
|
"endDate": "YYYY-MM-DD",
|
||||||
|
"periodType": "schuljahr|semester|trimester"
|
||||||
|
}
|
||||||
|
"""
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
period = db_session.query(AcademicPeriod).get(period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
||||||
|
|
||||||
|
if period.is_archived:
|
||||||
|
return jsonify({'error': 'Cannot update an archived period'}), 409
|
||||||
|
|
||||||
|
data = request.get_json(silent=True) or {}
|
||||||
|
|
||||||
|
# Update fields if provided
|
||||||
|
if 'name' in data:
|
||||||
|
name = data['name'].strip()
|
||||||
|
if not name:
|
||||||
|
return jsonify({'error': 'Name cannot be empty'}), 400
|
||||||
|
|
||||||
|
# Check uniqueness among non-archived (excluding self)
|
||||||
|
existing = db_session.query(AcademicPeriod).filter(
|
||||||
|
AcademicPeriod.name == name,
|
||||||
|
AcademicPeriod.is_archived == False,
|
||||||
|
AcademicPeriod.id != period_id
|
||||||
|
).first()
|
||||||
|
if existing:
|
||||||
|
return jsonify({'error': 'A non-archived period with this name already exists'}), 409
|
||||||
|
|
||||||
|
period.name = name
|
||||||
|
|
||||||
|
if 'displayName' in data:
|
||||||
|
period.display_name = data['displayName'].strip() or None
|
||||||
|
|
||||||
|
if 'periodType' in data:
|
||||||
|
period_type = data['periodType']
|
||||||
|
valid_types = ['schuljahr', 'semester', 'trimester']
|
||||||
|
if period_type not in valid_types:
|
||||||
|
return jsonify({'error': f'Invalid periodType. Must be one of: {", ".join(valid_types)}'}), 400
|
||||||
|
period.period_type = period_type
|
||||||
|
|
||||||
|
# Handle date updates with overlap checking
|
||||||
|
if 'startDate' in data or 'endDate' in data:
|
||||||
|
start_date = period.start_date
|
||||||
|
end_date = period.end_date
|
||||||
|
|
||||||
|
if 'startDate' in data:
|
||||||
|
try:
|
||||||
|
start_date = datetime.strptime(data['startDate'], '%Y-%m-%d').date()
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
return jsonify({'error': 'Invalid startDate format. Expected YYYY-MM-DD'}), 400
|
||||||
|
|
||||||
|
if 'endDate' in data:
|
||||||
|
try:
|
||||||
|
end_date = datetime.strptime(data['endDate'], '%Y-%m-%d').date()
|
||||||
|
except (ValueError, TypeError):
|
||||||
|
return jsonify({'error': 'Invalid endDate format. Expected YYYY-MM-DD'}), 400
|
||||||
|
|
||||||
|
if start_date > end_date:
|
||||||
|
return jsonify({'error': 'Start date must be less than or equal to end date'}), 400
|
||||||
|
|
||||||
|
# Check for overlaps within same period type (excluding self)
|
||||||
|
overlapping = db_session.query(AcademicPeriod).filter(
|
||||||
|
AcademicPeriod.period_type == period.period_type,
|
||||||
|
AcademicPeriod.is_archived == False,
|
||||||
|
AcademicPeriod.id != period_id,
|
||||||
|
AcademicPeriod.start_date <= end_date,
|
||||||
|
AcademicPeriod.end_date >= start_date
|
||||||
|
).first()
|
||||||
|
if overlapping:
|
||||||
|
return jsonify({'error': f'Overlapping {period.period_type.value} period already exists'}), 409
|
||||||
|
|
||||||
|
period.start_date = start_date
|
||||||
|
period.end_date = end_date
|
||||||
|
|
||||||
|
db_session.commit()
|
||||||
|
db_session.refresh(period)
|
||||||
|
|
||||||
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 200
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
|
# ============================================================================
|
||||||
|
# ACTIVATE ENDPOINT
|
||||||
|
# ============================================================================
|
||||||
|
|
||||||
|
@academic_periods_bp.route('/<int:period_id>/activate', methods=['POST'])
|
||||||
|
@admin_or_higher
|
||||||
|
def activate_academic_period(period_id):
|
||||||
|
"""
|
||||||
|
Activate an academic period (deactivates all others).
|
||||||
|
Cannot activate an archived period.
|
||||||
|
"""
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
period = db_session.query(AcademicPeriod).get(period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
||||||
|
|
||||||
|
if period.is_archived:
|
||||||
|
return jsonify({'error': 'Cannot activate an archived period'}), 409
|
||||||
|
|
||||||
|
# Deactivate all, then activate target
|
||||||
|
db_session.query(AcademicPeriod).update({AcademicPeriod.is_active: False})
|
||||||
|
period.is_active = True
|
||||||
|
db_session.commit()
|
||||||
|
db_session.refresh(period)
|
||||||
|
|
||||||
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 200
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
|
# ============================================================================
|
||||||
|
# ARCHIVE/RESTORE ENDPOINTS
|
||||||
|
# ============================================================================
|
||||||
|
|
||||||
|
@academic_periods_bp.route('/<int:period_id>/archive', methods=['POST'])
|
||||||
|
@admin_or_higher
|
||||||
|
def archive_academic_period(period_id):
|
||||||
|
"""
|
||||||
|
Archive an academic period (soft delete).
|
||||||
|
Cannot archive an active period or one with active recurring events.
|
||||||
|
"""
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
period = db_session.query(AcademicPeriod).get(period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
||||||
|
|
||||||
|
if period.is_archived:
|
||||||
|
return jsonify({'error': 'Period already archived'}), 409
|
||||||
|
|
||||||
|
if period.is_active:
|
||||||
|
return jsonify({'error': 'Cannot archive an active period'}), 409
|
||||||
|
|
||||||
|
# Check for recurrence spillover
|
||||||
|
now = datetime.now(timezone.utc)
|
||||||
|
recurring_events = db_session.query(Event).filter(
|
||||||
|
Event.academic_period_id == period_id,
|
||||||
|
Event.recurrence_rule != None
|
||||||
|
).all()
|
||||||
|
|
||||||
|
for evt in recurring_events:
|
||||||
|
try:
|
||||||
|
rrule_obj = rrulestr(evt.recurrence_rule, dtstart=evt.start)
|
||||||
|
next_occurrence = rrule_obj.after(now, inc=True)
|
||||||
|
if next_occurrence:
|
||||||
|
return jsonify({'error': f'Cannot archive: recurring event "{evt.title}" has active occurrences'}), 409
|
||||||
|
except Exception:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Archive
|
||||||
|
user_id = session.get('user_id')
|
||||||
|
period.is_archived = True
|
||||||
|
period.archived_at = datetime.now(timezone.utc)
|
||||||
|
period.archived_by = user_id
|
||||||
|
db_session.commit()
|
||||||
|
db_session.refresh(period)
|
||||||
|
|
||||||
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 200
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
|
@academic_periods_bp.route('/<int:period_id>/restore', methods=['POST'])
|
||||||
|
@admin_or_higher
|
||||||
|
def restore_academic_period(period_id):
|
||||||
|
"""
|
||||||
|
Restore an archived academic period (returns to inactive state).
|
||||||
|
"""
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
period = db_session.query(AcademicPeriod).get(period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
||||||
|
|
||||||
|
if not period.is_archived:
|
||||||
|
return jsonify({'error': 'Period is not archived'}), 409
|
||||||
|
|
||||||
|
# Restore
|
||||||
|
period.is_archived = False
|
||||||
|
period.archived_at = None
|
||||||
|
period.archived_by = None
|
||||||
|
db_session.commit()
|
||||||
|
db_session.refresh(period)
|
||||||
|
|
||||||
|
return jsonify({'period': dict_to_camel_case(period.to_dict())}), 200
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
|
||||||
|
|
||||||
|
# ============================================================================
|
||||||
|
# DELETE ENDPOINT
|
||||||
|
# ============================================================================
|
||||||
|
|
||||||
|
@academic_periods_bp.route('/<int:period_id>', methods=['DELETE'])
|
||||||
|
@admin_or_higher
|
||||||
|
def delete_academic_period(period_id):
|
||||||
|
"""
|
||||||
|
Hard delete an archived, inactive academic period.
|
||||||
|
Blocked if linked events exist, linked media exist, or recurrence spillover detected.
|
||||||
|
"""
|
||||||
|
db_session = Session()
|
||||||
|
try:
|
||||||
|
period = db_session.query(AcademicPeriod).get(period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({'error': 'AcademicPeriod not found'}), 404
|
||||||
|
|
||||||
|
if not period.is_archived:
|
||||||
|
return jsonify({'error': 'Cannot hard-delete a non-archived period'}), 409
|
||||||
|
|
||||||
|
if period.is_active:
|
||||||
|
return jsonify({'error': 'Cannot hard-delete an active period'}), 409
|
||||||
|
|
||||||
|
# Check for linked events
|
||||||
|
linked_events = db_session.query(Event).filter(
|
||||||
|
Event.academic_period_id == period_id
|
||||||
|
).count()
|
||||||
|
if linked_events > 0:
|
||||||
|
return jsonify({'error': f'Cannot delete: {linked_events} event(s) linked to this period'}), 409
|
||||||
|
|
||||||
|
# Delete
|
||||||
|
db_session.delete(period)
|
||||||
|
db_session.commit()
|
||||||
|
|
||||||
|
return jsonify({'message': 'Period deleted successfully'}), 200
|
||||||
|
finally:
|
||||||
|
db_session.close()
|
||||||
|
|||||||
@@ -421,6 +421,8 @@ def get_monitoring_overview():
|
|||||||
},
|
},
|
||||||
"latest_log": _serialize_log_entry(latest_log),
|
"latest_log": _serialize_log_entry(latest_log),
|
||||||
"latest_error": _serialize_log_entry(latest_error),
|
"latest_error": _serialize_log_entry(latest_error),
|
||||||
|
"mqtt_reconnect_count": client.mqtt_reconnect_count,
|
||||||
|
"mqtt_last_disconnect_at": client.mqtt_last_disconnect_at.isoformat() if client.mqtt_last_disconnect_at else None,
|
||||||
})
|
})
|
||||||
|
|
||||||
summary_counts["total_clients"] += 1
|
summary_counts["total_clients"] += 1
|
||||||
|
|||||||
@@ -1,7 +1,8 @@
|
|||||||
from server.database import Session
|
from server.database import Session
|
||||||
from models.models import Client, ClientGroup
|
from models.models import Client, ClientGroup, ClientCommand, ProcessStatus
|
||||||
from flask import Blueprint, request, jsonify
|
from flask import Blueprint, request, jsonify, session as flask_session
|
||||||
from server.permissions import admin_or_higher
|
from server.permissions import admin_or_higher
|
||||||
|
from server.routes.groups import get_grace_period, is_client_alive
|
||||||
from server.mqtt_helper import publish_client_group, delete_client_group_message, publish_multiple_client_groups
|
from server.mqtt_helper import publish_client_group, delete_client_group_message, publish_multiple_client_groups
|
||||||
import sys
|
import sys
|
||||||
import os
|
import os
|
||||||
@@ -9,13 +10,196 @@ import glob
|
|||||||
import base64
|
import base64
|
||||||
import hashlib
|
import hashlib
|
||||||
import json
|
import json
|
||||||
from datetime import datetime, timezone
|
import uuid as uuid_lib
|
||||||
|
from datetime import datetime, timezone, timedelta
|
||||||
sys.path.append('/workspace')
|
sys.path.append('/workspace')
|
||||||
|
|
||||||
clients_bp = Blueprint("clients", __name__, url_prefix="/api/clients")
|
clients_bp = Blueprint("clients", __name__, url_prefix="/api/clients")
|
||||||
|
|
||||||
VALID_SCREENSHOT_TYPES = {"periodic", "event_start", "event_stop"}
|
VALID_SCREENSHOT_TYPES = {"periodic", "event_start", "event_stop"}
|
||||||
|
|
||||||
|
COMMAND_SCHEMA_VERSION = "1.0"
|
||||||
|
COMMAND_TOPIC_TEMPLATE = "infoscreen/{uuid}/commands"
|
||||||
|
COMMAND_TOPIC_COMPAT_TEMPLATE = "infoscreen/{uuid}/command"
|
||||||
|
LEGACY_RESTART_TOPIC_TEMPLATE = "clients/{uuid}/restart"
|
||||||
|
COMMAND_EXPIRY_SECONDS = 240
|
||||||
|
REBOOT_LOCKOUT_WINDOW_MINUTES = 15
|
||||||
|
REBOOT_LOCKOUT_THRESHOLD = 3
|
||||||
|
API_ACTION_TO_COMMAND_ACTION = {
|
||||||
|
"restart": "reboot_host",
|
||||||
|
"shutdown": "shutdown_host",
|
||||||
|
"restart_app": "restart_app",
|
||||||
|
}
|
||||||
|
ALLOWED_COMMAND_ACTIONS = set(API_ACTION_TO_COMMAND_ACTION.keys())
|
||||||
|
|
||||||
|
|
||||||
|
def _iso_utc_z(ts: datetime) -> str:
|
||||||
|
return ts.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
|
||||||
|
|
||||||
|
|
||||||
|
def _command_to_dict(command: ClientCommand) -> dict:
|
||||||
|
return {
|
||||||
|
"commandId": command.command_id,
|
||||||
|
"clientUuid": command.client_uuid,
|
||||||
|
"action": command.action,
|
||||||
|
"status": command.status,
|
||||||
|
"reason": command.reason,
|
||||||
|
"requestedBy": command.requested_by,
|
||||||
|
"issuedAt": command.issued_at.isoformat() if command.issued_at else None,
|
||||||
|
"expiresAt": command.expires_at.isoformat() if command.expires_at else None,
|
||||||
|
"publishedAt": command.published_at.isoformat() if command.published_at else None,
|
||||||
|
"ackedAt": command.acked_at.isoformat() if command.acked_at else None,
|
||||||
|
"executionStartedAt": command.execution_started_at.isoformat() if command.execution_started_at else None,
|
||||||
|
"completedAt": command.completed_at.isoformat() if command.completed_at else None,
|
||||||
|
"failedAt": command.failed_at.isoformat() if command.failed_at else None,
|
||||||
|
"errorCode": command.error_code,
|
||||||
|
"errorMessage": command.error_message,
|
||||||
|
"createdAt": command.created_at.isoformat() if command.created_at else None,
|
||||||
|
"updatedAt": command.updated_at.isoformat() if command.updated_at else None,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def _publish_client_command(client_uuid: str, action: str, payload: dict) -> None:
|
||||||
|
import paho.mqtt.client as mqtt
|
||||||
|
|
||||||
|
broker_host = os.getenv("MQTT_BROKER_HOST", "mqtt")
|
||||||
|
broker_port = int(os.getenv("MQTT_BROKER_PORT", 1883))
|
||||||
|
username = os.getenv("MQTT_USER")
|
||||||
|
password = os.getenv("MQTT_PASSWORD")
|
||||||
|
|
||||||
|
mqtt_client = mqtt.Client()
|
||||||
|
if username and password:
|
||||||
|
mqtt_client.username_pw_set(username, password)
|
||||||
|
|
||||||
|
mqtt_client.connect(broker_host, broker_port)
|
||||||
|
|
||||||
|
# Primary topic for contract-based command handling.
|
||||||
|
command_topic = COMMAND_TOPIC_TEMPLATE.format(uuid=client_uuid)
|
||||||
|
result = mqtt_client.publish(command_topic, json.dumps(payload), qos=1, retain=False)
|
||||||
|
result.wait_for_publish(timeout=5.0)
|
||||||
|
|
||||||
|
# Transitional compatibility for clients that still consume singular topic naming.
|
||||||
|
compat_topic = COMMAND_TOPIC_COMPAT_TEMPLATE.format(uuid=client_uuid)
|
||||||
|
compat_result = mqtt_client.publish(compat_topic, json.dumps(payload), qos=1, retain=False)
|
||||||
|
compat_result.wait_for_publish(timeout=5.0)
|
||||||
|
|
||||||
|
# Transitional compatibility for existing restart-only clients.
|
||||||
|
if action == "restart":
|
||||||
|
legacy_topic = LEGACY_RESTART_TOPIC_TEMPLATE.format(uuid=client_uuid)
|
||||||
|
legacy_payload = {"action": "restart"}
|
||||||
|
legacy_result = mqtt_client.publish(legacy_topic, json.dumps(legacy_payload), qos=1, retain=False)
|
||||||
|
legacy_result.wait_for_publish(timeout=5.0)
|
||||||
|
|
||||||
|
mqtt_client.disconnect()
|
||||||
|
|
||||||
|
|
||||||
|
def _issue_client_command(client_uuid: str, action: str):
|
||||||
|
if action not in ALLOWED_COMMAND_ACTIONS:
|
||||||
|
return jsonify({"error": f"Unsupported action '{action}'"}), 400
|
||||||
|
|
||||||
|
command_action = API_ACTION_TO_COMMAND_ACTION[action]
|
||||||
|
|
||||||
|
data = request.get_json(silent=True) or {}
|
||||||
|
reason = str(data.get("reason", "")).strip() or None
|
||||||
|
requested_by = flask_session.get("user_id")
|
||||||
|
|
||||||
|
now_utc = datetime.now(timezone.utc)
|
||||||
|
expires_at = now_utc + timedelta(seconds=COMMAND_EXPIRY_SECONDS)
|
||||||
|
command_id = str(uuid_lib.uuid4())
|
||||||
|
|
||||||
|
db = Session()
|
||||||
|
try:
|
||||||
|
client = db.query(Client).filter_by(uuid=client_uuid).first()
|
||||||
|
if not client:
|
||||||
|
return jsonify({"error": "Client nicht gefunden"}), 404
|
||||||
|
|
||||||
|
# Safety lockout: avoid rapid repeated reboot loops per client.
|
||||||
|
if command_action in ("reboot_host", "restart_app"):
|
||||||
|
window_start = now_utc - timedelta(minutes=REBOOT_LOCKOUT_WINDOW_MINUTES)
|
||||||
|
recent_reboots = (
|
||||||
|
db.query(ClientCommand)
|
||||||
|
.filter(ClientCommand.client_uuid == client_uuid)
|
||||||
|
.filter(ClientCommand.action.in_(["reboot_host", "restart_app"]))
|
||||||
|
.filter(ClientCommand.created_at >= window_start)
|
||||||
|
.count()
|
||||||
|
)
|
||||||
|
if recent_reboots >= REBOOT_LOCKOUT_THRESHOLD:
|
||||||
|
blocked = ClientCommand(
|
||||||
|
command_id=command_id,
|
||||||
|
client_uuid=client_uuid,
|
||||||
|
action=command_action,
|
||||||
|
status="blocked_safety",
|
||||||
|
reason=reason,
|
||||||
|
requested_by=requested_by,
|
||||||
|
issued_at=now_utc,
|
||||||
|
expires_at=expires_at,
|
||||||
|
failed_at=now_utc,
|
||||||
|
error_code="lockout_threshold",
|
||||||
|
error_message="Reboot lockout active for this client",
|
||||||
|
)
|
||||||
|
db.add(blocked)
|
||||||
|
db.commit()
|
||||||
|
return jsonify({
|
||||||
|
"success": False,
|
||||||
|
"message": "Neustart voruebergehend blockiert (Sicherheits-Lockout)",
|
||||||
|
"command": _command_to_dict(blocked),
|
||||||
|
}), 429
|
||||||
|
|
||||||
|
command = ClientCommand(
|
||||||
|
command_id=command_id,
|
||||||
|
client_uuid=client_uuid,
|
||||||
|
action=command_action,
|
||||||
|
status="queued",
|
||||||
|
reason=reason,
|
||||||
|
requested_by=requested_by,
|
||||||
|
issued_at=now_utc,
|
||||||
|
expires_at=expires_at,
|
||||||
|
)
|
||||||
|
db.add(command)
|
||||||
|
db.commit()
|
||||||
|
|
||||||
|
command.status = "publish_in_progress"
|
||||||
|
db.commit()
|
||||||
|
|
||||||
|
payload = {
|
||||||
|
"schema_version": COMMAND_SCHEMA_VERSION,
|
||||||
|
"command_id": command.command_id,
|
||||||
|
"client_uuid": command.client_uuid,
|
||||||
|
"action": command.action,
|
||||||
|
"issued_at": _iso_utc_z(command.issued_at),
|
||||||
|
"expires_at": _iso_utc_z(command.expires_at),
|
||||||
|
"requested_by": command.requested_by,
|
||||||
|
"reason": command.reason,
|
||||||
|
}
|
||||||
|
|
||||||
|
try:
|
||||||
|
_publish_client_command(client_uuid=client_uuid, action=action, payload=payload)
|
||||||
|
# ACK can arrive very quickly (including terminal failure) while publish is in-flight.
|
||||||
|
# Refresh to avoid regressing a newer listener-updated state back to "published".
|
||||||
|
db.refresh(command)
|
||||||
|
command.published_at = command.published_at or datetime.now(timezone.utc)
|
||||||
|
if command.status in {"queued", "publish_in_progress"}:
|
||||||
|
command.status = "published"
|
||||||
|
db.commit()
|
||||||
|
return jsonify({
|
||||||
|
"success": True,
|
||||||
|
"message": f"Command published for client {client_uuid}",
|
||||||
|
"command": _command_to_dict(command),
|
||||||
|
}), 202
|
||||||
|
except Exception as publish_error:
|
||||||
|
command.status = "failed"
|
||||||
|
command.failed_at = datetime.now(timezone.utc)
|
||||||
|
command.error_code = "mqtt_publish_failed"
|
||||||
|
command.error_message = str(publish_error)
|
||||||
|
db.commit()
|
||||||
|
return jsonify({
|
||||||
|
"success": False,
|
||||||
|
"error": f"Failed to publish command: {publish_error}",
|
||||||
|
"command": _command_to_dict(command),
|
||||||
|
}), 500
|
||||||
|
finally:
|
||||||
|
db.close()
|
||||||
|
|
||||||
|
|
||||||
def _normalize_screenshot_type(raw_type):
|
def _normalize_screenshot_type(raw_type):
|
||||||
if raw_type is None:
|
if raw_type is None:
|
||||||
@@ -280,45 +464,148 @@ def get_clients_with_alive_status():
|
|||||||
"ip": c.ip,
|
"ip": c.ip,
|
||||||
"last_alive": c.last_alive.isoformat() if c.last_alive else None,
|
"last_alive": c.last_alive.isoformat() if c.last_alive else None,
|
||||||
"is_active": c.is_active,
|
"is_active": c.is_active,
|
||||||
"is_alive": bool(c.last_alive and c.is_active),
|
"is_alive": is_client_alive(c.last_alive, c.is_active),
|
||||||
})
|
})
|
||||||
session.close()
|
session.close()
|
||||||
return jsonify(result)
|
return jsonify(result)
|
||||||
|
|
||||||
|
|
||||||
|
@clients_bp.route("/crashed", methods=["GET"])
|
||||||
|
@admin_or_higher
|
||||||
|
def get_crashed_clients():
|
||||||
|
"""Returns clients that are crashed (process_status=crashed) or heartbeat-stale."""
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
from datetime import timedelta
|
||||||
|
grace = get_grace_period()
|
||||||
|
from datetime import datetime, timezone
|
||||||
|
stale_cutoff = datetime.now(timezone.utc) - timedelta(seconds=grace)
|
||||||
|
clients = (
|
||||||
|
session.query(Client)
|
||||||
|
.filter(Client.is_active == True)
|
||||||
|
.all()
|
||||||
|
)
|
||||||
|
result = []
|
||||||
|
for c in clients:
|
||||||
|
alive = is_client_alive(c.last_alive, c.is_active)
|
||||||
|
crashed = c.process_status == ProcessStatus.crashed
|
||||||
|
if not alive or crashed:
|
||||||
|
result.append({
|
||||||
|
"uuid": c.uuid,
|
||||||
|
"description": c.description,
|
||||||
|
"hostname": c.hostname,
|
||||||
|
"ip": c.ip,
|
||||||
|
"group_id": c.group_id,
|
||||||
|
"is_alive": alive,
|
||||||
|
"process_status": c.process_status.value if c.process_status else None,
|
||||||
|
"screen_health_status": c.screen_health_status.value if c.screen_health_status else None,
|
||||||
|
"last_alive": c.last_alive.isoformat() if c.last_alive else None,
|
||||||
|
"crash_reason": "process_crashed" if crashed else "heartbeat_stale",
|
||||||
|
})
|
||||||
|
return jsonify({
|
||||||
|
"crashed_count": len(result),
|
||||||
|
"grace_period_seconds": grace,
|
||||||
|
"clients": result,
|
||||||
|
})
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
@clients_bp.route("/service_failed", methods=["GET"])
|
||||||
|
@admin_or_higher
|
||||||
|
def get_service_failed_clients():
|
||||||
|
"""Returns clients that have a service_failed_at set (systemd gave up restarting)."""
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
clients = (
|
||||||
|
session.query(Client)
|
||||||
|
.filter(Client.service_failed_at.isnot(None))
|
||||||
|
.order_by(Client.service_failed_at.desc())
|
||||||
|
.all()
|
||||||
|
)
|
||||||
|
result = [
|
||||||
|
{
|
||||||
|
"uuid": c.uuid,
|
||||||
|
"description": c.description,
|
||||||
|
"hostname": c.hostname,
|
||||||
|
"ip": c.ip,
|
||||||
|
"group_id": c.group_id,
|
||||||
|
"service_failed_at": c.service_failed_at.isoformat() if c.service_failed_at else None,
|
||||||
|
"service_failed_unit": c.service_failed_unit,
|
||||||
|
"is_alive": is_client_alive(c.last_alive, c.is_active),
|
||||||
|
"last_alive": c.last_alive.isoformat() if c.last_alive else None,
|
||||||
|
}
|
||||||
|
for c in clients
|
||||||
|
]
|
||||||
|
return jsonify({"service_failed_count": len(result), "clients": result})
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
@clients_bp.route("/<client_uuid>/clear_service_failed", methods=["POST"])
|
||||||
|
@admin_or_higher
|
||||||
|
def clear_service_failed(client_uuid):
|
||||||
|
"""Clears the service_failed flag for a client and deletes the retained MQTT message."""
|
||||||
|
import paho.mqtt.client as mqtt_lib
|
||||||
|
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
c = session.query(Client).filter_by(uuid=client_uuid).first()
|
||||||
|
if not c:
|
||||||
|
return jsonify({"error": "Client nicht gefunden"}), 404
|
||||||
|
if c.service_failed_at is None:
|
||||||
|
return jsonify({"success": True, "message": "Kein service_failed Flag gesetzt."}), 200
|
||||||
|
|
||||||
|
c.service_failed_at = None
|
||||||
|
c.service_failed_unit = None
|
||||||
|
session.commit()
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
# Clear the retained MQTT message (publish empty payload, retained=True)
|
||||||
|
try:
|
||||||
|
broker_host = os.getenv("MQTT_BROKER_HOST", "mqtt")
|
||||||
|
broker_port = int(os.getenv("MQTT_BROKER_PORT", 1883))
|
||||||
|
username = os.getenv("MQTT_USER")
|
||||||
|
password = os.getenv("MQTT_PASSWORD")
|
||||||
|
mc = mqtt_lib.Client()
|
||||||
|
if username and password:
|
||||||
|
mc.username_pw_set(username, password)
|
||||||
|
mc.connect(broker_host, broker_port)
|
||||||
|
topic = f"infoscreen/{client_uuid}/service_failed"
|
||||||
|
mc.publish(topic, payload=None, qos=1, retain=True)
|
||||||
|
mc.disconnect()
|
||||||
|
except Exception as e:
|
||||||
|
# Log but don't fail — DB is already cleared
|
||||||
|
import logging
|
||||||
|
logging.warning(f"Could not clear retained service_failed MQTT message for {client_uuid}: {e}")
|
||||||
|
|
||||||
|
return jsonify({"success": True, "message": "service_failed Flag gelöscht."})
|
||||||
|
|
||||||
|
|
||||||
@clients_bp.route("/<uuid>/restart", methods=["POST"])
|
@clients_bp.route("/<uuid>/restart", methods=["POST"])
|
||||||
@admin_or_higher
|
@admin_or_higher
|
||||||
def restart_client(uuid):
|
def restart_client(uuid):
|
||||||
"""
|
return _issue_client_command(client_uuid=uuid, action="restart")
|
||||||
Route to restart a specific client by UUID.
|
|
||||||
Sends an MQTT message to the broker to trigger the restart.
|
|
||||||
"""
|
|
||||||
import paho.mqtt.client as mqtt
|
|
||||||
import json
|
|
||||||
|
|
||||||
# MQTT broker configuration
|
|
||||||
MQTT_BROKER = "mqtt"
|
|
||||||
MQTT_PORT = 1883
|
|
||||||
MQTT_TOPIC = f"clients/{uuid}/restart"
|
|
||||||
|
|
||||||
# Connect to the database to check if the client exists
|
@clients_bp.route("/<uuid>/shutdown", methods=["POST"])
|
||||||
session = Session()
|
@admin_or_higher
|
||||||
client = session.query(Client).filter_by(uuid=uuid).first()
|
def shutdown_client(uuid):
|
||||||
if not client:
|
return _issue_client_command(client_uuid=uuid, action="shutdown")
|
||||||
session.close()
|
|
||||||
return jsonify({"error": "Client nicht gefunden"}), 404
|
|
||||||
session.close()
|
|
||||||
|
|
||||||
# Send MQTT message
|
|
||||||
|
@clients_bp.route("/commands/<command_id>", methods=["GET"])
|
||||||
|
@admin_or_higher
|
||||||
|
def get_client_command_status(command_id):
|
||||||
|
db = Session()
|
||||||
try:
|
try:
|
||||||
mqtt_client = mqtt.Client()
|
command = db.query(ClientCommand).filter_by(command_id=command_id).first()
|
||||||
mqtt_client.connect(MQTT_BROKER, MQTT_PORT)
|
if not command:
|
||||||
payload = {"action": "restart"}
|
return jsonify({"error": "Command nicht gefunden"}), 404
|
||||||
mqtt_client.publish(MQTT_TOPIC, json.dumps(payload))
|
return jsonify(_command_to_dict(command)), 200
|
||||||
mqtt_client.disconnect()
|
finally:
|
||||||
return jsonify({"success": True, "message": f"Restart signal sent to client {uuid}"}), 200
|
db.close()
|
||||||
except Exception as e:
|
|
||||||
return jsonify({"error": f"Failed to send MQTT message: {str(e)}"}), 500
|
|
||||||
|
|
||||||
|
|
||||||
@clients_bp.route("/<uuid>/screenshot", methods=["POST"])
|
@clients_bp.route("/<uuid>/screenshot", methods=["POST"])
|
||||||
|
|||||||
@@ -487,7 +487,16 @@ def create_event():
|
|||||||
if not (ev.skip_holidays and ev.recurrence_rule):
|
if not (ev.skip_holidays and ev.recurrence_rule):
|
||||||
return
|
return
|
||||||
# Get holidays
|
# Get holidays
|
||||||
holidays = session.query(SchoolHoliday).all()
|
holidays_query = session.query(SchoolHoliday)
|
||||||
|
if ev.academic_period_id is not None:
|
||||||
|
holidays_query = holidays_query.filter(
|
||||||
|
SchoolHoliday.academic_period_id == ev.academic_period_id
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
holidays_query = holidays_query.filter(
|
||||||
|
SchoolHoliday.academic_period_id.is_(None)
|
||||||
|
)
|
||||||
|
holidays = holidays_query.all()
|
||||||
dtstart = ev.start.astimezone(UTC)
|
dtstart = ev.start.astimezone(UTC)
|
||||||
r = rrulestr(ev.recurrence_rule, dtstart=dtstart)
|
r = rrulestr(ev.recurrence_rule, dtstart=dtstart)
|
||||||
window_start = dtstart
|
window_start = dtstart
|
||||||
@@ -588,7 +597,16 @@ def update_event(event_id):
|
|||||||
if not (ev.skip_holidays and ev.recurrence_rule):
|
if not (ev.skip_holidays and ev.recurrence_rule):
|
||||||
return
|
return
|
||||||
# Get holidays
|
# Get holidays
|
||||||
holidays = session.query(SchoolHoliday).all()
|
holidays_query = session.query(SchoolHoliday)
|
||||||
|
if ev.academic_period_id is not None:
|
||||||
|
holidays_query = holidays_query.filter(
|
||||||
|
SchoolHoliday.academic_period_id == ev.academic_period_id
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
holidays_query = holidays_query.filter(
|
||||||
|
SchoolHoliday.academic_period_id.is_(None)
|
||||||
|
)
|
||||||
|
holidays = holidays_query.all()
|
||||||
dtstart = ev.start.astimezone(UTC)
|
dtstart = ev.start.astimezone(UTC)
|
||||||
r = rrulestr(ev.recurrence_rule, dtstart=dtstart)
|
r = rrulestr(ev.recurrence_rule, dtstart=dtstart)
|
||||||
window_start = dtstart
|
window_start = dtstart
|
||||||
|
|||||||
@@ -1,25 +1,203 @@
|
|||||||
from flask import Blueprint, request, jsonify
|
from flask import Blueprint, request, jsonify
|
||||||
from server.permissions import admin_or_higher
|
from server.permissions import admin_or_higher
|
||||||
from server.database import Session
|
from server.database import Session
|
||||||
from models.models import SchoolHoliday
|
from models.models import AcademicPeriod, SchoolHoliday, Event, EventException
|
||||||
from datetime import datetime
|
from datetime import datetime, date, timedelta
|
||||||
|
from sqlalchemy import func
|
||||||
|
from sqlalchemy.exc import IntegrityError
|
||||||
import csv
|
import csv
|
||||||
import io
|
import io
|
||||||
|
|
||||||
holidays_bp = Blueprint("holidays", __name__, url_prefix="/api/holidays")
|
holidays_bp = Blueprint("holidays", __name__, url_prefix="/api/holidays")
|
||||||
|
|
||||||
|
|
||||||
|
def _regenerate_for_period(session, academic_period_id) -> int:
|
||||||
|
"""Re-generate holiday skip exceptions for all skip_holidays recurring events in the period."""
|
||||||
|
from dateutil.rrule import rrulestr
|
||||||
|
from dateutil.tz import UTC
|
||||||
|
|
||||||
|
q = session.query(Event).filter(
|
||||||
|
Event.skip_holidays == True, # noqa: E712
|
||||||
|
Event.recurrence_rule.isnot(None),
|
||||||
|
)
|
||||||
|
if academic_period_id is not None:
|
||||||
|
q = q.filter(Event.academic_period_id == academic_period_id)
|
||||||
|
else:
|
||||||
|
q = q.filter(Event.academic_period_id.is_(None))
|
||||||
|
events = q.all()
|
||||||
|
|
||||||
|
hq = session.query(SchoolHoliday)
|
||||||
|
if academic_period_id is not None:
|
||||||
|
hq = hq.filter(SchoolHoliday.academic_period_id == academic_period_id)
|
||||||
|
else:
|
||||||
|
hq = hq.filter(SchoolHoliday.academic_period_id.is_(None))
|
||||||
|
holidays = hq.all()
|
||||||
|
|
||||||
|
holiday_dates = set()
|
||||||
|
for h in holidays:
|
||||||
|
d = h.start_date
|
||||||
|
while d <= h.end_date:
|
||||||
|
holiday_dates.add(d)
|
||||||
|
d = d + timedelta(days=1)
|
||||||
|
|
||||||
|
for ev in events:
|
||||||
|
session.query(EventException).filter(
|
||||||
|
EventException.event_id == ev.id,
|
||||||
|
EventException.is_skipped == True, # noqa: E712
|
||||||
|
EventException.override_title.is_(None),
|
||||||
|
EventException.override_description.is_(None),
|
||||||
|
EventException.override_start.is_(None),
|
||||||
|
EventException.override_end.is_(None),
|
||||||
|
).delete(synchronize_session=False)
|
||||||
|
if not holiday_dates:
|
||||||
|
continue
|
||||||
|
try:
|
||||||
|
dtstart = ev.start.astimezone(UTC)
|
||||||
|
r = rrulestr(ev.recurrence_rule, dtstart=dtstart)
|
||||||
|
window_start = dtstart
|
||||||
|
window_end = (
|
||||||
|
ev.recurrence_end.astimezone(UTC)
|
||||||
|
if ev.recurrence_end
|
||||||
|
else dtstart.replace(year=dtstart.year + 1)
|
||||||
|
)
|
||||||
|
for occ_start in r.between(window_start, window_end, inc=True):
|
||||||
|
occ_date = occ_start.date()
|
||||||
|
if occ_date in holiday_dates:
|
||||||
|
session.add(EventException(
|
||||||
|
event_id=ev.id,
|
||||||
|
exception_date=occ_date,
|
||||||
|
is_skipped=True,
|
||||||
|
))
|
||||||
|
except Exception:
|
||||||
|
pass # malformed recurrence rule — skip silently
|
||||||
|
|
||||||
|
return len(events)
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_academic_period_id(raw_value):
|
||||||
|
if raw_value in (None, ""):
|
||||||
|
return None
|
||||||
|
try:
|
||||||
|
return int(raw_value)
|
||||||
|
except (TypeError, ValueError) as exc:
|
||||||
|
raise ValueError("Invalid academicPeriodId") from exc
|
||||||
|
|
||||||
|
|
||||||
|
def _validate_holiday_dates_within_period(period, start_date, end_date, label="Ferienblock"):
|
||||||
|
if period is None or start_date is None or end_date is None:
|
||||||
|
return
|
||||||
|
if start_date < period.start_date or end_date > period.end_date:
|
||||||
|
period_name = period.display_name or period.name
|
||||||
|
raise ValueError(
|
||||||
|
f"{label} liegt außerhalb der akademischen Periode \"{period_name}\" "
|
||||||
|
f"({period.start_date.isoformat()} bis {period.end_date.isoformat()})"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _normalize_optional_text(value):
|
||||||
|
normalized = (value or "").strip()
|
||||||
|
return normalized or None
|
||||||
|
|
||||||
|
|
||||||
|
def _apply_period_filter(query, academic_period_id):
|
||||||
|
if academic_period_id is None:
|
||||||
|
return query.filter(SchoolHoliday.academic_period_id.is_(None))
|
||||||
|
return query.filter(SchoolHoliday.academic_period_id == academic_period_id)
|
||||||
|
|
||||||
|
|
||||||
|
def _identity_key(name, region):
|
||||||
|
normalized_name = _normalize_optional_text(name) or ""
|
||||||
|
normalized_region = _normalize_optional_text(region) or ""
|
||||||
|
return normalized_name.casefold(), normalized_region.casefold()
|
||||||
|
|
||||||
|
|
||||||
|
def _is_same_identity(holiday, name, region):
|
||||||
|
return _identity_key(holiday.name, holiday.region) == _identity_key(name, region)
|
||||||
|
|
||||||
|
|
||||||
|
def _find_overlapping_holidays(session, academic_period_id, start_date, end_date, exclude_id=None):
|
||||||
|
query = _apply_period_filter(session.query(SchoolHoliday), academic_period_id).filter(
|
||||||
|
SchoolHoliday.start_date <= end_date + timedelta(days=1),
|
||||||
|
SchoolHoliday.end_date >= start_date - timedelta(days=1),
|
||||||
|
)
|
||||||
|
if exclude_id is not None:
|
||||||
|
query = query.filter(SchoolHoliday.id != exclude_id)
|
||||||
|
return query.order_by(SchoolHoliday.start_date.asc(), SchoolHoliday.id.asc()).all()
|
||||||
|
|
||||||
|
|
||||||
|
def _split_overlap_candidates(overlaps, name, region):
|
||||||
|
same_identity = [holiday for holiday in overlaps if _is_same_identity(holiday, name, region)]
|
||||||
|
conflicts = [holiday for holiday in overlaps if not _is_same_identity(holiday, name, region)]
|
||||||
|
return same_identity, conflicts
|
||||||
|
|
||||||
|
|
||||||
|
def _merge_holiday_group(session, keeper, others, name, start_date, end_date, region, source_file_name=None):
|
||||||
|
all_starts = [start_date, keeper.start_date, *[holiday.start_date for holiday in others]]
|
||||||
|
all_ends = [end_date, keeper.end_date, *[holiday.end_date for holiday in others]]
|
||||||
|
keeper.name = _normalize_optional_text(name) or keeper.name
|
||||||
|
keeper.region = _normalize_optional_text(region)
|
||||||
|
keeper.start_date = min(all_starts)
|
||||||
|
keeper.end_date = max(all_ends)
|
||||||
|
if source_file_name is not None:
|
||||||
|
keeper.source_file_name = source_file_name
|
||||||
|
for holiday in others:
|
||||||
|
session.delete(holiday)
|
||||||
|
return keeper
|
||||||
|
|
||||||
|
|
||||||
|
def _format_overlap_conflict(label, conflicts):
|
||||||
|
conflict_labels = ", ".join(
|
||||||
|
f'{holiday.name} ({holiday.start_date.isoformat()} bis {holiday.end_date.isoformat()})'
|
||||||
|
for holiday in conflicts[:3]
|
||||||
|
)
|
||||||
|
suffix = "" if len(conflicts) <= 3 else f" und {len(conflicts) - 3} weitere"
|
||||||
|
return f"{label} überschneidet sich mit bestehenden Ferienblöcken: {conflict_labels}{suffix}"
|
||||||
|
|
||||||
|
|
||||||
|
def _find_duplicate_holiday(session, academic_period_id, name, start_date, end_date, region, exclude_id=None):
|
||||||
|
normalized_name = _normalize_optional_text(name)
|
||||||
|
normalized_region = _normalize_optional_text(region)
|
||||||
|
|
||||||
|
query = session.query(SchoolHoliday).filter(
|
||||||
|
func.lower(SchoolHoliday.name) == normalized_name.casefold(),
|
||||||
|
SchoolHoliday.start_date == start_date,
|
||||||
|
SchoolHoliday.end_date == end_date,
|
||||||
|
)
|
||||||
|
query = _apply_period_filter(query, academic_period_id)
|
||||||
|
|
||||||
|
if normalized_region is None:
|
||||||
|
query = query.filter(SchoolHoliday.region.is_(None))
|
||||||
|
else:
|
||||||
|
query = query.filter(func.lower(SchoolHoliday.region) == normalized_region.casefold())
|
||||||
|
|
||||||
|
if exclude_id is not None:
|
||||||
|
query = query.filter(SchoolHoliday.id != exclude_id)
|
||||||
|
|
||||||
|
return query.first()
|
||||||
|
|
||||||
|
|
||||||
@holidays_bp.route("", methods=["GET"])
|
@holidays_bp.route("", methods=["GET"])
|
||||||
def list_holidays():
|
def list_holidays():
|
||||||
session = Session()
|
session = Session()
|
||||||
region = request.args.get("region")
|
try:
|
||||||
q = session.query(SchoolHoliday)
|
region = request.args.get("region")
|
||||||
if region:
|
academic_period_id = _parse_academic_period_id(
|
||||||
q = q.filter(SchoolHoliday.region == region)
|
request.args.get("academicPeriodId") or request.args.get("academic_period_id")
|
||||||
rows = q.order_by(SchoolHoliday.start_date.asc()).all()
|
)
|
||||||
data = [r.to_dict() for r in rows]
|
|
||||||
session.close()
|
q = session.query(SchoolHoliday)
|
||||||
return jsonify({"holidays": data})
|
if region:
|
||||||
|
q = q.filter(SchoolHoliday.region == region)
|
||||||
|
if academic_period_id is not None:
|
||||||
|
q = q.filter(SchoolHoliday.academic_period_id == academic_period_id)
|
||||||
|
|
||||||
|
rows = q.order_by(SchoolHoliday.start_date.asc(), SchoolHoliday.end_date.asc()).all()
|
||||||
|
data = [r.to_dict() for r in rows]
|
||||||
|
return jsonify({"holidays": data})
|
||||||
|
except ValueError as exc:
|
||||||
|
return jsonify({"error": str(exc)}), 400
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
@holidays_bp.route("/upload", methods=["POST"])
|
@holidays_bp.route("/upload", methods=["POST"])
|
||||||
@@ -41,6 +219,7 @@ def upload_holidays():
|
|||||||
if file.filename == "":
|
if file.filename == "":
|
||||||
return jsonify({"error": "No selected file"}), 400
|
return jsonify({"error": "No selected file"}), 400
|
||||||
|
|
||||||
|
session = Session()
|
||||||
try:
|
try:
|
||||||
raw = file.read()
|
raw = file.read()
|
||||||
# Try UTF-8 first (strict), then cp1252, then latin-1 as last resort
|
# Try UTF-8 first (strict), then cp1252, then latin-1 as last resort
|
||||||
@@ -79,9 +258,35 @@ def upload_holidays():
|
|||||||
continue
|
continue
|
||||||
raise ValueError(f"Unsupported date format: {s}")
|
raise ValueError(f"Unsupported date format: {s}")
|
||||||
|
|
||||||
session = Session()
|
academic_period_id = _parse_academic_period_id(
|
||||||
|
request.form.get("academicPeriodId") or request.form.get("academic_period_id")
|
||||||
|
)
|
||||||
|
|
||||||
|
period = None
|
||||||
|
if academic_period_id is not None:
|
||||||
|
period = session.query(AcademicPeriod).get(academic_period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({"error": "Academic period not found"}), 404
|
||||||
|
if period.is_archived:
|
||||||
|
return jsonify({"error": "Cannot import holidays into an archived academic period"}), 409
|
||||||
|
|
||||||
inserted = 0
|
inserted = 0
|
||||||
updated = 0
|
updated = 0
|
||||||
|
merged_overlaps = 0
|
||||||
|
skipped_duplicates = 0
|
||||||
|
conflicts = []
|
||||||
|
|
||||||
|
def build_exact_key(name, start_date, end_date, region):
|
||||||
|
normalized_name = _normalize_optional_text(name)
|
||||||
|
normalized_region = _normalize_optional_text(region)
|
||||||
|
return (
|
||||||
|
(normalized_name or "").casefold(),
|
||||||
|
start_date,
|
||||||
|
end_date,
|
||||||
|
(normalized_region or "").casefold(),
|
||||||
|
)
|
||||||
|
|
||||||
|
seen_in_file = set()
|
||||||
|
|
||||||
# First, try headered CSV via DictReader
|
# First, try headered CSV via DictReader
|
||||||
dict_reader = csv.DictReader(io.StringIO(
|
dict_reader = csv.DictReader(io.StringIO(
|
||||||
@@ -90,34 +295,67 @@ def upload_holidays():
|
|||||||
has_required_headers = {"name", "start_date",
|
has_required_headers = {"name", "start_date",
|
||||||
"end_date"}.issubset(set(fieldnames_lower))
|
"end_date"}.issubset(set(fieldnames_lower))
|
||||||
|
|
||||||
def upsert(name: str, start_date, end_date, region=None):
|
def upsert(name: str, start_date, end_date, region=None, source_label="Ferienblock"):
|
||||||
nonlocal inserted, updated
|
nonlocal inserted, updated, merged_overlaps, skipped_duplicates
|
||||||
if not name or not start_date or not end_date:
|
if not name or not start_date or not end_date:
|
||||||
return
|
return
|
||||||
existing = (
|
_validate_holiday_dates_within_period(period, start_date, end_date, source_label)
|
||||||
session.query(SchoolHoliday)
|
normalized_name = _normalize_optional_text(name)
|
||||||
.filter(
|
normalized_region = _normalize_optional_text(region)
|
||||||
SchoolHoliday.name == name,
|
key = build_exact_key(normalized_name, start_date, end_date, normalized_region)
|
||||||
SchoolHoliday.start_date == start_date,
|
|
||||||
SchoolHoliday.end_date == end_date,
|
if key in seen_in_file:
|
||||||
SchoolHoliday.region.is_(
|
skipped_duplicates += 1
|
||||||
region) if region is None else SchoolHoliday.region == region,
|
return
|
||||||
)
|
seen_in_file.add(key)
|
||||||
.first()
|
|
||||||
|
duplicate = _find_duplicate_holiday(
|
||||||
|
session,
|
||||||
|
academic_period_id,
|
||||||
|
normalized_name,
|
||||||
|
start_date,
|
||||||
|
end_date,
|
||||||
|
normalized_region,
|
||||||
)
|
)
|
||||||
if existing:
|
if duplicate:
|
||||||
existing.region = region
|
duplicate.source_file_name = file.filename
|
||||||
existing.source_file_name = file.filename
|
|
||||||
updated += 1
|
updated += 1
|
||||||
else:
|
return
|
||||||
session.add(SchoolHoliday(
|
|
||||||
name=name,
|
overlaps = _find_overlapping_holidays(
|
||||||
start_date=start_date,
|
session,
|
||||||
end_date=end_date,
|
academic_period_id,
|
||||||
region=region,
|
start_date,
|
||||||
|
end_date,
|
||||||
|
)
|
||||||
|
same_identity, conflicting = _split_overlap_candidates(overlaps, normalized_name, normalized_region)
|
||||||
|
if conflicting:
|
||||||
|
conflicts.append(_format_overlap_conflict(source_label, conflicting))
|
||||||
|
return
|
||||||
|
if same_identity:
|
||||||
|
keeper = same_identity[0]
|
||||||
|
_merge_holiday_group(
|
||||||
|
session,
|
||||||
|
keeper,
|
||||||
|
same_identity[1:],
|
||||||
|
normalized_name,
|
||||||
|
start_date,
|
||||||
|
end_date,
|
||||||
|
normalized_region,
|
||||||
source_file_name=file.filename,
|
source_file_name=file.filename,
|
||||||
))
|
)
|
||||||
inserted += 1
|
merged_overlaps += 1
|
||||||
|
return
|
||||||
|
|
||||||
|
session.add(SchoolHoliday(
|
||||||
|
academic_period_id=academic_period_id,
|
||||||
|
name=normalized_name,
|
||||||
|
start_date=start_date,
|
||||||
|
end_date=end_date,
|
||||||
|
region=normalized_region,
|
||||||
|
source_file_name=file.filename,
|
||||||
|
))
|
||||||
|
inserted += 1
|
||||||
|
|
||||||
if has_required_headers:
|
if has_required_headers:
|
||||||
for row in dict_reader:
|
for row in dict_reader:
|
||||||
@@ -131,12 +369,12 @@ def upload_holidays():
|
|||||||
continue
|
continue
|
||||||
region = (norm.get("region")
|
region = (norm.get("region")
|
||||||
or None) if "region" in norm else None
|
or None) if "region" in norm else None
|
||||||
upsert(name, start_date, end_date, region)
|
upsert(name, start_date, end_date, region, f"Zeile {dict_reader.line_num}")
|
||||||
else:
|
else:
|
||||||
# Fallback: headerless rows -> use columns [1]=name, [2]=start, [3]=end
|
# Fallback: headerless rows -> use columns [1]=name, [2]=start, [3]=end
|
||||||
reader = csv.reader(io.StringIO(
|
reader = csv.reader(io.StringIO(
|
||||||
content), dialect=dialect) if dialect else csv.reader(io.StringIO(content))
|
content), dialect=dialect) if dialect else csv.reader(io.StringIO(content))
|
||||||
for row in reader:
|
for row_index, row in enumerate(reader, start=1):
|
||||||
if not row:
|
if not row:
|
||||||
continue
|
continue
|
||||||
# tolerate varying column counts (4 or 5); ignore first and optional last
|
# tolerate varying column counts (4 or 5); ignore first and optional last
|
||||||
@@ -152,10 +390,214 @@ def upload_holidays():
|
|||||||
end_date = parse_date(end_raw)
|
end_date = parse_date(end_raw)
|
||||||
except ValueError:
|
except ValueError:
|
||||||
continue
|
continue
|
||||||
upsert(name, start_date, end_date, None)
|
upsert(name, start_date, end_date, None, f"Zeile {row_index}")
|
||||||
|
|
||||||
session.commit()
|
session.commit()
|
||||||
session.close()
|
return jsonify({
|
||||||
return jsonify({"success": True, "inserted": inserted, "updated": updated})
|
"success": True,
|
||||||
except Exception as e:
|
"inserted": inserted,
|
||||||
|
"updated": updated,
|
||||||
|
"merged_overlaps": merged_overlaps,
|
||||||
|
"skipped_duplicates": skipped_duplicates,
|
||||||
|
"conflicts": conflicts,
|
||||||
|
"academic_period_id": academic_period_id,
|
||||||
|
})
|
||||||
|
except ValueError as e:
|
||||||
|
session.rollback()
|
||||||
return jsonify({"error": str(e)}), 400
|
return jsonify({"error": str(e)}), 400
|
||||||
|
except Exception as e:
|
||||||
|
session.rollback()
|
||||||
|
return jsonify({"error": str(e)}), 400
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
@holidays_bp.route("", methods=["POST"])
|
||||||
|
@admin_or_higher
|
||||||
|
def create_holiday():
|
||||||
|
data = request.json or {}
|
||||||
|
name = _normalize_optional_text(data.get("name")) or ""
|
||||||
|
start_date_str = (data.get("start_date") or "").strip()
|
||||||
|
end_date_str = (data.get("end_date") or "").strip()
|
||||||
|
region = _normalize_optional_text(data.get("region"))
|
||||||
|
|
||||||
|
if not name or not start_date_str or not end_date_str:
|
||||||
|
return jsonify({"error": "name, start_date und end_date sind erforderlich"}), 400
|
||||||
|
try:
|
||||||
|
start_date_val = date.fromisoformat(start_date_str)
|
||||||
|
end_date_val = date.fromisoformat(end_date_str)
|
||||||
|
except ValueError:
|
||||||
|
return jsonify({"error": "Ung\u00fcltiges Datumsformat. Erwartet: YYYY-MM-DD"}), 400
|
||||||
|
if end_date_val < start_date_val:
|
||||||
|
return jsonify({"error": "Enddatum muss nach oder gleich Startdatum sein"}), 400
|
||||||
|
|
||||||
|
academic_period_id = _parse_academic_period_id(data.get("academic_period_id"))
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
period = None
|
||||||
|
if academic_period_id is not None:
|
||||||
|
period = session.query(AcademicPeriod).get(academic_period_id)
|
||||||
|
if not period:
|
||||||
|
return jsonify({"error": "Akademische Periode nicht gefunden"}), 404
|
||||||
|
if period.is_archived:
|
||||||
|
return jsonify({"error": "Archivierte Perioden k\u00f6nnen nicht bearbeitet werden"}), 409
|
||||||
|
_validate_holiday_dates_within_period(period, start_date_val, end_date_val)
|
||||||
|
duplicate = _find_duplicate_holiday(
|
||||||
|
session,
|
||||||
|
academic_period_id,
|
||||||
|
name,
|
||||||
|
start_date_val,
|
||||||
|
end_date_val,
|
||||||
|
region,
|
||||||
|
)
|
||||||
|
if duplicate:
|
||||||
|
return jsonify({"error": "Ein Ferienblock mit diesem Namen und Zeitraum existiert bereits in dieser Periode"}), 409
|
||||||
|
overlaps = _find_overlapping_holidays(session, academic_period_id, start_date_val, end_date_val)
|
||||||
|
same_identity, conflicting = _split_overlap_candidates(overlaps, name, region)
|
||||||
|
if conflicting:
|
||||||
|
return jsonify({"error": _format_overlap_conflict("Der Ferienblock", conflicting)}), 409
|
||||||
|
merged = False
|
||||||
|
if same_identity:
|
||||||
|
holiday = _merge_holiday_group(
|
||||||
|
session,
|
||||||
|
same_identity[0],
|
||||||
|
same_identity[1:],
|
||||||
|
name,
|
||||||
|
start_date_val,
|
||||||
|
end_date_val,
|
||||||
|
region,
|
||||||
|
source_file_name="manual",
|
||||||
|
)
|
||||||
|
merged = True
|
||||||
|
else:
|
||||||
|
holiday = SchoolHoliday(
|
||||||
|
academic_period_id=academic_period_id,
|
||||||
|
name=name,
|
||||||
|
start_date=start_date_val,
|
||||||
|
end_date=end_date_val,
|
||||||
|
region=region,
|
||||||
|
source_file_name="manual",
|
||||||
|
)
|
||||||
|
session.add(holiday)
|
||||||
|
session.flush()
|
||||||
|
regenerated = _regenerate_for_period(session, academic_period_id)
|
||||||
|
session.commit()
|
||||||
|
return jsonify({"success": True, "holiday": holiday.to_dict(), "regenerated_events": regenerated, "merged": merged}), 201
|
||||||
|
except IntegrityError:
|
||||||
|
session.rollback()
|
||||||
|
return jsonify({"error": "Ein Ferienblock mit diesem Namen und Zeitraum existiert bereits in dieser Periode"}), 409
|
||||||
|
except ValueError as e:
|
||||||
|
session.rollback()
|
||||||
|
return jsonify({"error": str(e)}), 400
|
||||||
|
except Exception as e:
|
||||||
|
session.rollback()
|
||||||
|
return jsonify({"error": str(e)}), 400
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
@holidays_bp.route("/<int:holiday_id>", methods=["PUT"])
|
||||||
|
@admin_or_higher
|
||||||
|
def update_holiday(holiday_id):
|
||||||
|
data = request.json or {}
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
holiday = session.query(SchoolHoliday).get(holiday_id)
|
||||||
|
if not holiday:
|
||||||
|
return jsonify({"error": "Ferienblock nicht gefunden"}), 404
|
||||||
|
period = None
|
||||||
|
if holiday.academic_period_id is not None:
|
||||||
|
period = session.query(AcademicPeriod).get(holiday.academic_period_id)
|
||||||
|
if period and period.is_archived:
|
||||||
|
return jsonify({"error": "Archivierte Perioden k\u00f6nnen nicht bearbeitet werden"}), 409
|
||||||
|
if "name" in data:
|
||||||
|
holiday.name = _normalize_optional_text(data["name"]) or ""
|
||||||
|
if "start_date" in data:
|
||||||
|
try:
|
||||||
|
holiday.start_date = date.fromisoformat((data["start_date"] or "").strip())
|
||||||
|
except ValueError:
|
||||||
|
return jsonify({"error": "Ung\u00fcltiges Startdatum. Erwartet: YYYY-MM-DD"}), 400
|
||||||
|
if "end_date" in data:
|
||||||
|
try:
|
||||||
|
holiday.end_date = date.fromisoformat((data["end_date"] or "").strip())
|
||||||
|
except ValueError:
|
||||||
|
return jsonify({"error": "Ung\u00fcltiges Enddatum. Erwartet: YYYY-MM-DD"}), 400
|
||||||
|
if "region" in data:
|
||||||
|
holiday.region = _normalize_optional_text(data["region"])
|
||||||
|
if not holiday.name:
|
||||||
|
return jsonify({"error": "Name darf nicht leer sein"}), 400
|
||||||
|
if holiday.end_date < holiday.start_date:
|
||||||
|
return jsonify({"error": "Enddatum muss nach oder gleich Startdatum sein"}), 400
|
||||||
|
_validate_holiday_dates_within_period(period, holiday.start_date, holiday.end_date)
|
||||||
|
duplicate = _find_duplicate_holiday(
|
||||||
|
session,
|
||||||
|
holiday.academic_period_id,
|
||||||
|
holiday.name,
|
||||||
|
holiday.start_date,
|
||||||
|
holiday.end_date,
|
||||||
|
holiday.region,
|
||||||
|
exclude_id=holiday.id,
|
||||||
|
)
|
||||||
|
if duplicate:
|
||||||
|
return jsonify({"error": "Ein Ferienblock mit diesem Namen und Zeitraum existiert bereits in dieser Periode"}), 409
|
||||||
|
overlaps = _find_overlapping_holidays(
|
||||||
|
session,
|
||||||
|
holiday.academic_period_id,
|
||||||
|
holiday.start_date,
|
||||||
|
holiday.end_date,
|
||||||
|
exclude_id=holiday.id,
|
||||||
|
)
|
||||||
|
same_identity, conflicting = _split_overlap_candidates(overlaps, holiday.name, holiday.region)
|
||||||
|
if conflicting:
|
||||||
|
return jsonify({"error": _format_overlap_conflict("Der Ferienblock", conflicting)}), 409
|
||||||
|
merged = False
|
||||||
|
if same_identity:
|
||||||
|
_merge_holiday_group(
|
||||||
|
session,
|
||||||
|
holiday,
|
||||||
|
same_identity,
|
||||||
|
holiday.name,
|
||||||
|
holiday.start_date,
|
||||||
|
holiday.end_date,
|
||||||
|
holiday.region,
|
||||||
|
source_file_name="manual",
|
||||||
|
)
|
||||||
|
merged = True
|
||||||
|
session.flush()
|
||||||
|
academic_period_id = holiday.academic_period_id
|
||||||
|
regenerated = _regenerate_for_period(session, academic_period_id)
|
||||||
|
session.commit()
|
||||||
|
return jsonify({"success": True, "holiday": holiday.to_dict(), "regenerated_events": regenerated, "merged": merged})
|
||||||
|
except IntegrityError:
|
||||||
|
session.rollback()
|
||||||
|
return jsonify({"error": "Ein Ferienblock mit diesem Namen und Zeitraum existiert bereits in dieser Periode"}), 409
|
||||||
|
except Exception as e:
|
||||||
|
session.rollback()
|
||||||
|
return jsonify({"error": str(e)}), 400
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|
||||||
|
|
||||||
|
@holidays_bp.route("/<int:holiday_id>", methods=["DELETE"])
|
||||||
|
@admin_or_higher
|
||||||
|
def delete_holiday(holiday_id):
|
||||||
|
session = Session()
|
||||||
|
try:
|
||||||
|
holiday = session.query(SchoolHoliday).get(holiday_id)
|
||||||
|
if not holiday:
|
||||||
|
return jsonify({"error": "Ferienblock nicht gefunden"}), 404
|
||||||
|
if holiday.academic_period_id is not None:
|
||||||
|
period = session.query(AcademicPeriod).get(holiday.academic_period_id)
|
||||||
|
if period and period.is_archived:
|
||||||
|
return jsonify({"error": "Archivierte Perioden k\u00f6nnen nicht bearbeitet werden"}), 409
|
||||||
|
academic_period_id = holiday.academic_period_id
|
||||||
|
session.delete(holiday)
|
||||||
|
session.flush()
|
||||||
|
regenerated = _regenerate_for_period(session, academic_period_id)
|
||||||
|
session.commit()
|
||||||
|
return jsonify({"success": True, "regenerated_events": regenerated})
|
||||||
|
except Exception as e:
|
||||||
|
session.rollback()
|
||||||
|
return jsonify({"error": str(e)}), 400
|
||||||
|
finally:
|
||||||
|
session.close()
|
||||||
|
|||||||
365
test_power_intent_canary.py
Normal file
365
test_power_intent_canary.py
Normal file
@@ -0,0 +1,365 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Manual canary validation helper for TV power-intent Phase 1 server publishing.
|
||||||
|
|
||||||
|
This script demonstrates expected power-intent payloads and validates the
|
||||||
|
computation and publishing logic without requiring a full broker connection.
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python test_power_intent_canary.py
|
||||||
|
"""
|
||||||
|
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
from datetime import datetime, timedelta, timezone
|
||||||
|
from unittest.mock import MagicMock, patch
|
||||||
|
|
||||||
|
sys.path.insert(0, '/workspace')
|
||||||
|
|
||||||
|
from scheduler.db_utils import (
|
||||||
|
compute_group_power_intent_basis,
|
||||||
|
build_group_power_intent_body,
|
||||||
|
compute_group_power_intent_fingerprint,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def utc_now():
|
||||||
|
"""Get UTC now."""
|
||||||
|
return datetime.now(timezone.utc)
|
||||||
|
|
||||||
|
|
||||||
|
def test_scenario_1_no_active_events():
|
||||||
|
"""Scenario 1: No active events => OFF intent."""
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("SCENARIO 1: No active events => desired_state=OFF")
|
||||||
|
print("="*70)
|
||||||
|
|
||||||
|
now = utc_now()
|
||||||
|
events = [] # empty group
|
||||||
|
group_id = 1
|
||||||
|
|
||||||
|
intent_basis = compute_group_power_intent_basis(
|
||||||
|
events=events,
|
||||||
|
group_id=group_id,
|
||||||
|
now_utc=now
|
||||||
|
)
|
||||||
|
|
||||||
|
desired_state = intent_basis["desired_state"]
|
||||||
|
reason = intent_basis["reason"]
|
||||||
|
|
||||||
|
assert desired_state == "off", f"Expected 'off', got '{desired_state}'"
|
||||||
|
assert reason == "no_active_event", f"Expected reason 'no_active_event', got '{reason}'"
|
||||||
|
|
||||||
|
payload_body = build_group_power_intent_body(intent_basis, poll_interval_sec=15)
|
||||||
|
|
||||||
|
print(f"✓ Desired state: {desired_state}")
|
||||||
|
print(f"✓ Reason: {reason}")
|
||||||
|
print(f"✓ Event window: {intent_basis.get('event_window_start')} to {intent_basis.get('event_window_end')}")
|
||||||
|
print(f"✓ Payload body (pretty-print):")
|
||||||
|
print(json.dumps(payload_body, indent=2))
|
||||||
|
|
||||||
|
# Validate payload structure
|
||||||
|
assert "desired_state" in payload_body
|
||||||
|
assert payload_body["desired_state"] == "off"
|
||||||
|
assert "group_id" in payload_body
|
||||||
|
print("✓ Payload structure validated")
|
||||||
|
|
||||||
|
|
||||||
|
def test_scenario_2_single_active_event():
|
||||||
|
"""Scenario 2: One active event now => ON intent."""
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("SCENARIO 2: One active event now => desired_state=ON")
|
||||||
|
print("="*70)
|
||||||
|
|
||||||
|
now = utc_now()
|
||||||
|
start = now - timedelta(seconds=60)
|
||||||
|
end = now + timedelta(seconds=300)
|
||||||
|
group_id = 1
|
||||||
|
|
||||||
|
events = [
|
||||||
|
{
|
||||||
|
"id": 101,
|
||||||
|
"group_id": group_id,
|
||||||
|
"start": start.isoformat(),
|
||||||
|
"end": end.isoformat(),
|
||||||
|
"subject": "Morning Announcement",
|
||||||
|
"event_type": "message",
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
intent_basis = compute_group_power_intent_basis(
|
||||||
|
events=events,
|
||||||
|
group_id=group_id,
|
||||||
|
now_utc=now
|
||||||
|
)
|
||||||
|
|
||||||
|
desired_state = intent_basis["desired_state"]
|
||||||
|
reason = intent_basis["reason"]
|
||||||
|
|
||||||
|
assert desired_state == "on", f"Expected 'on', got '{desired_state}'"
|
||||||
|
assert reason == "active_event", f"Expected reason 'active_event', got '{reason}'"
|
||||||
|
|
||||||
|
payload_body = build_group_power_intent_body(intent_basis, poll_interval_sec=15)
|
||||||
|
|
||||||
|
print(f"✓ Desired state: {desired_state}")
|
||||||
|
print(f"✓ Reason: {reason}")
|
||||||
|
print(f"✓ event_window_start: {intent_basis.get('event_window_start')}")
|
||||||
|
print(f"✓ event_window_end: {intent_basis.get('event_window_end')}")
|
||||||
|
print(f"✓ Payload body (pretty-print):")
|
||||||
|
print(json.dumps(payload_body, indent=2))
|
||||||
|
|
||||||
|
assert payload_body["desired_state"] == "on"
|
||||||
|
print("✓ Payload structure validated")
|
||||||
|
|
||||||
|
|
||||||
|
def test_scenario_3_adjacent_events_no_off_blip():
|
||||||
|
"""Scenario 3: Adjacent events (no gap) => no OFF blip between them."""
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("SCENARIO 3: Adjacent events => no OFF between them")
|
||||||
|
print("="*70)
|
||||||
|
|
||||||
|
# Event 1: ends at T+300
|
||||||
|
# Event 2: starts at T+300 (adjacent, no gap)
|
||||||
|
base = utc_now()
|
||||||
|
group_id = 2
|
||||||
|
|
||||||
|
events_at_boundary = [
|
||||||
|
{
|
||||||
|
"id": 201,
|
||||||
|
"group_id": group_id,
|
||||||
|
"start": (base + timedelta(seconds=0)).isoformat(),
|
||||||
|
"end": (base + timedelta(seconds=300)).isoformat(),
|
||||||
|
"subject": "Event 1",
|
||||||
|
"event_type": "presentation",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 202,
|
||||||
|
"group_id": group_id,
|
||||||
|
"start": (base + timedelta(seconds=300)).isoformat(),
|
||||||
|
"end": (base + timedelta(seconds=600)).isoformat(),
|
||||||
|
"subject": "Event 2",
|
||||||
|
"event_type": "presentation",
|
||||||
|
},
|
||||||
|
]
|
||||||
|
|
||||||
|
# Sample times: before, at boundary, and after
|
||||||
|
scenarios = [
|
||||||
|
("Before boundary (Event 1 active)", base + timedelta(seconds=150)),
|
||||||
|
("At boundary (no gap)", base + timedelta(seconds=300)),
|
||||||
|
("After boundary (Event 2 active)", base + timedelta(seconds=450)),
|
||||||
|
]
|
||||||
|
|
||||||
|
for label, sample_time in scenarios:
|
||||||
|
intent_basis = compute_group_power_intent_basis(
|
||||||
|
events=events_at_boundary,
|
||||||
|
group_id=group_id,
|
||||||
|
now_utc=sample_time
|
||||||
|
)
|
||||||
|
desired_state = intent_basis["desired_state"]
|
||||||
|
reason = intent_basis["reason"]
|
||||||
|
|
||||||
|
print(f"\n {label}:")
|
||||||
|
print(f" Desired state: {desired_state}")
|
||||||
|
print(f" Reason: {reason}")
|
||||||
|
|
||||||
|
assert desired_state == "on", f"Expected 'on' at {label}, got '{desired_state}'"
|
||||||
|
|
||||||
|
print("\n✓ All boundary times show 'on' => no OFF blip between adjacent events")
|
||||||
|
|
||||||
|
|
||||||
|
def test_scenario_4_gap_between_events():
|
||||||
|
"""Scenario 4: Gap between events => OFF when not covered."""
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("SCENARIO 4: Gap between events => OFF during gap")
|
||||||
|
print("="*70)
|
||||||
|
|
||||||
|
base = utc_now()
|
||||||
|
group_id = 3
|
||||||
|
|
||||||
|
events_with_gap = [
|
||||||
|
{
|
||||||
|
"id": 301,
|
||||||
|
"group_id": group_id,
|
||||||
|
"start": (base + timedelta(seconds=0)).isoformat(),
|
||||||
|
"end": (base + timedelta(seconds=300)).isoformat(),
|
||||||
|
"subject": "Event 1",
|
||||||
|
"event_type": "presentation",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 302,
|
||||||
|
"group_id": group_id,
|
||||||
|
"start": (base + timedelta(seconds=600)).isoformat(),
|
||||||
|
"end": (base + timedelta(seconds=900)).isoformat(),
|
||||||
|
"subject": "Event 2",
|
||||||
|
"event_type": "presentation",
|
||||||
|
},
|
||||||
|
]
|
||||||
|
|
||||||
|
# Sample during gap: T+450 is between end(300) and start(600)
|
||||||
|
gap_time = base + timedelta(seconds=450)
|
||||||
|
|
||||||
|
intent_basis = compute_group_power_intent_basis(
|
||||||
|
events=events_with_gap,
|
||||||
|
group_id=group_id,
|
||||||
|
now_utc=gap_time
|
||||||
|
)
|
||||||
|
|
||||||
|
desired_state = intent_basis["desired_state"]
|
||||||
|
reason = intent_basis["reason"]
|
||||||
|
|
||||||
|
print(f"Sample time: {gap_time.isoformat()}")
|
||||||
|
print(f"Desired state: {desired_state}")
|
||||||
|
print(f"Reason: {reason}")
|
||||||
|
|
||||||
|
assert desired_state == "off", f"Expected 'off' during gap, got '{desired_state}'"
|
||||||
|
print("✓ Correctly recognizes gap => OFF")
|
||||||
|
|
||||||
|
|
||||||
|
def test_scenario_5_semantic_fingerprint_stable():
|
||||||
|
"""Scenario 5: Semantic fingerprint is stable for unchanged state."""
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("SCENARIO 5: Semantic fingerprint stability (transition detection)")
|
||||||
|
print("="*70)
|
||||||
|
|
||||||
|
payload_body_1 = {
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"group_id": 5,
|
||||||
|
"desired_state": "on",
|
||||||
|
"reason": "active_event",
|
||||||
|
"poll_interval_sec": 15,
|
||||||
|
"event_window_start": "2026-03-31T20:15:00Z",
|
||||||
|
"event_window_end": "2026-03-31T20:20:00Z",
|
||||||
|
"active_event_ids": [501],
|
||||||
|
}
|
||||||
|
|
||||||
|
payload_body_2 = {
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"group_id": 5,
|
||||||
|
"desired_state": "on",
|
||||||
|
"reason": "active_event",
|
||||||
|
"poll_interval_sec": 15,
|
||||||
|
"event_window_start": "2026-03-31T20:15:00Z",
|
||||||
|
"event_window_end": "2026-03-31T20:20:00Z",
|
||||||
|
"active_event_ids": [501],
|
||||||
|
}
|
||||||
|
|
||||||
|
payload_body_3_different = {
|
||||||
|
"schema_version": "1.0",
|
||||||
|
"group_id": 5,
|
||||||
|
"desired_state": "off", # Changed
|
||||||
|
"reason": "no_active_event",
|
||||||
|
"poll_interval_sec": 15,
|
||||||
|
"event_window_start": None,
|
||||||
|
"event_window_end": None,
|
||||||
|
"active_event_ids": [],
|
||||||
|
}
|
||||||
|
|
||||||
|
fp1 = compute_group_power_intent_fingerprint(payload_body_1)
|
||||||
|
fp2 = compute_group_power_intent_fingerprint(payload_body_2)
|
||||||
|
fp3 = compute_group_power_intent_fingerprint(payload_body_3_different)
|
||||||
|
|
||||||
|
print(f"Payload 1 (on, event X): {fp1}")
|
||||||
|
print(f"Payload 2 (on, same event X): {fp2}")
|
||||||
|
print(f"Payload 3 (off, no event): {fp3}")
|
||||||
|
|
||||||
|
assert fp1 == fp2, "Identical payloads should have same fingerprint"
|
||||||
|
assert fp1 != fp3, "Different desired_state should have different fingerprint"
|
||||||
|
|
||||||
|
print("✓ Fingerprint is stable for same state (no spurious transitions)")
|
||||||
|
print("✓ Fingerprint changes on semantic transition")
|
||||||
|
|
||||||
|
|
||||||
|
def test_scenario_6_timestamp_format_validation():
|
||||||
|
"""Scenario 6: Payload body contains window start/end in UTC Z format."""
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("SCENARIO 6: Event window timestamp format validation")
|
||||||
|
print("="*70)
|
||||||
|
|
||||||
|
now = utc_now()
|
||||||
|
group_id = 6
|
||||||
|
events = [
|
||||||
|
{
|
||||||
|
"id": 601,
|
||||||
|
"group_id": group_id,
|
||||||
|
"start": (now - timedelta(seconds=60)).isoformat(),
|
||||||
|
"end": (now + timedelta(seconds=300)).isoformat(),
|
||||||
|
"subject": "Event",
|
||||||
|
"event_type": "message",
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
intent_basis = compute_group_power_intent_basis(
|
||||||
|
events=events,
|
||||||
|
group_id=group_id,
|
||||||
|
now_utc=now
|
||||||
|
)
|
||||||
|
|
||||||
|
window_start = intent_basis.get("event_window_start")
|
||||||
|
window_end = intent_basis.get("event_window_end")
|
||||||
|
|
||||||
|
print(f"Event window start: {window_start}")
|
||||||
|
print(f"Event window end: {window_end}")
|
||||||
|
|
||||||
|
if window_start:
|
||||||
|
assert window_start.endswith("Z"), f"event_window_start must end with Z: {window_start}"
|
||||||
|
if window_end:
|
||||||
|
assert window_end.endswith("Z"), f"event_window_end must end with Z: {window_end}"
|
||||||
|
|
||||||
|
# Validate they are valid RFC3339 timestamps
|
||||||
|
try:
|
||||||
|
if window_start:
|
||||||
|
dt_start = datetime.fromisoformat(window_start.replace("Z", "+00:00"))
|
||||||
|
if window_end:
|
||||||
|
dt_end = datetime.fromisoformat(window_end.replace("Z", "+00:00"))
|
||||||
|
if window_start:
|
||||||
|
assert dt_end > dt_start, "window_end must be after window_start"
|
||||||
|
print("✓ Event window timestamps are valid RFC3339 UTC format with Z suffix")
|
||||||
|
except Exception as e:
|
||||||
|
print(f"✗ Timestamp parsing failed: {e}")
|
||||||
|
raise
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
"""Run all scenarios."""
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("TV POWER INTENT PHASE-1 SERVER CANARY VALIDATION")
|
||||||
|
print("="*70)
|
||||||
|
print("\nThis script validates server-side power-intent computation logic")
|
||||||
|
print("without requiring an MQTT broker connection.\n")
|
||||||
|
|
||||||
|
try:
|
||||||
|
test_scenario_1_no_active_events()
|
||||||
|
test_scenario_2_single_active_event()
|
||||||
|
test_scenario_3_adjacent_events_no_off_blip()
|
||||||
|
test_scenario_4_gap_between_events()
|
||||||
|
test_scenario_5_semantic_fingerprint_stable()
|
||||||
|
test_scenario_6_timestamp_format_validation()
|
||||||
|
|
||||||
|
print("\n" + "="*70)
|
||||||
|
print("ALL CANARY SCENARIOS PASSED ✓")
|
||||||
|
print("="*70)
|
||||||
|
print("\nNext steps for full validation:")
|
||||||
|
print("1. Enable POWER_INTENT_PUBLISH_ENABLED=true in scheduler")
|
||||||
|
print("2. Subscribe to infoscreen/groups/+/power/intent in MQTT broker")
|
||||||
|
print("3. Run scheduler and observe:")
|
||||||
|
print(" - ON payload on event start")
|
||||||
|
print(" - Same intent_id across heartbeat republishes")
|
||||||
|
print(" - OFF payload on event end")
|
||||||
|
print(" - No OFF blip between adjacent events")
|
||||||
|
print("4. Restart scheduler and verify immediate ON republish")
|
||||||
|
print("5. Disconnect MQTT broker and verify reconnect republish")
|
||||||
|
print("\nSee TV_POWER_CANARY_VALIDATION_CHECKLIST.md for full validation matrix.")
|
||||||
|
|
||||||
|
return 0
|
||||||
|
except AssertionError as e:
|
||||||
|
print(f"\n✗ VALIDATION FAILED: {e}")
|
||||||
|
return 1
|
||||||
|
except Exception as e:
|
||||||
|
print(f"\n✗ UNEXPECTED ERROR: {e}")
|
||||||
|
import traceback
|
||||||
|
traceback.print_exc()
|
||||||
|
return 1
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
sys.exit(main())
|
||||||
Reference in New Issue
Block a user