12 KiB
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 + 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.
Producción: https://penasquitoapps.newmont.com/camp/mtto_record/
¿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
#132A7C, logoNEM.png, pie con nombre del lugar).
Arquitectura
┌─────────────┐ escaneo ┌──────────────────┐
│ QR físico │ ───────────────► │ formulario.php │
│ en campo │ ?u=UB-00001 │ (público) │
└─────────────┘ └────────┬─────────┘
│ POST
▼
┌──────────────────┐
│ MariaDB │
│ registros, etc. │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Panel admin │
│ /admin/ │
└──────────────────┘
Requisitos
| Componente | Detalle |
|---|---|
| PHP | 8.0+ (pdo_mysql, mbstring) |
| MariaDB / MySQL | Base mantenimiento_campamento |
| Python 3 | Solo para generar QR (qrcode, Pillow) |
| Servidor web | Apache con .htaccess (producción) o php -S (local) |
Datos actuales
| Concepto | Cantidad |
|---|---|
| Módulos / áreas | 25 |
| Ubicaciones | 2 628 |
| Empresas | 4 (SODEXO, REYSAP, MTTO CAMP, SmartService) |
| Servicios | 7 (por empresa) |
Los datos viven en MariaDB. Respaldo completo en sql/backup_produccion.sql.
Configuración
Archivo principal: config/config.php
| Constante | Producción | Local |
|---|---|---|
BASE_URL |
https://penasquitoapps.newmont.com/camp/mtto_record |
http://localhost:8080 |
APP_BASE_PATH |
/camp/mtto_record |
— |
APP_ENV |
production (automático) |
local (si existe config.local.php) |
Archivos de entorno
| Archivo | Uso | ¿Versionar? |
|---|---|---|
config/config.php |
Valores por defecto + producción | Sí |
config/config.local.php |
Overrides de desarrollo local | No (.gitignore) |
config/config.production.php |
Credenciales BD del servidor Newmont | No (.gitignore) |
config/config.local.example.php |
Plantilla para local | Sí |
config/config.production.example.php |
Plantilla para producción | Sí |
Despliegue en producción
1. Preparar paquete (en local)
./scripts/prepare_deploy.sh
Genera:
sql/backup_produccion.sql— respaldo completo de la BDqr_data.csv— URLs con dominio de producción
2. Subir al servidor
Copiar el proyecto a la ruta /camp/mtto_record/ del servidor web.
Subir: código fuente, NEM.png, sql/backup_produccion.sql, .htaccess
No subir: config/config.local.php, .git/, .DS_Store
Crear en el servidor:
cp config/config.production.example.php config/config.production.php
# Editar credenciales MariaDB del entorno Newmont
3. Importar base de datos
# Si la BD no existe:
mysql -u USUARIO -p < sql/schema.sql
# Datos completos:
mysql -u USUARIO -p mantenimiento_campamento < sql/backup_produccion.sql
4. Permisos
mkdir -p output
chmod 755 output/
# El usuario del servidor web debe poder escribir en output/ y crear qr_data.csv
5. Verificar
| URL | Esperado |
|---|---|
/camp/mtto_record/admin/login.php |
Pantalla de login |
/camp/mtto_record/formulario.php?u=UB-00001 |
Formulario público |
/camp/mtto_record/install.php |
403 (bloqueado en producción) |
6. Post-despliegue
- Iniciar sesión (
admin/admin123) y cambiar la contraseña en Usuarios. - Admin → Códigos QR → Generar todos (PNG con URL de producción).
- Probar escaneo de un QR real.
Desarrollo local
1. Configuración
cp config/config.local.example.php config/config.local.php
Esto activa APP_ENV=local y BASE_URL=http://localhost:8080.
2. Base de datos
Importar el respaldo o usar el instalador:
mysql -u root -p mantenimiento_campamento < sql/backup_produccion.sql
O abrir http://localhost:8080/install.php (solo funciona con APP_ENV=local).
3. Servidor de desarrollo
cd /ruta/al/proyecto
php -S localhost:8080 -t .
El servidor debe estar corriendo mientras se prueba. Si Safari muestra "Can't connect to the server", ejecute el comando anterior.
4. Dependencias Python (QR)
pip3 install 'qrcode[pil]' pillow
Acceso al sistema
| Rol | URL producción | Credenciales iniciales |
|---|---|---|
| Administración | /camp/mtto_record/admin/login.php |
admin / admin123 |
| Formulario (QR) | /camp/mtto_record/formulario.php?u=UB-00001 |
Sin login |
Panel de administración
Ruta: /admin/ (requiere login)
| Sección | Función |
|---|---|
| Panel | Estadísticas, registros recientes, accesos rápidos |
| Registros | Consulta y filtrado por módulo, empresa, fechas |
| Módulos | Crear, editar nombres, activar/desactivar |
| Ubicaciones | Crear (una o varias), editar, filtrar, eliminar |
| Empresas | Gestionar contratistas, eliminar |
| Servicios | Servicios por empresa, eliminar |
| Códigos QR | Listado, vista previa, descarga individual, ZIP masivo, generación |
| Usuarios | Crear, editar, desactivar, eliminar |
Confirmación antes de eliminar
Toda acción destructiva (eliminar registros de catálogo, generar QR masivo) muestra un modal de confirmación bilingüe (ES/EN) antes de ejecutarse.
Reglas de eliminación
- Ubicaciones, empresas y servicios con registros de mantenimiento asociados no se pueden eliminar (usar desactivar).
- Al eliminar una ubicación se borra también su PNG en
output/y se actualizaqr_data.csv. - Al eliminar una empresa se eliminan también sus servicios (CASCADE).
Flujo del técnico en campo
- Escanea el QR pegado en la ubicación.
- Se abre el formulario con módulo y habitación prellenados.
- Selecciona Empresa → aparecen los servicios de esa empresa.
- Opcional: nombre del técnico y observaciones.
- Envía → el registro queda en la BD.
Identificadores únicos
| Entidad | Código ejemplo | Nombre editable | En el QR |
|---|---|---|---|
| Módulo | MOD-001 |
PLP | No |
| Ubicación | UB-00001 |
T-72-1 | Sí (?u=UB-00001) |
Si se renombra un módulo o habitación, el QR impreso no requiere regenerarse.
Códigos QR
Desde el panel
Admin → Códigos QR
- Filtrar por módulo, búsqueda, solo pendientes
- Ver — modal con vista previa
- Descargar — PNG individual por ubicación
- ZIP masivo — todos los QR (respeta filtro de módulo)
- Seleccionar + Descargar — ZIP de ubicaciones elegidas
- Generar todos — ejecuta
generate_qrs.py(pide confirmación)
Desde terminal
# Primero exportar CSV desde el panel, o:
php -r "require 'config/config.php'; require 'config/database.php'; require 'includes/functions.php'; regenerateQrCsv(getDB());"
python3 generate_qrs.py
Formato de etiqueta
- Color QR:
#132A7C - Logo
NEM.pngcentrado - Pie:
Módulo | Habitación - Archivo:
output/Módulo_Habitación.png - Colisión de nombre: se añade el código (
…_UB-01121.png)
qr_data.csv se genera automáticamente desde la BD. No se versiona.
Base de datos
Base: mantenimiento_campamento
| Tabla | Descripción |
|---|---|
modulos |
Áreas del campamento |
ubicaciones |
Habitaciones, trailas, equipos (vinculadas a un módulo) |
empresas |
Contratistas |
servicios |
Tipos de servicio por empresa |
registros |
Actividades de mantenimiento registradas |
usuarios |
Accesos al panel admin |
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 # Gestión QR (vista, descarga, ZIP)
│ ├── download_qr.php # Descarga individual y masiva
│ ├── generate_qrs.php
│ └── export_qr.php
├── api/
│ ├── guardar.php # Guarda registro del formulario
│ └── servicios.php # JSON: servicios por empresa
├── assets/
│ ├── css/ # style.css, admin.css
│ └── js/ # formulario.js, admin.js, admin-qrs.js
├── config/
│ ├── config.php
│ ├── config.local.example.php
│ ├── config.production.example.php
│ └── database.php
├── includes/ # Header, auth, funciones, bootstrap
├── scripts/
│ └── prepare_deploy.sh # Preparar paquete de producción
├── sql/
│ ├── schema.sql
│ └── backup_produccion.sql
├── .htaccess # Seguridad Apache (producción)
├── formulario.php # Formulario público (entrada QR)
├── install.php # Instalador (solo APP_ENV=local)
├── generate_qrs.py # Generador PNG
├── NEM.png # Logo
└── output/ # QR generados (PNG, no versionar)
Seguridad
| Medida | Detalle |
|---|---|
APP_ENV=production |
Oculta errores PHP al usuario |
| Sesión HTTPS | Cookies Secure, HttpOnly, SameSite=Lax |
install.php |
Bloqueado en producción (403) |
.htaccess |
Bloquea acceso web a config/, sql/, includes/, .sql, .py, .csv |
| Admin | Requiere login; contraseñas con password_hash() (bcrypt) |
| Formulario | Público (sin login) |
Notas técnicas
- Zona horaria:
America/Hermosillo - Los POST del admin procesan datos antes de enviar HTML
- Codificación BD: UTF-8 (
utf8mb4) - Interfaz admin: español; confirmaciones bilingües ES/EN
Comandos rápidos
# Desarrollo local
php -S localhost:8080 -t .
# Preparar despliegue
./scripts/prepare_deploy.sh
# Generar QR (tras exportar CSV desde panel)
python3 generate_qrs.py
English summary
Web-based maintenance logging for a mining camp. QR codes at each location open a pre-filled form (module + room). Staff selects contractor and service type. Data in MariaDB, managed via password-protected admin at https://penasquitoapps.newmont.com/camp/mtto_record/. Stable IDs (UB-XXXXX) allow renaming without reprinting QR. Admin supports CRUD with delete confirmation, individual/bulk QR download, and PNG generation with brand color #132A7C and NEM.png logo.