Merge pull request 'docs: Arbeitskarten Stand 2026-10-28' (#395) from docs/arbeitskarten-stand into main

docs/ARBEITSKARTEN.md

@@ -1,68 +1,70 @@
-# Arbeitskarten (Stand 2026-10-27)
+# Arbeitskarten (Stand 2026-10-28)
 
-Reihenfolge = Abarbeitungsfolge. Status: offen / blockiert / Entscheidung nötig / erledigt.
-Regel je Karte: eigener Branch, eigener PR, Tests auf 131 bzw. 204 (nie archivdms), PR-Beschreibung nennt Auswirkungen.
+Status: offen / wartet / Entscheidung nötig / erledigt. Regel je Karte: eigener Branch, eigener PR, Tests auf 131 bzw. 204 (nie archivdms), PR-Beschreibung nennt Auswirkungen.
+
+Offene PRs, die auf Merge warten, stehen unter C-01. Merge-Reihenfolge: erst DB-Tests auf 204 (siehe A-08), dann #385 und #394 (common), danach die Modul-PRs.
 
 ## A. common/-Modul
 
-### A-01 Tag common/v0.1.0 — blockiert
-- Ziel: Tag-Workflow `common-tag.yml` erzeugt `common/v0.1.0`.
-- Blockiert durch: Runner `nexarch-131-runner` arbeitet CI-Warteschlange ab (Unit `act_runner.service` auf 131).
-- Schritte: Warteschlange beobachten; bei Lauf-Fehler Log lesen und Workflow korrigieren; Tag per `git ls-remote --tags origin 'common/*'` prüfen.
-- Fertig, wenn: Tag existiert und `go list -m gitea.perlbach24.de/scripte/nexarch/common@v0.1.0` auf 131 mit GOPRIVATE und `.netrc` funktioniert.
-- Hinweis: Lesezugriff-Token auf 131 legt der User an; Claude fasst keine Tokens an.
+### A-01 Tag common/v0.1.0 — erledigt
+- Tag-Workflow hat `common/v0.1.0` (Merge-Commit von #378) und `common/v0.1.1` gesetzt. Der Runner auf 131 läuft als `act_runner.service`.
+- Lehre: Die CI-Warteschlange staute sich (über 100 Läufe, 1 Job gleichzeitig); wartende Läufe wurden mit Freigabe des Users abgebrochen.
 
-### A-02 Umstellung archive (Pilot) — wartet auf A-01
-- Vorlage: Branches `refactor/common-modul-pilot`, `refactor/common-batch-2`.
-- Schritte: `require .../common v0.1.0` und go.sum; Importe von httpharden, svcauth, auditclient, tenantregistryclient (soweit in archive genutzt) umschreiben; interne Kopien löschen; gofmt wegen Import-Reihenfolge; Pflichttest-Gate von archive um common-Muster erweitern; Modul-Guards wiederherstellen.
-- Test: `go build/vet/test ./...` im Modul auf 131 in frischem Wurfverzeichnis; DB-Tests auf 204 mit `dms_dev` und `TEST_ADMIN_DSN`.
-- Nachweis: normalisierter md5-Vergleich (ohne Kommentare/Imports) zeigt, dass gelöschte Kopie und common-Paket gleich waren.
-- Fertig, wenn: PR offen, Tests grün, Auswirkungsliste in der PR-Beschreibung.
+### A-02 bis A-05 Umstellung auf common — PRs offen
+| Modul | PR | Umgestellt | Nicht umgestellt |
+|---|---|---|---|
+| archive | #383 | apierror, auditclient, httpclient, httpharden, svcauth, tenantregistryclient | loadtest (andere API) |
+| dms | #384 | apierror, httpclient, tenantregistryclient (ersetzt #375) | httpharden, policyclient (dms-Varianten), migrate, testdb |
+| mail | #386 | httpclient, loadtest, policyclient | testdb (andere API) |
+| ai | #387 | auditclient, httpclient, loadtest, svcauth, tenantregistryclient | migrate, testdb |
+| connect | #388 | auditclient, httpclient, policyclient | loadtest (weicht ab), migrate, testdb |
+| workflow | #389 | svcauth, tenantregistryclient | migrate, testdb, loadtest |
 
-### A-03 bis A-07 Umstellung weiterer Module — je nach A-02
-Reihenfolge: dms, mail, ai, connect, workflow; danach Root-Modul.
-- Pro Modul wie A-02. NICHT nach common: audittrail, cutoverstage, crypto, notifyclient, dms-Varianten von apierror/policyclient/httpharden, Root-httpclient.
-- Je Modul eigener PR.
+### A-06 migrate mit Tabellenname — PR offen (#385, common v0.2.0)
+- `migrate.New(table)` statt fester `connect_schema_migrations`; Tag-Workflow nutzt `common/MINOR`.
+- Danach Umstellung in connect, ai (`connect_schema_migrations`), dms (`dms_schema_migrations`), workflow (`workflow_schema_migrations`). Der Tabellenname muss je Modul unverändert bleiben, sonst laufen auf Bestands-DBs alle Migrationen neu. Wartet auf Tag aus #385.
 
-### A-08 CI-DB-Tests ausweiten — Entscheidung nötig
-- Stand: `testdb.AdminDSN` und `.gitea/workflows/db-tests.yml` (Label `nexarch-test`) sind gemergt, Workflow deckt nur `common/` ab.
-- Entscheidungen des Users nötig: Runner mit Label `nexarch-test` auf 204 registrieren, Secret `TEST_ADMIN_DSN` (Wegwerf-DB, nie archivdms) setzen.
-- Schritte danach: Modul-Tests auf `testdb.AdminDSN` umstellen (jeweils mit A-02..A-07), Workflow-Pfade ergänzen.
+### A-07 testdb aus common — PRs offen
+- dms #390 (auf #384), ai #391 (auf #387), connect #392 (auf #388), workflow #393 (auf #389). Schemaname einheitlich `connecttest_*`. mail und archive bleiben.
+
+### A-08 CI-DB-Tests und DB-Tests auf 204 — Entscheidung nötig
+- `testdb.AdminDSN` und `.gitea/workflows/db-tests.yml` (Label `nexarch-test`) sind in main; der Workflow deckt nur `common/` ab.
+- Fehlt vom User: Datei `/root/.nexarch-testdb.env` auf 204 (`TEST_ADMIN_DSN` für `dms_dev`, `chmod 600`) für manuelle Läufe; Runner mit Label `nexarch-test` auf 204 und Secret `TEST_ADMIN_DSN` für die CI.
+- Danach: DB-Tests für #383 bis #394 laufen lassen, Ergebnis in die PRs eintragen.
 
 ### A-09 Reviewer für common/ — Entscheidung nötig
-- Offene Frage: Gitea-Benutzernamen für CODEOWNERS/Review-Pflicht auf `common/`.
+- Gitea-Benutzernamen für CODEOWNERS/Review-Pflicht auf `common/`.
 
-## B. Portal (Vorschlag Fable, Detail siehe Gesprächsverlauf)
+### A-10 moduleauth in common — PR offen (#394)
+- `common/moduleauth` (Verifier, JWKS, Bearer-Middleware) aus der mail-Fassung. Danach: mail auf common/moduleauth umstellen; dms hat eine eigene Middleware mit `caller`-Übergangsmodus und bleibt vorerst.
 
-### B-01 Fundament — erledigt auf feature/portal-ausbau (Entscheidung: Ports bleiben)
-- Entscheidung: Adressen per Proxy-Pfad `/app/<key>/` oder weiter Ports.
-- Schritte: `ModuleRegistryEntry` um `group`, `path`, optional `module`; Hrefs relativ, `resolveModuleHref` nur Fallback; Route `GET /api/module-urls` (liest `/.well-known/nexarch-modules`, Env-Override `NEXARCH_MODULE_URL_<KEY>`, Cache); `ModuleGrid` nach `group` gruppieren; `tenantLabel` in `ModuleNavShell` aus Sitzungs-Identität statt Env.
-- Dateien: `web/shl/components/ModuleNavShell.tsx`, `web/portal/lib/modules.ts`, `web/portal/app/ModuleGrid.tsx`, neu `web/portal/app/api/module-urls/route.ts`.
-- Test: `web/portal` und `web/shl` vitest auf 131; Betriebsauftrag: Produktionsdatei des Modulverzeichnisses fehlt.
+### A-11 Root-Modul — offen
+- Root-httpclient hat strengeren Wächtertest und bleibt. Prüfen, ob weitere Pakete des Root-Moduls (auditclient, svcauth, tenantregistryclient) identisch zu common sind.
 
-### B-02 Arbeitsvorrat — erledigt auf feature/portal-ausbau (Entscheidung: X-User-Id als Übergang)
-- Entscheidung: Übergang mit `X-User-Id` aus verifiziertem Token-`sub`, solange Workflow kein Bearer kennt.
-- Schritte: Route `GET /api/worklist` (Token prüfen, serverseitig `/approvals`, `/tasks`, `/reminders/kanban`, Antwort nur Zähler); Cache-Schlüssel mit `sub`, 15 s, `Cache-Control: no-store`; Badges an Workflow-Kacheln und "Heute"-Leiste; Fehler je Quelle tolerant; Schnellsuche-Zeile als Deep-Link; Env `PORTAL_WORKFLOW_API_URL`.
-- Datenschutz: nur eigene Zähler, keine Inhalte.
+## B. Portal
 
-### B-03 Admin-/Prüfer-Sicht — erledigt auf feature/portal-ausbau (ohne Favoriten und ohne Ampel an Kacheln, Statusnamen passen nicht sicher zu Registry-Keys)
-- Route `GET /api/system-status` (nur nach `authorize(core.tenant.admin)`, Status-Endpunkt nur serverseitig); Route `GET /api/kennzahlen-summary` (Mandant und Rolle aus Claims, nur Totals); Ampel an Kacheln; Favoriten (localStorage, nur Modul-Keys) optional.
-
-### B-04 Umgebungsvariablen dokumentieren — erledigt (web/portal/README.md)
-- Neue Variablen: `PORTAL_CORE_API_URL`, `PORTAL_TOKEN_ISSUER`, `PORTAL_TOKEN_AUDIENCE`, `PORTAL_VISIBLE_MODULES_CACHE_SECONDS`; dazu `PORTAL_POLICY_API_URL`, `PORTAL_POLICY_SERVICE_TOKEN`. Nirgends dokumentiert; Doku im Portal anlegen.
+### B-01 bis B-04 — erledigt, in main (#372, #382)
+- Gruppen, Mandant aus Sitzung, Port-Hrefs mit Override `NEXARCH_MODULE_URL_<KEY>`; `/api/worklist`; `/api/system-status`, `/api/kennzahlen-summary`; Umgebungsvariablen in `web/portal/README.md`.
+- Bewusst nicht gebaut: Favoriten, Ampel an den Kacheln.
 
 ### B-05 Zielmodul `portal` im Core — Entscheidung nötig
-- Der Core stellt Modul-Tokens mit Zielmodul aus (Standard `dms`). Soll `portal` in `NEXARCH_ACCOUNT_MODULE_AUDIENCES` aufgenommen und `PORTAL_TOKEN_AUDIENCE=portal` gesetzt werden? Dann muss die Sitzung `?module=portal` mitschicken.
+- Soll `portal` in `NEXARCH_ACCOUNT_MODULE_AUDIENCES` stehen und `PORTAL_TOKEN_AUDIENCE=portal` gesetzt werden? Dann muss die Sitzung `?module=portal` mitschicken.
 
-### B-06 Workflow auf Bearer umstellen — Folgeticket
-- Workflow-API von `X-User-Id` auf Bearer (Muster: `mail/internal/moduleauth`); danach Header im Portal-BFF entfernen. Gleiches gilt für Audit-Log in dms (`caller`-Query).
+### B-06 Workflow auf Bearer-Token — wartet auf A-10
+- Entscheidungen: Verifier aus common; Übergang mit `NEXARCH_WORKFLOW_ALLOW_HEADER_AUTH=1` (Default aus), Bearer bevorzugt.
+- Betroffen: Workflow-Pakete approvalapi, taskapi, caseapi, caseoverviewapi, routingruleapi, backchannelapi; Frontend-Proxy-Routen in `web/workflow-tasks`, `web/workflow-cases`, `web/routing-rules`, `web/workflow-approvals`; Portal-BFF (`/api/worklist`).
+- Danach Schalter entfernen. Gleiches Muster für Audit-Log in dms (`caller`-Query) als eigene Karte.
 
-## C. Laufender Betrieb
+### B-07 Betrieb des Portals — Entscheidung nötig
+- Variablen setzen: `PORTAL_WORKFLOW_API_URL`, `PORTAL_STATUS_API_URL`, `PORTAL_KENNZAHLEN_API_URL`. Die Statusseite ist nicht authentifiziert und darf nur vom Portal-Server erreichbar sein.
 
-### C-01 Offene PRs mergen (User)
-- #373 (qa*-Gates, migration*), #374 (workflow contracttest), #375 (dms apierror 5xx), #380 (Docs), #372 (SHL: AccountBar, Portal-Route).
-- Vor Merge DB-Tests auf 204 für #373, #374, #375 laufen lassen (nie gelaufen).
+## C. Betrieb
+
+### C-01 Offene PRs
+- Reihenfolge-Vorschlag: #385, #394 (common) → #383, #384, #386, #387, #388, #389 → #390, #391, #392, #393 (nach Umstellung ihrer Basis auf main).
+- Weitere offene PRs: #373, #374, #380.
+- #375 ist geschlossen (ersetzt durch #384).
 
 ### C-02 Aufräumen — nur mit Freigabe
-- `/root/manticore-backup-pre29` auf 131 löschen, wenn der User es sagt.
-- 204: Dateileichen im Manticore-Datenverzeichnis (`dms_src13_*`, `mail_documents_reindex_*`, `qa10loadtest_*`) nur nach Sichtung durch den User.
+- `/root/manticore-backup-pre29` auf 131; Dateileichen im Manticore-Datenverzeichnis auf 204 nur nach Sichtung durch den User.
+- Verwaiste Test-Schemas `dmstest_*`, `workflowtest_*` können nach den testdb-Umstellungen als `connecttest_*` auftauchen.