# US-MMD002-001: Crear Orden de Servicio

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-MMD002-001 |
| **Epica** | EPIC-MMD-002 - Ordenes de Servicio |
| **Modulo** | ordenes-servicio |
| **Prioridad** | P0 |
| **Story Points** | 5 |
| **Sprint** | Sprint 4 |
| **Estado** | Backlog |

---

## Historia de Usuario

**Como** recepcionista,
**quiero** crear una orden de servicio con datos del vehiculo y cliente,
**para** iniciar el proceso de atencion y darle seguimiento.

## Descripcion Detallada

Cuando un cliente llega al taller, la recepcionista debe poder crear rapidamente una orden de servicio. Si el vehiculo ya existe, se selecciona. Si es nuevo, se registra. La orden se crea en estado "RECIBIDO".

---

## Criterios de Aceptacion

**Escenario 1: Crear orden con vehiculo existente**
```gherkin
DADO que un cliente llega con un vehiculo ya registrado
CUANDO busco por placas "ABC-123"
ENTONCES el sistema encuentra el vehiculo
Y muestra sus datos y el cliente asociado
Y puedo crear la orden con un clic
```

**Escenario 2: Crear orden con vehiculo nuevo**
```gherkin
DADO que llega un vehiculo no registrado
CUANDO no encuentro las placas en el sistema
ENTONCES puedo registrar el vehiculo nuevo inline
Y asociarlo a un cliente existente o nuevo
Y crear la orden de servicio
```

**Escenario 3: Generar folio automatico**
```gherkin
DADO que creo una nueva orden
CUANDO confirmo la creacion
ENTONCES el sistema genera folio automatico: "OS-2025-0001"
Y el folio es unico y consecutivo
```

**Escenario 4: Registrar kilometraje de entrada**
```gherkin
DADO que recibo un vehiculo
CUANDO creo la orden
ENTONCES registro el kilometraje actual: 125,000 km
Y el sistema lo guarda en el historial del vehiculo
```

**Escenario 5: Imprimir comprobante de recepcion**
```gherkin
DADO que creo la orden exitosamente
CUANDO hago clic en "Imprimir comprobante"
ENTONCES se genera PDF con:
  | Folio orden | Fecha/hora | Vehiculo | Cliente | Km entrada |
Y el cliente puede firmarlo
```

---

## Datos de la Orden

| Campo | Tipo | Requerido | Descripcion |
|-------|------|-----------|-------------|
| folio | string | Auto | OS-YYYY-NNNN |
| vehicle_id | FK | Si | Vehiculo |
| client_id | FK | Si | Cliente |
| received_at | datetime | Si | Fecha/hora recepcion |
| km_entry | number | Si | Kilometraje de entrada |
| reported_issues | text | No | Sintomas reportados |
| received_by | FK | Auto | Usuario que recibe |
| status | enum | Auto | RECIBIDO |
| bay_id | FK | No | Bahia asignada |
| mechanic_id | FK | No | Mecanico asignado |

---

## Tareas Tecnicas

**Database:**
- [ ] DB-020: Crear tabla `service_orders` en schema `service_management`
- [ ] DB-021: Crear secuencia para folios
- [ ] DB-022: Indices por folio, vehiculo, cliente, status

**Backend:**
- [ ] BE-040: Crear ServiceOrderEntity
- [ ] BE-041: Crear ServiceOrderService.create()
- [ ] BE-042: Crear ServiceOrderController POST /api/orders
- [ ] BE-043: Generar folio con formato configurable
- [ ] BE-044: Endpoint PDF comprobante

**Frontend:**
- [ ] FE-040: Crear OrderCreatePage
- [ ] FE-041: Crear VehicleSearchInput component
- [ ] FE-042: Crear OrderForm component
- [ ] FE-043: Integracion con impresion PDF

---

## Dependencias

**Depende de:**
- [ ] MMD-001: Fundamentos (taller, bahias)
- [ ] MMD-005: Vehiculos (busqueda, registro)

**Bloquea:**
- [ ] Resto del flujo de ordenes

---

## Definition of Done (DoD)

- [ ] Crear orden con vehiculo existente
- [ ] Crear orden con vehiculo nuevo
- [ ] Folio automatico unico
- [ ] Comprobante PDF imprimible
- [ ] Tests pasando

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-06