305 lines
9.8 KiB
Markdown
305 lines
9.8 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 + 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.
|
||
- Importa **2 518 ubicaciones** desde `data.csv` (archivo original del proyecto).
|
||
- 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
|
||
├── generate_qrs.py # Generador de etiquetas PNG
|
||
├── data.csv # Datos originales (importación inicial)
|
||
├── qr_data.csv # URLs actuales para QR
|
||
├── 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**
|
||
- **2 518 ubicaciones**
|
||
- **2 518 códigos QR** (1 duplicado de nombre en origen: Trailas T9-1)
|
||
|
||
---
|
||
|
||
## Migraciones SQL adicionales
|
||
|
||
Si actualiza desde una versión anterior:
|
||
|
||
```bash
|
||
mysql -u root -p mantenimiento_campamento < sql/migrate_empresas.sql
|
||
mysql -u root -p mantenimiento_campamento < sql/migrate_usuarios.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
# 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.
|