checklist/README.md

# 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

## 📝 Control de Versiones

### Instrucciones para commits de Git

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

Formato recomendado:
```bash
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**:
```bash
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.