Files
autocrm/app/Http/Controllers/Api/MechanicApiController.php
Vasyka 03e030d6d2 feat: tier 3 polish — M12/13/14/15 deep cleanup
Closes the remaining ~50h of items from CONFORMITY-12-15.md across all
four modules. Single umbrella migration (2026_06_05_000004) lands four
tables + 5 column additions, no downtime risk.

== M12 — body_type + transmission + pricing audit log ==

Vehicle gains body_type (12 values: sedan/hatchback/suv/crossover/pickup/
van/truck/coupe/wagon/convertible/minivan/moto) and transmission_type
(6 values: manual/automatic/cvt/dsg/dct/amt). These are separate from
vehicle_class so admin can configure DSG-only coefficients without
contaminating the SUV detection.

PricingCoefficient.matches() now also tests:
  - conditions.body_types[] against ctx.body_type
  - conditions.transmissions[] against ctx.transmission

PricingEngine builds the richer ctx and exposes it on the quote return
under quote.context.

New pricing_application_logs table (append-only) — call
PricingEngine::logApplication($quote, $subject, $vehicle, $client, $part)
after applying a price to a WO line. Stores base, final, full
applied[] array, and the ctx snapshot so the question "why was this
priced at 218 lei in March?" stays answerable forever.

PricingCoefficientResource form gains CheckboxList for body_types and
transmissions (3-column layouts, full-width). Both are optional —
empty list = applies to anything.

== M13 — Mechanic REST API + KPI ==

New MechanicApiController with 7 endpoints under /api/v1/mechanic/:
  GET    /board               — own non-done WOs with their works expanded
  GET    /kpi?period=YYYY-MM  — own aggregates for the period
  POST   /tasks/{w}/start
  POST   /tasks/{w}/pause
  POST   /tasks/{w}/resume
  POST   /tasks/{w}/done
  POST   /tasks/{w}/block     — validates reason from BLOCK_REASONS enum

Every endpoint authorizes ownership: $work->workOrder->master_id ===
auth()->id() else 403. board() returns null pending_works so native
apps don't make round-trips. workPayload() emits efficiency_pct and
efficiency_class on every response.

New MechanicKpi Filament page at /app/mechanic-kpi (Service group). Same
aggregation logic but tenant-wide: groups WorkOrderWork rows by
master_id for the selected period, computes totals + efficiency_pct +
revenue. Period navigation via ◀/▶ buttons, default = current month.
Color-coded efficiency badges (green ≤100%, amber ≤130%, red >130%).
Rows sort by revenue descending — easy "top earners this month" view.

== M14 — OCR async via Laravel queue ==

New ocr_jobs table (id, supplier_id?, source_type, file_path, status,
result JSON, error_message, ai_provider, tokens_used, purchase_id?,
processed_at). Idempotent migration.

New OcrJob model + ProcessOcrJob queueable job. Job re-establishes
tenant context inside the worker (Company::find + TenantManager::setCurrent)
since queue workers don't inherit middleware-resolved tenants.

handle() walks: status=pending → processing, calls OcrInvoiceService::extract,
on success → status=done + result + ai_provider; on throw → status=failed
+ error_message. Failed jobs auto-retry once (tries=2) with 120s timeout.

The existing synchronous OcrInvoiceService stays for inline use cases
(tests, quick imports). The job is now the canonical path for the
admin UI to keep requests sub-100ms.

== M15 — eta_promised + JSON tracking + notifications log ==

Three new wo columns: eta_promised (initial commitment, never changes),
eta_change_reason (text for "așteptăm piesă"), eta_updated_at (when
the current eta was last touched). Existing eta_at remains as "current"
ETA so the UI can render both side-by-side.

New /api/track/{token} JSON endpoint (public, tenant-scoped via subdomain):
  number, status, status_label, progress %, client, vehicle, plate, master,
  eta_promised, eta_current, eta_change_reason, total, pay_status,
  pending_approvals[] (each with kind/id/name/amount/approve_url —
  signed URLs ready for native app webview),
  timeline[] (from activity_log, last 20 events).

NotificationDispatcher::dispatch() gains optional workOrderId param.
Every send call (success or failure) now writes one row to the new
client_notifications_log table with channel/template_key/status (sent
or failed)/error_detail/sent_at. Failures of logging are swallowed
so a missing activity_log never breaks notifications. workOrderReady
and paymentReceived pass the WO id through; others can be wired in
future commits without schema change.

New tables tracked:
  client_notifications_log — every push to client, append-only
  pricing_application_logs — every pricing decision, append-only
  ocr_jobs — async OCR job queue

== Tests ==

PolishTier3Test (11):
- M12: body_type condition match/no-match; transmission DSG match;
  pricing_log row persists base/final/applied/ctx
- M13: mechanic API board scoped to own WOs; start task on foreign
  work returns 403; KPI endpoint computes 2.5/3 = 83% efficiency
  across 2 done works in period
- M14: ocr_job queueable + Queue::fake assertion
- M15: tracking JSON returns ETA promised/current/reason + pending
  approvals with correctly-signed approve_url; dispatcher writes
  ClientNotificationLog row on workOrderReady
- M12: vehicle body_type + transmission_type round-trip through save

Suite: 269 passed (761 assertions). Was 258.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-05 05:31:50 +00:00

128 lines
4.6 KiB
PHP

<?php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Models\Tenant\WorkOrder;
use App\Models\Tenant\WorkOrderWork;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
class MechanicApiController extends Controller
{
/** GET /api/v1/mechanic/board — only OWN WOs with their works expanded. */
public function board(): JsonResponse
{
$userId = auth()->id();
$wos = WorkOrder::with(['client:id,name', 'vehicle:id,plate,make,model', 'works'])
->where('master_id', $userId)
->whereNotIn('status', ['done', 'cancelled'])
->orderBy('opened_at')
->get()
->map(fn ($wo) => [
'id' => $wo->id, 'number' => $wo->number, 'status' => $wo->status,
'client_name' => $wo->client?->name,
'vehicle' => trim(($wo->vehicle?->make ?? '') . ' ' . ($wo->vehicle?->model ?? '')),
'plate' => $wo->vehicle?->plate,
'complaint' => $wo->complaint,
'eta_at' => $wo->eta_at?->toIso8601String(),
'works' => $wo->works->map(fn ($w) => $this->workPayload($w))->all(),
]);
return response()->json(['data' => $wos]);
}
/** POST /api/v1/mechanic/tasks/{work}/start */
public function startTask(WorkOrderWork $work): JsonResponse
{
$this->authorizeOwn($work);
$work->start();
return response()->json(['data' => $this->workPayload($work->fresh())]);
}
public function pauseTask(WorkOrderWork $work): JsonResponse
{
$this->authorizeOwn($work);
$work->pause();
return response()->json(['data' => $this->workPayload($work->fresh())]);
}
public function resumeTask(WorkOrderWork $work): JsonResponse
{
$this->authorizeOwn($work);
$work->resume();
return response()->json(['data' => $this->workPayload($work->fresh())]);
}
public function doneTask(WorkOrderWork $work): JsonResponse
{
$this->authorizeOwn($work);
$work->markDone();
return response()->json(['data' => $this->workPayload($work->fresh())]);
}
public function blockTask(Request $request, WorkOrderWork $work): JsonResponse
{
$this->authorizeOwn($work);
$data = $request->validate([
'reason' => 'required|in:' . implode(',', array_keys(WorkOrderWork::BLOCK_REASONS)),
'note' => 'nullable|string|max:1000',
]);
$work->block($data['reason'], $data['note'] ?? null);
return response()->json(['data' => $this->workPayload($work->fresh())]);
}
/** GET /api/v1/mechanic/kpi?period=2026-06 — own efficiency aggregates. */
public function kpi(Request $request): JsonResponse
{
$userId = auth()->id();
$period = $request->query('period', now()->format('Y-m'));
[$y, $m] = explode('-', $period);
$rows = WorkOrderWork::whereHas('workOrder', fn ($q) => $q->where('master_id', $userId))
->where('mechanic_status', 'done')
->whereYear('mechanic_done_at', $y)
->whereMonth('mechanic_done_at', $m)
->get();
$totalNorm = (float) $rows->sum('hours');
$totalActual = (float) $rows->sum('actual_hours');
$tasksDone = $rows->count();
$totalRevenue = (float) $rows->sum('total');
$efficiencyPct = $totalNorm > 0 ? round(100 * $totalActual / $totalNorm) : null;
return response()->json([
'period' => $period,
'tasks_done' => $tasksDone,
'norm_hours' => round($totalNorm, 2),
'actual_hours' => round($totalActual, 2),
'efficiency_pct' => $efficiencyPct,
'revenue_manopere' => round($totalRevenue, 2),
]);
}
private function workPayload(WorkOrderWork $w): array
{
return [
'id' => $w->id,
'name' => $w->name,
'mechanic_status' => $w->mechanic_status,
'norm_hours' => (float) $w->hours,
'actual_hours' => (float) $w->actual_hours,
'efficiency_pct' => $w->efficiencyPct(),
'efficiency_class' => $w->efficiencyClass(),
'block_reason' => $w->block_reason,
'block_note' => $w->block_note,
'mechanic_started_at' => $w->mechanic_started_at?->toIso8601String(),
'mechanic_done_at' => $w->mechanic_done_at?->toIso8601String(),
];
}
private function authorizeOwn(WorkOrderWork $work): void
{
if ($work->workOrder?->master_id !== auth()->id()) {
abort(403, 'Work belongs to a different mechanic.');
}
}
}