readme actualizado para la Rama
This commit is contained in:
410
README_RECAMBIOS.md
Normal file
410
README_RECAMBIOS.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# 📦 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
|
||||
Reference in New Issue
Block a user