javier/construprogress
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(api): mobile API Milestone 4 — full PUSH (inspections/issues/features + conflicts)

Browse Source 
SyncController now handles the full mutation vocabulary:
- inspection.create (idempotent by uuid; project/layer derived from feature;
  authz member + 'create inspections'; status defaults to completed).
- issue.create (idempotent; authz member + 'create issues').
- issue.update (by server id; authz member + 'edit issues'; sets resolved_at
  when resolved/closed; last-write-wins conflict).
- feature.update (by server id; authz member + 'update progress'; recomputes
  phase progress; last-write-wins conflict).
- Conflict detection: client_updated_at vs server updated_at → returns
  'conflict' with the current server value.
Added uuid + client_updated_at to features/inspections/issues (guarded migration)
and their fillables. Tests: 16 passing (added inspection/issue/feature + conflict).

Note: 2 PRE-EXISTING test failures remain (not from this work, sqlite-only):
ExampleTest expects '/'=200 (app redirects), and the dashboard route uses MySQL
FIELD() which sqlite lacks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Javier Braña
2026-06-18 10:09:34 +02:00
parent b5deb1c53a
commit 9d2b63c8f4
6 changed files with 371 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/Http/Controllers/Api/V1/SyncController.php
+234 -30
View File
@@ -3,29 +3,36 @@
namespace App\Http\Controllers\Api\V1;
use App\Http\Controllers\Controller;
use App\Models\Feature;
use App\Models\Inspection;
use App\Models\Issue;
use App\Models\Phase;
use App\Models\ProgressUpdate;
use App\Models\Project;
use App\Models\User;
use Carbon\Carbon;
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).
* Push a batch of offline mutations. Returns a per-operation result
* (applied | duplicate | conflict | error). Never aborts the whole batch.
*
* Milestone 2: supports only progress_update.create (vertical slice).
* Identity:
* - create ops → the new record stores the client-generated `uuid` (idempotent).
* - update ops → target identified by `data.id` (server id); last-write-wins.
*/
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'],
'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();
@@ -43,59 +50,256 @@ class SyncController extends Controller
$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']);
return match ($op['entity'] . '.' . $op['op']) {
'progress_update.create' => $this->progressUpdateCreate($user, $uuid, $op),
'inspection.create' => $this->inspectionCreate($user, $uuid, $op),
'issue.create' => $this->issueCreate($user, $uuid, $op),
'issue.update' => $this->issueUpdate($user, $uuid, $op),
'feature.update' => $this->featureUpdate($user, $uuid, $op),
default => $this->error($uuid, 'unsupported entity/op: ' . $op['entity'] . '.' . $op['op']),
};
} catch (\Throwable $e) {
return $this->error($uuid, $e->getMessage());
}
}
// ── progress_update.create ───────────────────────────────────────────────────
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];
if ($existing = ProgressUpdate::where('uuid', $uuid)->first()) {
return $this->duplicate($uuid, $existing->id);
}
$validator = Validator::make($op['data'], [
$v = 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());
if ($v->fails()) {
return $this->error($uuid, 'validation: ' . $v->errors()->first());
}
$d = $validator->validated();
$d = $v->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')) {
if (! $this->canAccess($user, $phase->project) || ! $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
'user_id' => $user->id,
'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];
return $this->applied($uuid, $pu->id);
}
// ── inspection.create ──────────────────────────────────────────────────────────
private function inspectionCreate(User $user, string $uuid, array $op): array
{
if ($existing = Inspection::where('uuid', $uuid)->first()) {
return $this->duplicate($uuid, $existing->id);
}
$v = Validator::make($op['data'], [
'feature_id' => ['required', 'integer', 'exists:features,id'],
'template_id' => ['nullable', 'integer', 'exists:inspection_templates,id'],
'data' => ['nullable', 'array'],
'status' => ['nullable', 'string'],
'result' => ['nullable', 'string'],
'notes' => ['nullable', 'string'],
]);
if ($v->fails()) {
return $this->error($uuid, 'validation: ' . $v->errors()->first());
}
$d = $v->validated();
$feature = Feature::with('layer.phase.project')->findOrFail($d['feature_id']);
$project = $feature->layer?->phase?->project;
if (! $this->canAccess($user, $project) || ! $user->can('create inspections')) {
return $this->error($uuid, 'forbidden');
}
$inspection = Inspection::create([
'uuid' => $uuid,
'project_id' => $project->id,
'layer_id' => $feature->layer_id,
'feature_id' => $feature->id,
'template_id' => $d['template_id'] ?? null,
'user_id' => $user->id,
'data' => $d['data'] ?? [],
'status' => $d['status'] ?? 'completed',
'result' => $d['result'] ?? null,
'notes' => $d['notes'] ?? null,
'client_updated_at' => $op['client_updated_at'] ?? null,
]);
return $this->applied($uuid, $inspection->id);
}
// ── issue.create / issue.update ──────────────────────────────────────────────────
private function issueCreate(User $user, string $uuid, array $op): array
{
if ($existing = Issue::where('uuid', $uuid)->first()) {
return $this->duplicate($uuid, $existing->id);
}
$v = Validator::make($op['data'], [
'project_id' => ['required', 'integer', 'exists:projects,id'],
'feature_id' => ['nullable', 'integer', 'exists:features,id'],
'title' => ['required', 'string', 'max:255'],
'description' => ['nullable', 'string'],
'priority' => ['nullable', 'in:' . implode(',', Issue::PRIORITIES)],
'status' => ['nullable', 'in:' . implode(',', Issue::STATUSES)],
]);
if ($v->fails()) {
return $this->error($uuid, 'validation: ' . $v->errors()->first());
}
$d = $v->validated();
$project = Project::find($d['project_id']);
if (! $this->canAccess($user, $project) || ! $user->can('create issues')) {
return $this->error($uuid, 'forbidden');
}
$issue = Issue::create([
'uuid' => $uuid,
'project_id' => $project->id,
'feature_id' => $d['feature_id'] ?? null,
'title' => $d['title'],
'description' => $d['description'] ?? null,
'priority' => $d['priority'] ?? 'medium',
'status' => $d['status'] ?? 'open',
'reported_by' => $user->id,
'client_updated_at' => $op['client_updated_at'] ?? null,
]);
return $this->applied($uuid, $issue->id);
}
private function issueUpdate(User $user, string $uuid, array $op): array
{
$v = Validator::make($op['data'], [
'id' => ['required', 'integer', 'exists:issues,id'],
'title' => ['nullable', 'string', 'max:255'],
'description' => ['nullable', 'string'],
'priority' => ['nullable', 'in:' . implode(',', Issue::PRIORITIES)],
'status' => ['nullable', 'in:' . implode(',', Issue::STATUSES)],
'assigned_to' => ['nullable', 'integer', 'exists:users,id'],
'resolution_notes' => ['nullable', 'string'],
]);
if ($v->fails()) {
return $this->error($uuid, 'validation: ' . $v->errors()->first());
}
$d = $v->validated();
$issue = Issue::with('project')->findOrFail($d['id']);
if (! $this->canAccess($user, $issue->project) || ! $user->can('edit issues')) {
return $this->error($uuid, 'forbidden');
}
if ($conflict = $this->conflict($uuid, $issue, $op)) {
return $conflict;
}
$issue->fill(collect($d)->except('id')->toArray());
if (in_array($issue->status, ['resolved', 'closed'], true) && ! $issue->resolved_at) {
$issue->resolved_at = now();
}
$issue->client_updated_at = $op['client_updated_at'] ?? null;
$issue->save();
return $this->applied($uuid, $issue->id);
}
// ── feature.update ────────────────────────────────────────────────────────────
private function featureUpdate(User $user, string $uuid, array $op): array
{
$v = Validator::make($op['data'], [
'id' => ['required', 'integer', 'exists:features,id'],
'status' => ['nullable', 'string'],
'progress' => ['nullable', 'integer', 'min:0', 'max:100'],
'responsible' => ['nullable', 'string'],
]);
if ($v->fails()) {
return $this->error($uuid, 'validation: ' . $v->errors()->first());
}
$d = $v->validated();
$feature = Feature::with('layer.phase.project')->findOrFail($d['id']);
$project = $feature->layer?->phase?->project;
if (! $this->canAccess($user, $project) || ! $user->can('update progress')) {
return $this->error($uuid, 'forbidden');
}
if ($conflict = $this->conflict($uuid, $feature, $op)) {
return $conflict;
}
$feature->fill(collect($d)->except('id')->toArray());
$feature->client_updated_at = $op['client_updated_at'] ?? null;
$feature->save();
// Mirror web behaviour: recompute the phase progress from its features.
if ($phase = $feature->layer?->phase) {
$phase->progress_percent = (int) round($phase->features()->avg('progress') ?: 0);
$phase->save();
}
return $this->applied($uuid, $feature->id);
}
// ── Helpers ──────────────────────────────────────────────────────────────────────
private function canAccess(User $user, ?Project $project): bool
{
if (! $project) {
return false;
}
return $user->can('manage all')
|| $project->users()->where('user_id', $user->id)->exists();
}
/**
* Last-write-wins conflict detection: if the server row was updated after the
* client's edit, reject with the current server value.
*/
private function conflict(string $uuid, $model, array $op): ?array
{
if (empty($op['client_updated_at'])) {
return null;
}
$clientAt = Carbon::parse($op['client_updated_at']);
if ($model->updated_at && $model->updated_at->gt($clientAt)) {
return [
'uuid' => $uuid,
'status' => 'conflict',
'server' => $model->fresh()->toArray(),
];
}
return null;
}
private function applied(string $uuid, int $id): array
{
return ['uuid' => $uuid, 'status' => 'applied', 'server_id' => $id];
}
private function duplicate(string $uuid, int $id): array
{
return ['uuid' => $uuid, 'status' => 'duplicate', 'server_id' => $id];
}
private function error(string $uuid, string $message): array