feat: T6 wave 2 – medicine book, document rights, label particulars, herd events

- Veterinary medicine catalogue, lots and append-only movement ledger
  (rest always computed; corrections as counter-bookings; inactive
  medicines take no new stock; unit must match on lot moves).
- Documents of medicine lots, authority notices and restrictions need the
  domain right on top of documents:* (403 before any lookup).
- Label particulars: pure checkLabel with six mandatory gaps and four
  warnings, AFM font metrics, Berlin-day dates, geometric reading order
  for split addresses, new master-data fields with row-locked updates.
- Herd events ColonyCreated, ColonyMoved, ApiaryChanged and
  TskReferenceDayReached (ids only, never forwarded to webhooks); CSV
  import emits ColonyCreated with audit.
- ARCHITECTURE.md §12 Compliance (T6), Annahmen 59–70.

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

ApiCore-Backend/src/colonies/colonies.service.spec.ts

@@ -5,6 +5,7 @@ import { AuditLogService } from '../audit/audit-log.service';
 import { WebhooksService } from '../webhooks/webhooks.service';
 import { DomainEventsService } from '../domain-events/domain-events.service';
 import { berlinToday } from '../common/dates';
+import { expectOnlyIdPayloads } from '../domain-events/herd-payload.spec-helper';
 
 describe('ColoniesService', () => {
   let service: ColoniesService;
@@ -194,9 +195,12 @@ describe('ColoniesService', () => {
       'user-1',
     );
 
-    const [[, event]] = events.record.mock.calls as [
-      [unknown, { payload: { queenSource: unknown; splitOn: string } }],
-    ];
+    const event = (
+      events.record.mock.calls as [
+        unknown,
+        { type: string; payload: { queenSource: unknown; splitOn: string } },
+      ][]
+    ).find(([, recorded]) => recorded.type === 'ColonySplit')![1];
     expect(event.payload.queenSource).toBeNull();
     expect(event.payload.splitOn).toBe(berlinToday());
   });
@@ -514,6 +518,110 @@ describe('ColoniesService', () => {
     expect(tx.colonyApiaryHistory.create).not.toHaveBeenCalled();
   });
 
+  describe('herd events', () => {
+    // Whatever a test recorded, the herd payloads carry only ids.
+    afterEach(() => {
+      expectOnlyIdPayloads(events.record.mock.calls);
+    });
+
+    function recorded(type: string): unknown[] {
+      return (events.record.mock.calls as [unknown, { type: string }][]).filter(
+        ([, event]) => event.type === type,
+      );
+    }
+
+    it('create records ColonyCreated with the apiary inside the transaction', async () => {
+      tx.colony.create.mockResolvedValue({
+        id: 'colony-9',
+        apiaryId: 'apiary-1',
+      });
+
+      await service.create(
+        { code: 'V-9', apiaryId: 'apiary-1', colonyType: 'PRODUCTION_COLONY' },
+        'user-1',
+      );
+
+      expect(events.record).toHaveBeenCalledWith(tx, {
+        type: 'ColonyCreated',
+        aggregateType: 'Colony',
+        aggregateId: 'colony-9',
+        actorUserId: 'user-1',
+        payload: { apiaryId: 'apiary-1' },
+      });
+    });
+
+    it('split records ColonyCreated for the child next to ColonySplit', async () => {
+      prisma.colony.findUnique.mockResolvedValue(parentColony);
+      tx.colony.create.mockResolvedValue({
+        id: 'colony-2',
+        apiaryId: 'apiary-1',
+      });
+      tx.colonyLineage.create.mockResolvedValue({ id: 'lineage-1' });
+
+      await service.split(
+        'colony-1',
+        { code: 'V-001-A', colonyType: 'NUCLEUS_COLONY' },
+        'user-1',
+      );
+
+      const types = (
+        events.record.mock.calls as [unknown, { type: string }][]
+      ).map(([, event]) => event.type);
+      expect(types).toEqual(
+        expect.arrayContaining(['ColonySplit', 'ColonyCreated']),
+      );
+      expect(events.record).toHaveBeenCalledWith(tx, {
+        type: 'ColonyCreated',
+        aggregateType: 'Colony',
+        aggregateId: 'colony-2',
+        actorUserId: 'user-1',
+        payload: { apiaryId: 'apiary-1' },
+      });
+    });
+
+    it('move records ColonyMoved with from and to', async () => {
+      prisma.colony.findUnique.mockResolvedValue(parentColony);
+      tx.colony.update.mockResolvedValue({
+        ...parentColony,
+        apiaryId: 'apiary-2',
+      });
+
+      await service.move('colony-1', { apiaryId: 'apiary-2' }, 'user-1');
+
+      expect(events.record).toHaveBeenCalledWith(tx, {
+        type: 'ColonyMoved',
+        aggregateType: 'Colony',
+        aggregateId: 'colony-1',
+        actorUserId: 'user-1',
+        payload: { fromApiaryId: 'apiary-1', toApiaryId: 'apiary-2' },
+      });
+    });
+
+    it('update with a changed apiary records ColonyMoved and without one records none', async () => {
+      prisma.colony.findUnique.mockResolvedValue(parentColony);
+      tx.colony.update.mockResolvedValue({
+        ...parentColony,
+        apiaryId: 'apiary-2',
+      });
+
+      await service.update('colony-1', { apiaryId: 'apiary-2' }, 'user-1');
+      expect(recorded('ColonyMoved')).toHaveLength(1);
+      expect(events.record).toHaveBeenCalledWith(
+        tx,
+        expect.objectContaining({
+          type: 'ColonyMoved',
+          payload: { fromApiaryId: 'apiary-1', toApiaryId: 'apiary-2' },
+        }),
+      );
+
+      events.record.mockClear();
+      tx.colony.update.mockResolvedValue(parentColony);
+      await service.update('colony-1', { notes: 'x' }, 'user-1');
+      await service.update('colony-1', { apiaryId: 'apiary-1' }, 'user-1');
+      expect(recorded('ColonyMoved')).toHaveLength(0);
+    });
+  });
+
   it('update into CRITICAL health records ColonyStatusChanged with from/to snapshots', async () => {
     prisma.colony.findUnique.mockResolvedValue({
       ...parentColony,

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

@@ -8,6 +8,8 @@ import { PrismaService } from '../prisma/prisma.service';
 import { AuditLogService } from '../audit/audit-log.service';
 import { WebhooksService } from '../webhooks/webhooks.service';
 import { DomainEventsService } from '../domain-events/domain-events.service';
+import type { AnyNewDomainEvent } from '../domain-events/domain-event-types';
+import { colonyCreatedEvent } from './colony-created-event';
 import { Colony, ColonyStatus, Prisma } from '../../generated/prisma';
 import { CreateColonyDto } from './dto/create-colony.dto';
 import { UpdateColonyDto } from './dto/update-colony.dto';
@@ -23,6 +25,21 @@ import { lockRowsForUpdate } from '../prisma/row-lock';
 import { colonyTransitionEvents, lockColony } from './colony-events';
 import { berlinToday, dayToDate } from '../common/dates';
 
+function colonyMovedEvent(
+  colonyId: string,
+  fromApiaryId: string,
+  toApiaryId: string,
+  actorUserId: string,
+): AnyNewDomainEvent<'ColonyMoved'> {
+  return {
+    type: 'ColonyMoved',
+    aggregateType: 'Colony',
+    aggregateId: colonyId,
+    actorUserId,
+    payload: { fromApiaryId, toApiaryId },
+  };
+}
+
 export interface ColonyFilter {
   status?: ColonyStatus;
   apiaryId?: string;
@@ -96,10 +113,10 @@ export class ColoniesService {
         },
         tx,
       );
+      await this.events.record(tx, colonyCreatedEvent(created, actingUserId));
       return created;
     });
-    // No domain event for a new colony in this stage - the webhook stays on
-    // the direct path.
+    // The webhook stays on the direct path (the event is not forwarded).
     await this.webhooks.dispatch('colony.created', colony);
     return colony;
   }
@@ -159,6 +176,10 @@ export class ColoniesService {
           notes: 'Korrektur über Volk bearbeiten',
         },
       });
+      await this.events.record(
+        tx,
+        colonyMovedEvent(id, before.apiaryId, updated.apiaryId, actingUserId),
+      );
     }
     await this.events.recordAll(
       tx,
@@ -204,6 +225,12 @@ export class ColoniesService {
           notes: dto.notes,
         },
       });
+      if (before.apiaryId !== updated.apiaryId) {
+        await this.events.record(
+          tx,
+          colonyMovedEvent(id, before.apiaryId, updated.apiaryId, actingUserId),
+        );
+      }
       await this.auditLog.record(
         {
           entityType: 'Colony',
@@ -263,6 +290,7 @@ export class ColoniesService {
         },
         tx,
       );
+      await this.events.record(tx, colonyCreatedEvent(created, actingUserId));
       await this.events.record(tx, {
         type: 'ColonySplit',
         aggregateType: 'Colony',

ApiCore-Backend/src/colonies/colony-created-event.ts

@@ -0,0 +1,20 @@
+import type { Colony } from '../../generated/prisma';
+import type { AnyNewDomainEvent } from '../domain-events/domain-event-types';
+
+/**
+ * The ColonyCreated event of a colony that was just written (create, split
+ * child, CSV import). The caller records it in the transaction that wrote the
+ * colony. Backup restore deliberately records none.
+ */
+export function colonyCreatedEvent(
+  colony: Pick<Colony, 'id' | 'apiaryId'>,
+  actorUserId: string,
+): AnyNewDomainEvent<'ColonyCreated'> {
+  return {
+    type: 'ColonyCreated',
+    aggregateType: 'Colony',
+    aggregateId: colony.id,
+    actorUserId,
+    payload: { apiaryId: colony.apiaryId },
+  };
+}