# Permisos de Hoja de Distribución

El interruptor global es `parametros_backoffice.usa_hoja_distribucion`. Al
ponerlo en `S` se muestra el menú y se habilitan los endpoints del módulo; en
`N` el backend también rechaza el acceso. No existe una tabla secundaria de
permisos para Hoja.

La fuente por usuario es `maeusr` y se administra desde el mantenimiento normal
de usuarios, dentro del apartado **Hoja de Distribución**. La bandera
`hoja_todo='S'` concede todas las acciones propias del módulo. Si permanece en
`N`, se usan los permisos detallados `hoja_*`.

Se reutilizan las banderas históricas:

- `vercosto` y `verprecio`: visibilidad de valores.
- `modcosto`: editar costo y flete.
- `modprecio`: editar precio.
- `permite_anulacion_documento`: validación adicional al anular documentos.

## Mapa de permisos a columnas

Tomado de `HojaPermisoService::$columnas`. La columna izquierda es el nombre que
usa `assertHojaPermiso()` en el controlador; la derecha, la columna de `maeusr`.

| Permiso | Columna `maeusr` | Endpoints que lo exigen |
|---|---|---|
| `ver` | `hoja_ver` | índice, resumen, fechas (consulta), detalle, hojas, resumen de aplicación, ofertas, tipos de conversión |
| `crear` | `hoja_crear` | manual, por productos, ofertas, reposición, importar, convertir |
| `crear_desde_documentos` | `hoja_crear_documentos` | búsqueda de documentos y creación desde documentos |
| `editar_cantidades` | `hoja_editar_cantidades` | editar celdas `Txx`, encabezado (días), refrescar existencias y fuentes |
| `agregar_producto` | `hoja_agregar_producto` | buscar producto, agregar uno, agregar lote |
| `eliminar_producto` | `hoja_eliminar_producto` | eliminar producto, eliminar hoja, convertir |
| `editar_costo` | `modcosto` | editar celda de costo |
| `editar_flete` | `modcosto` | editar celda de flete |
| `editar_precio` | `modprecio` | editar celda de precio |
| `editar_gastos` | `hoja_editar_gastos` | consultar, previsualizar y guardar gastos; PDF de gastos |
| `cambiar_fechas` | `hoja_cambiar_fechas` | fechas por tienda, fecha de aplicación, fecha del encabezado |
| `aplicar` | `hoja_aplicar` | aplicar |
| `reaplicar` | `hoja_reaplicar` | aplicar con `reemplazar=1` |
| `desaplicar` | `hoja_desaplicar` | desaplicar |
| `bloquear` | `hoja_bloquear` | bloqueo con `S` |
| `desbloquear` | `hoja_desbloquear` | bloqueo con `N` |
| `imprimir_hoja` | `hoja_imprimir` | PDF de la hoja |
| `imprimir_vales` | `hoja_imprimir_vales` | tiendas del vale, previsualización y PDF |
| `consultar_ventas` | `hoja_ventas` | consulta, EXPLAIN, exportación y PDF de ventas |
| `auditoria_individual` | `hoja_auditoria_individual` | auditoría individual y revisión |
| `auditoria_global` | `hoja_auditoria_global` | auditoría rápida, detallada, de valores y sus exportaciones |
| `sincronizar_costos` | `hoja_sincronizar_costos` | sincronizar costo, flete y precio |
| `exportar_remotamente` | `hoja_exportar` | estado y envío de exportación remota |

Dos permisos comparten columna a propósito: `editar_costo` y `editar_flete`
ambos usan `modcosto`, porque en el legado el flete es parte del costo y quien
puede tocar uno puede tocar el otro. Se documenta la equivalencia en lugar de
crear una columna nueva sin necesidad.

Algunas acciones exigen además las banderas históricas de visibilidad: gastos
requiere `vercosto`, y sincronizar valores requiere `vercosto` y `verprecio`.
Los importes del vale se omiten si el usuario no tiene `verprecio`.

`HojaPermisoService` lee directamente la fila del usuario en `maeusr`. Cada
endpoint valida el permiso en backend; ocultar el control en Twig es únicamente
una ayuda visual.

Durante un despliegue donde aún no existe `maeusr.hoja_ver`, un usuario
autenticado puede abrir sólo la consulta y el diagnóstico. Las escrituras y
reportes sensibles permanecen bloqueados. Al agregar las columnas, todos los
permisos nuevos empiezan en `N`.

`hoja_todo` no modifica permisos generales de otros módulos. La visibilidad de
costos y precios continúa dependiendo de `vercosto` y `verprecio`.

## Verificación

El recuento se hace sobre el código, no sobre esta tabla: los 48 endpoints de
`HojaController` llaman a `assertHojaPermiso()` y las 24 escrituras `POST`
llaman además a `assertHojaWriteRequest()`, que valida sesión y token CSRF. Si se
agrega un endpoint sin permiso, el recuento descrito en
`docs/hoja-distribucion-resultados-pruebas.md` lo delata.