375 lines
12 KiB
Markdown
375 lines
12 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
./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:**
|
|
|
|
```bash
|
|
cp config/config.production.example.php config/config.production.php
|
|
# Editar credenciales MariaDB del entorno Newmont
|
|
```
|
|
|
|
### 3. Importar base de datos
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|