411 lines
10 KiB
Markdown
411 lines
10 KiB
Markdown
# 📦 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
|