Offline-fähige App für Außendienst: Daten erfassen ohne Netz

// outbox.ts: Warteschlange für Änderungen, die auf dem Gerät entstehen.
// Konfliktregel (Server): Kennt das Gerät die aktuelle Version, gilt die
// Änderung. Sonst wird je Feld verglichen: Steht auf dem Server noch der
// Ausgangswert des Geräts (oder schon der neue Wert), wird übernommen.
// Hat jemand das Feld anders geändert, bleibt der Serverwert, und das
// Gerät legt den Fall in die Konfliktliste, damit ein Mensch entscheidet.

export type Value = string | null;
export type Fields = Record<string, Value>;
export type LocalRecord = { id: string; version: number; fields: Fields };
export type Change = {
  changeId: string;    // UUID vom Gerät: macht wiederholtes Senden harmlos
  recordId: string;
  baseVersion: number; // Serverversion, die das Gerät beim Bearbeiten kannte
  fields: Record<string, { from: Value; to: Value }>;
};
export type Conflict = { recordId: string; field: string; mine: Value; server: Value };
export type SyncResult = {
  status: 'applied' | 'conflict';
  version: number;
  record: Fields;      // Serverstand nach dieser Änderung
  conflicts: Record<string, { mine: Value; server: Value }>;
};

// Ablage auf dem Gerät, z. B. SQLite: jede Methode läuft als eine Transaktion.
export interface Store {
  getRecord(id: string): Promise<LocalRecord>;
  saveEdit(record: LocalRecord, change: Change): Promise<void>;
  outbox(): Promise<Change[]>; // älteste Änderung zuerst
  settle(changeId: string, record: LocalRecord, conflicts: Conflict[]): Promise<void>;
}

export async function edit(store: Store, id: string, patch: Fields): Promise<void> {
  const rec = await store.getRecord(id);
  const fields: Change['fields'] = {};
  for (const [name, to] of Object.entries(patch)) {
    const from = rec.fields[name] ?? null;
    if (from !== to) fields[name] = { from, to };
  }
  if (Object.keys(fields).length === 0) return;
  const change: Change = {
    changeId: crypto.randomUUID(), recordId: id, baseVersion: rec.version, fields,
  };
  // Datensatz und Outbox-Eintrag gemeinsam speichern, nie getrennt
  await store.saveEdit({ ...rec, fields: { ...rec.fields, ...patch } }, change);
}

export async function flush(
  store: Store, send: (c: Change) => Promise<SyncResult>,
): Promise<number> {
  let done = 0;
  for (const change of await store.outbox()) {
    let result: SyncResult;
    try {
      result = await send(change);
    } catch {
      break; // kein Netz oder Serverfehler: Reihenfolge bleibt, später erneut
    }
    // Serverstand übernehmen, noch nicht gesendete eigene Änderungen obenauf
    const fields: Fields = { ...result.record };
    for (const p of await store.outbox()) {
      if (p.recordId !== change.recordId || p.changeId === change.changeId) continue;
      for (const [name, f] of Object.entries(p.fields)) fields[name] = f.to;
    }
    const conflicts = Object.entries(result.conflicts)
      .map(([field, v]) => ({ recordId: change.recordId, field, ...v }));
    await store.settle(change.changeId,
      { id: change.recordId, version: result.version, fields }, conflicts);
    done++;
  }
  return done;
}

// Versand an Laravel. apiBase ist die volle Adresse des Servers, etwa
// 'https://api.example.de': Eine relative Adresse wie '/api/...' zeigt in
// einer Capacitor-App auf den lokalen WebView-Server, nicht auf Laravel.
// getToken liefert das Sanctum-Token des angemeldeten Geräts.
// Der Timeout bricht hängende Anfragen im schwachen Netz ab; flush()
// behandelt das wie ein Funkloch und versucht es später erneut.
export function httpSender(
  apiBase: string, getToken: () => Promise<string>, timeoutMs = 15000,
): (c: Change) => Promise<SyncResult> {
  return async (c) => {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeoutMs);
    try {
      const res = await fetch(`${apiBase}/api/sync/changes`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json', Accept: 'application/json',
          Authorization: `Bearer ${await getToken()}`,
        },
        body: JSON.stringify({
          change_id: c.changeId, record_id: c.recordId,
          base_version: c.baseVersion, fields: c.fields,
        }),
        signal: controller.signal,
      });
      if (res.status === 200 || res.status === 409) return await res.json();
      throw new Error(`Sync abgebrochen: HTTP ${res.status}`); // z. B. 401: neu anmelden
    } finally {
      clearTimeout(timer);
    }
  };
}

// Verwendung: await flush(store, httpSender('https://api.example.de', loadToken));

<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;

// routes/api.php: Route::post('/sync/changes', SyncChangeController::class)->middleware('auth:sanctum');
class SyncChangeController
{
    private const FIELDS = ['location_note', 'access_hint', 'status'];

    public function __invoke(Request $request): JsonResponse
    {
        $data = $request->validate([
            'change_id' => ['required', 'uuid'],
            'record_id' => ['required', 'uuid'],
            'base_version' => ['required', 'integer', 'min:0'],
            'fields' => ['required', 'array:'.implode(',', self::FIELDS)],
            'fields.*.from' => ['present', 'nullable', 'string'],
            'fields.*.to' => ['present', 'nullable', 'string'],
        ]);

        $result = DB::transaction(function () use ($data) {
            // Zeile sperren, bis die Transaktion endet: keine zwei Abgleiche gleichzeitig
            $row = (array) DB::table('meter_points')
                ->where('id', $data['record_id'])
                ->lockForUpdate()
                ->firstOrFail();

            // Schon verarbeitet (Antwort ging verloren)? Dann dieselbe Antwort noch einmal
            $previous = DB::table('sync_changes')->where('change_id', $data['change_id'])->value('result');
            if ($previous !== null) {
                return json_decode($previous, true);
            }

            $merge = self::merge($row, (int) $data['base_version'], $data['fields']);
            if ($merge['changed'] !== []) {
                DB::table('meter_points')->where('id', $row['id'])
                    ->update($merge['changed'] + ['version' => $merge['version']]);
            }

            $result = [
                'status' => $merge['status'],
                'version' => $merge['version'],
                'record' => array_intersect_key($merge['changed'] + $row, array_flip(self::FIELDS)),
                'conflicts' => (object) $merge['conflicts'],
            ];
            DB::table('sync_changes')->insert([
                'change_id' => $data['change_id'],
                'result' => json_encode($result),
                'created_at' => now(),
            ]);

            return $result;
        });

        return response()->json($result, $result['status'] === 'conflict' ? 409 : 200);
    }

    // Konfliktregel wie im Beitrag beschrieben; Felder sind Textspalten
    public static function merge(array $row, int $baseVersion, array $fields): array
    {
        $updates = [];
        $conflicts = [];
        foreach ($fields as $name => $change) {
            $server = $row[$name];
            if ($baseVersion === (int) $row['version'] || $server === $change['from']) {
                $updates[$name] = $change['to'];
            } elseif ($server !== $change['to']) {
                $conflicts[$name] = ['mine' => $change['to'], 'server' => $server];
            }
        }
        $changed = array_filter($updates, fn ($value, $name) => $row[$name] !== $value, ARRAY_FILTER_USE_BOTH);

        return [
            'status' => $conflicts === [] ? 'applied' : 'conflict',
            'version' => $changed === [] ? (int) $row['version'] : (int) $row['version'] + 1,
            'changed' => $changed,
            'conflicts' => $conflicts,
        ];
    }
}