feat(queens): verdrängte Königin bekommt ihren Endstatus automatisch

Entscheidung Inhaber: Zieht eine neue Königin ein, wird die bisherige
„Ersetzt“; Vereinigen und Auflösen eines Volks setzen dessen Königin auf
„Ersetzt“, ein Winterverlust auf „Eingegangen“. Nur aus einem verfügbaren
Status (ACTIVE, RESERVE, MATED, UNMATED), über updateStatusIn in derselben
Transaktion mit Archivdatum und Audit (QueensService.retireIn). Ein von
Hand gesetzter Endstatus eines Volks fragt weiter über den Aufräum-
Vorschlag nach.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

ApiCore-Backend/src/queens/queens.service.ts

@@ -232,6 +232,28 @@ export class QueensService {
     return updated;
   }
 
+  /**
+   * Retires a queen who just left her colony with it (displaced by a new
+   * queen, colony merged, dissolved or died): sets `status` through
+   * updateStatusIn while she is still recorded as available, so she moves to
+   * the archive. A status that already takes her out of use stays. The
+   * caller has released her from the colony first.
+   */
+  async retireIn(
+    tx: Prisma.TransactionClient,
+    id: string,
+    status: QueenStatus,
+    actingUserId: string,
+  ): Promise<void> {
+    assertTransactionClient(tx, 'QueensService.retireIn');
+    await lockRowForUpdate(tx, 'Queen', id);
+    const queen = await tx.queen.findUnique({ where: { id } });
+    if (!queen || QUEEN_NO_LONGER_AVAILABLE_STATUSES.includes(queen.status)) {
+      return;
+    }
+    await this.updateStatusIn(tx, id, status, actingUserId);
+  }
+
   async assignColony(
     id: string,
     dto: AssignColonyDto,
@@ -321,6 +343,14 @@ export class QueensService {
           status: colony.status === 'QUEENLESS' ? 'ACTIVE' : undefined,
         },
       });
+      if (colony.currentQueenId) {
+        await this.retireIn(
+          tx,
+          colony.currentQueenId,
+          'REPLACED',
+          actingUserId,
+        );
+      }
       const history = await tx.queenColonyHistory.create({
         data: {
           queenId: queen.id,