feat(backend): Voelker-Modul (Modul 3)

ColoniesModule: CRUD + Move/Split/Merge/Dissolve/History, entsprechend
Lastenheft §4.4 (Lebenszyklus eines Volkes):
- move: Standortwechsel, protokolliert in ColonyApiaryHistory.
- split: erzeugt Ableger als neues Volk, Abstammung ueber
  ColonyLineage(SPLIT, von Mutter- zu Ablegervolk).
- merge: vereinigtes Volk bleibt historisch erhalten (status MERGED,
  deactivatedAt gesetzt statt geloescht), ColonyLineage(MERGE) je
  vereinigtem Volk zum Zielvolk.
- dissolve: Volk wird deaktiviert (status DISSOLVED), Dokumentation
  bleibt erhalten.
- history: aggregiert Standort-Historie, Koeniginnen-Historie und
  Abstammungslinien (als Quelle und als Ergebnis).

Move/Split/Merge laufen transaktional (prisma.$transaction). Rollen wie
bei Apiaries: Lesen offen, Schreiben auf ADMIN/BEEKEEPER beschraenkt.

9 Unit-Tests + 6 e2e-Tests (inkl. vollstaendigem Move->Split->Merge->
Dissolve-Flow und Rollenpruefung), Lint, Typecheck und Build gruen.

ApiCore-Backend/test/colonies.e2e-spec.ts

@@ -0,0 +1,192 @@
+import { INestApplication } from '@nestjs/common';
+import * as bcrypt from 'bcryptjs';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { PrismaService } from '../src/prisma/prisma.service';
+import { createTestApp } from './utils/create-test-app';
+import { login } from './utils/api';
+
+interface ColonyBody {
+  id: string;
+  code: string;
+  apiaryId: string;
+  status: string;
+}
+
+interface ColonyHistoryBody {
+  apiaryHistory: unknown[];
+  queenHistory: unknown[];
+  lineageAsSource: unknown[];
+  lineageAsResult: unknown[];
+}
+
+describe('Colonies (e2e)', () => {
+  let app: INestApplication<App>;
+  let prisma: PrismaService;
+  const beekeeperEmail = `colonies-e2e-beekeeper-${Date.now()}@example.com`;
+  const staffEmail = `colonies-e2e-staff-${Date.now()}@example.com`;
+  const password = 'SuperSecret123!';
+  let beekeeperId: string;
+  let staffId: string;
+  let beekeeperToken: string;
+  let staffToken: string;
+  let apiaryAId: string;
+  let apiaryBId: string;
+  let colonyId: string;
+  let childColonyId: string;
+  let colonyToMergeId: string;
+
+  beforeAll(async () => {
+    app = await createTestApp();
+    prisma = app.get(PrismaService);
+
+    const passwordHash = await bcrypt.hash(password, 12);
+    const beekeeper = await prisma.user.create({
+      data: {
+        email: beekeeperEmail,
+        passwordHash,
+        name: 'Beekeeper',
+        role: 'BEEKEEPER',
+      },
+    });
+    beekeeperId = beekeeper.id;
+    const staff = await prisma.user.create({
+      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+    });
+    staffId = staff.id;
+
+    beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;
+    staffToken = (await login(app, staffEmail, password)).accessToken;
+
+    const apiaryA = await prisma.apiary.create({
+      data: { name: `Stand A ${Date.now()}` },
+    });
+    apiaryAId = apiaryA.id;
+    const apiaryB = await prisma.apiary.create({
+      data: { name: `Stand B ${Date.now()}` },
+    });
+    apiaryBId = apiaryB.id;
+  });
+
+  afterAll(async () => {
+    await prisma.colonyLineage.deleteMany({
+      where: { OR: [{ fromColonyId: colonyId }, { toColonyId: colonyId }] },
+    });
+    await prisma.colonyApiaryHistory.deleteMany({ where: { colonyId } });
+    await prisma.colony.deleteMany({
+      where: {
+        id: { in: [colonyId, childColonyId, colonyToMergeId].filter(Boolean) },
+      },
+    });
+    await prisma.apiary.deleteMany({
+      where: { id: { in: [apiaryAId, apiaryBId] } },
+    });
+    await prisma.refreshToken.deleteMany({
+      where: { userId: { in: [beekeeperId, staffId] } },
+    });
+    await prisma.auditLog.deleteMany({
+      where: { userId: { in: [beekeeperId, staffId] } },
+    });
+    await prisma.user.deleteMany({
+      where: { id: { in: [beekeeperId, staffId] } },
+    });
+    await app.close();
+  });
+
+  it('rejects colony creation for STAFF', () => {
+    return request(app.getHttpServer())
+      .post('/api/v1/colonies')
+      .set('Authorization', `Bearer ${staffToken}`)
+      .send({
+        code: `V-${Date.now()}`,
+        apiaryId: apiaryAId,
+        colonyType: 'PRODUCTION_COLONY',
+      })
+      .expect(403);
+  });
+
+  it('lets a BEEKEEPER create a colony', async () => {
+    const response = await request(app.getHttpServer())
+      .post('/api/v1/colonies')
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .send({
+        code: `V-${Date.now()}`,
+        apiaryId: apiaryAId,
+        colonyType: 'PRODUCTION_COLONY',
+      })
+      .expect(201);
+    const created = response.body as ColonyBody;
+    expect(created.apiaryId).toBe(apiaryAId);
+    colonyId = created.id;
+  });
+
+  it('moves the colony to another apiary and records history', async () => {
+    const response = await request(app.getHttpServer())
+      .post(`/api/v1/colonies/${colonyId}/move`)
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .send({ apiaryId: apiaryBId, notes: 'Umzug' })
+      .expect(201);
+    expect((response.body as ColonyBody).apiaryId).toBe(apiaryBId);
+
+    const history = await request(app.getHttpServer())
+      .get(`/api/v1/colonies/${colonyId}/history`)
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .expect(200);
+    expect((history.body as ColonyHistoryBody).apiaryHistory).toHaveLength(1);
+  });
+
+  it('splits the colony into a new nucleus colony', async () => {
+    const response = await request(app.getHttpServer())
+      .post(`/api/v1/colonies/${colonyId}/split`)
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .send({ code: `V-${Date.now()}-A`, colonyType: 'NUCLEUS_COLONY' })
+      .expect(201);
+    const child = response.body as ColonyBody;
+    expect(child.apiaryId).toBe(apiaryBId);
+    childColonyId = child.id;
+
+    const history = await request(app.getHttpServer())
+      .get(`/api/v1/colonies/${colonyId}/history`)
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .expect(200);
+    expect((history.body as ColonyHistoryBody).lineageAsSource).toHaveLength(1);
+  });
+
+  it('merges another colony into the surviving one', async () => {
+    const otherColony = await request(app.getHttpServer())
+      .post('/api/v1/colonies')
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .send({
+        code: `V-${Date.now()}-M`,
+        apiaryId: apiaryBId,
+        colonyType: 'PRODUCTION_COLONY',
+      })
+      .expect(201);
+    colonyToMergeId = (otherColony.body as ColonyBody).id;
+
+    await request(app.getHttpServer())
+      .post(`/api/v1/colonies/${colonyId}/merge`)
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .send({ mergedColonyIds: [colonyToMergeId] })
+      .expect(201);
+
+    const merged = await request(app.getHttpServer())
+      .get(`/api/v1/colonies/${colonyToMergeId}`)
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .expect(200);
+    expect((merged.body as ColonyBody).status).toBe('MERGED');
+  });
+
+  it('dissolves the colony without deleting it', async () => {
+    const response = await request(app.getHttpServer())
+      .post(`/api/v1/colonies/${colonyId}/dissolve`)
+      .set('Authorization', `Bearer ${beekeeperToken}`)
+      .expect(201);
+    expect((response.body as ColonyBody).status).toBe('DISSOLVED');
+
+    await request(app.getHttpServer())
+      .get(`/api/v1/colonies/${colonyId}`)
+      .set('Authorization', `Bearer ${staffToken}`)
+      .expect(200);
+  });
+});