AutoFiller_QR_Campamento/README.md

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.