certimine/README.md
remaster ff0fd6a89d API Peñasquito: ticket persistente, company y mejor flujo de búsqueda
- Renombrado «DC3» a «API Peñasquito» (URL base del documento) en UI/docs;
  rutas y claves de config conservadas por compatibilidad.
- Persistencia de ticket_id en nueva tabla `penasquito_tickets`:
  POST /search/ guarda el ticket y los siguientes requests retoman
  GET /result/<ticket_id>/ sin reencolar.
- Polling acotado por request HTTP (~6 s) con `PenasquitoPendingException`
  y caja «reintentar» en lookup; ticket queda válido 1 h.
- `users_cache.company` nuevo (con migración idempotente); persistResult
  guarda empresa + competencias en transacción y aplica source distinto.
- Mensajes HTTP específicos (400/401/403/404/408/429/5xx) y `/` final
  forzado en rutas (DRF), FOLLOWLOCATION habilitado.
- Vista de perfil muestra «Empresa» y aviso cuando no hay competencias.
- Auth::login evita doble fetch cuando ya tenemos el `result` del API.
- i18n ES/EN actualizados; lookup_pending_*; limpieza de archivos lang.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-13 19:43:37 -06:00

155 lines
5.4 KiB
Markdown

# CertiMine
**Gestión de certificaciones y competencias** para el contexto **Newmont Peñasquito**.
Portal **bilingüe (ES / EN)**, backend en **PHP** y datos en **MariaDB**.
---
## Qué hace la aplicación
| Área | Descripción |
|------|-------------|
| **Biblioteca FRM** | Listado público de estándares FRM y vínculos con competencias NOM (solo consulta). |
| **Consulta rápida** | Búsqueda por número de empleado, ID de contratista o **passport** (p. ej. `E000055821`). Puede leer datos locales o, si está configurado el token del **API en la URL base del documento** (Wotbi), consultar en tiempo real y guardar en base. |
| **Perfil público** | Certificaciones, autorizaciones FRM (contratistas) e indicador de **licencia verde**. Enlace tipo QR con firma opcional (`qr_enforce` en config). |
| **Inicio de sesión** | Con ese **API** configurado, el usuario introduce su **passport**; el sistema valida contra `penasquito.wotbi.com` y sincroniza competencias. Sin token: modo **mock** para demostración. |
| **Panel (dashboard)** | Certificados del usuario y **cursos sugeridos** según competencias NOM válidas. |
| **Webhook** | `POST` para sincronizar certificados / autorizaciones desde otros sistemas (eventos idempotentes). |
---
## Flujo de datos (resumen)
```mermaid
flowchart LR
subgraph web [Navegador]
U[Usuario]
end
subgraph cert [CertiMine PHP]
P[public/index.php]
DB[(MariaDB)]
end
subgraph ext [Servicios]
PQ[API Peñasquito (documento / Wotbi)]
end
U --> P
P --> DB
P --> PQ
```
1. **Sin token del API (documento):** los formularios usan datos de **semilla SQL** y **mock** de login.
2. **Con `CERTIMINE_PENASQUITO_TOKEN` (o alias `CERTIMINE_DC3_TOKEN`):** búsqueda y login usan el API REST (token estático `Authorization: Token …`, búsqueda por passport y *polling* de tickets si aplica).
3. Los resultados se pueden **persistir** en tablas `users_cache`, `certificates`, `contractor_authorizations`.
---
## Requisitos
- PHP 8.x con extensión **pdo_mysql** y **curl**
- **MariaDB** o MySQL 8
- Servidor web con **document root** en `public/` (Apache, Nginx o `php -S`)
---
## Instalación rápida
### 1. Base de datos
```bash
mysql -u root -p < sql/schema.sql
mysql -u root -p < sql/seed.sql
```
Ajusta usuario y contraseña si no usas el ejemplo del proyecto.
### 2. Configuración
```bash
cp config/config.example.php config/config.php
```
Edita `config/config.php`:
- **`db`**: host, nombre de base, usuario y contraseña.
- **`app.public_url`**: URL pública del sitio (para enlaces y QR).
- **Token del API (URL base del documento) — orden:**
1) `CERTIMINE_PENASQUITO_TOKEN`
2) `CERTIMINE_DC3_TOKEN` (alias)
3) `penasquito_dc3.static_token` en `config.php` (sección que agrupa también `base_url` y rutas del PDF)
4) **`config/token.php`** (copia de `config/token.example.php`; **no se sube a git**).
Documentación del proceso sin secretos: **`docs/DatosPdf.example.txt`**. Tu copia local **`DatosPdf.txt`** puede quedar fuera de git (véase `.gitignore`).
- **`mobiliseme.mock`:** `true` para demo sin API legacy JWT; `false` solo si usas otro backend configurado en `mobiliseme`.
### 3. Servidor de desarrollo
```bash
cd public
php -S 127.0.0.1:8080
```
Abre `http://127.0.0.1:8080/index.php?r=home`.
Con **Apache**, el archivo `public/.htaccess` redirige al front controller.
---
## Rutas principales
Todas pasan por `public/index.php` con el parámetro **`r`**:
| `r` | Uso |
|-----|-----|
| `home` | Inicio |
| `frm-library` | Biblioteca FRM |
| `lookup` | Consulta empleado / contratista / passport |
| `profile` | Perfil público (`id`, `sig` opcional según config) |
| `login` / `logout` | Sesión |
| `dashboard` | Panel (requiere sesión) |
| `api-docs` | Texto de documentación del API (markdown servido como plano) |
**Webhook:** `public/api/webhook.php` (JSON; firma opcional con `X-Certimine-Signature`).
**Mantenimiento:** `php bin/recompute_green.php` — recalcula licencias verdes en lote.
---
## Documentación del API externo
- Resumen en [**docs/mobiliseme-api.md**](docs/mobiliseme-api.md)
- Detalle operativo también en **DatosPdf.txt** (extracto del proceso Mobilise-Me / scraping).
---
## Estructura del proyecto
```
certimine/
├── public/ # Web pública (index.php, webhook, .htaccess)
├── src/ # PHP (Auth, repositorios, cliente API Peñasquito, etc.)
├── views/ # Plantillas HTML + Bootstrap 5
├── lang/ # Cadenas ES / EN
├── config/ # config.example.php (plantilla); config.php local ignorado por git)
├── sql/ # Esquema y datos semilla
├── docs/ # Documentación API
└── bin/ # Scripts CLI
```
---
## Seguridad (notas)
- No commitear **`config/config.php`** ni tokens; usar variables de entorno cuando sea posible.
- En producción: HTTPS, `cookie_secure` según tu despliegue, y **`qr_enforce = true`** si los enlaces de perfil deben ir siempre firmados.
- El token de ejemplo en documentos históricos debe sustituirse por secretos reales en el servidor.
---
## Licencia y contexto
Proyecto **CertiMine / Penasquito**. Ajusta licencia y contacto según la política de tu organización.
---
<p align="center">
<sub>CertiMine · PHP · MariaDB · Bootstrap 5</sub>
</p>