5a0c1bc686
- Update copilot-instructions.md with user model, API routes, and frontend patterns - Update README.md with RBAC details, user management API, and security sections - Add user management technical documentation to TECH-CHANGELOG.md - Bump version to 2025.1.0-alpha.13 with user management changelog entries
235 lines
19 KiB
Markdown
235 lines
19 KiB
Markdown
|
||
# TECH-CHANGELOG
|
||
|
||
|
||
|
||
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`.
|
||
|
||
## 2025.1.0-beta.1 (TBD)
|
||
- 🔐 **User Management & Role-Based Access Control**:
|
||
- Backend: Implemented comprehensive user management API (`server/routes/users.py`) with 6 endpoints (GET, POST, PUT, DELETE users + password reset).
|
||
- Data model: Extended `User` with 7 audit/security fields via Alembic migration (`4f0b8a3e5c20_add_user_audit_fields.py`):
|
||
- `last_login_at`, `last_password_change_at`: TIMESTAMP (UTC) for auth event tracking
|
||
- `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)
|
||
- Role hierarchy: 4-tier privilege escalation (user → editor → admin → superadmin) enforced at API and UI levels:
|
||
- Admin cannot see, create, or manage superadmin accounts
|
||
- Admin can manage user/editor/admin roles only
|
||
- Superadmin can manage all roles including other superadmins
|
||
- Auth routes enhanced (`server/routes/auth.py`):
|
||
- Login: Sets `last_login_at`, resets `failed_login_attempts` on success; increments `failed_login_attempts` and `last_failed_login_at` on failure
|
||
- Password change: Sets `last_password_change_at` on both self-service and admin reset
|
||
- New endpoint: `PUT /api/auth/change-password` for self-service password change (all authenticated users; requires current password verification)
|
||
- User API security:
|
||
- Admin cannot reset superadmin passwords
|
||
- Self-account protections: cannot change own role/status, cannot delete self
|
||
- Admin cannot use password reset endpoint for their own account (backend check enforces self-service requirement)
|
||
- All user responses include audit fields in camelCase (lastLoginAt, lastPasswordChangeAt, failedLoginAttempts, deactivatedAt, deactivatedBy)
|
||
- Soft-delete pattern: Deactivation by default (sets `deactivated_at` and `deactivated_by`); hard-delete superadmin-only
|
||
- 🖥️ **Frontend User Management**:
|
||
- New page: `dashboard/src/users.tsx` – Full CRUD interface (820 lines) with Syncfusion components
|
||
- 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 display: last login, password change, last failed login, deactivation timestamps and deactivating user
|
||
- Self-protection: Delete button hidden for current user (prevents accidental self-deletion)
|
||
- Menu visibility: "Benutzer" sidebar item only visible to admin+ (role-gated in App.tsx)
|
||
- 💬 **Header User Menu**:
|
||
- Enhanced top-right dropdown with "Passwort ändern" (lock icon), "Profil", and "Abmelden"
|
||
- Self-service password change dialog: Available to all authenticated users; requires current password verification, new password min 6 chars, must match confirm field
|
||
- Implemented with Syncfusion DropDownButton (`@syncfusion/ej2-react-splitbuttons`)
|
||
- 🔌 **API Client**:
|
||
- New file: `dashboard/src/apiUsers.ts` – Type-safe TypeScript client (143 lines) for user operations
|
||
- Functions: listUsers(), getUser(), createUser(), updateUser(), resetUserPassword(), deleteUser()
|
||
- All functions include proper error handling and camelCase JSON mapping
|
||
- 📖 **Documentation**:
|
||
- Updated `.github/copilot-instructions.md`: Added comprehensive sections on user model audit fields, user management API routes, auth routes, header menu, and user management page implementation
|
||
- Updated `README.md`: Added user management to Key Features, API endpoints (User Management + Authentication sections), Pages Overview, and Security & Authentication sections with RBAC details
|
||
- Updated `TECH-CHANGELOG.md`: Documented all technical changes and integration notes
|
||
|
||
Notes for integrators:
|
||
- User CRUD endpoints accept/return all audit fields in camelCase
|
||
- Admin password reset (`PUT /api/users/<id>/password`) cannot be used for admin's own account; users must use self-service endpoint
|
||
- Frontend enforces role-gated menu visibility; backend validates all role transitions to prevent privilege escalation
|
||
- Soft-delete is default; hard-delete (superadmin-only) requires explicit confirmation
|
||
- Audit fields populated automatically on login/logout/password-change/deactivation events
|
||
|
||
|
||
|
||
Backend rework (post-release notes; no version bump):
|
||
- 🧩 Dev Container hygiene: Remote Containers runs on UI (`remote.extensionKind`), removed in-container install to prevent reappearance loops; switched `postCreateCommand` to `npm ci` for reproducible dashboard installs; `postStartCommand` aliases made idempotent.
|
||
- 🔄 Serialization: Consolidated snake_case→camelCase via `server/serializers.py` for all JSON outputs; ensured enums/UTC datetimes serialize consistently across routes.
|
||
- 🕒 Time handling: Normalized naive timestamps to UTC in all back-end comparisons (events, scheduler, groups) and kept ISO strings without `Z` in API responses; frontend appends `Z`.
|
||
- 📡 Streaming: Stabilized range-capable endpoint (`/api/eventmedia/stream/<media_id>/<filename>`), clarified client handling; scheduler emits basic HEAD-probe metadata (`mime_type`, `size`, `accept_ranges`).
|
||
- 📅 Recurrence/exceptions: Ensured EXDATE tokens (RFC 5545 UTC) align with occurrence start; detached-occurrence flow confirmed via `POST /api/events/<id>/occurrences/<date>/detach`.
|
||
- 🧰 Routes cleanup: Applied `dict_to_camel_case()` before `jsonify()` uniformly; verified Session lifecycle consistency (open/commit/close) across blueprints.
|
||
- 🔄 **API Naming Convention Standardization**:
|
||
- Created `server/serializers.py` with `dict_to_camel_case()` and `dict_to_snake_case()` utilities for consistent JSON serialization
|
||
- Events API refactored: `GET /api/events` and `GET /api/events/<id>` now return camelCase JSON (`id`, `subject`, `startTime`, `endTime`, `type`, `groupId`, etc.) instead of PascalCase
|
||
- Internal event dictionaries use snake_case keys, then converted to camelCase via `dict_to_camel_case()` before `jsonify()`
|
||
- **Breaking**: External API consumers must update field names from PascalCase to camelCase
|
||
- ⏰ **UTC Time Handling**:
|
||
- Standardized datetime handling: Database stores timestamps in UTC (naive timestamps normalized by backend)
|
||
- API returns ISO strings without 'Z' suffix: `"2025-11-27T20:03:00"`
|
||
- Frontend appends 'Z' to parse as UTC and displays in user's local timezone via `toLocaleTimeString('de-DE')`
|
||
- All time comparisons use UTC; `date.toISOString()` sends UTC back to API
|
||
- 🖥️ **Dashboard Major Redesign**:
|
||
- Completely redesigned dashboard with card-based layout for Raumgruppen (room groups)
|
||
- Global statistics summary card: total infoscreens, online/offline counts, warning groups
|
||
- Filter buttons with dynamic counts: All, Online, Offline, Warnings
|
||
- Active event display per group: shows currently playing content with type icon, title, date ("Heute"/"Morgen"/date), and time range
|
||
- Health visualization: color-coded progress bars showing online/offline ratio per group
|
||
- Expandable client details: shows last alive timestamps with human-readable format ("vor X Min.", "vor X Std.", "vor X Tagen")
|
||
- Bulk restart functionality: restart all offline clients in a group
|
||
- Manual refresh button with toast notifications
|
||
- 15-second auto-refresh interval
|
||
- "Nicht zugeordnet" group always appears last in sorted list
|
||
- 🎨 **Frontend Technical**:
|
||
- Dashboard (`dashboard/src/dashboard.tsx`): Uses Syncfusion ButtonComponent, ToastComponent, and card CSS classes
|
||
- Appointments page updated to map camelCase API responses to internal PascalCase for Syncfusion compatibility
|
||
- Time formatting functions (`formatEventTime`, `formatEventDate`) handle UTC string parsing with 'Z' appending
|
||
- TypeScript lint errors resolved: unused error variables removed, null safety checks added with optional chaining
|
||
- 📖 **Documentation**:
|
||
- Updated `.github/copilot-instructions.md` with comprehensive sections on:
|
||
- API patterns: JSON serialization, datetime handling conventions
|
||
- Frontend patterns: API response format, UTC time parsing
|
||
- Dashboard page overview with features
|
||
- Conventions & gotchas: datetime and JSON naming guidelines
|
||
- Updated `README.md` with recent changes, API response format section, and dashboard page details
|
||
|
||
Notes for integrators:
|
||
- **Breaking change**: All Events API endpoints now return camelCase field names. Update client code accordingly.
|
||
- Frontend must append 'Z' to API datetime strings before parsing: `const utcStr = dateStr.endsWith('Z') ? dateStr : dateStr + 'Z'; new Date(utcStr);`
|
||
- Use `dict_to_camel_case()` from `server/serializers.py` for any new API endpoints returning JSON
|
||
- Dev container: prefer `npm ci` and UI-only Remote Containers to avoid extension drift in-container.
|
||
|
||
---
|
||
|
||
### Component build metadata template (for traceability)
|
||
Record component builds under the unified app version when releasing:
|
||
|
||
```
|
||
Component builds for this release
|
||
- API: image tag `ghcr.io/robbstarkaustria/api:<short-sha>` (commit `<sha>`)
|
||
- Dashboard: image tag `ghcr.io/robbstarkaustria/dashboard:<short-sha>` (commit `<sha>`)
|
||
- Scheduler: image tag `ghcr.io/robbstarkaustria/scheduler:<short-sha>` (commit `<sha>`)
|
||
- Listener: image tag `ghcr.io/robbstarkaustria/listener:<short-sha>` (commit `<sha>`)
|
||
- Worker: image tag `ghcr.io/robbstarkaustria/worker:<short-sha>` (commit `<sha>`)
|
||
```
|
||
|
||
This is informational (build metadata) and does not change the user-facing version number.
|
||
|
||
## 2025.1.0-alpha.11 (2025-11-05)
|
||
- 🗃️ Data model & API:
|
||
- Added `muted` (Boolean) to `Event` with Alembic migration; create/update and GET endpoints now accept, persist, and return `muted` alongside `autoplay`, `loop`, and `volume` for video events.
|
||
- Video event fields consolidated: `event_media_id`, `autoplay`, `loop`, `volume`, `muted`.
|
||
- 🔗 Streaming:
|
||
- Added range-capable streaming endpoint: `GET /api/eventmedia/stream/<media_id>/<filename>` (supports byte-range requests 206 for seeking).
|
||
- Scheduler: Performs a best-effort HEAD probe for video stream URLs and includes basic metadata in the emitted payload (`mime_type`, `size`, `accept_ranges`). Placeholders added for `duration`, `resolution`, `bitrate`, `qualities`, `thumbnails`, `checksum`.
|
||
- 🖥️ Frontend/Dashboard:
|
||
- Settings page refactored to nested tabs with controlled tab selection (`selectedItem`) to prevent sub-tab jumps.
|
||
- Settings → Events → Videos: Added system-wide defaults with load/save via system settings keys: `video_autoplay`, `video_loop`, `video_volume`, `video_muted`.
|
||
- Event modal (CustomEventModal): Exposes per-event video options including “Ton aus” (`muted`) and initializes all video fields from system defaults when creating new events.
|
||
- Academic Calendar (Settings): Merged “Schulferien Import” and “Liste” into a single sub-tab “📥 Import & Liste”.
|
||
- 📖 Documentation:
|
||
- Updated `README.md` and `.github/copilot-instructions.md` for video payload (incl. `muted`), streaming endpoint (206), nested Settings tabs, and video defaults keys; clarified client handling of `video` payloads.
|
||
- Updated `dashboard/public/program-info.json` (user-facing changelog) and bumped version to `2025.1.0-alpha.11` with corresponding UI/UX notes.
|
||
|
||
Notes for integrators:
|
||
- Clients should parse `event_type` and handle the nested `video` payload, honoring `autoplay`, `loop`, `volume`, and `muted`. Use the streaming endpoint with HTTP Range for seeking.
|
||
- System settings keys for video defaults: `video_autoplay`, `video_loop`, `video_volume`, `video_muted`.
|
||
|
||
## 2025.1.0-alpha.10 (2025-10-25)
|
||
- No new developer-facing changes in this release.
|
||
- UI/UX updates are documented in `dashboard/public/program-info.json`:
|
||
- Event modal: Surfaced video options (Autoplay, Loop, Volume).
|
||
- FileManager: Increased upload limits (Full-HD); client-side duration validation (max 10 minutes).
|
||
|
||
## 2025.1.0-alpha.9 (2025-10-19)
|
||
- 🗓️ Events/API:
|
||
- Implemented new `webuntis` event type. Event creation now resolves the URL from the system setting `supplement_table_url`; returns 400 if unset.
|
||
- Removed obsolete `webuntis-url` settings endpoints. Use `GET/POST /api/system-settings/supplement-table` for URL and enabled state (shared for WebUntis/Vertretungsplan).
|
||
- Initialization defaults: dropped `webuntis_url`; updated `supplement_table_url` description to “Vertretungsplan / WebUntis”.
|
||
- 🚦 Scheduler payloads:
|
||
- Unified Website/WebUntis payload: both emit a nested `website` object `{ "type": "browser", "url": "…" }`; `event_type` remains either `website` or `webuntis` for dispatch.
|
||
- Payloads now include a top-level `event_type` string for all events to aid client dispatch.
|
||
- 🖥️ Frontend/Dashboard:
|
||
- Program info updated to `2025.1.0-alpha.13` with release notes.
|
||
- Settings → Events: WebUntis now uses the existing Supplement-Table URL; no separate WebUntis URL field.
|
||
- Event modal: WebUntis type behaves like Website (no per-event URL input).
|
||
- 📖 Documentation:
|
||
- Added `MQTT_EVENT_PAYLOAD_GUIDE.md` (message structure, client best practices, versioning).
|
||
- Added `WEBUNTIS_EVENT_IMPLEMENTATION.md` (design notes, admin setup, testing checklist).
|
||
- Updated `.github/copilot-instructions.md` and `README.md` for the unified Website/WebUntis handling and settings usage.
|
||
|
||
Notes for integrators:
|
||
- If you previously integrated against `/api/system-settings/webuntis-url`, migrate to `/api/system-settings/supplement-table`.
|
||
- Clients should now parse `event_type` and use the corresponding nested payload (`presentation`, `website`, …). `webuntis` and `website` should be handled identically (nested `website` payload).
|
||
|
||
|
||
## 2025.1.0-alpha.8 (2025-10-18)
|
||
- 🛠️ Backend: Seeded presentation defaults (`presentation_interval`, `presentation_page_progress`, `presentation_auto_progress`) in system settings; applied on event creation.
|
||
- 🗃️ Data model: Added `page_progress` and `auto_progress` fields to `Event` (with Alembic migration).
|
||
- 🗓️ Scheduler: Now publishes only currently active events per group (at "now"); clears retained topics by publishing `[]` for groups with no active events; normalizes naive timestamps and compares times in UTC; presentation payloads include `page_progress` and `auto_progress`.
|
||
- 🖥️ Dashboard: Settings → Events tab now includes Presentations defaults (interval, page-progress, auto-progress) with load/save via API; event modal applies defaults on create and persists per-event values on edit.
|
||
- 📖 Docs: Updated README and Copilot instructions for new scheduler behavior, UTC handling, presentation defaults, and per-event flags.
|
||
|
||
---
|
||
|
||
## 2025.1.0-alpha.11 (2025-10-16)
|
||
- ✨ Settings page: New tab layout (Syncfusion) with role-based visibility – Tabs: 📅 Academic Calendar, 🖥️ Display & Clients, 🎬 Media & Files, 🗓️ Events, ⚙️ System.
|
||
- 🛠️ Settings (Technical): API calls now use relative /api paths via the Vite proxy (prevents CORS and double /api).
|
||
- 📖 Docs: README updated for settings page (tabs) and system settings API.
|
||
|
||
## 2025.1.0-alpha.10 (2025-10-15)
|
||
- 🔐 Auth: Login and user management implemented (role-based, persistent sessions).
|
||
- 🧩 Frontend: Syncfusion SplitButtons integrated (react-splitbuttons) and Vite config updated for pre-bundling.
|
||
- 🐛 Fix: Import error ‘@syncfusion/ej2-react-splitbuttons’ – instructions added to README (optimizeDeps + volume reset).
|
||
|
||
## 2025.1.0-alpha.9 (2025-10-14)
|
||
- ✨ UI: Unified deletion workflow for appointments – all types (single, single instance, entire series) handled with custom dialogs.
|
||
- 🔧 Frontend: Syncfusion RecurrenceAlert and DeleteAlert intercepted and replaced with custom dialogs (including final confirmation for series deletion).
|
||
- 📖 Docs: README and Copilot instructions expanded for deletion workflow and dialog handling.
|
||
|
||
## 2025.1.0-alpha.8 (2025-10-11)
|
||
- 🎨 Theme: Migrated to Syncfusion Material 3; centralized CSS imports in main.tsx
|
||
- 🧹 Cleanup: Tailwind CSS completely removed (packages, PostCSS, Stylelint, config files)
|
||
- 🧩 Group management: "infoscreen_groups" migrated to Syncfusion components (Buttons, Dialogs, DropDownList, TextBox); improved spacing
|
||
- 🔔 Notifications: Unified toast/dialog wording; last alert usage replaced
|
||
- 📖 Docs: README and Copilot instructions updated (Material 3, centralized styles, no Tailwind)
|
||
|
||
## 2025.1.0-alpha.7 (2025-09-21)
|
||
- 🧭 UI: Period selection (Syncfusion) next to group selection; compact layout
|
||
- ✅ Display: Badge for existing holiday plan + counter ‘Holidays in view’
|
||
- 🛠️ API: Endpoints for academic periods (list, active GET/POST, for_date)
|
||
- 📅 Scheduler: By default, no scheduling during holidays; block display like all-day event; black text color
|
||
- 📤 Holidays: Upload from TXT/CSV (headless TXT uses columns 2–4)
|
||
- 🔧 UX: Switches in a row; dropdown widths optimized
|
||
|
||
## 2025.1.0-alpha.6 (2025-09-20)
|
||
- 🗓️ NEW: Academic periods system – support for school years, semesters, trimesters
|
||
- 🏗️ DATABASE: New 'academic_periods' table for time-based organization
|
||
- 🔗 EXTENDED: Events and media can now optionally be linked to an academic period
|
||
- 📊 ARCHITECTURE: Fully backward-compatible implementation for gradual rollout
|
||
- ⚙️ TOOLS: Automatic creation of standard school years for Austrian schools
|
||
|
||
## 2025.1.0-alpha.5 (2025-09-14)
|
||
- Backend: Complete redesign of backend handling for group assignments of new clients and steps for changing group assignment.
|
||
|
||
## 2025.1.0-alpha.4 (2025-09-01)
|
||
- Deployment: Base structure for deployment tested and optimized.
|
||
- FIX: Program error when switching view on media page fixed.
|
||
|
||
## 2025.1.0-alpha.3 (2025-08-30)
|
||
- NEW: Program info page with dynamic data, build info, and changelog.
|
||
- NEW: Logout functionality implemented.
|
||
- FIX: Sidebar width corrected in collapsed state.
|
||
|
||
## 2025.1.0-alpha.2 (2025-08-29)
|
||
- INFO: Analysis and display of used open-source libraries.
|
||
|
||
## 2025.1.0-alpha.1 (2025-08-28)
|
||
- Initial project setup and base structure.
|