AutoFiller_QR_Campamento/README.md

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, logo NEM.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 BD
  • qr_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

  1. Iniciar sesión (admin / admin123) y cambiar la contraseña en Usuarios.
  2. Admin → Códigos QR → Generar todos (PNG con URL de producción).
  3. 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 actualiza qr_data.csv.
  • Al eliminar una empresa se eliminan también sus servicios (CASCADE).

Flujo del técnico en campo

  1. Escanea el QR pegado en la ubicación.
  2. Se abre el formulario con módulo y habitación prellenados.
  3. Selecciona Empresa → aparecen los servicios de esa empresa.
  4. Opcional: nombre del técnico y observaciones.
  5. 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.png centrado
  • 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.