Base Principal del Proyecto
This commit is contained in:
386
README.md
Normal file
386
README.md
Normal file
@@ -0,0 +1,386 @@
|
||||
# Sistema de Checklists Inteligentes - MVP
|
||||
|
||||
Sistema completo de gestión de checklists para talleres mecánicos con integración de IA.
|
||||
|
||||
## 🚀 Características
|
||||
|
||||
- ✅ Gestión de checklists dinámicos (Admin)
|
||||
- ✅ Ejecución de inspecciones (Mecánico)
|
||||
- ✅ Sistema de puntuación automática
|
||||
- ✅ Upload de múltiples fotos
|
||||
- ✅ Firma digital
|
||||
- ✅ Generación de PDF profesional
|
||||
- ✅ API REST completa
|
||||
- ✅ Autenticación JWT
|
||||
- ✅ Base de datos PostgreSQL
|
||||
|
||||
## 📋 Requisitos Previos
|
||||
|
||||
- Docker & Docker Compose instalados
|
||||
- OpenAI API Key (opcional, solo para análisis IA)
|
||||
|
||||
## 🛠️ Instalación Rápida
|
||||
|
||||
### 1. Clonar/Descargar el proyecto
|
||||
|
||||
```bash
|
||||
cd checklist-mvp
|
||||
```
|
||||
|
||||
### 2. Configurar variables de entorno
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Editar `.env` y configurar:
|
||||
- `OPENAI_API_KEY` (si deseas usar análisis IA)
|
||||
- Cambiar `SECRET_KEY` por una clave segura
|
||||
|
||||
### 3. Levantar servicios con Docker
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
Esto levantará:
|
||||
- PostgreSQL en puerto 5432
|
||||
- Backend (FastAPI) en puerto 8000
|
||||
- Frontend (React) en puerto 5173
|
||||
|
||||
### 4. Crear usuario administrador
|
||||
|
||||
```bash
|
||||
docker-compose exec backend python -c "
|
||||
from app.core.database import SessionLocal
|
||||
from app.models import User
|
||||
from app.core.security import get_password_hash
|
||||
|
||||
db = SessionLocal()
|
||||
admin = User(
|
||||
username='admin',
|
||||
password_hash=get_password_hash('admin123'),
|
||||
role='admin',
|
||||
email='admin@taller.com',
|
||||
full_name='Administrador'
|
||||
)
|
||||
db.add(admin)
|
||||
db.commit()
|
||||
print('Usuario admin creado: admin / admin123')
|
||||
"
|
||||
```
|
||||
|
||||
### 5. Crear usuario mecánico
|
||||
|
||||
```bash
|
||||
docker-compose exec backend python -c "
|
||||
from app.core.database import SessionLocal
|
||||
from app.models import User
|
||||
from app.core.security import get_password_hash
|
||||
|
||||
db = SessionLocal()
|
||||
mechanic = User(
|
||||
username='mecanico1',
|
||||
password_hash=get_password_hash('mecanico123'),
|
||||
role='mechanic',
|
||||
email='mecanico@taller.com',
|
||||
full_name='Juan Pérez'
|
||||
)
|
||||
db.add(mechanic)
|
||||
db.commit()
|
||||
print('Usuario mecánico creado: mecanico1 / mecanico123')
|
||||
"
|
||||
```
|
||||
|
||||
## 🌐 Acceso a la Aplicación
|
||||
|
||||
- **Frontend**: http://localhost:5173
|
||||
- **API Backend**: http://localhost:8000
|
||||
- **Documentación API**: http://localhost:8000/docs
|
||||
|
||||
## 👥 Usuarios de Prueba
|
||||
|
||||
| Usuario | Contraseña | Rol |
|
||||
|---------|-----------|-----|
|
||||
| admin | admin123 | Administrador |
|
||||
| mecanico1 | mecanico123 | Mecánico |
|
||||
|
||||
## 📱 Flujo de Uso
|
||||
|
||||
### Como Administrador:
|
||||
|
||||
1. Login con `admin / admin123`
|
||||
2. Ir a "Checklists"
|
||||
3. Crear nuevo checklist
|
||||
4. Agregar preguntas con tipos:
|
||||
- pass_fail: Revisado / En mal estado
|
||||
- good_bad: Buen estado / Mal estado
|
||||
- text: Respuesta libre
|
||||
- numeric: Números (KM, porcentajes)
|
||||
5. Configurar puntos por pregunta
|
||||
6. Activar el checklist
|
||||
|
||||
### Como Mecánico:
|
||||
|
||||
1. Login con `mecanico1 / mecanico123`
|
||||
2. Ir a "Nueva Inspección"
|
||||
3. Seleccionar checklist activo
|
||||
4. Ingresar datos del vehículo (OR, matrícula, KM)
|
||||
5. Completar preguntas paso a paso
|
||||
6. Subir fotos (máx 3 por pregunta)
|
||||
7. Ver score en tiempo real
|
||||
8. Firmar digitalmente
|
||||
9. Finalizar inspección
|
||||
10. Descargar PDF generado
|
||||
|
||||
## 🗂️ Estructura del Proyecto
|
||||
|
||||
```
|
||||
checklist-mvp/
|
||||
├── docker-compose.yml # Orquestación de servicios
|
||||
├── .env.example # Variables de entorno
|
||||
│
|
||||
├── backend/ # API FastAPI
|
||||
│ ├── Dockerfile
|
||||
│ ├── requirements.txt
|
||||
│ └── app/
|
||||
│ ├── main.py # Endpoints principales
|
||||
│ ├── models.py # Modelos SQLAlchemy
|
||||
│ ├── schemas.py # Schemas Pydantic
|
||||
│ └── core/
|
||||
│ ├── config.py # Configuración
|
||||
│ ├── database.py # Conexión BD
|
||||
│ └── security.py # JWT & Hashing
|
||||
│
|
||||
└── frontend/ # React + Vite
|
||||
├── Dockerfile
|
||||
├── package.json
|
||||
├── vite.config.js
|
||||
├── tailwind.config.js
|
||||
└── src/
|
||||
├── App.jsx # App principal
|
||||
├── pages/ # Páginas
|
||||
├── components/ # Componentes
|
||||
└── services/ # API calls
|
||||
```
|
||||
|
||||
## 🔌 API Endpoints Principales
|
||||
|
||||
### Autenticación
|
||||
```
|
||||
POST /api/auth/register # Registrar usuario
|
||||
POST /api/auth/login # Login
|
||||
GET /api/auth/me # Usuario actual
|
||||
```
|
||||
|
||||
### Checklists
|
||||
```
|
||||
GET /api/checklists # Listar checklists
|
||||
POST /api/checklists # Crear checklist (admin)
|
||||
GET /api/checklists/{id} # Ver detalle con preguntas
|
||||
PUT /api/checklists/{id} # Actualizar
|
||||
```
|
||||
|
||||
### Preguntas
|
||||
```
|
||||
POST /api/questions # Crear pregunta (admin)
|
||||
PUT /api/questions/{id} # Actualizar
|
||||
DELETE /api/questions/{id} # Eliminar
|
||||
```
|
||||
|
||||
### Inspecciones
|
||||
```
|
||||
GET /api/inspections # Listar inspecciones
|
||||
POST /api/inspections # Crear inspección
|
||||
GET /api/inspections/{id} # Ver detalle completo
|
||||
PUT /api/inspections/{id} # Actualizar (guardar borrador)
|
||||
POST /api/inspections/{id}/complete # Finalizar
|
||||
```
|
||||
|
||||
### Respuestas
|
||||
```
|
||||
POST /api/answers # Crear respuesta
|
||||
PUT /api/answers/{id} # Actualizar respuesta
|
||||
```
|
||||
|
||||
### Archivos
|
||||
```
|
||||
POST /api/answers/{id}/upload # Subir foto
|
||||
```
|
||||
|
||||
## 🗄️ Modelo de Datos
|
||||
|
||||
### Users
|
||||
- id, username, email, password_hash
|
||||
- role (admin/mechanic)
|
||||
- full_name, is_active
|
||||
|
||||
### Checklists
|
||||
- id, name, description
|
||||
- ai_mode (off/assisted/copilot)
|
||||
- scoring_enabled, max_score
|
||||
- is_active, created_by
|
||||
|
||||
### Questions
|
||||
- id, checklist_id, section
|
||||
- text, type, points
|
||||
- options (JSON), order
|
||||
- allow_photos, max_photos
|
||||
|
||||
### Inspections
|
||||
- id, checklist_id, mechanic_id
|
||||
- or_number, vehicle_plate, vehicle_km
|
||||
- score, max_score, percentage
|
||||
- flagged_items_count
|
||||
- status (draft/completed)
|
||||
- signature_data
|
||||
|
||||
### Answers
|
||||
- id, inspection_id, question_id
|
||||
- answer_value, status (ok/warning/critical)
|
||||
- points_earned, comment
|
||||
- is_flagged, ai_analysis (JSON)
|
||||
|
||||
### MediaFiles
|
||||
- id, answer_id
|
||||
- file_path, file_type, caption
|
||||
|
||||
## 🎨 Tipos de Preguntas
|
||||
|
||||
| Tipo | Descripción | Opciones |
|
||||
|------|-------------|----------|
|
||||
| pass_fail | Pasa/Falla | REVISADO / EN MAL ESTADO |
|
||||
| good_bad | Estado | Buen estado / Mal estado |
|
||||
| status | Acción | REVISADO / SUSTITUIDO / Ninguna acción |
|
||||
| text | Texto libre | - |
|
||||
| numeric | Número | - |
|
||||
| date | Fecha | - |
|
||||
| multiple_choice | Opciones | Configurables |
|
||||
|
||||
## 🔒 Seguridad
|
||||
|
||||
- Autenticación JWT con tokens Bearer
|
||||
- Passwords hasheados con bcrypt
|
||||
- CORS configurado para desarrollo
|
||||
- Validación con Pydantic
|
||||
- Autorización por roles (admin/mechanic)
|
||||
|
||||
## 🐛 Debugging
|
||||
|
||||
### Ver logs del backend
|
||||
```bash
|
||||
docker-compose logs -f backend
|
||||
```
|
||||
|
||||
### Ver logs del frontend
|
||||
```bash
|
||||
docker-compose logs -f frontend
|
||||
```
|
||||
|
||||
### Ver logs de PostgreSQL
|
||||
```bash
|
||||
docker-compose logs -f postgres
|
||||
```
|
||||
|
||||
### Acceder a la base de datos
|
||||
```bash
|
||||
docker-compose exec postgres psql -U checklist_user -d checklist_db
|
||||
```
|
||||
|
||||
### Reiniciar servicios
|
||||
```bash
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
### Detener todo
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Eliminar volúmenes (resetear BD)
|
||||
```bash
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
## 📝 Crear Checklist de Ejemplo
|
||||
|
||||
Puedes usar la API directamente o crear via SQL:
|
||||
|
||||
```sql
|
||||
-- Conectar a la BD
|
||||
docker-compose exec postgres psql -U checklist_user -d checklist_db
|
||||
|
||||
-- Insertar checklist
|
||||
INSERT INTO checklists (name, description, ai_mode, scoring_enabled, max_score, is_active, created_by)
|
||||
VALUES ('Mantenimiento Básico', 'Checklist de mantenimiento estándar', 'assisted', true, 0, true, 1);
|
||||
|
||||
-- Insertar preguntas
|
||||
INSERT INTO questions (checklist_id, section, text, type, points, order, allow_photos) VALUES
|
||||
(1, 'Sistema Eléctrico', 'Estado de la batería', 'good_bad', 1, 1, true),
|
||||
(1, 'Sistema Eléctrico', 'Bocina', 'pass_fail', 1, 2, false),
|
||||
(1, 'Frenos', 'Frenos (pastillas, discos)', 'pass_fail', 2, 3, true),
|
||||
(1, 'Motor', 'Nivel de aceite', 'pass_fail', 1, 4, true),
|
||||
(1, 'Motor', 'Fugas de aceite', 'pass_fail', 2, 5, true);
|
||||
|
||||
-- Actualizar max_score del checklist
|
||||
UPDATE checklists SET max_score = (
|
||||
SELECT SUM(points) FROM questions WHERE checklist_id = 1
|
||||
) WHERE id = 1;
|
||||
```
|
||||
|
||||
## 🚀 Despliegue en Producción
|
||||
|
||||
### Cambios necesarios para producción:
|
||||
|
||||
1. **Variables de entorno**:
|
||||
- Cambiar `SECRET_KEY` por una clave segura aleatoria
|
||||
- Configurar `OPENAI_API_KEY`
|
||||
- Usar base de datos PostgreSQL externa
|
||||
|
||||
2. **Frontend**:
|
||||
- Cambiar `VITE_API_URL` a URL del backend en producción
|
||||
- Ejecutar `npm run build`
|
||||
- Servir carpeta `dist/` con Nginx
|
||||
|
||||
3. **Backend**:
|
||||
- Configurar CORS con dominio específico
|
||||
- Usar Gunicorn en lugar de Uvicorn
|
||||
- Configurar HTTPS con certificado SSL
|
||||
|
||||
4. **Base de datos**:
|
||||
- Usar PostgreSQL gestionado (AWS RDS, DigitalOcean, etc)
|
||||
- Hacer backups automáticos
|
||||
- Configurar conexiones SSL
|
||||
|
||||
5. **Storage**:
|
||||
- Usar S3 o similar para archivos
|
||||
- Configurar CDN para imágenes
|
||||
|
||||
## 📄 Licencia
|
||||
|
||||
MIT License - Uso libre para proyectos comerciales y personales
|
||||
|
||||
## 🆘 Soporte
|
||||
|
||||
Para problemas o preguntas:
|
||||
1. Revisar logs con `docker-compose logs`
|
||||
2. Verificar que todos los servicios están corriendo con `docker-compose ps`
|
||||
3. Revisar documentación de API en http://localhost:8000/docs
|
||||
|
||||
## 🎯 Próximos Pasos (Post-MVP)
|
||||
|
||||
- [ ] Lógica condicional en preguntas
|
||||
- [ ] Modo Copiloto IA completo
|
||||
- [ ] Análisis avanzado de imágenes
|
||||
- [ ] Dashboard de estadísticas
|
||||
- [ ] Historial de vehículos
|
||||
- [ ] Notificaciones por email/WhatsApp
|
||||
- [ ] App móvil React Native
|
||||
- [ ] Multi-tenant para varios talleres
|
||||
- [ ] Integración con sistemas ERP
|
||||
|
||||
---
|
||||
|
||||
**¡Listo para usar! 🎉**
|
||||
|
||||
Recuerda cambiar las contraseñas por defecto antes de usar en producción.
|
||||
Reference in New Issue
Block a user