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

cd checklist-mvp

2. Configurar variables de entorno

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

docker-compose up -d

Esto levantará:

• PostgreSQL en puerto 5432
• Backend (FastAPI) en puerto 8000
• Frontend (React) en puerto 5173

4. Crear usuario administrador

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

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

docker-compose logs -f backend

Ver logs del frontend

docker-compose logs -f frontend

Ver logs de PostgreSQL

docker-compose logs -f postgres

Acceder a la base de datos

docker-compose exec postgres psql -U checklist_user -d checklist_db

Reiniciar servicios

docker-compose restart

Detener todo

docker-compose down

Eliminar volúmenes (resetear BD)

docker-compose down -v

📝 Crear Checklist de Ejemplo

Puedes usar la API directamente o crear via 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

📝 Control de Versiones

Instrucciones para commits de Git

IMPORTANTE: Siempre incluir la versión actualizada en los mensajes de commit.

Formato recomendado:

git add .
git commit -m "tipo: descripción del cambio

- Detalle 1
- Detalle 2
- Frontend vX.X.XX / Backend vX.X.XX"

Tipos de commit:

• feat: Nueva funcionalidad
• fix: Corrección de bugs
• refactor: Refactorización de código
• style: Cambios de formato/estilo
• docs: Actualización de documentación
• perf: Mejoras de rendimiento
• test: Añadir o actualizar tests

Ejemplo real:

git add .
git commit -m "feat: Add pagination (10 items/page) to all main tabs

- Pagination for Inspections, Checklists, and Reports
- Auto-reset on filter changes
- Smart page navigation with ellipsis
- Result counters showing X-Y of Z items
- Frontend v1.0.64"

Versionado

Seguir Semantic Versioning (MAJOR.MINOR.PATCH):

• MAJOR: Cambios incompatibles en la API
• MINOR: Nueva funcionalidad compatible con versiones anteriores
• PATCH: Correcciones de bugs

Ubicación de versiones:

• Frontend: frontend/package.json → "version": "X.X.XX"
• Backend: backend/app/main.py → version="X.X.XX" en FastAPI app

🆘 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.