feat(api): mobile API Milestone 1+2 — Sanctum auth + offline sync vertical slice

Milestone 1 (auth foundation): - Installed laravel/sanctum; HasApiTokens on User; published config + migration. - routes/api.php with /api/v1; Sanctum 'ability' middleware alias registered. - AuthController: POST login (long-lived revocable device token w/ ability mobile-sync + devices table), GET me, POST logout. New Device model/table. Milestone 2 (vertical slice, offline-first): - progress_updates: +uuid (client-generated) +client_updated_at. - ProjectApiController: GET projects (accessibleBy), GET projects/{id}/bundle (project/phases/layers/features, membership-authorized). - SyncController: POST sync — batch ops, idempotent by uuid, per-op result (applied/duplicate/error), server-set user_id, authz by permission+membership. Currently handles progress_update.create. Tests: tests/Feature/Api/MobileApiTest (9 passing) — auth, accessible projects, bundle authz, sync apply+idempotency, permission enforcement. Also fixed a latent schema bug: projects.reference (and external_reference_1) existed in the live DB but had no migration — added a guarded migration so fresh installs match production. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-18 09:05:20 +02:00
parent ba363e7e18
commit 17a824f925
16 changed files with 794 additions and 8 deletions
@@ -0,0 +1,105 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Models\Phase;
+use App\Models\ProgressUpdate;
+use App\Models\User;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Validator;
+
+class SyncController extends Controller
+{
+    /**
+     * Push a batch of offline mutations. Idempotent by client-generated `uuid`.
+     * Returns a per-operation result (applied | duplicate | conflict | error).
+     *
+     * Milestone 2: supports only progress_update.create (vertical slice).
+     */
+    public function sync(Request $request)
+    {
+        $data = $request->validate([
+            'operations'                     => ['required', 'array'],
+            'operations.*.entity'            => ['required', 'string'],
+            'operations.*.op'                => ['required', 'string'],
+            'operations.*.uuid'              => ['required', 'uuid'],
+            'operations.*.data'              => ['required', 'array'],
+            'operations.*.client_updated_at' => ['nullable', 'date'],
+        ]);
+
+        $user = $request->user();
+        $results = [];
+
+        foreach ($data['operations'] as $op) {
+            $results[] = $this->handle($user, $op);
+        }
+
+        return response()->json(['results' => $results]);
+    }
+
+    private function handle(User $user, array $op): array
+    {
+        $uuid = $op['uuid'];
+
+        try {
+            if ($op['entity'] === 'progress_update' && $op['op'] === 'create') {
+                return $this->progressUpdateCreate($user, $uuid, $op);
+            }
+
+            return $this->error($uuid, 'unsupported entity/op: ' . $op['entity'] . '.' . $op['op']);
+        } catch (\Throwable $e) {
+            return $this->error($uuid, $e->getMessage());
+        }
+    }
+
+    private function progressUpdateCreate(User $user, string $uuid, array $op): array
+    {
+        // Idempotency: same uuid already applied → duplicate (no-op).
+        $existing = ProgressUpdate::where('uuid', $uuid)->first();
+        if ($existing) {
+            return ['uuid' => $uuid, 'status' => 'duplicate', 'server_id' => $existing->id];
+        }
+
+        $validator = Validator::make($op['data'], [
+            'phase_id' => ['required', 'integer', 'exists:phases,id'],
+            'progress' => ['required', 'integer', 'min:0', 'max:100'],
+            'comment'  => ['nullable', 'string'],
+            'location' => ['nullable', 'array'],
+        ]);
+        if ($validator->fails()) {
+            return $this->error($uuid, 'validation: ' . $validator->errors()->first());
+        }
+        $d = $validator->validated();
+
+        $phase = Phase::with('project')->findOrFail($d['phase_id']);
+
+        // Authorization: project membership + permission (per-op, never abort the batch).
+        $isMember = $user->can('manage all')
+            || ($phase->project && $phase->project->users()->where('user_id', $user->id)->exists());
+        if (! $isMember || ! $user->can('update progress')) {
+            return $this->error($uuid, 'forbidden');
+        }
+
+        $pu = ProgressUpdate::create([
+            'uuid'              => $uuid,
+            'phase_id'          => $phase->id,
+            'user_id'           => $user->id,          // server-set, never trust client
+            'progress_percent'  => $d['progress'],
+            'comment'           => $d['comment'] ?? null,
+            'location'          => $d['location'] ?? null,
+            'client_updated_at' => $op['client_updated_at'] ?? null,
+        ]);
+
+        // Mirror the web behaviour: reflect latest progress on the phase.
+        $phase->progress_percent = $d['progress'];
+        $phase->save();
+
+        return ['uuid' => $uuid, 'status' => 'applied', 'server_id' => $pu->id];
+    }
+
+    private function error(string $uuid, string $message): array
+    {
+        return ['uuid' => $uuid, 'status' => 'error', 'error' => $message];
+    }
+}