b4um_generators 0.2.17 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39e3c318690d26739ba27564ca702e481d33cce273b21a46b8c304a60251d31a
-  data.tar.gz: 657648494cdca9cd40e9aafc9f333ee49967c6c31786ae67fdbc951575ca158a
+  metadata.gz: 15fb9392677d61fa44d0d18bfa6fa71f8cde33202c1d3ab846eeded8cc255240
+  data.tar.gz: 07256f3c068de795270adf8e1376f155f657c6a13b4d356ce414a289c6456be2
 SHA512:
-  metadata.gz: e375a782413296d33953bbe9192657a7e8772ee9095480b2c30c1a4b3d13da6dd3fefe0b04b170f7bc8747939beb43a3728f9b73e018cbcdf1c7ab032421d167
-  data.tar.gz: 9fd996e86f29f3c47a791a2cda1f663c4e465b576ef240cab9c88adea8d572bfe48ab91c833830ae8d27bb924bd71bb0d21d2a74fb0cc3b85436a94f81dcd662
+  metadata.gz: c2c4efca4c04e8e8ef528e246d16c2e536c1b54e6dd356c284e96659664756edeacdfcb93d135cbebdf39ace19f869c5ca49dafbfe5ad9867c3703c92228bb8b
+  data.tar.gz: af333b2df50d0530cfbf701b3fa040a80ba5d716cae4a67909be39d1f59d5c1bad6795b9a39691284e6cce2e867ed512ec7cf047f72bdff579db3741e8349ee6

data/CHANGELOG.md

@@ -1,5 +1,35 @@
+# Changelog
+
+All notable changes to b4um Generators will be documented in this file.
+
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-12
+
+### Added
+
+- Added administrator management with `b4um:admin`
+- Added command-line creation of the first administrator
+- Added blocking, unblocking, deletion and administrator permission management
+- Added `--required` support to the scaffold generator
+- Added automatic required-field handling in generated forms
+- Added temporary guest access with `b4um:guest`
+- Added configurable guest account expiration with `--expires-in`
+- Added guest-to-regular-account conversion while preserving the existing account record
+- Added cleanup task for expired guest accounts
+- Added guest expiration warnings
+- Added dynamic field detection for administrator and guest account creation
+
+### Changed
+
+- Improved authentication integration with required model fields
+- Improved administrator creation prompts and validation handling
+- Improved administrator creation after guest access has been installed
+- Improved generated Admin dashboard and user management layouts
+- Improved migration generation to avoid duplicate migration version numbers
+- Improved English and German documentation
+- Extended `b4um:help` with Admin and Guest documentation
+
 ## [0.1.0] - 2026-09-17
 
 - Initial release

data/README.de.md

@@ -6,8 +6,8 @@ b4um Generators ist eine Sammlung wiederverwendbarer Rails-Generatoren, Template
 für b4um-Rails-Projekte.
 
 Das Gem bietet eine einheitliche Grundlage für Rails-Anwendungen und enthält Generatoren für Scaffolds, Controller,
-Bento-Layouts, Tabellen, Pagination, Infinite Scroll, Suche, Kommentare, Authentifizierung, Attachments und
-Rich-Text-Bearbeitung.
+Bento-Layouts, Tabellen, Pagination, Infinite Scroll, Suche, Kommentare, Authentifizierung, Administration, Gastzugänge,
+Attachments und Rich-Text-Bearbeitung.
 
 Die generierten Komponenten verwenden ein gemeinsames b4um-Styling und sind darauf ausgelegt, miteinander zu
 funktionieren.
@@ -24,7 +24,7 @@ b4um Generators wird während der Entwicklung derzeit als lokales Gem verwendet.
 Füge das Gem zur `Gemfile` der Rails-Anwendung hinzu:
 
 ```ruby
-gem "b4um_generators", "~> 0.2.0", path: "/pfad/zu/b4um_generators"
+gem "b4um_generators", "~> 0.4.0", path: "/pfad/zu/b4um_generators"
 ```
 
 Führe anschließend aus:
@@ -81,9 +81,12 @@ b4um:controller
 b4um:pagination
 b4um:infinite_scroll
 b4um:search
+b4um:sortable
 b4um:comments
 b4um:in_place
 b4um:authentication
+b4um:admin
+b4um:guest
 b4um:trix
 b4um:readable
 b4um:help
@@ -115,6 +118,7 @@ Der Scaffold-Generator bietet:
 - Index-, Show-, New- und Edit-Views
 - Standardmäßig ein Bento-Index-Layout
 - Optionales Tabellen-Index-Layout
+- Pflichtfelder mit `presence`-Validierung
 - Select-Felder mit eigenen Anzeigebezeichnungen
 - Radio-Felder mit eigenen Anzeigebezeichnungen
 - Automatischen Navigationseintrag
@@ -124,6 +128,34 @@ Der Scaffold-Generator bietet:
 - Unterstützung für Passwortfelder
 - Optionale lesbare URL-Parameter
 
+### Pflichtfelder
+
+Mit `--required` können Felder ausgewählt werden, für die der Scaffold-Generator eine `presence`-Validierung im Modell
+erzeugt.
+
+Verwende:
+
+```text
+--required=FIELD,FIELD
+```
+
+Beispiel:
+
+```bash
+bin/rails generate b4um:scaffold Customer first_name:string last_name:string company:string email:string --required=first_name,last_name,email
+```
+
+Dadurch wird dem generierten Modell folgende Validierung hinzugefügt:
+
+```ruby
+validates :first_name, :last_name, :email, presence: true
+```
+
+Felder, die nicht mit `--required` angegeben werden, bleiben optional.
+
+`--required` kann mit den anderen Scaffold-Optionen wie `--select`, `--radio`, `--layout` und `--param` kombiniert
+werden.
+
 ### Select- und Radio-Felder
 
 Der Scaffold-Generator kann String-Attribute als Select- oder Radio-Felder mit eigenen Anzeigebezeichnungen erzeugen.
@@ -545,6 +577,308 @@ passenden Vorschlag für einen b4um-Scaffold-Befehl ab.
 Bei wiederholter Ausführung werden Authentifizierungs-Helper, Routen, Navigationselemente und Controller-Schutz nicht
 dupliziert.
 
+## Administration
+
+Füge einem bestehenden b4um-Authentifizierungsmodell eine Benutzer- und Administratorverwaltung hinzu:
+
+```bash
+bin/rails generate b4um:admin MODEL
+```
+
+Beispiel:
+
+```bash
+bin/rails generate b4um:admin User
+bin/rails db:migrate
+```
+
+Der Admin-Generator baut auf der bestehenden b4um-Authentifizierung auf. Für das ausgewählte Modell muss daher zuerst
+die b4um-Authentifizierung eingerichtet werden.
+
+Ein vollständiger Ablauf sieht so aus:
+
+```bash
+bin/rails generate b4um:scaffold User name:string email:string password_digest:string
+bin/rails db:migrate
+
+bin/rails generate b4um:authentication User
+
+bin/rails generate b4um:admin User
+bin/rails db:migrate
+```
+
+Der Admin-Generator fügt dem Authentifizierungsmodell zwei boolesche Felder hinzu:
+
+```text
+admin
+blocked
+```
+
+Beide Felder haben standardmäßig den Wert `false`.
+
+Der Generator fügt außerdem Folgendes hinzu:
+
+- Admin-Dashboard
+- Schutz des Admin-Bereichs
+- Benutzerverwaltung
+- Admin-Routen
+- Benutzer sperren und entsperren
+- Administratorrechte vergeben und entziehen
+- Benutzer löschen
+- Schutz vor dem Sperren des eigenen Kontos
+- Schutz vor dem Löschen des eigenen Kontos
+- Schutz vor dem Entziehen der Rechte des letzten Administrators
+- Verhinderung der Anmeldung gesperrter Benutzer
+- Automatische Ungültigmachung bestehender Sitzungen gesperrter Benutzer
+
+### Ersten Administrator anlegen
+
+Administratorrechte können nicht über die öffentliche Registrierung vergeben werden.
+
+Nach dem Ausführen des Admin-Generators und der Datenbankmigration wird der erste Administrator über die Kommandozeile
+angelegt:
+
+```bash
+bin/rails b4um:admin:create
+```
+
+Führe vor dem Anlegen des ersten Administrators die Datenbankmigration aus:
+
+```bash
+bin/rails db:migrate
+```
+
+Die Aufgabe erkennt zusätzliche Felder des Authentifizierungsmodells automatisch.
+
+Felder mit einer unbedingten `presence`-Validierung werden mit `*` gekennzeichnet und müssen ausgefüllt werden. Andere
+erkannte Felder sind optional und können leer bleiben.
+
+E-Mail-Adresse, Passwort und Passwortbestätigung sind immer erforderlich.
+
+Ein Authentifizierungsmodell mit den Pflichtfeldern `first_name` und `last_name` sowie dem optionalen Feld `company`
+kann zum Beispiel zu folgender Abfrage führen:
+
+```text
+First name *: Alex
+Last name *: Beispiel
+Company:
+Email *: admin@example.com
+Password *:
+Confirm password *:
+Administrator admin@example.com was created successfully.
+```
+
+Das Passwort wird während der Eingabe im Terminal nicht angezeigt.
+
+Wurde die Admin-Migration noch nicht ausgeführt, bricht die Aufgabe ab und weist darauf hin, `bin/rails db:migrate`
+auszuführen.
+
+Das Konto wird mit folgenden Werten angelegt:
+
+```text
+admin: true
+blocked: false
+```
+
+Existiert bereits ein Konto mit der eingegebenen E-Mail-Adresse, bricht die Aufgabe ab. Ein vorhandenes Konto erhält
+dadurch nicht automatisch Administratorrechte.
+
+Bestehende Benutzer können nach dem Anlegen des ersten Administrators über die Admin-Benutzerverwaltung zu
+Administratoren gemacht werden.
+
+### Admin-Bereich
+
+Der generierte Admin-Bereich ist erreichbar unter:
+
+```text
+/admin
+```
+
+Nur ein angemeldetes Konto mit Administratorrechten kann auf diesen Bereich zugreifen.
+
+Das Admin-Dashboard führt zur generierten Benutzerverwaltung.
+
+Dort können Administratoren:
+
+- Benutzer sperren
+- Benutzer entsperren
+- Administratorrechte vergeben
+- Administratorrechte entziehen
+- Benutzer löschen
+
+Der aktuell angemeldete Administrator kann sein eigenes Konto über die generierte Benutzerverwaltung weder sperren noch
+löschen.
+
+Dem letzten verbliebenen Administrator können die Administratorrechte nicht entzogen werden. Dadurch wird verhindert,
+dass eine Anwendung versehentlich ohne Administrator zurückbleibt.
+
+### Benutzer sperren
+
+Beim Sperren eines Benutzers wird das Feld `blocked` des Authentifizierungsmodells auf `true` gesetzt.
+
+Ein gesperrter Benutzer kann sich auch mit dem richtigen Passwort nicht anmelden.
+
+Wird ein bereits angemeldeter Benutzer gesperrt, wird seine bestehende Sitzung ungültig, sobald die Authentifizierung
+erneut geprüft wird.
+
+Nach dem Entsperren kann sich der Benutzer wieder anmelden.
+
+### Administratorrechte
+
+Der Zugriff auf den Admin-Bereich wird über das Feld `admin` des Authentifizierungsmodells gesteuert.
+
+Ein normal registrierter Benutzer startet mit:
+
+```text
+admin: false
+blocked: false
+```
+
+Ein Administrator kann einem bestehenden Benutzer über die Admin-Benutzerverwaltung Administratorrechte geben.
+
+Administratorrechte können dort auch wieder entzogen werden, solange dadurch nicht dem letzten Administrator seine
+Rechte entzogen würden.
+
+Der Admin-Generator verwendet dasselbe Authentifizierungsmodell und dasselbe Anmeldesystem wie `b4um:authentication`. Es
+wird weder ein separates Administratorkonto-System noch ein zweiter Login erzeugt.
+
+## Gastzugang
+
+Füge einem bestehenden b4um-Authentifizierungsmodell einen zeitlich begrenzten Gastzugang hinzu:
+
+```bash
+bin/rails generate b4um:guest MODEL --required=FIELDS
+```
+
+Beispiel:
+
+```bash
+bin/rails generate b4um:guest User --required=first_name,email
+bin/rails db:migrate
+```
+
+Der Guest-Generator baut auf der bestehenden b4um-Authentifizierung auf. Für das ausgewählte Modell muss daher zuerst
+die b4um-Authentifizierung eingerichtet werden.
+
+Mit `--required` muss mindestens ein Feld angegeben werden.
+
+Eine vollständige Einrichtung kann zum Beispiel so aussehen:
+
+```bash
+bin/rails generate b4um:scaffold User first_name:string last_name:string company:string email:string password_digest:string --required=first_name,last_name,email
+bin/rails db:migrate
+
+bin/rails generate b4um:authentication User
+
+bin/rails generate b4um:guest User --required=first_name,email
+bin/rails db:migrate
+```
+
+Der Guest-Generator fügt dem Authentifizierungsmodell zwei Felder hinzu:
+
+```text
+guest
+guest_expires_at
+```
+
+Gastkonten verwenden dasselbe Authentifizierungsmodell wie regulär registrierte Konten. Der Generator erzeugt kein
+separates Gastmodell.
+
+### Felder für Gastkonten
+
+Die mit `--required` angegebenen Felder sind beim Erstellen eines Gastkontos Pflichtfelder.
+
+Beispiel:
+
+```bash
+bin/rails generate b4um:guest User --required=first_name,email
+```
+
+In diesem Beispiel sind `first_name` und `email` für Gastkonten erforderlich.
+
+Weitere geeignete Felder des Authentifizierungsmodells werden automatisch erkannt und können beim Erstellen des
+Gastkontos ausgefüllt werden. Felder, die nicht mit `--required` angegeben wurden, bleiben optional.
+
+Technische und sensible Felder werden nicht als normale Profilfelder für Gastkonten angeboten.
+
+Der Guest-Generator passt die normalen Presence-Validierungen des Kontos so an, dass ein Gast mit der kleineren, über
+`--required` festgelegten Feldmenge erstellt werden kann. Bei der Umwandlung in ein reguläres Konto gelten weiterhin die
+normalen Pflichtfelder des Kontos.
+
+### Passwörter für Gastkonten
+
+Gastkonten verwenden das bestehende `has_secure_password`-Authentifizierungssystem.
+
+Für ein Gastkonto wird automatisch ein sicheres internes Passwort erzeugt. Der Gast muss beim Erstellen des Gastzugangs
+kein Passwort auswählen oder eingeben.
+
+Wird das Gastkonto später in ein reguläres Konto umgewandelt, muss ein normales Passwort festgelegt werden.
+
+### Ablaufzeit
+
+Ein Gastzugang läuft automatisch ab.
+
+Die Standardlaufzeit beträgt 7 Tage.
+
+Mit `--expires-in` kann eine andere Laufzeit festgelegt werden:
+
+```bash
+bin/rails generate b4um:guest User --required=first_name,email --expires-in=14
+```
+
+In diesem Beispiel erhalten neu erstellte Gastkonten 14 Tage Gastzugang.
+
+Der Ablaufzeitpunkt wird gespeichert in:
+
+```text
+guest_expires_at
+```
+
+Gastbenutzer erhalten vor dem Ablauf ihres Kontos einen Hinweis.
+
+### Gastkonto umwandeln
+
+Ein Gastkonto kann in ein regulär registriertes Konto umgewandelt werden.
+
+Bei der Umwandlung wird der bestehende Datensatz des Authentifizierungsmodells weiterverwendet und kein zweiter Benutzer
+angelegt. Daten, die bereits mit dem Gastkonto verknüpft sind, bleiben dadurch dem umgewandelten Konto zugeordnet.
+
+Bei der Umwandlung fragt das generierte Formular die für ein reguläres Konto erforderlichen Felder sowie ein Passwort
+und die Passwortbestätigung ab.
+
+Nach erfolgreicher Umwandlung gilt:
+
+```text
+guest: false
+guest_expires_at: nil
+```
+
+Das Konto verhält sich anschließend wie ein regulär authentifiziertes Konto.
+
+### Gastkonto löschen
+
+Ein Gast kann das temporäre Konto löschen, anstatt es in ein reguläres Konto umzuwandeln.
+
+Abgelaufene Gastkonten können außerdem mit der generierten Cleanup-Task entfernt werden:
+
+```bash
+bin/rails b4um:guests:cleanup
+```
+
+Diese Task sollte in einer Produktionsumgebung regelmäßig ausgeführt werden, damit abgelaufene Gastkonten nicht
+dauerhaft gespeichert bleiben.
+
+Wie die Task zeitgesteuert ausgeführt wird, bleibt bewusst der Anwendung und ihrer jeweiligen Deployment-Umgebung
+überlassen.
+
+### Gastzugang und Administration
+
+Gastzugang und Admin-Verwaltung verwenden dasselbe Authentifizierungsmodell.
+
+Der Guest-Generator kann deshalb zusammen mit `b4um:admin` verwendet werden. Die Gast-spezifische Behandlung der
+Validierungen erhält die Anforderungen für reguläre Konten, sodass bei der Administrator-Erstellung und bei der normalen
+Registrierung weiterhin die entsprechenden Pflichtfelder verlangt werden.
+
 ## Active Storage und Bilder
 
 Bildanhänge verwenden Rails Active Storage.
@@ -732,6 +1066,86 @@ Die Suche bietet:
 - Kein zusätzliches Such-Gem erforderlich
 - Sichere wiederholte Ausführung des Generators
 
+## Sortable
+
+Füge einer bestehenden Ressource eine dauerhaft gespeicherte Sortierreihenfolge hinzu:
+
+```bash
+bin/rails generate b4um:sortable Product
+bin/rails db:migrate
+```
+
+Der Generator fügt eine `position`-Spalte hinzu und weist bestehenden Datensätzen beim Ausführen der generierten
+Migration automatisch Positionen zu.
+
+Neue Datensätze werden automatisch am Ende der Liste eingefügt.
+
+Standardmäßig wird die bestehende Index-Seite zur sortierbaren Seite:
+
+```text
+/products
+```
+
+Das bestehende Index-Layout wird auf das b4um-Sortable-Layout umgestellt. Die gespeicherte Position wird außerdem als
+Standardsortierung der Ressource verwendet.
+
+Sortable bietet:
+
+- Dauerhaft in der Datenbank gespeicherte ganzzahlige Positionen
+- Automatische Positionierung bestehender Datensätze während der Migration
+- Automatische Positionierung neuer Datensätze am Ende
+- Drag-and-Drop-Sortierung mit Stimulus
+- Direkte Änderung der Position über ein Zahlenfeld
+- Automatisches Verschieben der betroffenen Datensätze
+- Lückenlose Positionen nach dem Verschieben oder Löschen von Datensätzen
+- Serverseitige Sortierung innerhalb einer Datenbanktransaktion
+- CSRF-geschützte Update-Anfragen
+- Integration mit b4um Search und Pagination
+- Kein zusätzliches Sortier-Gem erforderlich
+- Sichere wiederholte Ausführung des Generators
+
+### Separate Sortierseite
+
+Mit `--path` kann eine separate Sortierseite erstellt werden:
+
+```bash
+bin/rails generate b4um:sortable Product --path=sortierung
+bin/rails db:migrate
+```
+
+Dadurch wird die sortierbare Seite genau unter folgender URL erstellt:
+
+```text
+/sortierung
+```
+
+während der normale Ressourcen-Index weiterhin unter
+
+```text
+/products
+```
+
+verfügbar bleibt.
+
+Das bestehende Index-Layout, beispielsweise Bento oder Table, bleibt unverändert. Es verwendet weiterhin die
+gespeicherte `position`-Sortierung.
+
+Die separate Sortierseite verwendet den bestehenden Controller der Ressource. Es wird kein zusätzlicher Controller und
+kein Namespace erzeugt.
+
+Der mit `--path` angegebene Wert bestimmt direkt die URL der separaten Sortierseite. Zum Beispiel:
+
+```bash
+bin/rails generate b4um:sortable Product --path=produktuebersicht
+bin/rails generate b4um:sortable Product --path=verwaltung
+bin/rails generate b4um:sortable Product --path=admin
+```
+
+Dadurch entstehen entsprechend `/produktuebersicht`, `/verwaltung` und `/admin`.
+
+Eine separate Sortierseite ermöglicht außerdem, nur die `sort`-Action durch die Authentifizierung zu schützen, während
+der normale Ressourcen-Index öffentlich bleiben kann.
+
 ## Kommentare
 
 Füge einem bestehenden Modell polymorphe Kommentare hinzu:
@@ -1135,7 +1549,7 @@ wird.
 
 ## Version
 
-Aktuelle Version: `0.2.17`
+Aktuelle Version: `0.4.0`
 
 ## Autor