@startuml uml-sequence-cliente-solicita-orden
!include _style.iuml

title 1. Cliente solicita orden de servicio

' Fuente: apps/web/src/app/api/v1/mobile/orders/route.ts:53-86
' Fuente: apps/web/src/lib/api/handler.ts:35-110
' Fuente: 00.sql:792-874 (asignar_prestador_auto + trigger after insert)

autoactivate on

actor "Cliente" as Cli

box "Mobile Client (Expo)" #F0F0F0
  participant "App\nmobile-client" as App
end box

box "API REST Next.js" #F5F5F5
  boundary "POST /api/v1/mobile/orders" as Route
  control "withApiHandler\n+ defineEndpoint" as Handler
  control "requireSession\nZod validate" as Guard
end box

box "Persistencia Postgres (Neon)" #EAEAEA
  database "ordenes_servicio" as DBOrd
  entity "trigger\nasignar_prestador_auto" as Trg
  database "historial_estatus_orden" as DBHist
end box

participant "Push notifier\n(prestador)" as Push

== Captura y validación ==

Cli -> App ++ : Selecciona servicio + dirección + nota
App ->> Route ++ : POST /orders {servicio_id, notas, fecha_programada}
Route -> Handler ++ : delegar
Handler -> Guard ++ : requireSession(req)\nZod parse body
note right of Guard
  handler.ts:53-67
  401 si no hay JWT
  422 si Zod falla
end note
Guard --> Handler -- : SessionPayload + body
Handler -> DBOrd ++ : SELECT precio_base FROM servicios
DBOrd --> Handler -- : precio_base
Handler -> DBOrd ++ : SELECT direccion predeterminada
DBOrd --> Handler -- : direccion.id

== Persistencia transaccional ==

Handler -> DBOrd ++ : BEGIN\nINSERT ordenes_servicio\n(estatus = solicitada)
note right of DBOrd
  route.ts:76-82
  monto_total = precio_base
end note
DBOrd ->> Trg ++ : AFTER INSERT row trigger
Trg -> Trg : evaluar candidatos\n(carga_activa, no overlap)

alt candidato encontrado
  Trg -> DBOrd : UPDATE ordenes\nestatus = 'asignada'\nprestador_id = X
  Trg -> DBHist ++ : INSERT historial\n(solicitada -> asignada)
  DBHist --> Trg --
  Trg --> DBOrd -- : prestador asignado
  DBOrd --> Handler -- : COMMIT
  Handler ->> Push : notificar prestador asignado
else sin match disponible
  Trg --> DBOrd : RETURN NULL\norden queda solicitada
  DBOrd --> Handler -- : COMMIT
  note over Handler #FEF3C7
    Operaciones revisará desde panel
    para asignación manual.
  end note
end

== Respuesta ==

Handler --> Route -- : NextResponse 201 {data:{id}}
Route --> App -- : 201 Created
App --> Cli -- : "Orden creada" + tracking

footer Fuente: apps/web/src/app/api/v1/mobile/orders/route.ts | 00.sql L792-L874 | apps/web/src/lib/api/handler.ts
@enduml