AutoFiller_QR_Campamento/README.md

311 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Sistema de Mantenimiento por QR — Campamento
Sistema web para registrar actividades de mantenimiento en un campamento minero. Reemplaza el flujo anterior basado en **Microsoft Forms** por una aplicación propia en **PHP + MySQL/MariaDB**, con códigos QR físicos en cada ubicación.
Al escanear un QR, el técnico abre un formulario con **módulo** y **habitación ya prellenados**. Solo debe indicar la **empresa** que realizó el servicio y el **tipo de servicio** correspondiente.
---
## ¿Qué problema resuelve?
- Evita que el personal escriba manualmente el lugar (errores de captura).
- Centraliza todos los registros en una base de datos consultable.
- Permite **renombrar módulos y habitaciones** sin reimprimir QR, gracias a identificadores únicos estables.
- Genera etiquetas QR con el **mismo estilo visual** de la versión anterior (color azul `#132A7C`, logo `NEM.png`, pie con nombre del lugar).
---
## Arquitectura general
```
┌─────────────┐ escaneo ┌──────────────────┐
│ QR físico │ ───────────────► │ formulario.php │
│ en campo │ ?u=UB-00001 │ (formulario) │
└─────────────┘ └────────┬─────────┘
│ POST
▼
┌──────────────────┐
│ MariaDB │
│ registros, etc. │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Panel admin │
│ /admin/ │
└──────────────────┘
```
---
## Requisitos
| Componente | Versión / detalle |
|------------|-------------------|
| PHP | 8.0+ (extensiones `pdo_mysql`, `mbstring`) |
| MariaDB / MySQL | localhost |
| Python 3 | Solo para generar QR (`qrcode`, `Pillow`) |
| Servidor web | Apache, Nginx o `php -S` |
---
## Instalación
### 1. Base de datos
Editar credenciales en `config/config.php` si es necesario:
```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'mantenimiento_campamento');
define('DB_USER', 'root');
define('DB_PASS', 'R3m4st3r');
define('BASE_URL', 'http://localhost:8080'); // Ajustar a su URL real
```
### 2. Ejecutar instalador
Abrir en el navegador o ejecutar por CLI:
```
http://localhost:8080/install.php
```
El instalador:
- Crea la base de datos y tablas.
- **2 518 ubicaciones** desde `data.csv` (archivo original del proyecto).
- Ubicaciones adicionales con `php import_faltantes.php` desde `Faltantes.csv`.
- Asigna códigos únicos a cada módulo (`MOD-001`…) y ubicación (`UB-00001`…).
- Carga catálogos de **empresas** y **servicios**.
- Crea el usuario administrador inicial.
- Genera `qr_data.csv` para el script de QR.
### 3. Dependencias Python (QR)
```bash
pip3 install 'qrcode[pil]' pillow
```
### 4. Iniciar servidor (desarrollo)
```bash
php -S localhost:8080 -t .
```
---
## Acceso al sistema
| Rol | URL | Credenciales iniciales |
|-----|-----|------------------------|
| **Administración** | `/admin/login.php` | Usuario: `admin` / Contraseña: `admin123` |
| **Formulario (QR)** | `/formulario.php?u=UB-00001` | Sin login (público) |
> Cambie la contraseña de `admin` en **Admin → Usuarios** después del primer acceso.
---
## Flujo del técnico en campo
1. Escanea el QR pegado en la ubicación.
2. Se abre el formulario con datos automáticos:
- **Módulo** (ej. PLP)
- **Habitación / ubicación** (ej. T-72-1)
3. Selecciona **Empresa** (SODEXO, REYSAP, MTTO CAMP, SmartService).
4. Aparecen los **servicios** disponibles para esa empresa (lógica condicional).
5. Opcional: nombre del técnico y observaciones.
6. Envía → el registro queda guardado en la base de datos.
---
## Panel de administración
Ruta base: `/admin/`
| Sección | Función |
|---------|---------|
| **Panel** | Estadísticas, registros recientes, accesos rápidos |
| **Registros** | Consulta y filtrado por módulo, empresa, fechas y búsqueda libre |
| **Módulos** | Ver, editar nombres, activar/desactivar y **crear nuevos módulos** |
| **Ubicaciones** | Ver, editar, filtrar y **crear nuevas habitaciones** (una o varias por lote) |
| **Empresas** | Gestionar empresas contratistas |
| **Servicios** | Gestionar servicios por empresa (aparecen condicionalmente en el formulario) |
| **Códigos QR** | Vista previa, exportar CSV, generar etiquetas PNG |
| **Usuarios** | Crear, editar, desactivar y eliminar accesos al panel |
Todas las páginas admin requieren **inicio de sesión**.
---
## Identificadores únicos (clave del diseño)
Cada módulo y ubicación tiene un **código permanente** independiente del nombre visible:
| Entidad | Código ejemplo | Nombre editable | En el QR |
|---------|----------------|-----------------|----------|
| Módulo | `MOD-001` | PLP | No (solo en BD) |
| Ubicación | `UB-00001` | T-72-1 | Sí (`?u=UB-00001`) |
**Ventaja:** si mañana "PLP" pasa a llamarse "Campamento Norte", solo se edita el nombre en el panel. El QR impreso sigue apuntando a `UB-00001` sin regenerar nada.
Al crear nuevos módulos o ubicaciones, el sistema asigna automáticamente el siguiente código disponible (`MOD-020`, `UB-02519`, etc.).
---
## Generación de códigos QR
### Desde el panel
**Admin → Códigos QR → Generar QR**
### Desde terminal
```bash
python3 generate_qrs.py
```
### Formato de cada etiqueta
- Color QR: `#132A7C`
- Logo `NEM.png` centrado (corrección de errores alta)
- Pie de imagen: `Módulo | Habitación` (ej. `PLP | T-72-1`)
- Archivo PNG en `output/`, nombre: `Módulo_Habitación.png`
- Si hay colisión de nombre (mismo módulo + misma habitación), se añade el código: `…_UB-01121.png`
### Archivo de datos
`qr_data.csv` contiene columnas: `codigo`, `modulo`, `ubicacion`, `url`
Se regenera al instalar, exportar desde el panel o al crear ubicaciones nuevas.
---
## Base de datos
Base: `mantenimiento_campamento`
| Tabla | Descripción |
|-------|-------------|
| `modulos` | Áreas del campamento (PLP, COCINA, 100´s, etc.) |
| `ubicaciones` | Habitaciones, trailas, equipos, etc. (vinculadas a un módulo) |
| `empresas` | Contratistas (SODEXO, REYSAP, …) |
| `servicios` | Tipos de servicio por empresa |
| `registros` | Cada actividad de mantenimiento registrada |
| `usuarios` | Accesos al panel de administración |
---
## Estructura de archivos
```
autofillqr/
├── admin/ # Panel de administración
│ ├── index.php # Dashboard
│ ├── login.php / logout.php
│ ├── registros.php
│ ├── modulos.php
│ ├── ubicaciones.php
│ ├── empresas.php
│ ├── servicios.php
│ ├── usuarios.php
│ ├── qrs.php
│ ├── generate_qrs.php
│ └── export_qr.php
├── api/
│ ├── guardar.php # Guarda registro del formulario
│ └── servicios.php # API JSON: servicios por empresa
├── assets/css/ # Estilos
├── assets/js/ # JS formulario y admin
├── config/
│ ├── config.php # Configuración general
│ └── database.php # Conexión PDO
├── includes/ # Header, auth, funciones
├── sql/ # Esquema e migraciones
├── formulario.php # Formulario público (entrada QR)
├── install.php # Instalador
├── import_faltantes.php # Importar ubicaciones desde Faltantes.csv
├── generate_qrs.py # Generador de etiquetas PNG
├── data.csv # Datos originales (importación inicial)
├── Faltantes.csv # Ubicaciones adicionales (módulo, habitación)
├── qr_data.csv # URLs actuales para QR (generado)
├── NEM.png # Logo del campamento
└── output/ # QR generados (PNG)
```
---
## Catálogos precargados
### Empresas
- SODEXO
- REYSAP
- MTTO CAMP
- SmartService
### Servicios por empresa
| Empresa | Servicios |
|---------|-----------|
| SODEXO | Limpieza / Supervisión, Fumigación |
| REYSAP | Servicio de Mantenimiento |
| MTTO CAMP | Mtto Preventivo, Mtto Correctivo |
| SmartService | Mtto Cocina |
Todos editables desde el panel admin.
---
## Datos importados
Desde `data.csv` (formato original de Microsoft Forms):
- **19 módulos / áreas** iniciales + adicionales vía `Faltantes.csv`
- **2 628 ubicaciones** (2 518 base + 108 faltantes)
---
## Importar ubicaciones faltantes
Archivo `Faltantes.csv` con columnas `modulo,ubicacion` (UTF-8):
```bash
php import_faltantes.php
```
O desde el navegador (requiere login admin): `/import_faltantes.php`
---
## Notas técnicas
- Zona horaria: `America/Hermosillo`
- Contraseñas de usuarios: hash con `password_hash()` (bcrypt)
- El formulario público no requiere autenticación; el panel admin sí
- Los POST del admin procesan datos **antes** de enviar HTML (evita errores de headers)
- Codificación CSV original: ISO-8859-1; la BD usa UTF-8
---
## Resumen rápido de comandos
```bash
# Instalar (navegador)
open http://localhost:8080/install.php
# Importar ubicaciones faltantes
php import_faltantes.php
# Servidor desarrollo
php -S localhost:8080 -t .
# Generar todos los QR
python3 generate_qrs.py
```
---
## English summary
Web-based maintenance logging system for a mining camp. QR codes at each physical location open a pre-filled form (module + room). Staff selects contractor company and service type. Data is stored in MariaDB and managed through a password-protected admin panel. Unique stable IDs (`UB-XXXXX`) allow renaming locations without reprinting QR codes. PNG labels use brand color `#132A7C` and embedded `NEM.png` logo.