# EPICA: EPIC-MMD-002 - Ordenes de Servicio

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MMD-002 |
| **Nombre** | Ordenes de Servicio |
| **Modulo** | ordenes-servicio |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 55 |
| **Sprint(s)** | Sprint 4-5 |

---

## Descripcion

Modulo central del sistema que gestiona el ciclo completo de ordenes de servicio: desde la recepcion del vehiculo, diagnostico, cotizacion, aprobacion, ejecucion de trabajos, hasta el cierre y entrega. Incluye tracking en tiempo real, asignacion de mecanicos y registro de refacciones utilizadas.

---

## Objetivo de Negocio

- Reducir tiempo de gestion de ordenes en 50%
- Eliminar ordenes perdidas o sin seguimiento
- Trazabilidad completa de cada servicio
- Mejorar comunicacion con clientes
- Facilitar facturacion posterior

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MMD002-001 | Como recepcionista, quiero crear orden de servicio con datos del vehiculo y cliente para iniciar el proceso | P0 | 5 | Backlog |
| US-MMD002-002 | Como recepcionista, quiero registrar sintomas/fallas reportadas por el cliente para informar al mecanico | P0 | 3 | Backlog |
| US-MMD002-003 | Como jefe de taller, quiero asignar orden a un mecanico y bahia para distribuir trabajo | P0 | 5 | Backlog |
| US-MMD002-004 | Como mecanico, quiero ver mis ordenes asignadas del dia para planear mi trabajo | P0 | 5 | Backlog |
| US-MMD002-005 | Como mecanico, quiero registrar trabajos realizados con tiempo y refacciones para documentar el servicio | P0 | 8 | Backlog |
| US-MMD002-006 | Como mecanico, quiero solicitar refacciones al almacen para completar la reparacion | P0 | 5 | Backlog |
| US-MMD002-007 | Como jefe de taller, quiero ver estado de todas las ordenes en tablero Kanban para supervisar | P0 | 8 | Backlog |
| US-MMD002-008 | Como recepcionista, quiero cerrar orden y generar pre-factura para cobrar al cliente | P0 | 5 | Backlog |
| US-MMD002-009 | Como cliente, quiero recibir notificacion cuando mi vehiculo este listo para recogerlo | P1 | 3 | Backlog |
| US-MMD002-010 | Como jefe de taller, quiero ver historial de ordenes por vehiculo para consulta rapida | P1 | 5 | Backlog |
| US-MMD002-011 | Como admin, quiero configurar estados personalizados de orden para adaptarlos a mi proceso | P2 | 3 | Backlog |

**Total Story Points:** 55 SP

---

## Flujo de Estados de Orden

```
┌─────────────┐
│   RECIBIDO  │  ← Vehiculo llega, se crea orden
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ EN_DIAGNOST │  ← Mecanico evalua el vehiculo
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  COTIZADO   │  ← Se genera cotizacion para cliente
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  APROBADO   │  ← Cliente aprueba trabajos
└──────┬──────┘
       │
       ▼
┌─────────────┐
│EN_REPARACION│  ← Mecanico ejecuta trabajos
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   LISTO     │  ← Trabajos completados
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  ENTREGADO  │  ← Cliente recoge vehiculo
└─────────────┘
```

**Estados adicionales:**
- `ESPERANDO_REFACCIONES` - Orden pausada por falta de partes
- `CANCELADO` - Orden cancelada por cliente

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Crear orden con datos minimos: vehiculo, cliente, sintomas
- [ ] Asignar orden a mecanico y bahia
- [ ] Registrar trabajos con tiempo y costo
- [ ] Solicitar y registrar refacciones usadas
- [ ] Transiciones de estado con validaciones
- [ ] Tablero Kanban de ordenes activas
- [ ] Historial completo por vehiculo
- [ ] Notificaciones por WhatsApp/SMS (opcional)

**No Funcionales:**
- [ ] Carga de tablero < 2 segundos
- [ ] Busqueda de orden por folio < 500ms
- [ ] Soporte 50+ ordenes activas simultaneas

**Tecnicos:**
- [ ] Integracion con modulo Inventario (refacciones)
- [ ] Integracion con modulo Vehiculos (historial)
- [ ] Integracion con modulo Diagnosticos (resultados)
- [ ] Tests de flujo completo

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MMD-001 Fundamentos | Backlog | Si |
| EPIC-MMD-003 Diagnosticos | Backlog | Si |
| EPIC-MMD-004 Inventario | Backlog | Si |
| EPIC-MMD-005 Vehiculos | Backlog | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-MMD-006 Cotizaciones | Requiere ordenes |
| EPIC-MME-007 Facturacion | Requiere ordenes cerradas |
| EPIC-MME-008 Reportes | Requiere datos de ordenes |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `service_management`
- [ ] Tablas: 8 (ordenes, orden_items, orden_refacciones, estados_log, etc.)
- [ ] Funciones: 4 (calcular_total, cambiar_estado, etc.)
- [ ] Indices: Por folio, vehiculo, mecanico, estado

**Backend:**
- [ ] Modulo: `service-orders`
- [ ] Entities: 6 (ServiceOrder, OrderItem, OrderPart, StateLog, etc.)
- [ ] Endpoints: 20+
- [ ] Tests: 40+

**Frontend:**
- [ ] Paginas: 5 (OrdersList, OrderDetail, OrderCreate, KanbanBoard, OrderHistory)
- [ ] Componentes: 15+ (OrderCard, OrderForm, StateSelect, PartsRequest, etc.)
- [ ] Stores: 2 (ordersStore, kanbanStore)

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/orders | Crear orden |
| GET | /api/orders | Listar ordenes (paginado, filtros) |
| GET | /api/orders/:id | Detalle de orden |
| PATCH | /api/orders/:id | Actualizar orden |
| POST | /api/orders/:id/items | Agregar trabajo a orden |
| POST | /api/orders/:id/parts | Solicitar refaccion |
| POST | /api/orders/:id/state | Cambiar estado |
| GET | /api/orders/kanban | Vista Kanban |
| GET | /api/vehicles/:id/orders | Historial por vehiculo |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Flujo muy rigido | Media | Alto | Estados configurables |
| Conflictos de inventario | Media | Medio | Reservas de refacciones |
| Ordenes huerfanas | Baja | Medio | Alertas de ordenes sin movimiento |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Modulos dependientes completados
- [ ] Diseno de flujo aprobado

## Definition of Done (DoD)

- [ ] Flujo completo funcionando
- [ ] Tablero Kanban operativo
- [ ] Integraciones con inventario y vehiculos
- [ ] Tests de integracion pasando
- [ ] Documentacion de API
- [ ] Demo con usuario real

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-06 | Creacion de epica | Requirements-Analyst |

---

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