# BIX-IO · Fases 1 a 4 + flujo semanal y estado de resultados

Tableros de inteligencia de negocios sobre Dolibarr, con el copiloto BIXIO (este llega en la Fase 4).
PHP 7.2+ puro, MySQL 5.7+ / MariaDB 10.2+, sin frameworks y sin Node en el servidor.

## Qué incluye este sprint

| Pieza | Estado |
|---|---|
| Esquema propio `bixio` (configuración, reglas, presupuestos, roles, bitácora, fotografías) | Listo |
| Capa semántica: vistas `v_venta_linea`, `v_venta_pedido`, `v_cxc`, `v_cxp`, `v_cobro`, `v_banco_saldo`, `v_gasto_clasificado` | Listo |
| Configuración inicial para Pepusco (proveedores, cuentas, reglas de gasto, presupuestos) | Propuesta para validar |
| Acceso con usuario/contraseña de Dolibarr, roles, CSRF, bloqueo por intentos, bitácora | Listo |
| Resumen ejecutivo: cascada venta → utilidad real, índice de salud, 12 meses, proveedores, clientes | Listo |
| Corte de venta (réplica de los Excel de corte y semanal), con gasto presupuestado o registrado | Listo |
| Tesorería y cartera (réplica del reporte financiero): cuentas, CxP, CxC, cobertura, calendario | Listo |
| Salud de datos: 7 reglas con índice proporcional | Listo |
| Configuración (solo lectura) | Listo · edición en Sprint 2 |
| Fotografía diaria de saldos (`cli/snapshot.php`) | Listo |
| Conciliación contra Excel (`cli/reconciliar.php`) | Listo |
| Panel BIXIO | Interfaz lista · motor en Fase 4 |

## Conciliación con los Excel (datos del respaldo del 24-sep-2026)

Reporte semanal del 1 al 15 de septiembre:

| Concepto | Excel | BIX-IO | Coincidencia |
|---|---:|---:|---:|
| Venta | 233,482.64 | 231,932.70 | 99.3 % |
| Proveedores | 160,442.37 | 159,060.50 | 99.1 % |
| Margen total | 73,040.27 | 72,872.20 | **99.8 %** |
| Utilidad o pérdida | −11,959.73 | −12,127.80 | 101.4 % |

En el reporte financiero del 23 de septiembre, las próximas facturas por vencer coinciden al centavo. Son Pegaduro por $9,992.01 el 24-sep, Dumex por $12,710.21 el 12-oct y otros proveedores por $4,176.00 el 26-sep. El vencido de Pegaduro también cuadra: 49,573.96 − 9,992.01 = 39,581.95, porque la factura del 24-sep aún no vencía el día del corte.

La diferencia en el reparto Dumex/Pegaduro (±4 %) se debe a que el Excel asigna el proveedor manualmente. Queda como punto de la Fase 0.

## Instalación

### 1. Requisitos del servidor
PHP 7.2 o superior con las extensiones `pdo_mysql` y `mbstring`. Apache con `mod_rewrite`, o nginx.

### 2. Usuario de base de datos

```sql
CREATE USER 'bixio'@'localhost' IDENTIFIED BY 'una-clave-larga';
GRANT SELECT ON dolibarr.* TO 'bixio'@'localhost';   -- solo lectura sobre el ERP
GRANT ALL    ON bixio.*    TO 'bixio'@'localhost';   -- esquema propio de BIX-IO
FLUSH PRIVILEGES;
```

BIX-IO nunca escribe en las tablas de Dolibarr.

### 3. Código y configuración

```bash
cd /var/www && unzip bixio.zip && cd bixio
cp config/config.sample.php config/config.php     # ajustar credenciales, esquema, prefijo, empresa
chmod 640 config/config.php
chown -R www-data: storage
php cli/diagnostico.php                            # qué tableros funcionarán en esta instancia (solo lee)
php cli/install.php                                # esquema + vistas + configuración base
php cli/install.php --perfil pepusco               # …o además el perfil de un cliente (sql/perfiles_<cliente>.sql)
```

Otras opciones del instalador:
- `php cli/install.php --views` recrea solo las vistas. Úsalo después de actualizar Dolibarr.
- `php cli/install.php --no-seed` omite la configuración inicial.
- El instalador detecta los módulos de Dolibarr y elige la fuente de venta (pedidos o facturas); se cambia en Configuración → Instancia.

### 4. Servidor web (el DocumentRoot es `public/`)

Apache:

```apache
<VirtualHost *:443>
  ServerName bix.pepusco.mx
  DocumentRoot /var/www/bixio/public
  <Directory /var/www/bixio/public>
    AllowOverride All
    Require all granted
  </Directory>
  # SSLEngine on ... (certificado)
</VirtualHost>
```

nginx:

```nginx
server {
  server_name bix.pepusco.mx;
  root /var/www/bixio/public;
  location / { try_files $uri /index.php$is_args$args; }
  location ~ \.php$ { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass unix:/run/php/php7.2-fpm.sock; }
}
```

Si BIX-IO vive en una subcarpeta (por ejemplo `/bixio`), define `app.base_url = '/bixio'`.

### 5. Cron

```cron
50 23 * * * php /var/www/bixio/cli/snapshot.php >> /var/www/bixio/storage/logs/cron.log 2>&1
```

### 6. Accesos
Los administradores de Dolibarr entran con rol `direccion`. Para dar acceso a otros usuarios:

```sql
INSERT INTO bixio.bixio_user_role (login, rol) VALUES ('bryan arriaga', 'finanzas');
```

Roles disponibles:
- `direccion`: todas las pantallas.
- `finanzas`: todas excepto Configuración.
- `ventas`: Resumen y Corte.
- `lectura`: solo Resumen.

## Desarrollo local

```bash
php -S 127.0.0.1:8080 -t public public/router.php
npm install && npm run css        # solo si cambias estilos; el CSS compilado ya va incluido
```

Compatibilidad PHP 7.2 verificada con PHPCompatibility, además de una revisión manual de sintaxis 7.4+ y 8.x. No se usan propiedades tipadas, `fn`, `??=`, `match`, `str_contains` ni *nullsafe*.

## Estructura

```
public/        index.php (front controller), assets (CSS compilado, ECharts, Alpine, fuentes y logos locales)
app/Core/      Config, Db, Session, Csrf, Auth, Audit, Periodo, View
app/Metrics/   Ventas, Gastos, Tesoreria, CalidadDatos, Salud   ← aquí se conectarán las herramientas de BIXIO
app/Reports/   Corte
app/Http/      controladores
app/Views/     plantillas
sql/           01_schema, 02_views, 03_seed_pepusco
cli/           install, reconciliar, snapshot
```

Todos los assets se sirven localmente: no hay CDN y el sistema funciona sin salida a internet. Solo el copiloto la necesitará.

## Fase 2 · Reemplazo de los Excel

| Pieza | Estado |
|---|---|
| Exportación a Excel con el formato de los tres reportes actuales (corte, semanal, financiero) | Listo |
| Fórmulas vivas en todos los totales; hojas de detalle con cada pedido o factura | Listo |
| Celdas de captura (amarillas) solo para lo que Dolibarr no registra | Listo |
| Reporte financiero "al corte": documentos y pagos capturados hasta la fecha elegida | Listo |
| Lectura rápida para dirección (reglas) en Corte y Tesorería, y con fórmulas dentro del Excel | Listo |
| Imprimir o guardar PDF desde cada tablero (`?imprimir=1`) | Listo |
| Conciliación paralela: capturar cifras del Excel manual y comparar | Listo |
| Exportación por consola para envíos programados (`cli/exportar.php`) | Listo |
| Generador XLSX propio: funciona con o sin la extensión `zip` de PHP | Listo |

Verificación: los tres archivos se recalcularon en LibreOffice con 0 errores (709 fórmulas).

Resultados al conciliar contra los Excel reales:

- **Cuentas por pagar al 23-sep:** $229,730.47, coincide al centavo. Por proveedor, próxima factura y vencido de Pegaduro también son exactos.
- **Vencido total:** difiere exactamente $4,900. Es una sola factura de "Público en General" que vencía el 21-sep y sigue abierta en Dolibarr.
- **Cartera del mes:** difiere 15 %. El Excel asigna a Pegaduro $50.9k que en Dolibarr son productos de categoría Dumex, o facturas sin proveedor. Es una decisión de criterio de la Fase 0.
- **Semanal:** el margen coincide al 99.8 %.

Exportar por consola:

```bash
php cli/exportar.php corte      2026-09-01 2026-09-15 /ruta/salida
php cli/exportar.php semanal    2026-09-01 2026-09-15 /ruta/salida
php cli/exportar.php financiero 2026-09-23            /ruta/salida
```

Instalar o actualizar: `php cli/install.php` es idempotente y agrega la tabla `bixio_conciliacion` y las vistas `v_factura_costo` y `v_cobro_aplicado` (esquema v2).

## Fase 3 · Finanzas y operación ampliada

**Decisión aplicada:** el proveedor lo define la **categoría del producto**. Queda registrado en `bixio_setting.criterio_proveedor`. El almacén del pedido solo es respaldo en ventas para productos sin categoría.

| Pieza | Estado |
|---|---|
| Análisis de ventas por cliente, producto, proveedor, vendedor (comercial asignado al cliente), almacén, mes y día; filtros, comparativo y Excel | Listo |
| Gastos: tendencia de 12 meses contra presupuesto, salidas por categoría, bandeja de clasificación con sugerencias por similitud y creación de reglas | Listo |
| Inventario: valor a costo, días de inventario, rotación por proveedor, dinero detenido, cobertura de lo más vendido, existencias negativas | Listo |
| Reparto del dinero en cuentas (proveedor / propio / por conciliar) con reglas por cuenta y tope en lo que se debe a cada proveedor | Listo |
| El Excel financiero prellena las celdas amarillas con ese reparto | Listo |
| Importador de estados de cuenta CSV con detección de columnas y conciliación automática contra Dolibarr | Listo |
| Productos sin proveedor: sugerencia con evidencia; asignación en Dolibarr por API REST o lista descargable | Listo |
| Configuración editable: parámetros, proveedores, cuentas, reglas, categorías, presupuestos, accesos y prueba de API | Listo |
| Histórico reconstruido día por día (`cli/snapshot.php --desde`) y gráfica de cartera y pagos | Listo |
| Salud de datos: 9 reglas (se agregan saldo por conciliar y existencias negativas) con acceso directo para resolverlas | Listo |

### Actualizar a la Fase 3

```bash
php cli/install.php                          # esquema v3: bixio_setting, bancos, vistas de vendedor e inventario
php cli/snapshot.php --desde 2026-06-01      # reconstruye el histórico (una sola vez, ~1 min por trimestre)
chown -R www-data: storage                   # storage/tmp guarda los CSV mientras se revisan
```

Para asignar proveedores desde BIX-IO:
1. Activa en Dolibarr el módulo **API REST**.
2. Crea un usuario técnico con permisos de productos y categorías.
3. Guarda `dolibarr.url` y `dolibarr.api_key` en `config.php`.
4. Pruébalo en Configuración → API de Dolibarr.

BIX-IO solo escribe en Dolibarr por la API oficial.

### Hallazgos con los datos del respaldo

- **Inventario:** $210,509 (61 % del inventario, 193 productos) no se ha vendido en 90 días. Hay 32 existencias negativas.
- **Productos sin proveedor:** 273 productos con $617,952 de venta en 12 meses no tienen categoría. BIX-IO sugiere proveedor para 91 de ellos, que suman $597,522 de esa venta; por ejemplo, Imperubber, con $197k vendidos, 98 % desde el almacén Pegaduro.
- **Dinero en cuentas:** de $1.43 M, $186k se estiman de proveedores y $57k propios. Hay $1.19 M por conciliar, casi todo en HSBC, que no se explican con cobros ni con deudas a proveedores. La holgura de pagos ya no cuenta ese saldo.
- **Cartera de septiembre:** la diferencia contra el Excel (Pegaduro $50.9k contra $1,961) **no** la explican ni la categoría ni el almacén del pedido. Hay que revisarla con quien arma el Excel.
- **Vendedor:** todos los pedidos los captura un usuario, así que el vendedor se toma del comercial asignado al cliente. 12 % de la venta es de clientes sin comercial.

## Fase 4 · Copiloto BIXIO

| Pieza | Estado |
|---|---|
| Proveedores de IA intercambiables: Anthropic (Claude), OpenAI (GPT), Google (Gemini) y modo demostración sin IA | Listo |
| Elección de proveedor y modelo en Configuración → BIXIO (IA); selector en el chat si hay más de uno | Listo |
| 12 herramientas sobre las métricas existentes; el modelo nunca escribe SQL y cada herramienta respeta el rol | Listo |
| Chat lateral: respuestas con formato, gráficas dentro de la conversación, "Consultó: …" en cada respuesta, historial y preguntas sugeridas por pantalla | Listo |
| Bitácora de preguntas, herramientas usadas, tiempos y tokens; consumo del mes por modelo; límite diario por usuario | Listo |
| Pruebas de los adaptadores (`php tests/test_llm.php`, 22 casos) y batería de evaluación (`php cli/bixio_eval.php`) | Listo |
| Sidebar colapsable con botón de hamburguesa: solo íconos, nombre al pasar el mouse, preferencia recordada | Listo |
| Etiqueta configurable ("Etiqueta (proveedor)" para este cliente) y nueva dimensión "Proveedor (compras)" desde facturas de proveedor | Listo |

### Etiqueta contra proveedor
- **Etiqueta.** Es la categoría de producto en Dolibarr que agrupa el análisis. Su nombre en pantalla se configura: este cliente la ve como "Etiqueta (proveedor)"; otra empresa puede llamarla "Línea" o "Marca".
- **Proveedor (compras).** Sale de la última factura de proveedor de cada producto, o de su precio de proveedor. Sirve en instalaciones donde la etiqueta no es un proveedor.
- **Interruptor "La etiqueta identifica al proveedor"** (Configuración → Parámetros). Decide qué se usa para repartir el dinero en cuentas y para el tope por deuda.
- **Margen.** Siempre es venta menos el precio de compra de cada línea, sin importar la etiqueta.

### Activar BIXIO
1. Agrega al menos una llave en `config/config.php` (`llm.anthropic.api_key`, `llm.openai.api_key` o `llm.gemini.api_key`) o en las variables `BIXIO_ANTHROPIC_KEY`, `BIXIO_OPENAI_KEY` o `BIXIO_GEMINI_KEY`.
2. Corre `php cli/install.php`. Crea las tablas del chat (esquema v4).
3. En Configuración → BIXIO (IA), elige proveedor y modelo y usa **Probar conexión**.
4. Corre `php cli/bixio_eval.php` con ese proveedor. Libéralo al equipo solo si la cifra correcta llega al 90 % o más.

El servidor necesita salida HTTPS a `api.anthropic.com`, `api.openai.com` o `generativelanguage.googleapis.com`, según el proveedor.

Modelos preconfigurados (los nombres se pueden cambiar en `config.php` sin tocar código):

| Proveedor | Recomendado | Rápido y económico | Máxima capacidad |
|---|---|---|---|
| Anthropic | Claude Sonnet 5 | Claude Haiku 4.5 | Claude Opus 5.5 |
| OpenAI | GPT-6 Sol | GPT-6 Luna | GPT-6 Astra |
| Gemini | Gemini 3.5 Flash | — | Gemini 3.1 Pro (vista previa) |

### Detalles de integración
- **Gemini 3.x.** Exige devolver sin cambios las firmas de pensamiento de sus llamadas a funciones, y cada `functionResponse` debe llevar el `id` de su llamada. El adaptador lo hace y está cubierto por las pruebas.
- **Historial.** Entre preguntas se envía solo el texto de los turnos anteriores. Las llamadas a herramientas viven únicamente dentro del turno en curso. Así se puede cambiar de proveedor sin conflictos y se ahorran tokens.
- **Sin streaming.** La respuesta llega completa, con un indicador de progreso mientras BIXIO consulta.

## Reporte financiero general y flujo semanal

Basado en las plantillas "Funcionamiento financiero general" y "Registro de seguimiento de flujo de efectivo".

### Estado de resultados (Tableros → Estado de resultados)
- **Ingresos (sin IVA):** ventas facturadas y ventas sin factura ("mostrador"), a partir de los pedidos validados.
- **Costos:** costo de la mercancía (precio de compra de cada línea) y mano de obra.
- **Gastos:** cada categoría de gasto se asigna a una línea del formato (nómina, renta, servicios, publicidad, pago de deudas, IMSS, otros) en Configuración → Reglas de gasto.
- **Resultado:** % de cada concepto sobre ventas, comparativo con el periodo anterior y utilidad antes de ISR. El % de utilidad es el máximo repartible en bonos y comisiones.
- **Excel:** mismo formato que la plantilla, con fórmulas.
- **Nota sobre la plantilla original:** el total de ingresos está capturado a mano como $125,000, pero la suma de sus renglones es $120,000. En BIX-IO todos los totales son fórmulas.

### Flujo de efectivo semanal (Tableros → Flujo semanal)
- **Periodo:** semanas de lunes a domingo. Proyección de 8, 13 o 26 semanas o el resto del año; semanas pasadas: 4, 8, 13 o 26, o desde enero.
- **Semanas pasadas:** real contra presupuesto. El presupuesto de cada semana se **congela al iniciar** (`cli/snapshot.php`); las semanas anteriores a BIX-IO se reconstruyen con lo capturado en Dolibarr al inicio de cada una.
- **Cobranza de cartera:** se proyecta con los **días que cada cliente suele tardar en pagar** (últimos 12 meses). En este Dolibarr casi todas las facturas tienen plazo de 1 día y no sirve la fecha de vencimiento; la opción por vencimiento está disponible para otras instalaciones.
- **Cartera vencida:** la de hasta 60 días se reparte en las primeras 4 semanas; la más atrasada se reporta como cartera en riesgo y no se proyecta.
- **Pagos a proveedores:** por fecha de vencimiento; lo vencido cae en la semana en curso.
- **Conceptos presupuestados:** semanales, quincenales, mensuales o únicos, con ajuste por celda (clic en la cifra). Lo real de cada concepto se mide con las categorías de gasto que se le asignen.
- **Cobros de ventas nuevas:** se sugieren con la **mediana** de las últimas 8 semanas, para que cobros extraordinarios no la inflen.
- **Saldo inicial:** por defecto el verificable (excluye lo por conciliar).
- **Excel:** formato de la plantilla (SEM 1…n en bloques de 4 con TOTAL y GRAN TOTAL, cobranza por cliente con fecha de pago y retraso, flujo acumulado con fórmulas), más una hoja de presupuesto contra real.
- **BIXIO:** dos herramientas nuevas, `flujo_semanal` y `estado_resultados`.

Instalar o actualizar: `php cli/install.php` (esquema v5). El cron diario de `cli/snapshot.php` congela el presupuesto de la semana en curso.

## Varias instancias de Dolibarr

Ver **[docs/GUIA_PERSONALIZACION.md](docs/GUIA_PERSONALIZACION.md)**: qué averiguar en cada cliente, qué tableros aplican por tipo de empresa y qué falta en el núcleo.

- **`cli/diagnostico.php`.** Antes de instalar revisa versión, módulos, tablas y columnas por tablero, volumen y calidad de captura.
- **Configuración base + perfil.** `sql/03_seed_base.sql` sirve a cualquier Dolibarr; `sql/perfiles_<cliente>.sql` guarda las decisiones de cada cliente.
- **Configuración → Instancia.**
  - Fuente de venta: pedidos validados, o facturas validadas con notas de crédito en negativo y TakePOS como mostrador.
  - Costo de respaldo: si la línea no trae precio de compra, se usa el costo del producto.
  - Tableros visibles y perfiles de arranque (distribución, solo facturación, comercio, manufactura).
- **Tableros por módulo.** Cada tablero declara el módulo de Dolibarr que necesita y se oculta solo si no está activo.
- **Lectura rápida redactada por BIXIO.** Corte y Tesorería. Cada cifra se verifica contra el cálculo por reglas, la redacción se reutiliza mientras las cifras no cambien, y sin IA o ante un error se muestran las reglas.

Pruebas: `php tests/test_llm.php` (adaptadores de IA) y `php tests/test_lectura.php` (verificación de cifras de la lectura).

## Presupuesto por categoría (fuente única)

- **Fuente única.** Configuración → Presupuestos tiene una fila por categoría: ventas por etiqueta, préstamos y otros ingresos, pagos a proveedores y cada categoría de gasto (incluidas las categorías bancarias de Dolibarr si el cliente las usa).
- **Nada se precarga.** Los montos del Excel de ejemplo que se habían cargado se eliminan al actualizar con `cli/install.php`.
- **Una sola captura para todo.** Gastos, Corte, Estado de resultados y Flujo semanal leen de ahí.
  - En reportes por periodo el monto se prorratea; una quincena es la mitad del mes.
  - En el flujo cae en la fecha de su frecuencia.
- **Sin presupuesto capturado,** el Corte usa lo registrado en Dolibarr y lo dice.
- **Estado de resultados** por categorías de Dolibarr: ventas y costo por etiqueta, servicios comprados por proveedor, gastos por categoría y pago de deudas.
- **Flujo semanal** por categoría, con explicación del saldo proyectado (saldo en bancos − por conciliar) y desglose por cuenta.
- **IA.**
  - OpenAI usa la API Responses (`/v1/responses`, sin retención), requerida por los modelos GPT-6 con herramientas.
  - Gemini ya no rechaza llamadas sin argumentos.

## Siguiente (Fase 5)
1. Alertas proactivas nocturnas redactadas por BIXIO; resumen matutino por correo o WhatsApp.
2. Proyección de flujo de efectivo a 15 y 30 días.
3. Respuestas en streaming y consulta avanzada controlada sobre las vistas `bixio`.
4. Instalador multi-cliente para replicar BIX-IO en otras instalaciones de Dolibarr.