# 📦 Sistema de Gestión de Recambios - Feature Branch

> **Rama**: `feature/typescript-shadcn-migration`  
> **Estado**: 🚧 En Desarrollo  
> **Stack**: TypeScript + shadcn/ui + React 18 + FastAPI

---

## 🎯 Objetivo de esta Rama

Desarrollar un **Sistema Integral de Gestión de Recambios** para talleres mecánicos, integrado con el sistema existente de checklists. Este módulo añade capacidades completas de gestión de pedidos, proveedores, inventario y facturación.

## 🏗️ Arquitectura del Módulo

### Frontend (TypeScript + shadcn/ui)

```
frontend/src/
├── modules/
│   └── recambios/
│       ├── RecambiosApp.tsx          ✅ Componente principal con navegación
│       ├── pages/
│       │   ├── KanbanPedidos.tsx     🚧 Tablero Kanban de estados
│       │   ├── PanelProveedor.tsx    🚧 Gestión de proveedores
│       │   ├── GestionAlbaranes.tsx  🚧 Registro de albaranes
│       │   ├── GestionClientes.tsx   🚧 Base de datos clientes
│       │   ├── Inventario.tsx        🚧 Control de stock
│       │   └── Configuracion.tsx     🚧 Ajustes del módulo
│       ├── components/
│       │   ├── PedidoCard.tsx        🚧 Tarjeta de pedido
│       │   ├── ProveedorForm.tsx     🚧 Formulario proveedor
│       │   ├── AlbaranForm.tsx       🚧 Formulario albarán
│       │   └── EstadoBadge.tsx       🚧 Badge de estado
│       └── types/
│           └── recambios.types.ts    🚧 Interfaces TypeScript
├── components/ui/                     ✅ shadcn/ui components
│   ├── button.tsx
│   ├── card.tsx
│   ├── badge.tsx
│   └── tabs.tsx
└── lib/
    └── utils.ts                       ✅ Utilidades (cn helper)
```

### Backend (FastAPI + SQLAlchemy)

```
backend/app/
├── modules/
│   └── recambios/
│       ├── __init__.py
│       ├── models.py                  🚧 15+ modelos SQLAlchemy
│       ├── schemas.py                 🚧 Pydantic schemas
│       ├── routes.py                  🚧 Endpoints REST
│       └── services.py                🚧 Lógica de negocio
└── migrations/
    └── add_recambios_tables.sql       🚧 Schema inicial
```

---

## 📊 Modelo de Datos

### Entidades Principales

#### 1. **rec_clientes**
```sql
- id, nombre, telefono, email, direccion, cif_nif
- vehiculos_asociados (JSON)
- historial_pedidos
```

#### 2. **rec_proveedores**
```sql
- id, nombre, contacto, telefono, email
- plazo_entrega_dias, condiciones_pago
- rating, notas
```

#### 3. **rec_referencias**
```sql
- id, codigo_referencia, descripcion
- proveedor_id, precio_compra, precio_venta
- estado (13 estados posibles)
- stock_actual, ubicacion_almacen
```

#### 4. **rec_pedidos_cliente**
```sql
- id, cliente_id, fecha_pedido, total
- estado, prioridad, asesor_id
- vehiculo_datos (JSON)
```

#### 5. **rec_lineas_pedido**
```sql
- id, pedido_cliente_id, referencia_id
- cantidad, precio_unitario, subtotal
- estado_linea
```

#### 6. **rec_pedidos_proveedor**
```sql
- id, proveedor_id, fecha_pedido
- estado, total_pedido, recambista_id
```

#### 7. **rec_albaranes**
```sql
- id, pedido_proveedor_id, numero_albaran
- fecha_recepcion, recibido_por
- observaciones, foto_albaran_url
```

#### 8. **rec_devoluciones**
```sql
- id, referencia_id, motivo, estado
- fecha_devolucion, fecha_abono
- importe_abonado
```

#### 9. **rec_movimientos_stock**
```sql
- id, referencia_id, tipo_movimiento
- cantidad, fecha, usuario_id
```

#### 10. **rec_facturas**
```sql
- id, cliente_id, numero_factura
- fecha_emision, total, estado
- archivo_pdf_url
```

---

## 🔄 Máquina de Estados (13 Estados)

```
┌─────────────────────┐
│ pendiente_decidir   │ ← Estado inicial
└──────────┬──────────┘
           │
           ├─→ pedido_proveedor
           ├─→ alternativa
           ├─→ usado
           └─→ descartada
                │
    ┌───────────┴───────────┐
    │                       │
    ▼                       ▼
  recibida              recibida_parcial
    │                       │
    ├─→ devolucion          │
    ├─→ entregada ──────────┘
    └─→ instalada
           │
           └─→ facturada
```

### Transiciones de Estado

1. **pendiente_decidir** → Usuario decide acción
2. **pedido_proveedor** → Pedido enviado al proveedor
3. **alternativa** → Buscando opción alternativa
4. **usado** → Referencia de segunda mano
5. **recibida** → Llegó completa del proveedor
6. **recibida_parcial** → Llegó solo parte del pedido
7. **devolucion** → En proceso de devolución
8. **entregada** → Entregada al cliente
9. **instalada** → Instalada en el vehículo
10. **facturada** → Facturada al cliente
11. **descartada** → No se procede con la referencia
12. **pendiente_abono** → Esperando abono de devolución
13. **abonada** → Devolución abonada

---

## 👥 Roles y Permisos

### Asesor de Servicio
- ✅ Crear pedidos de cliente
- ✅ Consultar estado de referencias
- ✅ Modificar prioridades
- ✅ Ver historial de cliente

### Recambista
- ✅ Gestionar pedidos a proveedores
- ✅ Registrar albaranes
- ✅ Gestionar stock
- ✅ Actualizar estados de referencias
- ✅ Procesar devoluciones

### Administración
- ✅ Generar facturas
- ✅ Ver reportes financieros
- ✅ Gestionar proveedores
- ✅ Configurar precios

---

## 🎨 Diseño UI con shadcn/ui

### Componentes Implementados ✅

- **Button** - Botones con variantes (default, outline, ghost, destructive)
- **Card** - Tarjetas con header, content, footer
- **Badge** - Etiquetas de estado con colores
- **Tabs** - Navegación entre secciones

### Componentes Pendientes 🚧

- **Input** - Campos de texto
- **Select** - Dropdowns
- **Dialog** - Modales
- **Table** - Tablas de datos
- **Toast** - Notificaciones
- **Dropdown Menu** - Menús contextuales
- **Date Picker** - Selector de fechas
- **Form** - Formularios validados

---

## 📋 Plan de Implementación

### ✅ Sprint 0: Fundación (COMPLETADO)
- [x] Configuración TypeScript
- [x] Setup shadcn/ui
- [x] Componentes base UI
- [x] Estructura de carpetas
- [x] Prototipo Kanban visual

### 🚧 Sprint 1: Backend Core (EN PROGRESO)
- [ ] Modelos SQLAlchemy (15 tablas)
- [ ] Migraciones de base de datos
- [ ] Schemas Pydantic
- [ ] Endpoints CRUD básicos
- [ ] Autenticación y permisos

### 🔜 Sprint 2: Frontend Básico
- [ ] Páginas principales (6 tabs)
- [ ] Formularios con validación
- [ ] Integración API
- [ ] Gestión de estado
- [ ] Tipos TypeScript completos

### 🔜 Sprint 3: Funcionalidades Avanzadas
- [ ] Kanban drag & drop
- [ ] Upload de fotos (albaranes)
- [ ] Generación de PDFs
- [ ] Sistema de notificaciones
- [ ] Búsqueda y filtros

### 🔜 Sprint 4: Integración y Testing
- [ ] Integración con sistema de checklists
- [ ] Tests unitarios
- [ ] Tests E2E
- [ ] Optimización de rendimiento
- [ ] Documentación completa

---

## 🚀 Comandos de Desarrollo

### Levantar Entorno de Desarrollo

```powershell
# Frontend
cd frontend
npm run dev

# Backend
cd backend
docker-compose up -d
```

### Ver el Módulo de Recambios

1. Inicia sesión como **admin**
2. Haz clic en **📦 Recambios** en el sidebar
3. Navega entre las 6 pestañas

### Compilar TypeScript

```powershell
cd frontend
npm run build
```

---

## 🔧 Tecnologías Utilizadas

### Frontend
- **React 18** - Framework UI
- **TypeScript 5.9** - Type safety
- **shadcn/ui** - Component library
- **Radix UI** - Primitive components
- **Tailwind CSS 3.4** - Utility-first CSS
- **Lucide React** - Icon library
- **Vite 5** - Build tool

### Backend
- **FastAPI** - Python web framework
- **SQLAlchemy** - ORM
- **PostgreSQL 15** - Base de datos
- **Pydantic** - Data validation
- **JWT** - Autenticación

---

## 📝 Convenciones de Código

### TypeScript
```typescript
// Interfaces con prefijo 'I' o sufijo del dominio
interface Pedido {
  id: number;
  cliente: string;
  estado: EstadoPedido;
}

// Tipos para estados
type EstadoPedido = 'pendiente_decidir' | 'pedido_proveedor' | 'recibida';

// Componentes con tipo React.FC
const PedidoCard: React.FC<PedidoCardProps> = ({ pedido }) => { ... }
```

### Python
```python
# Modelos con tabla explícita
class RecCliente(Base):
    __tablename__ = "rec_clientes"
    
# Schemas con validación
class PedidoCreate(BaseModel):
    cliente_id: int
    referencias: List[LineaPedido]
    
# Rutas con prefijo /api/recambios
@router.post("/api/recambios/pedidos")
```

---

## 🐛 Debugging

### Frontend
```powershell
# Ver errores TypeScript
npm run dev

# Limpiar caché
rm -r node_modules .vite
npm install
```

### Backend
```powershell
# Ver logs
docker-compose logs -f backend

# Entrar al contenedor
docker-compose exec backend bash

# Verificar tablas
docker-compose exec postgres psql -U user -d checklist_db -c "\dt rec_*"
```

---

## 📚 Documentación Relacionada

- [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) - Guía de migración TypeScript
- [AI_FUNCTIONALITY.md](./AI_FUNCTIONALITY.md) - Sistema de IA (checklists)
- [API_DOCUMENTATION.md](./API_DOCUMENTATION.md) - Documentación API
- [shadcn/ui Docs](https://ui.shadcn.com/) - Documentación componentes

---

## 🎯 Próximos Pasos

1. **Crear modelos de backend** (15 tablas)
2. **Escribir schemas Pydantic**
3. **Implementar endpoints CRUD**
4. **Desarrollar páginas TypeScript**
5. **Conectar frontend con API**
6. **Agregar drag & drop al Kanban**
7. **Implementar búsqueda y filtros**
8. **Testing completo**

---

## 👨‍💻 Contribución

Esta es una rama de desarrollo activo. Para contribuir:

1. Crea una sub-rama desde `feature/typescript-shadcn-migration`
2. Implementa tu funcionalidad
3. Haz commit con mensajes descriptivos
4. Crea PR hacia esta rama (NO hacia main)

---

## 📞 Contacto

**Proyecto**: Ayutec - Sistema Inteligente de Inspecciones  
**Versión Recambios**: 0.1.0 (Alpha)  
**Última Actualización**: Diciembre 2025