feat: platform backbone and field capture, first part (checkpoint)

Platform backbone (plan 2026-10-13-plattform-rueckgrat), reviewed tasks:
- run roles api/worker/job/all with shared startup checks (Task 1)
- schema and migration for DomainEvent, deliveries, JobRun, ThrottlerHit (Task 2)
- audit, notifications and domain events written in the same transaction (Task 3)
- dispatcher with SKIP LOCKED claims, retries and stale release (Task 4)
- worker building blocks: tick, LISTEN/NOTIFY wake-up, health (Task 5)
- worker process and entry points (Task 6)
- throttler counters in Postgres (Task 19)
- separate keys per purpose with key ring (Task 20)
- public origin page without exact location (Task 22)
- shop keys split into read and write (Task 23)
- Kustomize base, components, overlay encry, CI validation (Task 26)

Field capture T3 (plan 2026-10-13-t3-erfassung-am-stand), reviewed tasks:
- brood frames, read endpoints, apiary overview and offline pack
- network basics, offline queue v3, navigation sheets, form building blocks
- new inspection with last-time hints and weather, varroa per day,
  treatment prefill, apiary page with round
- inspection photo (Task 10) is implemented, review pending

Not rolled out. Remaining tasks follow in later commits.

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

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

@@ -2,25 +2,35 @@ import { ForbiddenException, NotFoundException } from '@nestjs/common';
 import { NotificationsService } from './notifications.service';
 import { PrismaService } from '../prisma/prisma.service';
 
+type CreateManyArg = { data: { userId: string; message: string }[] };
+
 describe('NotificationsService', () => {
   let service: NotificationsService;
   let prisma: {
     notification: {
       create: jest.Mock;
+      createMany: jest.Mock;
       findMany: jest.Mock;
       findUnique: jest.Mock;
       update: jest.Mock;
     };
+    user: { findMany: jest.Mock };
   };
 
   beforeEach(() => {
     prisma = {
       notification: {
         create: jest.fn(),
+        createMany: jest
+          .fn()
+          .mockImplementation(({ data }: CreateManyArg) =>
+            Promise.resolve({ count: data.length }),
+          ),
         findMany: jest.fn(),
         findUnique: jest.fn(),
         update: jest.fn(),
       },
+      user: { findMany: jest.fn().mockResolvedValue([]) },
     };
     service = new NotificationsService(prisma as unknown as PrismaService);
   });
@@ -44,6 +54,93 @@ describe('NotificationsService', () => {
     });
   });
 
+  it('records through the transaction client when one is given', async () => {
+    const tx = { notification: { create: jest.fn() } };
+
+    await service.record(
+      { priority: 'HINWEIS', message: 'Aufgabe fällig' },
+      tx as never,
+    );
+
+    expect(tx.notification.create).toHaveBeenCalledTimes(1);
+    expect(prisma.notification.create).not.toHaveBeenCalled();
+  });
+
+  describe('recordForPermission', () => {
+    it('notifies every active user whose active role holds the permission', async () => {
+      prisma.user.findMany.mockResolvedValue([{ id: 'u1' }, { id: 'u2' }]);
+
+      await expect(
+        service.recordForPermission('backup:configure', {
+          priority: 'WARNUNG',
+          message: 'Job „App-Backup“ fehlgeschlagen',
+        }),
+      ).resolves.toBe(2);
+
+      const [[createArg]] = prisma.notification.createMany.mock.calls as [
+        [CreateManyArg],
+      ];
+      expect(createArg.data.map((n) => n.userId)).toEqual(['u1', 'u2']);
+      expect(createArg.data[0]).toEqual({
+        userId: 'u1',
+        priority: 'WARNUNG',
+        message: 'Job „App-Backup“ fehlgeschlagen',
+      });
+    });
+
+    it('selects recipients like the permission guard: active user, active role, granted key', async () => {
+      await service.recordForPermission('backup:configure', {
+        priority: 'WARNUNG',
+        message: 'x',
+      });
+
+      expect(prisma.user.findMany).toHaveBeenCalledWith({
+        where: {
+          isActive: true,
+          role: {
+            status: 'ACTIVE',
+            permissions: {
+              some: { permission: { key: 'backup:configure' } },
+            },
+          },
+        },
+        select: { id: true },
+      });
+    });
+
+    it('writes nothing and returns 0 when nobody holds the permission', async () => {
+      await expect(
+        service.recordForPermission('backup:configure', {
+          priority: 'WARNUNG',
+          message: 'x',
+        }),
+      ).resolves.toBe(0);
+
+      expect(prisma.notification.createMany).not.toHaveBeenCalled();
+    });
+
+    it('reads and writes through the transaction client when one is given', async () => {
+      const tx = {
+        user: { findMany: jest.fn().mockResolvedValue([{ id: 'u1' }]) },
+        notification: {
+          createMany: jest.fn().mockResolvedValue({ count: 1 }),
+        },
+      };
+
+      await expect(
+        service.recordForPermission(
+          'backup:configure',
+          { priority: 'WARNUNG', message: 'x' },
+          tx as never,
+        ),
+      ).resolves.toBe(1);
+
+      expect(tx.notification.createMany).toHaveBeenCalledTimes(1);
+      expect(prisma.user.findMany).not.toHaveBeenCalled();
+      expect(prisma.notification.createMany).not.toHaveBeenCalled();
+    });
+  });
+
   it('lists notifications for a user including broadcast notifications', async () => {
     await service.findAll({ userId: 'user-1' });
 

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

@@ -4,7 +4,13 @@ import {
   NotFoundException,
 } from '@nestjs/common';
 import { PrismaService } from '../prisma/prisma.service';
-import { Notification, NotificationPriority } from '../../generated/prisma';
+import { DbClient } from '../prisma/db-client';
+import { PermissionKey } from '../auth/permissions/permission-catalog';
+import {
+  Notification,
+  NotificationPriority,
+  Prisma,
+} from '../../generated/prisma';
 
 export interface CreateNotificationInput {
   userId?: string;
@@ -23,8 +29,42 @@ export interface NotificationFilter {
 export class NotificationsService {
   constructor(private readonly prisma: PrismaService) {}
 
-  async record(input: CreateNotificationInput): Promise<Notification> {
-    return this.prisma.notification.create({ data: { ...input } });
+  async record(
+    input: CreateNotificationInput,
+    tx?: Prisma.TransactionClient,
+  ): Promise<Notification> {
+    const db: DbClient = tx ?? this.prisma;
+    return db.notification.create({ data: { ...input } });
+  }
+
+  /**
+   * One notification per user who may act on it: active account, active
+   * role, permission granted - the same rule the PermissionsGuard applies.
+   * Returns how many were written.
+   */
+  async recordForPermission(
+    permission: PermissionKey,
+    input: Omit<CreateNotificationInput, 'userId'>,
+    tx?: Prisma.TransactionClient,
+  ): Promise<number> {
+    const db: DbClient = tx ?? this.prisma;
+    const recipients = await db.user.findMany({
+      where: {
+        isActive: true,
+        role: {
+          status: 'ACTIVE',
+          permissions: { some: { permission: { key: permission } } },
+        },
+      },
+      select: { id: true },
+    });
+    if (recipients.length === 0) {
+      return 0;
+    }
+    const { count } = await db.notification.createMany({
+      data: recipients.map((recipient) => ({ ...input, userId: recipient.id })),
+    });
+    return count;
   }
 
   async findAll(filter: NotificationFilter = {}): Promise<Notification[]> {