# Contexto de negocio para changelog IA (MBInventario)

## Proposito
Este archivo define como debe interpretar la IA los cambios de MBInventario para generar changelog utiles para:
- Operacion (usuarios no tecnicos)
- Gerencia (resumen ejecutivo)
- Equipo tecnico (bitacora forense)

La IA debe priorizar impacto real en operacion diaria y evitar lenguaje de codigo cuando la audiencia no es tecnica.

## Dominio del sistema
MBInventario administra inventario y operacion comercial de tiendas y bodegas.
Procesos principales:
- Entradas y salidas de inventario
- Traslados entre tiendas/bodegas
- Recepcion de traslados
- Compras y ventas vinculadas a inventario
- Documentos (facturas, notas, recibos y tipos de documento)
- Reporteria operativa y gerencial

## Audiencias y lenguaje esperado
### Operacion
- Lenguaje simple, orientado a "que debo hacer distinto".
- Evitar frases tecnicas como "query", "controller", "refactor".
- Decir explicitamente si no hay cambio visible para usuario.

### Gerencia
- Hablar de impacto: control, riesgo, continuidad, consistencia de datos, velocidad operativa.
- No listar detalles de implementacion.

### Tecnico
- Ser preciso: modulo, tipo de ajuste, riesgo y posibles sintomas.
- Mantener trazabilidad (PR/merge/archivos/commits).

## Modulos y conceptos clave
- Catalogos: productos, proveedores, vendedores, tipos de documento, tiendas.
- Documentos: ingreso, edicion, validaciones, anulaciones, trazabilidad.
- Inventario: existencias, movimientos, costo, conciliacion.
- Reportes: ventas, compras, utilidad, existencias, traslados, comparativos.
- Interfaz: vistas, formularios, filtros, tabla dinamica, modales.

Terminos frecuentes:
- "Existencia": stock disponible por tienda/bodega.
- "Trazabilidad": relacion entre movimientos y documentos origen/destino.
- "Conciliacion": comparacion entre reporte y transaccion real.
- "Costo": criterio de valor para existencia/utilidad (impacta reportes y cierres).

## Las areas y pantallas que EXISTEN (lista cerrada)

⚠️ Agregado el 17-ago-2026. Mas arriba ya decia "prohibido inventar pantallas, campos,
modulos" — pero no habia contra que comparar, asi que la IA tomaba el nombre del
archivo cambiado y lo presentaba como area de negocio. En la version 5793 salio "area
con mayor impacto operativo: Parameters Defaults", con Riesgo Alto. Eso es un archivo
de configuracion, no un area.

**Si el area no esta en esta lista, no se nombra un area: se dice que el cambio es
interno.** El nombre tecnico va entre parentesis solo para reconocerlo, nunca para
mostrarlo.

- **Operacion del punto de venta**: Cuadre Diario (`CuadreDiario`), Cierres, Caja y
  correlativos (`Maecaj`, `CajaCorrelativos`, `OpcionCaja`), Formas de pago
  (`FormasPago`), Tiquetes, Documentos (`Maedoc`, `Documento`).
- **Inventario**: Producto (`Producto`, `Maeart`), Fisico (`Fisico`), Traslados
  (`Traslado`, `TrasladoEnTransito`), Minimos y maximos (`MinimosMaximos`), Categorias,
  lineas y marcas (`Categorias`, `Maelin`, `Maemar`), Produccion
  (`ProduccionMaestro`).
- **Compras y proveedores**: Pedidos a proveedor y cotizaciones (`PedidoProveedor`),
  Proveedores (`Maepro`), Ofertas (`Maeofe`), Listas de precios (`Listaprecios`,
  `ListaPreciosMayoreo`), Back order (`BackOrder`).
- **Ventas y clientes**: Pedidos (`Maeped`, `DisplayPedido`), Clientes (`Maecli`),
  Vendedores (`Maeven`), Cupones (`Maecup`), Rutas y motoristas (`Maerutas`,
  `Maemotorista`), Manifiesto, Credito y cobros (`Maepago`,
  `LimiteClienteDiasCorte`).
- **Reportes y consultas**: Reportes (`Reporte`, `Reportes`, `ReporteAjax`,
  `WebReporte`), Consultas (`Consultas`), Dashboard, Formatos y formulas (`Formatos`,
  `FormulasVariablesMaestro`).
- **Facturacion electronica (FEL)**: Emisores y cuotas (`Maeemi`, `ParametrosMaeemi`),
  Frases FEL (`FelFrases`).
- **Administracion**: Administracion (`Administracion`), Usuarios (`Maeusr`), Tiendas
  (`Maetie`), Procesos, Diccionario (`Dic`).
- **Avisos**: Mensajitos (`Mensajitos`, `MensajitosTelefonos`, `MensajitosTipos`).
- **Integraciones**: API (`Api`, `ParametrosApi`, `WebServices`), Carrusel
  (`Carrusel`), Videos.
- **POSTouch**: Mapa y teclado (`TouchMapa`, `TouchTeclado`), Comandas
  (`ParametrosComandasPapeleta`, `ParametrosComandasResumen`), Cocineros
  (`Maecocinero`).

### Lo que NO es un area ni una pantalla

Nada de esto va como "area con mayor impacto" ni como "pantalla a revisar":

- **Configuracion**: `app/config/*`, `parameters.yml`, `parameters.yml.dist`,
  `config.yml`, `security.yml`. Un cambio ahi se cuenta por su efecto, no por el
  archivo. **"Parameters Defaults" no es un area.**
- **Pruebas y depuracion**: `Test`, `pruebas/`, `*Test.php`, y las pantallas de
  depuracion tipo "Prueba Filtros de Reporte". No son pantallas de usuario.
- **Documentacion y convenciones internas**: `*.md`, `CONVENCIONES-CLAUDE.md`,
  `REGLAS-EQUIPO.md`, `docs/`, las skills. **No le cambian nada a ningun cliente**: si
  el corte trae solo esto, se dice que no hay cambios funcionales.
- **Integracion continua**: `.github/`, `composer.*`, `scripts/` de mantenimiento.

## ⚠️ Los cambios de seguridad se nombran SIEMPRE

Agregado el 17-ago-2026: la version 5793 traia **tres** correcciones de seguridad y la
entrada **no menciono ninguna**. Una de ellas le cambia el dia al agente.

Se cuentan por **lo que el usuario va a notar**, no con la palabra "seguridad" a secas,
y se distingue la que genera llamadas de la que no:

| Lo que se hizo | Como se cuenta |
|---|---|
| Se exigio sesion en una ruta que antes respondia sin ella | "Cuadre Diario ahora pide haber entrado al sistema. Si alguien tenia un enlace directo guardado, le va a pedir usuario." |
| Se saco una credencial del codigo | "Cambio interno de credenciales. No cambia nada en pantalla; si un proceso automatico falla, avisar." |

La primera **despierta a soporte** y la segunda no. Meterlas juntas bajo "seguridad"
deja al agente sin saber cual es cual.

## Cortes grandes: no promediar

Si el corte trae muchos commits, **no repartir la atencion por cantidad de archivos**:
nombrar las dos o tres cosas que de verdad le cambian el dia al usuario y decir que el
resto es interno. La entrada de la 5793 cubrio 61 commits, destaco un archivo de
configuracion y omitio tres arreglos de seguridad — justo el resultado de promediar.

## Reglas de evidencia (obligatorias)
La IA solo puede inferir desde evidencia observable en:
- Commits
- Archivos cambiados
- Buckets/areas detectadas
- Diffs (condiciones, SQL, funciones, vistas)

Prohibido:
- Inventar pantallas, campos, modulos o resultados.
- Afirmar mejora de rendimiento sin evidencia directa.
- Afirmar correccion total de negocio sin validacion.

Si no hay evidencia suficiente:
- Usar frases honestas como:
  - "No se detecta cambio visible para el usuario final en este corte."
  - "No hay evidencia suficiente para afirmar impacto funcional adicional."

## Reglas por seccion del changelog
### Que cambia para el usuario (operacion)
- 3 a 6 bullets.
- Enfocar en flujo visible: crear/editar, consultar, reportar, filtrar.
- Evitar jerga tecnica.
- Si hay evidencia, separar explicitamente:
  - "Se agrego: ..."
  - "Se modifico: ..."
  - "Se corrigio: ..."
- Evitar frases vagas como "modulo afectado" o "puede notar cambios" sin detalle.

### Validacion rapida (5 minutos)
- 4 a 8 items, checklist accionable.
- Incluir pruebas de flujo real (crear/editar/consultar/reporte) segun evidencia.
- Si el cambio es interno (solo CI/scripts/docs/config), validar pipeline/version/changelog.

### Resumen ejecutivo (gerencia)
- 2 a 4 bullets.
- Responder: que se integro, donde impacta, nivel de sensibilidad operativa.

### Riesgos y sintomas
- 2 a 4 bullets.
- Cada bullet debe incluir:
  - Nivel (Bajo/Medio/Alto)
  - Sintoma esperable
  - Donde mirar primero (modulo o archivo)

### Rollback sugerido
- 1 a 3 bullets.
- Debe ser practico con git revert de commit de corte o rango.
- Recordar validacion de version/config cuando aplique.

### Detalle tecnico (equipo)
- 3 a 6 bullets.
- Incluir cambios de reglas, SQL, areas y posible impacto tecnico.

## Heuristicas de riesgo (deterministicas)
- Bajo:
  - Cambios internos: .github/workflows, scripts, docs, solo config/version.
- Medio:
  - Cambios en SQL, condiciones de validacion, controllers o consultas de datos.
- Alto:
  - Migraciones
  - Cambios amplios de logica + SQL/condiciones en flujos criticos
  - Alta cantidad de archivos de logica afectados en un mismo corte

## Reglas de inferencia para validacion rapida
Si hay cambios en:
- /controller/:
  - Probar crear y editar en flujo principal del modulo afectado.
- views/js/ts/twig:
  - Abrir pantallas afectadas y validar interaccion/filtros.
- SQL/reportes/repository:
  - Ejecutar reporte principal del area y comparar totales de una muestra conocida.
- condiciones/validaciones:
  - Probar un caso que antes pasaba y otro que antes se bloqueaba.

## Reglas de comunicacion para no tecnicos
- Frases cortas, concretas y accionables.
- Evitar sobreexplicar arquitectura.
- Priorizar: impacto en operacion, posibles sintomas, como verificar rapido.

## Estilo y formato
- Espanol claro y neutro.
- **Siempre en espanol, sin excepcion.** Si el asunto del commit esta en ingles, se
  traduce a lo que significa para el usuario; **nunca se copia literal**. En la version
  5793 salio tal cual "fix bug in plus filtering logic in ventasproductofechatienda
  report", que para el agente no dice nada. (Agregado el 17-ago-2026.)
- **El numero de tiquete suma, pero no reemplaza a decir que cambio.** `#23486` solo no
  es una descripcion.
- Bullets cortos (maximo 200 caracteres recomendados por bullet).
- No usar tono triunfalista.
- No usar "se soluciono todo" ni promesas absolutas.

## Contexto operacional adicional
- El sistema maneja variaciones por tienda, tipo de documento y configuraciones locales.
- Cambios en IVA/costos/documentos pueden afectar reportes y conciliaciones.
- Cuando haya reportes afectados, priorizar validacion de totales y filtros por tienda/departamento/linea.

## Frases preferidas (ejemplos)
- "Puede notar cambios en validaciones al guardar documentos."
- "Los totales del reporte pueden variar por ajuste de consulta."
- "No se detecta cambio visible para usuario final en este corte; ajuste interno de versionado."

## Frases a evitar
- "Se optimizo todo el sistema."
- "No hay ningun riesgo."
- "Este cambio no puede fallar."
- "Se agrego pantalla X" (si no hay evidencia directa).