ai-app: Deployment-Anbindung (Port 8900, Migrationswerkzeug, systemd-Template)

Standard-Port in den fuer ai reservierten Bereich verschoben (9600 belegt
workflow-app). Fortschrittstabelle ai_schema_migrations statt
connect_schema_migrations.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

ai/cmd/ai-app/main.go

@@ -49,7 +49,7 @@ import (
 
 const workerPollInterval = 2 * time.Second
 
-const defaultListenAddr = "127.0.0.1:9600"
+const defaultListenAddr = "127.0.0.1:8900"
 const defaultModel = "default"
 
 type config struct {

ai/cmd/migrate/main.go

@@ -0,0 +1,40 @@
+// Command migrate wendet die offenen Postgres-Migrationen des AI-Moduls an.
+// Einmal gegen eine frische Datenbank ausfuehren, bevor ai-app startet.
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"gitea.perlbach24.de/scripte/nexarch/ai/internal/migrate"
+)
+
+func main() {
+	dsn := os.Getenv("NEXARCH_AI_APP_TENANT_DSN")
+	if dsn == "" {
+		log.Fatal("migrate: NEXARCH_AI_APP_TENANT_DSN ist erforderlich")
+	}
+	dir := "migrations"
+	if len(os.Args) > 1 {
+		dir = os.Args[1]
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		log.Fatalf("migrate: datenbankverbindung: %v", err)
+	}
+	defer pool.Close()
+
+	migrations, err := migrate.Load(dir)
+	if err != nil {
+		log.Fatalf("migrate: migrationen laden: %v", err)
+	}
+	applied, err := migrate.Up(ctx, pool, migrations)
+	if err != nil {
+		log.Fatalf("migrate: migrationen anwenden: %v", err)
+	}
+	log.Printf("migrate: %d migration(en) angewendet", len(applied))
+}

ai/docs/BETRIEB-UMGEBUNGSVARIABLEN.md

@@ -0,0 +1,26 @@
+# Betrieb: ai-app
+
+Port-Bereich 8900 bis 8999 (`deploy/ports.tsv`), Routenpräfix `/api/ai/v1` (`deploy/routes.tsv`). Secrets gehören ausschließlich in die Umgebung (`/etc/nexarch/ai-app.env`, Rechte 600), nie in Code, Logs oder Dokumentation.
+
+## Einrichten
+
+1. Datenbank und Rolle anlegen (nicht Teil der Units).
+2. `/etc/nexarch/ai-app.env` mit den Variablen unten anlegen.
+3. Migrationen anwenden: `NEXARCH_AI_APP_TENANT_DSN=... ./migrate ai/migrations` (Fortschrittstabelle `ai_schema_migrations`).
+4. Unit aus `deploy/systemd/nexarch-ai-app.service.tmpl` installieren (`__INSTALL_DIR__` ersetzen), `systemctl enable --now nexarch-ai-app`.
+5. Health: `GET /healthz`.
+
+Eine Datenbank, die vor ENG-10 mit den AI-Migrationen angelegt wurde, führte den Fortschritt in `connect_schema_migrations`. Ist sie ausschließlich AI-Datenbank, vor dem ersten Lauf `ALTER TABLE connect_schema_migrations RENAME TO ai_schema_migrations;`. Bei gemeinsamer Datenbank mit Connect nicht umbenennen, sondern die AI-Einträge von Hand in die neue Tabelle übertragen.
+
+## Variablen
+
+| Variable | Standard | Wirkung |
+|---|---|---|
+| `NEXARCH_AI_APP_TENANT_DSN` | Pflicht | Datenbank des AI-Moduls |
+| `NEXARCH_AI_APP_SERVICE_TOKEN` | Pflicht | Service-Token, das alle Aufrufer im Header `X-Service-Token` senden |
+| `NEXARCH_AI_APP_LISTEN_ADDR` | `127.0.0.1:8900` | Lauschadresse |
+| `NEXARCH_AI_APP_MODEL` | `default` | Modellname für Inferenzaufrufe |
+| `NEXARCH_AI_APP_POLICY_URL` / `_POLICY_SERVICE_TOKEN` | Pflicht, oder Übergangsschalter | Rechteprüfung der semantischen Suche; Token Pflicht, sobald URL gesetzt |
+| `NEXARCH_AI_APP_POLICY_DISABLED` | aus | `1` startet ohne Rechteprüfung (Übergang, Warnlog) |
+| `NEXARCH_AI_APP_MODULE_BASE_URLS` | leer | `modul=url,modul2=url2`, Basis-URLs für den Rückschreib-Push |
+| `NEXARCH_AI_APP_CORE_BASE_URL` / `_CORE_SERVICE_TOKEN` | leer | Core-Anbindung; ohne sie ist die Objekttyp-Registrierung (GOV-01) deaktiviert |

ai/docs/ENG-10-PRUEFPROTOKOLL.md

@@ -0,0 +1,40 @@
+# ENG-10 – ai-app: Deployment-Anbindung – Prüfprotokoll
+
+Datum: 2026-11-06. Host: Entwicklungshost 192.168.1.204 (Wegwerf-Rolle/DB `eng10_test`, nach Abschluss entfernt).
+
+## Befund (Ausgangslage)
+
+- `ai-app` lauschte standardmäßig auf `127.0.0.1:9600`, außerhalb des für `ai` reservierten Bereichs 8900 bis 8999 (`deploy/ports.tsv`). 9600 belegt außerdem `workflow-app` (`docs/BETRIEB-PORTAL.md`). `scripts/check-port-defaults.sh` erkennt nur `":NNNN"`-Literale und meldete den Verstoß nicht.
+- Kein systemd-Template für `ai-app` (Connect und DMS haben eines).
+- Kein Migrationswerkzeug für das AI-Modul; `ai/internal/migrate` führte den Fortschritt in der Tabelle `connect_schema_migrations` (Kopierfehler aus dem Connect-Modul).
+
+## Umsetzung
+
+- Standard-Lauschadresse `127.0.0.1:8900`.
+- `ai/cmd/migrate` (Muster `connect/cmd/migrate`, DSN aus `NEXARCH_AI_APP_TENANT_DSN`, Verzeichnis als Argument).
+- Fortschrittstabelle `ai_schema_migrations`.
+- `deploy/systemd/nexarch-ai-app.service.tmpl` nach dem Muster von `nexarch-connect-app` (gleiche Härtung).
+- `ai/docs/BETRIEB-UMGEBUNGSVARIABLEN.md` mit Einrichtungsschritten und Variablen.
+
+## Akzeptanzkriterien
+
+| # | Kriterium | Ergebnis |
+|---|---|---|
+| 1 | Standard-Port liegt im Bereich von `ai` | **Erfüllt.** 8900. `scripts/check-port-defaults.sh` meldet für `ai/cmd/ai-app` nichts (dort erkennt es allerdings das Format `127.0.0.1:NNNN` ohnehin nicht, siehe Einschränkungen). |
+| 2 | systemd-Template vorhanden und gehärtet | **Erfüllt.** `scripts/check-systemd-hardening.sh`: ok, 18 Dienste geprüft. Start der Unit selbst nicht getestet. |
+| 3 | Migrationen anwendbar, idempotent | **Erfüllt.** Frische DB: 16 Migrationen angewendet, zweiter Lauf 0; ohne DSN klare Fehlermeldung, Abbruch. |
+| 4 | Eigene Fortschrittstabelle | **Erfüllt.** `ai_schema_migrations` existiert, `connect_schema_migrations` nicht (`TestUp_UsesOwnTrackingTable`, echte DB). |
+
+## Prüfungen vor der Abnahme
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Migrationswerkzeug gegen frische Wegwerf-DB | **Bestanden** (siehe AK3). |
+| 2 | Bestehende Modultests | **Bestanden.** `./internal/migrate/`, `./cmd/ai-app/` grün, `go build ./...` und `go vet` sauber. |
+| 3 | Unit startet `ai-app` real | **Offen.** Template nicht auf einem Host installiert, `systemctl` nicht ausgeführt. |
+
+## Einschränkungen
+
+- Umbenennung der Fortschrittstabelle betrifft bestehende AI-Datenbanken; Hinweis in `BETRIEB-UMGEBUNGSVARIABLEN.md`. Eine automatische Übernahme gibt es nicht.
+- Nicht Teil der Kachel: Aufnahme in `deploy/rollout-131-*.sh` (Host-131-Rollout), Provisionierung von DB, Rolle und Secrets.
+- Weitere Port-Verstöße außerhalb von `ai`, die beim Prüfen auffielen und nicht behoben wurden: `workflow-app` und `tasks-a11y-fixture` auf 9600 (Bereich 8800 bis 8899), Connect-Fixtures doppelt auf 9500, mehrere Fixtures und `verapdf-sidecar` außerhalb ihrer Bereiche. `check-port-defaults.sh` erkennt `127.0.0.1:NNNN`-Literale nicht; eine Erweiterung würde diese Verstöße sichtbar machen und braucht eine eigene Entscheidung.

ai/internal/migrate/migrate.go

@@ -12,7 +12,7 @@ import (
 
 type Migration = cmigrate.Migration
 
-const TrackingTable = "connect_schema_migrations"
+const TrackingTable = "ai_schema_migrations"
 
 var migrator = cmigrate.MustNew(TrackingTable)
 

ai/internal/migrate/migrate_test.go

@@ -0,0 +1,41 @@
+package migrate
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"gitea.perlbach24.de/scripte/nexarch/common/testdb"
+)
+
+func TestUp_UsesOwnTrackingTable(t *testing.T) {
+	dsn := os.Getenv("TEST_TENANT_DSN")
+	if dsn == "" {
+		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest uebersprungen")
+	}
+	pool := testdb.Pool(t, dsn)
+	dir, err := filepath.Abs("../../migrations")
+	if err != nil {
+		t.Fatal(err)
+	}
+	migrations, err := Load(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx := context.Background()
+	if _, err := Up(ctx, pool, migrations); err != nil {
+		t.Fatal(err)
+	}
+	again, err := Up(ctx, pool, migrations)
+	if err != nil || len(again) != 0 {
+		t.Fatalf("zweiter lauf soll nichts anwenden: %v %v", again, err)
+	}
+	var own, foreign bool
+	if err := pool.QueryRow(ctx, `SELECT to_regclass('ai_schema_migrations') IS NOT NULL, to_regclass('connect_schema_migrations') IS NOT NULL`).Scan(&own, &foreign); err != nil {
+		t.Fatal(err)
+	}
+	if !own || foreign {
+		t.Fatalf("fortschrittstabelle: ai=%v connect=%v", own, foreign)
+	}
+}

connect/cmd/connect-app/main.go

@@ -18,9 +18,12 @@ import (
 	"gitea.perlbach24.de/scripte/nexarch/common/bearerauth"
 	"gitea.perlbach24.de/scripte/nexarch/common/moduleauth"
 	"gitea.perlbach24.de/scripte/nexarch/common/policyclient"
+	"gitea.perlbach24.de/scripte/nexarch/connect/internal/archiveclient"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/connectorsetupapi"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/credential"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/crypto"
+	"gitea.perlbach24.de/scripte/nexarch/connect/internal/datevapi"
+	"gitea.perlbach24.de/scripte/nexarch/connect/internal/datevexport"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/dms2import"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/dms2importapi"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/fieldmapping"
@@ -56,6 +59,25 @@ func buildPolicyClient() *policyclient.Client {
 	return policyclient.New(policyURL, token)
 }
 
+// buildDatevExports liefert nil ohne NEXARCH_CONNECT_APP_ARCHIVE_URL; dann ist
+// /datev/exports nicht registriert. Die DATEV-Uebertragung ist hier nicht verdrahtet.
+func buildDatevExports(pool *pgxpool.Pool) *datevexport.Store {
+	archiveURL := os.Getenv("NEXARCH_CONNECT_APP_ARCHIVE_URL")
+	if archiveURL == "" {
+		log.Print("connect-app: NEXARCH_CONNECT_APP_ARCHIVE_URL fehlt, /datev/exports nicht registriert")
+		return nil
+	}
+	token := os.Getenv("NEXARCH_CONNECT_APP_ARCHIVE_SERVICE_TOKEN")
+	if token == "" {
+		log.Fatal("connect-app: NEXARCH_CONNECT_APP_ARCHIVE_SERVICE_TOKEN ist erforderlich, wenn NEXARCH_CONNECT_APP_ARCHIVE_URL gesetzt ist")
+	}
+	return &datevexport.Store{
+		Pool:        pool,
+		Archive:     archiveclient.New(archiveURL, token),
+		CallbackURL: os.Getenv("NEXARCH_CONNECT_APP_DATEV_CALLBACK_URL"),
+	}
+}
+
 func main() {
 	if !killswitch.Enabled() {
 		log.Printf("connect-app: deaktiviert (%s=false), kein Start", killswitch.EnvEnabled)
@@ -98,6 +120,9 @@ func main() {
 	statusapi.NewServer(syncjob.NewStore(pool)).WithPolicy(policy).RegisterRoutes(mux)
 	dms2importapi.NewServer(mappings, dms2import.NewStore(pool)).RegisterRoutes(mux)
 	connectorsetupapi.NewServer(credentials, mappings).WithPolicy(policy).RegisterRoutes(mux)
+	if exports := buildDatevExports(pool); exports != nil {
+		datevapi.NewServer(exports, nil).WithPolicy(policy).RegisterRoutes(mux)
+	}
 
 	srv := &http.Server{
 		Addr:              addr,

connect/internal/datevapi/datevapi.go

@@ -9,6 +9,7 @@ import (
 	"net/http"
 	"time"
 
+	"gitea.perlbach24.de/scripte/nexarch/common/policyclient"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/datevexport"
 	"gitea.perlbach24.de/scripte/nexarch/connect/internal/datevtransfer"
 )
@@ -16,6 +17,12 @@ import (
 type Server struct {
 	Exports   *datevexport.Store
 	Transfers *datevtransfer.Store
+	policy    *policyclient.Client
+}
+
+func (s *Server) WithPolicy(client *policyclient.Client) *Server {
+	s.policy = client
+	return s
 }
 
 func NewServer(exports *datevexport.Store, transfers *datevtransfer.Store) *Server {
@@ -23,8 +30,32 @@ func NewServer(exports *datevexport.Store, transfers *datevtransfer.Store) *Serv
 }
 
 func (s *Server) RegisterRoutes(mux *http.ServeMux) {
-	mux.HandleFunc("POST /datev/exports", s.requireIdentity(s.handleTrigger))
-	mux.HandleFunc("GET /datev/exports", s.requireIdentity(s.handleList))
+	mux.HandleFunc("POST /datev/exports", s.requireIdentity(s.requirePermission("connect.datev.write", s.handleTrigger)))
+	mux.HandleFunc("GET /datev/exports", s.requireIdentity(s.requirePermission("connect.datev.read", s.handleList)))
+}
+
+func (s *Server) requirePermission(permission string, next func(w http.ResponseWriter, r *http.Request, tenantSlug string)) func(w http.ResponseWriter, r *http.Request, tenantSlug string) {
+	return func(w http.ResponseWriter, r *http.Request, tenantSlug string) {
+		if s.policy != nil {
+			allowed, err := s.policy.Allowed(r.Context(), tenantSlug, roleOf(r), permission)
+			if err != nil {
+				writeError(w, http.StatusServiceUnavailable, "berechtigungsdienst nicht erreichbar")
+				return
+			}
+			if !allowed {
+				writeError(w, http.StatusForbidden, "keine berechtigung")
+				return
+			}
+		}
+		next(w, r, tenantSlug)
+	}
+}
+
+func roleOf(r *http.Request) string {
+	if role := r.Header.Get("X-User-Role"); role != "" {
+		return role
+	}
+	return "user"
 }
 
 func (s *Server) requireIdentity(next func(w http.ResponseWriter, r *http.Request, tenantSlug string)) http.HandlerFunc {

connect/internal/datevapi/datevapi_policy_test.go

@@ -0,0 +1,46 @@
+package datevapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"gitea.perlbach24.de/scripte/nexarch/common/policyclient"
+)
+
+func TestPolicy_PermissionAndRoleReachCore(t *testing.T) {
+	type ask struct{ role, permission string }
+	var got []ask
+	policyAPI := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var body struct {
+			Role       string `json:"role"`
+			Permission string `json:"permission"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&body)
+		got = append(got, ask{body.Role, body.Permission})
+		_ = json.NewEncoder(w).Encode(map[string]bool{"allowed": false})
+	}))
+	defer policyAPI.Close()
+	mux := http.NewServeMux()
+	(&Server{}).WithPolicy(policyclient.New(policyAPI.URL, "tok")).RegisterRoutes(mux)
+
+	for _, c := range []struct{ method, role string }{{"GET", "tenant_admin"}, {"POST", ""}} {
+		req := httptest.NewRequest(c.method, "/datev/exports", strings.NewReader("{}"))
+		req.Header.Set("X-User-Id", "u1")
+		req.Header.Set("X-Tenant-Slug", "acme")
+		if c.role != "" {
+			req.Header.Set("X-User-Role", c.role)
+		}
+		rec := httptest.NewRecorder()
+		mux.ServeHTTP(rec, req)
+		if rec.Code != http.StatusForbidden {
+			t.Fatalf("%s: erwartet 403, bekam %d", c.method, rec.Code)
+		}
+	}
+	want := []ask{{"tenant_admin", "connect.datev.read"}, {"user", "connect.datev.write"}}
+	if len(got) != 2 || got[0] != want[0] || got[1] != want[1] {
+		t.Fatalf("erwartet %v, bekam %v", want, got)
+	}
+}

connect/internal/statusapi/statusapi.go

@@ -22,8 +22,7 @@ type Server struct {
 
 // WithPolicy aktiviert RBAC-12: echte Rechtepruefung gegen Core (POST
 // /authorize), zusaetzlich zur bestehenden X-User-Id/X-Tenant-Slug-Pruefung.
-// Rolle ist mangels eigenem Rollenkonzept in Connect fest "user" (Uebergang,
-// wie beim restlichen Header-basierten Identitaetsmodell dieses Pakets).
+// Die Rolle kommt aus X-User-Role (setzt bearerauth aus dem Token), sonst "user".
 func (s *Server) WithPolicy(client *policyclient.Client) *Server {
 	s.policy = client
 	return s
@@ -40,7 +39,7 @@ func (s *Server) RegisterRoutes(mux *http.ServeMux) {
 func (s *Server) requirePermission(permission string, next func(w http.ResponseWriter, r *http.Request, tenantSlug string)) func(w http.ResponseWriter, r *http.Request, tenantSlug string) {
 	return func(w http.ResponseWriter, r *http.Request, tenantSlug string) {
 		if s.policy != nil {
-			allowed, err := s.policy.Allowed(r.Context(), tenantSlug, "user", permission)
+			allowed, err := s.policy.Allowed(r.Context(), tenantSlug, roleOf(r), permission)
 			if err != nil {
 				writeError(w, http.StatusServiceUnavailable, "berechtigungsdienst nicht erreichbar")
 				return
@@ -54,6 +53,13 @@ func (s *Server) requirePermission(permission string, next func(w http.ResponseW
 	}
 }
 
+func roleOf(r *http.Request) string {
+	if role := r.Header.Get("X-User-Role"); role != "" {
+		return role
+	}
+	return "user"
+}
+
 func (s *Server) requireIdentity(next func(w http.ResponseWriter, r *http.Request, tenantSlug string)) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		if r.Header.Get("X-User-Id") == "" {

connect/internal/statusapi/statusapi_policy_test.go

@@ -60,3 +60,32 @@ func TestHandleList_PolicyAllows_Passes(t *testing.T) {
 		t.Fatalf("erwartet 200 mit berechtigung, bekam %d: %s", rec.Code, rec.Body.String())
 	}
 }
+
+func TestHandleList_RoleFromHeaderReachesPolicy(t *testing.T) {
+	var got []string
+	policyAPI := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var body struct {
+			Role string `json:"role"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&body)
+		got = append(got, body.Role)
+		_ = json.NewEncoder(w).Encode(map[string]bool{"allowed": true})
+	}))
+	defer policyAPI.Close()
+	s := newTestServer(t).WithPolicy(policyclient.New(policyAPI.URL, "test-token"))
+	mux := http.NewServeMux()
+	s.RegisterRoutes(mux)
+
+	for _, role := range []string{"tenant_admin", ""} {
+		req := httptest.NewRequest("GET", "/connectors/status", nil)
+		req.Header.Set("X-User-Id", "u1")
+		req.Header.Set("X-Tenant-Slug", "acme")
+		if role != "" {
+			req.Header.Set("X-User-Role", role)
+		}
+		mux.ServeHTTP(httptest.NewRecorder(), req)
+	}
+	if len(got) != 2 || got[0] != "tenant_admin" || got[1] != "user" {
+		t.Fatalf("erwartet [tenant_admin user], bekam %v", got)
+	}
+}

deploy/systemd/nexarch-ai-app.service.tmpl

@@ -0,0 +1,23 @@
+[Unit]
+Description=NEXARCH AI - ai-app (ENG-10)
+After=network.target postgresql.service
+Wants=postgresql.service
+
+[Service]
+Type=simple
+User=nexarch
+Group=nexarch
+EnvironmentFile=/etc/nexarch/ai-app.env
+ExecStart=__INSTALL_DIR__/bin/ai-app
+Restart=on-failure
+RestartSec=3
+WorkingDirectory=__INSTALL_DIR__
+# QA-15 F-13/OPS-08: reiner Netzwerkdienst (HTTP + Postgres-DSN aus
+# EnvironmentFile), keine eigene Schreibarbeit im Dateisystem.
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target