feat: support parallel legacy and sandbox extensions

2026-07-13 15:09:21 +02:00
parent b8ad580ae5
commit 58dcc9f943
89 changed files with 10102 additions and 123 deletions
--- a/docs/legacy-sandbox-development.md
+++ b/docs/legacy-sandbox-development.md
@@ -0,0 +1,76 @@
+# Legacy- und Sandbox-Entwicklung
+
+## Unterstuetzte Varianten
+
+| Variante | Matrix42 ESM | Runtime | Solution | Paket |
+|---|---|---|---|---|
+| Legacy | 12.1.3 bis 25.x | .NET Framework 4.7.2 | `C4IT - F4SD - M42WebApi.Legacy.sln` | `artifacts/Legacy/<Configuration>/` |
+| Sandbox | 26.1 und neuer | .NET 8 | `C4IT - F4SD - M42WebApi.sln` | `artifacts/<Configuration>/` |
+
+Beide Varianten verwenden dieselbe Version aus `SharedAssemblyInfo.cs`. Die Webservice-spezifischen Ticketvertraege liegen in `F4SDHelper/Common/C4IT.F4SD.WebApi.Contracts.cs`. Die externe `_Common/C4IT.F4SD.Base.Ticket.cs` bleibt unveraendert, da sie auch F4SD Client und Server verwenden.
+
+## Entwicklungsregeln
+
+- Fachliche Aenderungen werden in beiden Hosts umgesetzt und mit derselben Postman-Collection getestet.
+- Matrix42-Abhaengigkeiten, Controller-Rueckgaben, Journalzugriff und Paketformat bleiben host-spezifisch.
+- Bestehende SID-Routen bleiben kompatibel; neue Funktionen sollen bevorzugt die `userId`-Routen verwenden.
+- Matrix42-Operation-IDs bestehender Routen duerfen nicht geaendert werden.
+- Eine neue Operation erhaelt einmalig eine feste ID, die in Legacy- und Sandbox-Paket identisch ist.
+- Legacy wird gegen die Bibliotheken der 12.1.3-Umgebung gebaut. Die Laufzeitkompatibilitaet muss zusaetzlich auf einer aktuellen 25.x-Installation geprueft werden.
+
+## TFS nach Git
+
+1. Aktuellen TFS-Stand in ein separates Verzeichnis holen.
+2. In Git den Branch `sync/tfs-legacy` vom zuletzt integrierten Stand erstellen.
+3. Nur die verwalteten Legacy-Quellen importieren:
+
+```powershell
+.\tools\Sync-TfsLegacy.ps1 `
+  -TfsExportRoot 'C:\Workspace\C4IT FASD\F4SD_M42WebApi\sonstiges\F4SD_M42WebApi_TFS' `
+  -Changeset '<TFS-Changeset>'
+```
+
+4. Diff pruefen und den Snapshot als eigenen Commit einchecken.
+5. Den Sync-Branch per normalem Drei-Wege-Merge in den Entwicklungsbranch integrieren.
+6. Fachliche Konflikte im gemeinsamen Verhalten aufloesen; Legacy-Projektdateien niemals ueber Sandbox-Projektdateien kopieren.
+
+Das Skript importiert ausschliesslich vom TFS nach Git. Es fuehrt keinen TFS-Check-in aus.
+
+## Git nach TFS
+
+Der Rueckweg ist absichtlich manuell:
+
+1. Finalen Git-Diff der Legacy-Dateien pruefen.
+2. Die betroffenen Legacy- und gemeinsamen Dateien in den lokalen TFS-Workspace uebernehmen.
+3. In Visual Studio unter Pending Changes kontrollieren, welche Dateien geaendert werden.
+4. Legacy-Solution aus dem TFS-Workspace bauen und testen.
+5. Check-in-Kommentar mit Git-Commit und Paketversion versehen.
+6. Den TFS-Check-in manuell in Visual Studio ausfuehren.
+
+Automatische `tf checkin`-, Reconcile- oder Upload-Skripte sind fuer dieses Repository nicht zulaessig.
+
+## Builds
+
+```powershell
+msbuild '.\C4IT - F4SD - M42WebApi.Legacy.sln' /restore /p:Configuration=Debug
+msbuild '.\C4IT - F4SD - M42WebApi.sln' /restore /p:Configuration=Debug
+```
+
+Verfuegbare Konfigurationen fuer beide Varianten:
+
+- `Debug`: Debug-DLLs und Debug-Paket
+- `Release`: optimiertes, unsigniertes Paket
+- `Release_signed`: optimiertes und signiertes Paket
+
+Das Signing ist nur in `Release_signed` automatisch aktiv und signiert alle Paket-DLLs in einem Aufruf.
+
+## Abnahmetests
+
+- Beide Solutions bauen.
+- Paket- und Assembly-Version stimmen ueberein.
+- Bestehende SID-Routen funktionieren weiterhin.
+- `userId`-Routen liefern fuer denselben Benutzer fachlich dieselben Ergebnisse.
+- Leere Ticketlisten liefern `[]`.
+- Alle Query-Parameter werden gebunden.
+- Ticketdetails, Journal, Pickup, Rollen, Direct Links und `isAlive` werden getestet.
+- Operationsdateien sind in `install.xml` registriert und erzeugen nach Service-Synchronisierung keine Duplikate.
--- a/docs/matrix42-26-1-extension-migration.md
+++ b/docs/matrix42-26-1-extension-migration.md
@@ -1,6 +1,8 @@
 # Matrix42 26.1 Legacy Extension Migration

-Diese Notizen dokumentieren die bisherigen Learnings aus der Migration einer alten Matrix42 Extension inklusive Custom Web Service auf eine Matrix42 26.1 Sandboxed Extension.
+Diese Notizen dokumentieren die bisherigen Learnings aus der Migration einer alten Matrix42 Extension inklusive Custom Web Service auf eine Matrix42 26.1 Sandboxed Extension.
+
+Die parallele Pflege der Legacy- und Sandbox-Varianten sowie der manuelle TFS-Rueckweg sind in `docs/legacy-sandbox-development.md` beschrieben.

 Die Anleitung ist bewusst als wiederverwendbare Checkliste fuer weitere Legacy-Pakete formuliert. Sie trennt zwischen belastbaren Ergebnissen, verworfenen Zwischenansaetzen und Punkten, die bei jeder Extension erneut geprueft werden muessen.

--- a/docs/postman/C4IT-F4SD-M42WebApi.postman_collection.json
+++ b/docs/postman/C4IT-F4SD-M42WebApi.postman_collection.json
@@ -928,7 +928,100 @@
            }
          }
        }
-      ]
-    }
-  ]
-}
+      ]
+    },
+    {
+      "name": "05 User ID APIs",
+      "item": [
+        {
+          "name": "getTicketListForUser",
+          "request": {
+            "method": "GET",
+            "header": [{ "key": "Accept", "value": "application/json" }],
+            "url": {
+              "raw": "{{baseUrl}}/api/c4itf4sdwebapi/getTicketListForUser?userId={{userId}}&hours={{hours}}&queueoption={{queueOption}}&queues={{queues}}",
+              "host": ["{{baseUrl}}"],
+              "path": ["api", "c4itf4sdwebapi", "getTicketListForUser"],
+              "query": [
+                { "key": "userId", "value": "{{userId}}" },
+                { "key": "hours", "value": "{{hours}}" },
+                { "key": "queueoption", "value": "{{queueOption}}" },
+                { "key": "queues", "value": "{{queues}}" }
+              ]
+            }
+          }
+        },
+        {
+          "name": "getTicketOverviewCountsForUser",
+          "request": {
+            "method": "GET",
+            "header": [{ "key": "Accept", "value": "application/json" }],
+            "url": {
+              "raw": "{{baseUrl}}/api/c4itf4sdwebapi/getTicketOverviewCountsForUser?userId={{userId}}&scope={{scope}}&keys={{overviewKeys}}&queueoption={{queueOption}}&queues={{queues}}",
+              "host": ["{{baseUrl}}"],
+              "path": ["api", "c4itf4sdwebapi", "getTicketOverviewCountsForUser"],
+              "query": [
+                { "key": "userId", "value": "{{userId}}" },
+                { "key": "scope", "value": "{{scope}}" },
+                { "key": "keys", "value": "{{overviewKeys}}" },
+                { "key": "queueoption", "value": "{{queueOption}}" },
+                { "key": "queues", "value": "{{queues}}" }
+              ]
+            }
+          }
+        },
+        {
+          "name": "getTicketOverviewCountsByRolesForUser",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Accept", "value": "application/json" },
+              { "key": "Content-Type", "value": "application/json" }
+            ],
+            "body": {
+              "mode": "raw",
+              "raw": "{\r\n  \"userId\": \"{{userId}}\",\r\n  \"RoleGuids\": [\"{{roleGuid}}\"],\r\n  \"Keys\": [\"TicketsNew\", \"TicketsActive\"],\r\n  \"QueueOption\": {{queueOption}},\r\n  \"Queues\": \"{{queues}}\"\r\n}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/api/c4itf4sdwebapi/getTicketOverviewCountsByRolesForUser",
+              "host": ["{{baseUrl}}"],
+              "path": ["api", "c4itf4sdwebapi", "getTicketOverviewCountsByRolesForUser"]
+            }
+          }
+        },
+        {
+          "name": "getTicketOverviewRelationsForUser",
+          "request": {
+            "method": "GET",
+            "header": [{ "key": "Accept", "value": "application/json" }],
+            "url": {
+              "raw": "{{baseUrl}}/api/c4itf4sdwebapi/getTicketOverviewRelationsForUser?userId={{userId}}&scope={{scope}}&key={{overviewKey}}&count={{overviewRelationExpectedCount}}&queueoption={{queueOption}}&queues={{queues}}",
+              "host": ["{{baseUrl}}"],
+              "path": ["api", "c4itf4sdwebapi", "getTicketOverviewRelationsForUser"],
+              "query": [
+                { "key": "userId", "value": "{{userId}}" },
+                { "key": "scope", "value": "{{scope}}" },
+                { "key": "key", "value": "{{overviewKey}}" },
+                { "key": "count", "value": "{{overviewRelationExpectedCount}}" },
+                { "key": "queueoption", "value": "{{queueOption}}" },
+                { "key": "queues", "value": "{{queues}}" }
+              ]
+            }
+          }
+        },
+        {
+          "name": "getRoleMemberships path by user id",
+          "request": {
+            "method": "GET",
+            "header": [{ "key": "Accept", "value": "application/json" }],
+            "url": {
+              "raw": "{{baseUrl}}/api/c4itf4sdwebapi/getRoleMemberships/{{userId}}",
+              "host": ["{{baseUrl}}"],
+              "path": ["api", "c4itf4sdwebapi", "getRoleMemberships", "{{userId}}"]
+            }
+          }
+        }
+      ]
+    }
+  ]
+}