feat: platform backbone and field capture complete (checkpoint)

Platform backbone (plan 2026-10-13-plattform-rueckgrat), all tasks reviewed:
- webhooks with delivery table, retries and stable delivery id
- calendar handlers; a finished task removes its Outlook event
- tasks, automations, inspections, varroa, treatments, feedings,
  harvests, colonies, wintering, stock and bottling record domain events
  in the same transaction; legacy post-commit calls removed
- row locks through one helper (lockRowForUpdate, lockRowsForShare,
  lockRowsForUpdate)
- job framework with JobRun, cli exit codes, cleanup, task templates,
  daily evaluation, hourly app-backup and the rekey job
- system API and page "Verwaltung > System" with retry
- @nestjs/schedule removed, guard tests against in-process schedulers

Field capture T3 (plan 2026-10-13-t3-erfassung-am-stand), all tasks reviewed:
- inspection photo offline without metadata
- bulk capture for treatments, feedings and varroa (backend + frontend)
- offline stand mode with service worker, offline pages and packs
- offline session, cold start and logout on shared devices

Docs: ARCHITECTURE.md assumptions and sections updated, TASKS.md.
Gates: backend lint, typecheck, 1770 unit, 420 e2e, build, no schema
drift; frontend lint, typecheck, 913 tests, build. Not rolled out.

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

ApiCore-Frontend/src/lib/offline/sync.spec.ts

@@ -2,10 +2,12 @@ import "fake-indexeddb/auto";
 import { IDBFactory } from "fake-indexeddb";
 import { openDB } from "idb";
 import { beforeEach, describe, expect, it, vi, type MockedFunction } from "vitest";
+import { readHandOvers, rememberHandOver } from "@/lib/photos/handover";
 
 vi.mock("@/lib/inspections/api", () => ({ createInspection: vi.fn() }));
 vi.mock("@/lib/treatments/api", () => ({ createTreatment: vi.fn() }));
 vi.mock("@/lib/documents/api", () => ({ uploadDocument: vi.fn() }));
+vi.mock("@/lib/apiaries/offline-pack", () => ({ refreshPacksAfterSync: vi.fn() }));
 
 // What the inspection drain hands over to the photos, seen at that moment.
 const photoHandOver = vi.hoisted(() => ({
@@ -44,6 +46,9 @@ let ApiError: ApiErrorClass;
 let createInspection: MockedFunction<typeof import("@/lib/inspections/api").createInspection>;
 let createTreatment: MockedFunction<typeof import("@/lib/treatments/api").createTreatment>;
 let uploadDocument: MockedFunction<typeof import("@/lib/documents/api").uploadDocument>;
+let refreshPacksAfterSync: MockedFunction<
+  typeof import("@/lib/apiaries/offline-pack").refreshPacksAfterSync
+>;
 
 function inspection(colony: number) {
   return { colonyId: `colony-${colony}`, date: "2026-10-01T00:00:00.000Z" };
@@ -81,6 +86,7 @@ describe("syncPendingEntries", () => {
     // A fresh database and fresh modules: nothing (no open connection, no
     // in-flight run) carries over from the previous test.
     globalThis.indexedDB = new IDBFactory();
+    window.localStorage.clear();
     vi.resetModules();
     db = await import("./db");
     sync = await import("./sync");
@@ -89,10 +95,14 @@ describe("syncPendingEntries", () => {
     createInspection = vi.mocked((await import("@/lib/inspections/api")).createInspection);
     createTreatment = vi.mocked((await import("@/lib/treatments/api")).createTreatment);
     uploadDocument = vi.mocked((await import("@/lib/documents/api")).uploadDocument);
+    refreshPacksAfterSync = vi.mocked(
+      (await import("@/lib/apiaries/offline-pack")).refreshPacksAfterSync,
+    );
     // The mocks themselves outlive resetModules - start them from scratch too.
     createInspection.mockReset();
     createTreatment.mockReset();
     uploadDocument.mockReset();
+    refreshPacksAfterSync.mockReset().mockResolvedValue(undefined);
     photoHandOver.calls.length = 0;
     photoHandOver.failFor = null;
     photoHandOver.isQueued = async (key) =>
@@ -160,6 +170,81 @@ describe("syncPendingEntries", () => {
     expect(kept.lastError?.status).toBe(400);
   });
 
+  it("an inspection for a colony ended since the pack was loaded stays queued with the server message and the packs are refreshed", async () => {
+    // Review Focus 1: the pack still listed V-03 as living when the
+    // inspection was recorded offline; the server knows better.
+    await db.queueInspection(inspection(3), "key-3", "user-1");
+    const body = { statusCode: 400, message: "Volk V-03 ist beendet." };
+    createInspection.mockRejectedValue(new ApiError(400, "Volk V-03 ist beendet.", body));
+
+    const result = await sync.syncPendingEntries("user-1");
+
+    expect(result).toEqual({ synced: 0, failed: 1, skippedForeign: 0 });
+    const [kept] = await db.getPendingEntries("pending-inspections");
+    expect(kept.lastError?.message).toBe("Volk V-03 ist beendet.");
+    expect(kept.lastError?.status).toBe(400);
+    // The packs holding V-03 are reloaded at once, not only after 1 h.
+    expect(refreshPacksAfterSync).toHaveBeenCalledTimes(1);
+    expect(refreshPacksAfterSync).toHaveBeenCalledWith(
+      "user-1",
+      expect.any(Number),
+      expect.any(Function),
+      { force: true, colonyIds: ["colony-3"] },
+    );
+  });
+
+  it("refreshes the packs by age only when nothing was rejected", async () => {
+    await db.queueInspection(inspection(1), "key-1", "user-1");
+    createInspection.mockResolvedValue({ id: "x" } as never);
+
+    await sync.syncPendingEntries("user-1");
+
+    expect(refreshPacksAfterSync).toHaveBeenCalledTimes(1);
+    expect(refreshPacksAfterSync.mock.calls[0]).toHaveLength(3);
+  });
+
+  it("does not force a pack reload after a network failure", async () => {
+    await db.queueInspection(inspection(1), "key-1", "user-1");
+    createInspection.mockRejectedValue(new TypeError("Failed to fetch"));
+
+    await sync.syncPendingEntries("user-1");
+
+    expect(refreshPacksAfterSync.mock.calls[0]).toHaveLength(3);
+  });
+
+  it("forces the reload for the colonies of every rejected entry, each once", async () => {
+    await db.queueInspection(inspection(3), "key-3", "user-1");
+    await db.queueInspection(inspection(3), "key-3b", "user-1");
+    await db.queueTreatment(
+      { colonyId: "colony-5", date: "2026-10-01T00:00:00.000Z", product: "Oxuvar" },
+      "key-t",
+      "user-1",
+    );
+    createInspection.mockRejectedValue(new ApiError(400, "Volk V-03 ist beendet."));
+    createTreatment.mockRejectedValue(new ApiError(400, "Volk V-05 ist beendet."));
+
+    await sync.syncPendingEntries("user-1");
+
+    const options = refreshPacksAfterSync.mock.calls[0][3];
+    expect(options?.force).toBe(true);
+    expect([...(options?.colonyIds ?? [])].sort()).toEqual(["colony-3", "colony-5"]);
+  });
+
+  it("refreshes the packs only for the run's user and never after cancelSync()", async () => {
+    await db.queueInspection(inspection(1), "key-1", "user-1");
+    const request = openRequest();
+    createInspection.mockReturnValueOnce(request.promise);
+
+    const run = sync.syncPendingEntries("user-1");
+    await vi.waitFor(() => expect(createInspection).toHaveBeenCalledTimes(1));
+    const cancelled = sync.cancelSync();
+    request.answer({ id: "server-1" });
+    await run;
+    await cancelled;
+
+    expect(refreshPacksAfterSync).not.toHaveBeenCalled();
+  });
+
   it("continues with the rest of the queue after a server rejection", async () => {
     await db.queueInspection(inspection(1), "key-1", "user-1");
     await db.queueInspection(inspection(2), "key-2", "user-1");
@@ -212,6 +297,51 @@ describe("syncPendingEntries", () => {
     expect(createInspection).toHaveBeenCalledTimes(1);
   });
 
+  it("a caller that changed nothing shares the running run, even once it has begun", async () => {
+    await takePhoto("session-1");
+    await photos.attachSessionToInspection("session-1", "srv-1");
+    const upload = openRequest();
+    uploadDocument.mockReturnValueOnce(upload.promise);
+    const running = sync.syncPendingEntries("user-1");
+    await vi.waitFor(() => expect(uploadDocument).toHaveBeenCalledTimes(1));
+
+    // The band's triggers on a reconnect (`online` event, connectivity check).
+    const reconnect = sync.syncPendingEntries("user-1");
+    upload.answer({ id: "doc-1" });
+
+    expect(reconnect).toBe(running);
+    expect(await running).toEqual({ synced: 1, failed: 0, skippedForeign: 0 });
+    expect(uploadDocument).toHaveBeenCalledTimes(1);
+  });
+
+  it("runs exactly once more for callers that changed something after the run began, so it does not wait", async () => {
+    await takePhoto("session-1");
+    await photos.attachSessionToInspection("session-1", "srv-1");
+    const firstUpload = openRequest();
+    uploadDocument
+      .mockReturnValueOnce(firstUpload.promise)
+      .mockResolvedValue({ id: "doc-2" } as never);
+    const running = sync.syncPendingEntries("user-1");
+    await vi.waitFor(() => expect(uploadDocument).toHaveBeenCalledTimes(1));
+
+    // An online save while the running sync uploads: its photo is ready only now.
+    await takePhoto("session-2");
+    await photos.attachSessionToInspection("session-2", "srv-2");
+    const afterSave = sync.syncPendingEntries("user-1", { afterChange: true });
+    // e.g. „Erneut senden“
+    const afterRetry = sync.syncPendingEntries("user-1", { afterChange: true });
+    firstUpload.answer({ id: "doc-1" });
+
+    expect(await running).toEqual({ synced: 1, failed: 0, skippedForeign: 0 });
+    expect(afterRetry).toBe(afterSave);
+    expect(await afterSave).toEqual({ synced: 1, failed: 0, skippedForeign: 0 });
+    expect(uploadDocument.mock.calls.map(([, inspectionId]) => inspectionId)).toEqual([
+      "srv-1",
+      "srv-2",
+    ]);
+    expect(await photos.listSessionPhotos("session-2")).toEqual([]);
+  });
+
   it("never sends a user's entries after cancelSync() during a running sync", async () => {
     await db.queueInspection(inspection(1), "key-1", "user-1");
     await db.queueInspection(inspection(2), "key-2", "user-1");
@@ -370,6 +500,34 @@ describe("syncPendingEntries", () => {
     expect(await photos.listSessionPhotos("session-1")).toEqual([]);
   });
 
+  it("finishes the user's open photo hand-overs before uploading, never another user's", async () => {
+    const own = await takePhoto("session-1");
+    await photos.addDraftPhoto({
+      sessionId: "session-2",
+      ownerUserId: "user-2",
+      blob: new Blob(["jpeg"], { type: "image/jpeg" }),
+      date: "2026-10-01",
+    });
+    // Saved online, but the photos could not be tied to the inspection then.
+    rememberHandOver({ userId: "user-1", sessionId: "session-1", inspectionId: "srv-1" });
+    rememberHandOver({ userId: "user-2", sessionId: "session-2", inspectionId: "srv-2" });
+    uploadDocument.mockResolvedValue({ id: "doc-1" } as never);
+
+    const result = await sync.syncPendingEntries("user-1");
+
+    expect(result).toEqual({ synced: 1, failed: 0, skippedForeign: 0 });
+    expect(uploadDocument).toHaveBeenCalledTimes(1);
+    expect(uploadDocument).toHaveBeenCalledWith("INSPECTION", "srv-1", expect.anything(), {
+      idempotencyKey: own.uploadIdempotencyKey,
+      fileName: own.fileName,
+    });
+    expect(readHandOvers()).toEqual([
+      { userId: "user-2", sessionId: "session-2", inspectionId: "srv-2" },
+    ]);
+    const [foreign] = await photos.listSessionPhotos("session-2");
+    expect(foreign.state).toBe("draft");
+  });
+
   it("keeps an inspection whose photo hand-over failed and still finishes the run", async () => {
     await db.queueInspection(inspection(1), "key-1", "user-1");
     await db.queueInspection(inspection(2), "key-2", "user-1");