# ERP COTENI – Administración General V1.1 Operativa

Plataforma web en **PHP 8.2+ y MySQL 8** diseñada para comenzar la operación administrativa de COTENI y generar cultura de uso antes de una migración futura a Laravel.

## Qué integra esta versión

### Núcleo y catálogos maestros
- Empresas/unidades.
- Áreas, departamentos y puestos.
- Colaboradores.
- Clientes y proveedores.
- Proyectos y centros de costo.
- Categorías de gasto.
- Monedas e impuestos.
- Bancos y formas de pago.
- Usuarios, roles, permisos y bitácora.
- Folios automáticos por año y tipo de transacción.

### Flujo de compra completo

`REQ → autorización → cotizaciones → comparativo → proveedor seleccionado → OC → recepción → factura proveedor → validación → CxP → autorización de pago → pago → cierre`

Incluye:
- Validación de presupuesto disponible.
- Presupuesto autorizado / comprometido / ejercido / disponible.
- Reglas de autorización configurables por proceso, importe, área, nivel, rol o usuario.
- Cotizaciones y comparación.
- Recepciones parciales/completas.
- Validación básica de tres vías: OC + recepción + factura.
- Creación automática de CxP desde factura validada.
- Programación y autorización de pagos.
- Evidencia bancaria.

### Facturación y cuentas por cobrar

`Servicio terminado → solicitud de facturación → factura → CxC → cobros parciales/totales → complemento → cierre`

### Activos + RH
- Las partidas de compra marcadas como activo generan altas preliminares al recibirse.
- Asignación de activo a colaborador.
- Resguardo documental.
- Devolución y condición de retorno.
- Baja de colaborador bloqueada si conserva activos asignados.
- Checklist administrativo de alta/cambio/baja.

### Contratos
- Contratos de cliente/proveedor y otras vigencias.
- Días de alerta configurables.
- Renovación manual/automática como dato de control.
- Alertas por vencimiento.

### Viáticos
`Solicitud → autorización → anticipo → comprobación → diferencia → cierre`

### Expediente documental
Cada operación puede relacionar documentos sin recapturar la operación: cotizaciones, OC, facturas, evidencias, resguardos, complementos, contratos y otros soportes.

### Alertas y notificaciones
- Contratos próximos a vencer.
- CxP vencidas.
- CxC vencidas.
- Presupuestos excedidos.
- Activos asignados sin resguardo.
- Nuevas autorizaciones.
- Centro interno de notificaciones.
- Cola de correo mediante `mail()` de PHP cuando el servidor tenga correo saliente configurado.

### BI / Dirección
- Presupuesto.
- Gasto.
- CxP / CxC.
- Pendientes de autorización.
- Contratos por vencer.
- Riesgos.
- Gasto por área.
- Gasto por proyecto.
- Compras por proveedor.
- Gasto por periodo.

### PWA
Incluye `manifest.json` y `service worker`; puede instalarse desde un navegador compatible como aplicación en Windows/macOS. Para instalación PWA real en producción debe usarse HTTPS.

### API
API inicial con token Bearer:
- `GET api/index.php?resource=dashboard`
- `GET api/index.php?resource=purchase_requests`
- `GET api/index.php?resource=payables`
- `GET api/index.php?resource=receivables`
- `GET api/index.php?resource=assets`
- `GET api/index.php?resource=areas`
- `GET api/index.php?resource=suppliers`
- `POST api/index.php?resource=purchase_requests`

Los tokens se generan desde **API e integraciones** como superadministrador.

## Instalación limpia

1. Copia la carpeta a Apache/Nginx.
2. Copia `config/config.example.php` como `config/config.php`.
3. Configura la conexión MySQL y `base_url`.
4. Da permisos de escritura a `storage/uploads`. Los archivos nuevos se guardan fuera de `public` y se sirven mediante una ruta autenticada.
5. Ejecuta `php public/install.php` por consola, definiendo antes `COTENI_ADMIN_PASSWORD` con una contraseña de al menos 12 caracteres. El instalador web está bloqueado.
6. Usuario inicial:
   - `admin@coteni.local`
   - Contraseña definida en `COTENI_ADMIN_PASSWORD`.
7. Cambia la contraseña.
8. Elimina o renombra `install.php`.

## Actualización desde la V1 anterior

1. Haz respaldo completo de la base de datos, `public/uploads` (V1 anterior) y `storage/uploads` (V1.1).
2. Sustituye el código por V1.1 Operativa conservando tu `config/config.php` y archivos subidos.
3. Accede por consola al servidor con una cuenta autorizada.
4. Ejecuta `php public/upgrade.php` una sola vez. La actualización web está bloqueada.
5. Valida la operación.
6. Elimina o renombra `upgrade.php`.

> Si la V1 todavía no tiene datos productivos, es preferible una instalación limpia de V1.1.

## Correo

En `config/config.php`:

```php
'mail' => [
    'enabled' => false,
    'from' => 'no-reply@coteni.local',
],
```

La V1.1 utiliza la función `mail()` de PHP. Para correo real, configura Postfix/relay del servidor o mantenlo desactivado. En la migración a Laravel se recomienda SMTP mediante Laravel Mail.

## Alertas programadas

Configura una clave fuerte en `cron_key` y ejecuta cada hora o cada día:

```bash
php /ruta/erp/public/cron.php TU-CLAVE-CRON
```

El proceso:
- actualiza vencimientos;
- genera notificaciones sin duplicarlas durante el mismo día;
- procesa la cola de correo si está activada.

## Antes de declarar producción definitiva

Aunque esta versión implementa el flujo funcional, para una operación corporativa formal realiza primero:
- respaldo probado de MySQL y uploads;
- HTTPS;
- revisión de permisos por rol;
- cambio de credenciales iniciales;
- pruebas de recuperación;
- política documental;
- pruebas de usuario y aceptación;
- revisión de seguridad del servidor;
- validación fiscal/contable de los procesos que se decida automatizar.

## Evolución a Laravel

La base se diseñó para conservar los conceptos principales. La migración futura debería convertir:
- servicios PHP → Services/Actions Laravel;
- roles/permisos → Middleware/Policies;
- validaciones → Form Requests;
- archivos → Laravel Storage;
- eventos → Events/Listeners/Queues;
- notificaciones → Laravel Notifications/Mail;
- API → Sanctum;
- módulos → Controllers + Eloquent Models.

La experiencia y los flujos del usuario pueden mantenerse, reduciendo el impacto cultural de la migración.

### Caja chica
- Fondos de caja por responsable.
- Saldo inicial, saldo disponible y límite autorizado.
- Entradas, salidas y reembolsos.
- Folio automático `CAJ-AAAA-######`.
- Comprobante y bitácora de movimientos.

## Correcciones de seguridad e integridad — septiembre 2026

Consulta `CORRECCIONES_SEGURIDAD.md` para el detalle y las pruebas. Requisiciones y gastos requieren partida presupuestal suficiente. Las cotizaciones mayores al importe autorizado vuelven a autorización. Los módulos operativos se modifican exclusivamente desde sus flujos integrados.

Los formularios de operación vencen a las dos horas y no pueden reutilizarse tras una operación exitosa. Recarga las páginas abiertas antes de la actualización.

## Recuperación excepcional de contraseña

Desde el inicio de sesión, selecciona **Olvidé mi contraseña**. La pantalla requiere el correo de un superadministrador activo, una clave temporal y la nueva contraseña (mínimo 12 caracteres). No crea usuarios ni cambia sus roles.

Para emitir una clave temporal desde una consola autorizada del servidor:

```bash
php tools/create_admin_recovery.php
```

La clave vence a las 24 horas y queda consumida tras restablecer la contraseña. Emitir otra reemplaza la anterior. El archivo `storage/maintenance/admin_recovery_token.json` contiene únicamente su hash; el proceso PHP necesita permisos de lectura y escritura sobre él. Si falla la confirmación de la base de datos después de consumir la clave, genera otra desde consola.
