10 KiB
10 KiB
📦 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
- id, nombre, telefono, email, direccion, cif_nif
- vehiculos_asociados (JSON)
- historial_pedidos
2. rec_proveedores
- id, nombre, contacto, telefono, email
- plazo_entrega_dias, condiciones_pago
- rating, notas
3. rec_referencias
- id, codigo_referencia, descripcion
- proveedor_id, precio_compra, precio_venta
- estado (13 estados posibles)
- stock_actual, ubicacion_almacen
4. rec_pedidos_cliente
- id, cliente_id, fecha_pedido, total
- estado, prioridad, asesor_id
- vehiculo_datos (JSON)
5. rec_lineas_pedido
- id, pedido_cliente_id, referencia_id
- cantidad, precio_unitario, subtotal
- estado_linea
6. rec_pedidos_proveedor
- id, proveedor_id, fecha_pedido
- estado, total_pedido, recambista_id
7. rec_albaranes
- id, pedido_proveedor_id, numero_albaran
- fecha_recepcion, recibido_por
- observaciones, foto_albaran_url
8. rec_devoluciones
- id, referencia_id, motivo, estado
- fecha_devolucion, fecha_abono
- importe_abonado
9. rec_movimientos_stock
- id, referencia_id, tipo_movimiento
- cantidad, fecha, usuario_id
10. rec_facturas
- 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
- pendiente_decidir → Usuario decide acción
- pedido_proveedor → Pedido enviado al proveedor
- alternativa → Buscando opción alternativa
- usado → Referencia de segunda mano
- recibida → Llegó completa del proveedor
- recibida_parcial → Llegó solo parte del pedido
- devolucion → En proceso de devolución
- entregada → Entregada al cliente
- instalada → Instalada en el vehículo
- facturada → Facturada al cliente
- descartada → No se procede con la referencia
- pendiente_abono → Esperando abono de devolución
- 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)
- Configuración TypeScript
- Setup shadcn/ui
- Componentes base UI
- Estructura de carpetas
- 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
# Frontend
cd frontend
npm run dev
# Backend
cd backend
docker-compose up -d
Ver el Módulo de Recambios
- Inicia sesión como admin
- Haz clic en 📦 Recambios en el sidebar
- Navega entre las 6 pestañas
Compilar TypeScript
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
// 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
# 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
# Ver errores TypeScript
npm run dev
# Limpiar caché
rm -r node_modules .vite
npm install
Backend
# 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 - Guía de migración TypeScript
- AI_FUNCTIONALITY.md - Sistema de IA (checklists)
- API_DOCUMENTATION.md - Documentación API
- shadcn/ui Docs - Documentación componentes
🎯 Próximos Pasos
- Crear modelos de backend (15 tablas)
- Escribir schemas Pydantic
- Implementar endpoints CRUD
- Desarrollar páginas TypeScript
- Conectar frontend con API
- Agregar drag & drop al Kanban
- Implementar búsqueda y filtros
- Testing completo
👨💻 Contribución
Esta es una rama de desarrollo activo. Para contribuir:
- Crea una sub-rama desde
feature/typescript-shadcn-migration - Implementa tu funcionalidad
- Haz commit con mensajes descriptivos
- 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