docs: README con arquitectura, instalación y rutas de CertiMine
Describe el flujo DC3, configuración, webhook y estructura del proyecto; incluye diagrama Mermaid y tablas para navegación rápida. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
parent
a72656f9d4
commit
b78a4955c7
1 changed files with 152 additions and 0 deletions
152
README.md
Normal file
152
README.md
Normal file
|
|
@ -0,0 +1,152 @@
|
||||||
|
# CertiMine
|
||||||
|
|
||||||
|
**Gestión de certificaciones y competencias DC3** 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 API DC3, 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 **API DC3**: el usuario introduce su **passport**; el sistema valida contra `penasquito.wotbi.com` y sincroniza competencias. Sin token DC3: 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]
|
||||||
|
DC3[API DC3 Wotbi]
|
||||||
|
end
|
||||||
|
U --> P
|
||||||
|
P --> DB
|
||||||
|
P --> DC3
|
||||||
|
```
|
||||||
|
|
||||||
|
1. **Sin token DC3:** los formularios usan datos de **semilla SQL** y **mock** de login.
|
||||||
|
2. **Con `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).
|
||||||
|
- **API DC3 (opcional):**
|
||||||
|
`export CERTIMINE_DC3_TOKEN='tu_token'`
|
||||||
|
o rellena `penasquito_dc3.static_token` (no subas secretos al repositorio).
|
||||||
|
- **`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 DC3, 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>
|
||||||
Loading…
Add table
Reference in a new issue