sichere-express-actions

Generisches Fullstack-Framework fuer sichere Mehrbenutzer-Anwendungen. Eine fachliche Datei erzeugt Datenbank, Express-API, React-Frontend, Tests und Dokumentation.

Kann

| Bereich | Automatisch enthalten | |---|---| | Datenbank | SQLite/WAL oder MySQL/InnoDB, Tabellen, Referenzen, Indizes, partielles Unique, Seeds und Migrationen | | Backend | CRUD, eigene Fachactions, Transaktionen, Validierung und einheitliche 4xx/5xx-Fehler | | Mehrbenutzer | Mutex, Optimistic Locking, 409-Konflikte, 423-Sperren, Vormerkungen und Ablaufzeiten | | Rechte | Rollen, Status, Besitzer, Nicht-Besitzer und Vier-Augen-Regeln; standardmaessig geschlossen konfigurierbar | | Prozesse | Workflows, bedingte Statuswechsel und resource-uebergreifende Effekte innerhalb der Transaktion | | Read-Models | berechnete Felder wie frei, belegt oder anzahlOffen, ohne redundante Datenbankspalte | | Frontend | Login, Navigation, Adminansichten, CRUD, Actions, Historie, Konfliktdialog, Sperren und SSE/Polling | | Schnittstellen | freie Tabellen-, Feld- und API-Namen sowie eigene Express-Routen als Escape Hatch | | Nachweise | ausfuehrbare HTTP-, Parallel-, SQL- und Rollback-Szenarien mit echten Ergebnisdateien | | Dokumentation | Markdown, HTML, PDF, gerendertes ERD, Diagramme, API, Rechte, Tests, automatische UI-Screenshots und Validierung |

Es gibt keine eingebauten Auto- oder Vermietungsbegriffe. Dasselbe Framework passt fuer Lager, Termine, Tickets, Geraete, Fischtanks, Freigaben oder andere Fachgebiete.

Start

npx sichere-express-actions create meine-app
cd meine-app
npm install
npx playwright install chromium
npm run dev

Frontend: http://localhost:5173

Eine fachliche Datei

import { fileURLToPath } from 'node:url';
import { defineApp } from 'sichere-express-actions';
import { SQLiteAuditAdapter, sqlite } from 'sichere-express-actions/sqlite';

const database = sqlite(fileURLToPath(new URL('./data.db', import.meta.url)));

export default defineApp({
  name: 'Geraeteverleih',
  database,
  audit: new SQLiteAuditAdapter(database),
  api: { prefix: '/api', eventsPath: '/ereignisse' },
  auth: { resource: 'account', username: 'name', password: 'passwort', role: 'rolle' },
  resources: {
    account: {
      fields: {
        name: { type: 'string', required: true, unique: true },
        passwort: { type: 'string', required: true, sensitive: true },
        rolle: ['mitarbeiter', 'admin'],
      },
    },
    geraet: {
      fields: {
        bezeichnung: 'string!',
        status: { enum: ['frei', 'verliehen'], default: 'frei', readonly: true },
      },
      optimisticLock: true,
      audit: true,
      live: { mode: 'both', intervalMs: 5000 },
      computed: {
        frei: { type: 'boolean', query: { resource: 'ausleihe', where: { geraetId: '$record.id', ende: null }, aggregate: 'notExists' } },
      },
    },
    ausleihe: {
      fields: {
        geraetId: 'ref:geraet!',
        ende: { type: 'datetime', optional: true, nullable: true, readonly: true },
        accountId: 'ref:account!',
      },
      optimisticLock: true,
      tracking: { actorResource: 'account' },
      audit: true,
      editingLock: { expiresIn: '10m', actorResource: 'account' },
      workflow: {
        initial: 'aktiv',
        endpoint: { path: '/status', field: 'status' },
        transitions: {
          zuruecknehmen: {
            from: 'aktiv', to: 'abgeschlossen', roles: ['mitarbeiter', 'admin'],
            effects: [{ resource: 'geraet', id: '$record.geraetId', values: { status: 'frei' } }],
          },
        },
      },
    },
  },
  actions: {
    ausleihen: {
      input: { geraetId: { ref: 'geraet', required: true, lock: true } },
      roles: ['mitarbeiter', 'admin'],
      transaction: true,
      create: { resource: 'ausleihe', values: { geraetId: '$input.geraetId', accountId: '$user.id', ende: null, status: 'aktiv' } },
      effects: [{ resource: 'geraet', id: '$input.geraetId', values: { status: 'verliehen' } }],
    },
  },
  seed: {
    account: [{ name: 'admin', passwort: '1234', rolle: 'admin' }],
    geraet: [{ bezeichnung: 'G-001', status: 'frei' }],
  },
});

Kurztypen: string!, int!, number, boolean, email, date, datetime, ref:name! und ['a', 'b'].

api.prefix legt den API-Basispfad fest. api.eventsPath legt den SSE-Pfad relativ dazu fest; ohne Angabe bleibt er bei /events.

Befehle

npm run dev        # Backend und generiertes Frontend
npm run seed       # definierter Anfangszustand
npm test           # Smoke- und Szenariotests mit echten Nachweisen
npm run build      # auslieferbares Frontend
npm run docs       # Diagramme, API und Projektdokumentation
npm run sql        # SQLite-Konsole
npm run db:update  # sichere additive Migration

Dokumentation

Ein Befehl erzeugt die technische Abgabe aus derselben fachlichen Konfiguration:

npm run docs

Fertig ist insbesondere:

docs/generated/dokumentation.pdf

Zusaetzlich bleiben dokumentation.md, dokumentation.html, das PlantUML-ERD, ein gerendertes SVG, Resource-, API-, Workflow-, Action-, Rechte- und Testdokumente erhalten. reports/generation.md nennt echte Anzahlen, Warnungen und alles, was noch manuell fehlt.

Screenshots

Das Framework startet Backend und generiertes Frontend selbst auf freien Ports. Es nimmt nur wirklich vorhandene Ansichten auf: Anmeldung, Anwendungsuebersicht, Resource-Listen, erreichbare Create-/Edit-/History-Ansichten und Action-Formulare. Screenshots werden fachlich beim passenden Kapitel eingebunden. Alte generierte Screenshots entfernt der naechste Lauf ueber sein Manifest.

Chromium wird einmal pro Rechner installiert:

npx playwright install chromium

Dokumentationsdaten und Login

Die Aufnahme laeuft mit einer eigenen In-Memory-SQLite-Datenbank. Reihenfolge: documentation.fixtures, vorhandene Seeds, danach sicher ableitbare Beispieldaten. Die echte Projekt- oder Produktionsdatenbank wird nicht beschrieben. Standard-Auth wird mit einem isolierten Seed-Konto automatisch bedient; Passwoerter, Tokens, Cookies und Storage-State werden nie unter docs/ gespeichert.

Nur bei einer vollstaendig eigenen Anmeldung ist ein Hook noetig:

documentation: {
  screenshots: {
    async setup(page) {
      // individuelle Anmeldung
    },
  },
}

Ausgabe und Sicherheit

npm run docs erzeugt und prueft:

docs/generated/
  dokumentation.md
  dokumentation.html
  dokumentation.pdf
  architecture/erd.puml
  architecture/erd.svg
  api/endpoints.md
  security/rights.md
  resources/*.md
  workflows/*.md
  actions/*.md
  screenshots/**
  reports/tests.md
  reports/generation.md

Die Validierung kontrolliert Bilder, relative Links, PDF/SVG, unsichere absolute Pfade und bekannte sensitive Werte. Am Schluss zeigt die CLI kompakt, was automatisch erstellt wurde und welche menschlichen Angaben wie Autor oder Projektbeschreibung noch fehlen.

Pruefungsworkflow

Modell und individuelle Fachlogik definieren
-> npm test
-> npm run docs
-> docs/generated/dokumentation.pdf abgeben

Frei erweiterbar

Vollstaendige field(), resource() und action()-Definitionen, eigene Funktionen, extend(), configure(), eigene Express-Routen und eigene React-Komponenten bleiben moeglich. Die Kurzform vereinfacht Standardfaelle, sie begrenzt die Anwendung nicht.

Installation ohne Starter:

npm install sichere-express-actions express zod

Lizenz: MIT