Documentación de Proyecto Sincro

API Documentation

Classes

Ruta: Declaración de una acción de la API.
Contexto: Petición ya autorizada. Si un handler recibe un Contexto, el guard le dio paso.
Respuesta: Punto único de salida de la API.
Guard: Aplica el control de acceso declarado por la ruta.
Ruta: Declaración de una acción de la API.
Contexto: Petición ya autorizada. Si un handler recibe un Contexto, el guard le dio paso.
Respuesta: Punto único de salida de la API.
Guard: Aplica el control de acceso declarado por la ruta.
Conexion: Conexion — Manager de instancias mysqli (patrón Multiton).
ControladorAceite: Controlador Gestiona el modulo de aceite
ControladorBodega: ControladorBodega Gestiona el módulo de bodegas: listado, detalle, alta bodega, alta depósito y asignación de depósitos a bodega.
ControladorCampanias: Controlador para el módulo de Campañas.
ControladorCategorias: ControladorCategorias Resuelve la conexión y el centro activo, delega en CategoriasDao.
ControladorCliente: ControladorCliente — Lógica de aplicación del módulo Clientes.
ControladorConexiones: ControladorConexiones — Lógica de la página panelCentros.
ControladorConfig: ControladorConfig — gestión de la configuración global del sistema.
ControladorDeposito: Controlador para el módulo de Depósitos.
ControladorEntradas: ControladorEntradas Orquesta la creación de una entrada externa: 1. INSERT partidaexterna 2. Por cada depósito de la entrada: a. INSERT partidaexternadeposito b. INSERT trasiego c. UPDATE deposito (kilos + ponderación precio/acidez)
ControladorFiltrados: ControladorFiltrados Resuelve la conexión y delega en FiltradosDao
ControladorMatriculaProveedor: ControladorMatriculaProveedor Gestiona las matrículas asociadas a un proveedor.
ControladorPaginas: ControladorPaginas Gestión CRUD de la tabla `paginas` en trackingweb.
ControladorPartidasEST: ControladorPartidasEST Gestiona Entradas, Salidas y Trasiegos directos.
ControladorPartidasProc: ControladorPartidasProc Gestiona partidas de forma especializada a diferencia de EST
ControladorPermisos: ControladorPermisos — Lógica de aplicación sobre el modelo (usuario × página × conexión).
ControladorPesada: ControladorPesada — lógica de aplicación del módulo Pesada.
ControladorProveedor: ControladorProveedor Resuelve la conexión, delega en ProveedorDao y etiqueta cada fila con conexion_id / conexion_nombre.
ControladorRendimiento: Controlador del módulo Rendimiento de Pesada.
ControladorSalidas: ControladorSalidas Orquesta la creación de una salida a granel: 1. INSERT partidasalida 2. Por cada depósito de la salida: a. Leer acidez y precio actuales del depósito b. INSERT partidasalidadeposito c. INSERT trasiego (salida=idPartidaSalida, con vacío opcional) d. UPDATE deposito (descuenta kilos, sin ponderación)
ControladorSubtipoPrimario
ControladorTrasiegos: ControladorTrasiegos Orquesta la creación de un trasiego directo (origen → destino distinto):
ControladorUsers: Controlador de usuarios.
ControladorVOrganico: ControladorVOrganico
AceiteDao: DAO SQL puro para la tabla 'muestraaceite' en BDs destino Recibe mysqli como parametro — nunca lo resuelve solo
BodegaDao: BodegaDao SQL puro para las tablas `bodega` y `bodegaasignacion` en BDs destino (tr_*).
CampaniaDao: Dao de la tabla Campania de tracking_*
CategoriasDao: CategoriasDao SQL puro para la tabla `categoria` en BDs destino (tr_*).
ClienteDao: ClienteDao — Acceso a datos de `cliente` en BDs destino (tr_*).
ConexionConfigDao: ConexionConfigDao — Acceso a datos de la tabla `conexion`.
ConfigDao: ConfigDao — Configuración global del sistema persistida en fichero JSON.
DAODeposito
DaoRendimientoPesada: DAO para la gestión de registros de RendimientoPesada.
DepositoDao: DepositoDao SQL puro para la tabla `deposito` en BDs destino (tr_*).
FiltradosDao: FiltradosDao SQL puro para la tabla `filtrado_tipo` en BDs destino (tr_*).
MatriculaClienteDao: MatriculaClienteDao SQL puro para la tabla `clientematricula` en BDs destino (tr_*).
MatriculaProveedorDao: MatriculaProveedorDao SQL puro para la tabla `proveedormatricula` en BDs destino (tr_*).
paginasDao: DAO para la gestión de las paginas.
PartidaEntradaDao: PartidaEntradaDao SQL puro para partidaexterna y sus tablas relacionadas en BDs destino (tr_*).
PartidaSalidaDao: PartidaSalidaDao SQL puro para partidasalida y sus tablas relacionadas en BDs destino (tr_*).
PartidasProcDao: PartidasProcDao Funciones completas sobre partida y sus procedimientos relacionados
PermisosDao: PermisosDao — Operaciones sobre la tabla `permisos`. Usa mysqli.
PesadaDao: PesadaDao — acceso a datos de la tabla `pesada` en BDs destino (tr_*).
ProveedorDao: ProovedorDAO — SQL puro para la tabla 'proveedor' en BDs destino Afecta la tabla 'proveedor' y sus relaciones necesarias como: - comunidades
SubtipoPrimarioDao: SubtipoPrimarioDao SQL puro para la tabla `subtipoprimario` en BDs destino (tr_*).
TrasiegoDao: TrasiegoDao SQL puro para trasiegos directos (sin partida de entrada ni salida) en BDs destino (tr_*).
usuarioWebDao: usuarioWebDao — CRUD sobre `usuario_web`. Usa mysqli.
vOrganicoDao: VOrganicoDao SQL puro para la tabla `valoracionorganoleptica` en BDs destino (tr_*).
caminohmi: Modelado de la tabla 'caminohmi'
Campania: Modelo de Campania
Cliente: Modelado de la tabla 'Cliente'
ClienteMatricula: Modelado de la tabla 'clienteMatricula'
ConexionConfig: ConexionConfig: Entidad que representa una fila de la tabla `conexion`.
Deposito: Modelado de la tabla 'Deposito'
Filtrado: Modelado de la tabla 'Filtrado'
muestraAceite: Modelado de la tabla 'muestraAceite'
paginas: Modelado de la tabla 'paginas' de trackingweb
Partida: Modelado de la tabla 'Partida'
PartidaExterna: Modelado de la tabla 'PartidaExterna'
PartidaExternaDeposito: Modelado de la tabla 'PartidaExternaDeposito'
partidaListadoProc
Pesada: Modelo Pesada — adaptado a la arquitectura trackingwebNEW.
ProveedorMatricula: Modelado de la tabla 'ProveedorMatricula'
RendimientoPesada: Clase RendimientoPesada
Trasiego: Modelado de la tabla 'trasiegos'
usuarioWeb: Entidad que representa a la tabla usuarioWeb del sistema Gestiona los datos del perfil y el control y verificación de contraseñas
ApiTestCase: Clase base abstracta para todos los tests de la API.
ApiContratoTest: Contrato general de la API: forma de la respuesta, métodos HTTP admitidos y tratamiento de acciones inválidas.
AuthTest: Test unitarios de todas las funciones relacionadas con auth
AutorizacionTest: Autorización de la API: acceso a acciones protegidas sin sesión y validación del parámetro conexion_ids que gobierna sobre qué base tracking se opera.
SeguridadSesionTest: Seguridad de la sesión: binding con User-Agent, regeneración del identificador tras el login y ausencia de sesión tras un login fallido.
NavegacionTest: Sección NAVEGACIÓN de la API — páginas visibles en el sidebar y resolución de la página principal del usuario.
PanelAdminTest: Sección PANEL ADMIN de la API — gestión de usuarios y de sus permisos.
PanelCentrosTest: Sección PANEL CENTROS de la API — gestión de las conexiones a las bases de explotación.
PanelConfiguracionTest: Sección PANEL CONFIGURACIÓN de la API — variables globales del sistema persistidas en backend/variable/config.json.
PanelPaginasTest: Sección PANEL PÁGINAS de la API — catálogo de módulos del sistema.
SesionTest: Sección SESIÓN de la API — reglas de autenticación propias del modelo usuario_web (login único, usuarios deshabilitados, no enumeración).
BdDestinoHelper: BdDestinoHelper — Helpers para operaciones comunes sobre BDs destino (tr_*).
Crypto: Crypto — Helper de cifrado simétrico AES-256-GCM.
Csrf: Token sincronizador contra falsificación de peticiones entre sitios (CSRF).
SuperToken: Clase para gestionar la creacion de tokens

Enums

Acceso: Nivel mínimo exigido para ejecutar una ruta. Jerárquico: SUPER cumple ADMIN, ADMIN cumple AUTENTICADO.
Ambito: Ámbito de datos sobre el que opera la ruta.
Acceso: Nivel mínimo exigido para ejecutar una ruta. Jerárquico: SUPER cumple ADMIN, ADMIN cumple AUTENTICADO.
Ambito: Ámbito de datos sobre el que opera la ruta.

Constants

CAMPOS_CONEXION_PUBLICOS = ['id', 'nombre', 'host', 'puerto', 'descripcion']: Campos de la tabla `conexion` que pueden viajar al navegador.
CONTEXTO_API = \true: Marca la petición como perteneciente a la API. La red de fatales de bootstrap.php la consulta para decidir si responde en JSON: en las páginas web no debe hacerlo, o el navegador mostraría el objeto en crudo.
DIR_FRONTEND = __DIR__ . '/../../frontend'
DIR_RUTAS = __DIR__ . '/../api/v2_test/rutas'
ESCRIBEN_SESION = ['login', 'cambiar_campania', 'update_user_permisos']: Acciones cuyo handler modifica $_SESSION. Deben declarar escribeSesion: true, o el despachador liberará el bloqueo de sesión antes de ejecutarlas y sus escrituras no se persistirán.
EXCLUIDOS = '#[\\\\/](node_modules|dist|vendor|\.git|\.idea)[\\\\/]#': Directorios que no forman parte del código propio.
PAGINAS_ROL_MINIMO = [ 'paneladministrador' => 1, // admin y super 'panelpaginas' => 1, // admin y super 'panelconexiones' => 2, // solo super 'panelconfiguracion' => 2, ]: Páginas cuyo acceso NO depende de la tabla `permisos` sino del rol.
PATRONES_ACCION = ['/[\'"]?action[\'"]?\s*[:=]\s*[\'"]([a-zA-Z0-9_]+)[\'"]/', '/append\(\s*[\'"]action[\'"]\s*,\s*[\'"]([a-zA-Z0-9_]+)[\'"]/', '/action=([a-zA-Z0-9_]+)/']: Formas en que el frontend puede declarar la acción. La primera cubre el objeto literal de $.ajax; la segunda, las subidas con FormData; la tercera, las cadenas de consulta construidas a mano.
PERMISOS_TTL = 300
PERMISOS_TTL_REINTENTO = 30
PREFIJOS_ESCRITURA = ['crear_', 'insert_', 'eliminar_', 'delete_', 'modificar_', 'update_', 'actualizar_', 'anadir_', 'add_', 'ajuste_', 'ajustar_', 'asignar_', 'deshabilitar_', 'habilitar_', 'reajustar_', 'cambio_', 'set_']: Prefijos que delatan una acción de escritura por su nombre.
RID = \bin2hex(\random_bytes(4))
SESSION_TIMEOUT_SECONDS = 30 * 60

Functions

registrarRutas() : array<string, Ruta>: Combina los módulos detectando colisiones.
jsonResponse() : never
requireAuthApi() : void: Valida sesión activa + binding IP/UA.
requirePermisos() : array{paginaId: int, conexionIds: int[]}: Valida que el usuario tiene permiso para una página sobre TODAS las conexiones recibidas. Aborta con 403 si falla.
obtenerFechaActual() : string: Devuelve la fecha y hora actuales en formato MySQL.
writeLog() : void: Registra una acción en la tabla `log` de la base de datos tracking.
_agSesion() : void: Comprueba que la sesion está abierta o sino la abre
rutaCanonica() : string: Normaliza cualquier forma de ruta a una única clave.
_agCacheVacia() : array<string|int, mixed>: Crea una cache vacia con un error por parametro
permisosCache() : array<string|int, mixed>: Devuelve la caché, construyéndola o revalidándola si toca.
conexionesDePagina() : array<string|int, int>: Conexiones sobre las que el usuario puede operar en esa página.
puedeAccederPagina() : bool: ¿Puede el usuario ver la página? Basta con 1 permiso.
conexionesDisponibles() : array<int, array<string|int, mixed>>: Conexiones de la página ya "hidratadas" con su ficha (id, nombre, host…).
menuSidebar() : array<string|int, mixed>: Árbol de menú ya filtrado por permisos, listo para renderizar.
paginaPrincipal() : string|null: Ruta canónica de la primera página accesible (destino tras el login).
conexionPorDefecto() : int|null: Primera conexión sobre la que el usuario tiene algún permiso.
invalidarCachePermisos() : void: Fuerza la reconstrucción en la PRÓXIMA lectura (solo de la sesión actual).
requireAuthPage() : void: Comprueba si el usuario tiene acceso a la pagina que lo invoca
sesionExpiradaPorInactividad() : bool: Timeout por INACTIVIDAD. true = expirada.
_construirCachePermisos() : array<string|int, mixed>: Construccion de la cache Se construye al hacer loggin y se renueva segune el TTL definido al principio del archivo
_agInsertarEnMenu() : void: Coloca una página en el árbol categoria → subcategoria → subsubcategoria.
prompt() : string
promptInt() : int
promptBool() : bool
promptPassword() : string: Lee una contraseña ocultando el eco en sistemas Unix.
sqlEscape() : string: Escapa una cadena para inclusión segura en una sentencia SQL como literal.

CAMPOS_CONEXION_PUBLICOS

Campos de la tabla `conexion` que pueden viajar al navegador.


    public
        mixed
    CAMPOS_CONEXION_PUBLICOS
    = ['id', 'nombre', 'host', 'puerto', 'descripcion']

Lista blanca a propósito: esa tabla guarda credenciales de las bases de explotación (usuario, password) y estas fichas se sirven tal cual al selector de conexiones. Todo lo que no esté aquí no sale del servidor.

CONTEXTO_API

Marca la petición como perteneciente a la API. La red de fatales de bootstrap.php la consulta para decidir si responde en JSON: en las páginas web no debe hacerlo, o el navegador mostraría el objeto en crudo.


    public
        mixed
    CONTEXTO_API
    = \true

Debe definirse ANTES de incluir el bootstrap.

DIR_FRONTEND


    public
        mixed
    DIR_FRONTEND
    = __DIR__ . '/../../frontend'

DIR_RUTAS


    public
        mixed
    DIR_RUTAS
    = __DIR__ . '/../api/v2_test/rutas'

ESCRIBEN_SESION

Acciones cuyo handler modifica $_SESSION. Deben declarar escribeSesion: true, o el despachador liberará el bloqueo de sesión antes de ejecutarlas y sus escrituras no se persistirán.


    public
        mixed
    ESCRIBEN_SESION
    = ['login', 'cambiar_campania', 'update_user_permisos']

Lista mantenida a mano, pero convierte un fallo silencioso —el caso del token CSRF que el servidor nunca llega a guardar— en un error visible.

EXCLUIDOS

Directorios que no forman parte del código propio.


    public
        mixed
    EXCLUIDOS
    = '#[\\\\/](node_modules|dist|vendor|\.git|\.idea)[\\\\/]#'

PAGINAS_ROL_MINIMO

Páginas cuyo acceso NO depende de la tabla `permisos` sino del rol.


    public
        mixed
    PAGINAS_ROL_MINIMO
    = [
    'paneladministrador' => 1,
    // admin y super
    'panelpaginas' => 1,
    // admin y super
    'panelconexiones' => 2,
    // solo super
    'panelconfiguracion' => 2,
]

Funcionan estén o no dadas de alta en la tabla paginas.

Clave = ruta canónica (minúsculas, sin carpeta ni .php).

PATRONES_ACCION

Formas en que el frontend puede declarar la acción. La primera cubre el objeto literal de $.ajax; la segunda, las subidas con FormData; la tercera, las cadenas de consulta construidas a mano.


    public
        mixed
    PATRONES_ACCION
    = ['/[\'"]?action[\'"]?\s*[:=]\s*[\'"]([a-zA-Z0-9_]+)[\'"]/', '/append\(\s*[\'"]action[\'"]\s*,\s*[\'"]([a-zA-Z0-9_]+)[\'"]/', '/action=([a-zA-Z0-9_]+)/']

PERMISOS_TTL


    public
        mixed
    PERMISOS_TTL
    = 300

PERMISOS_TTL_REINTENTO


    public
        mixed
    PERMISOS_TTL_REINTENTO
    = 30

PREFIJOS_ESCRITURA

Prefijos que delatan una acción de escritura por su nombre.


    public
        mixed
    PREFIJOS_ESCRITURA
    = ['crear_', 'insert_', 'eliminar_', 'delete_', 'modificar_', 'update_', 'actualizar_', 'anadir_', 'add_', 'ajuste_', 'ajustar_', 'asignar_', 'deshabilitar_', 'habilitar_', 'reajustar_', 'cambio_', 'set_']

RID


    public
        mixed
    RID
    = \bin2hex(\random_bytes(4))

SESSION_TIMEOUT_SECONDS


    public
        mixed
    SESSION_TIMEOUT_SECONDS
    = 30 * 60

registrarRutas()

Combina los módulos detectando colisiones.


    
                    registrarRutas(array<string, Ruta> ...$modulos) : array<string, Ruta>

array_merge sobrescribiría en silencio una acción declarada dos veces, y podría prevalecer la que tiene el nivel de acceso más permisivo.

Parameters

$modulos : array<string, Ruta>

Return values

array<string, Ruta>

jsonResponse()


    
                    jsonResponse(mixed $data[, int $status = 200 ]) : never

Parameters

$data : mixed
$status : int = 200

Return values

never

requireAuthApi()

Valida sesión activa + binding IP/UA.


    
                    requireAuthApi() : void

Aborta con 401 si no supera la comprobación.

Renombrada respecto a auth_guard::requireAuthPage para diferenciar:

requireAuthApi() → endpoints (este archivo) → responde JSON 401
requireAuthPage() → páginas .php → redirige a login

requirePermisos()

Valida que el usuario tiene permiso para una página sobre TODAS las conexiones recibidas. Aborta con 403 si falla.


    
                    requirePermisos() : array{paginaId: int, conexionIds: int[]}

Lee pagina_id y conexion_ids (JSON array) del POST.

Return values

array{paginaId: int, conexionIds: int[]}

obtenerFechaActual()

Devuelve la fecha y hora actuales en formato MySQL.


    
                    obtenerFechaActual() : string

Return values

string

writeLog()

Registra una acción en la tabla `log` de la base de datos tracking.


    
                    writeLog(string $frase, int $conexionId) : void

Parameters

$frase : string: Descripción de la acción realizada.
$conexionId : int

_agSesion()

Comprueba que la sesion está abierta o sino la abre


    
                    _agSesion() : void

rutaCanonica()

Normaliza cualquier forma de ruta a una única clave.


    
                    rutaCanonica(string $ruta) : string

Parameters

$ruta : string

Return values

string

_agCacheVacia()

Crea una cache vacia con un error por parametro


    
                    _agCacheVacia([string|null $error = null ]) : array<string|int, mixed>

Parameters

$error : string|null = null

Return values

array<string|int, mixed>

permisosCache()

Devuelve la caché, construyéndola o revalidándola si toca.


    
                    permisosCache() : array<string|int, mixed>

Return values

array<string|int, mixed>

conexionesDePagina()

Conexiones sobre las que el usuario puede operar en esa página.


    
                    conexionesDePagina(string $ruta) : array<string|int, int>

Parameters

$ruta : string: : ruta de la pagina a la que se quiere acceder

Return values

array<string|int, int> —

vacío = sin acceso

puedeAccederPagina()

¿Puede el usuario ver la página? Basta con 1 permiso.


    
                    puedeAccederPagina(string $ruta) : bool

Parameters

$ruta : string

Return values

bool

conexionesDisponibles()

Conexiones de la página ya "hidratadas" con su ficha (id, nombre, host…).


    
                    conexionesDisponibles(string $ruta) : array<int, array<string|int, mixed>>

Es lo que consume conexion-selector.js.

Parameters

$ruta : string: : ruta de la que se quiere obtener sus conexiones

Return values

array<int, array<string|int, mixed>>

menuSidebar()

Árbol de menú ya filtrado por permisos, listo para renderizar.


    
                    menuSidebar() : array<string|int, mixed>

Return values

array<string|int, mixed>

paginaPrincipal()

Ruta canónica de la primera página accesible (destino tras el login).


    
                    paginaPrincipal() : string|null

Return values

string|null

conexionPorDefecto()

Primera conexión sobre la que el usuario tiene algún permiso.


    
                    conexionPorDefecto() : int|null

Return values

int|null

invalidarCachePermisos()

Fuerza la reconstrucción en la PRÓXIMA lectura (solo de la sesión actual).


    
                    invalidarCachePermisos() : void

requireAuthPage()

Comprueba si el usuario tiene acceso a la pagina que lo invoca


    
                    requireAuthPage(string $ruta) : void

Parameters

$ruta : string: : ruta de la pagina invocante

sesionExpiradaPorInactividad()

Timeout por INACTIVIDAD. true = expirada.


    
                    sesionExpiradaPorInactividad([bool $renovar = true ]) : bool

Parameters

$renovar : bool = true

Return values

bool

_construirCachePermisos()

Construccion de la cache Se construye al hacer loggin y se renueva segune el TTL definido al principio del archivo


    
                    _construirCachePermisos(int $userId, int $rol) : array<string|int, mixed>

Parameters

$userId : int: : id del usuario solicitante
$rol : int: : rol del usuario solicitante

Return values

array<string|int, mixed> —

: estructura de permisos

_agInsertarEnMenu()

Coloca una página en el árbol categoria → subcategoria → subsubcategoria.


    
                    _agInsertarEnMenu(array<string|int, mixed> &$menu, array<string|int, mixed> $p, string $clave) : void

Parameters

$menu : array<string|int, mixed>
$p : array<string|int, mixed>
$clave : string

prompt()


    
                    prompt(string $label[, string|null $default = null ][, bool $required = true ]) : string

Parameters

$label : string
$default : string|null = null
$required : bool = true

Return values

string

promptInt()


    
                    promptInt(string $label, int $default) : int

Parameters

$label : string
$default : int

Return values

int

promptBool()


    
                    promptBool(string $label, bool $default) : bool

Parameters

$label : string
$default : bool

Return values

bool

promptPassword()

Lee una contraseña ocultando el eco en sistemas Unix.


    
                    promptPassword(string $label) : string

En Windows muestra el texto en claro (limitación de stty).

Parameters

$label : string

Return values

string

sqlEscape()

Escapa una cadena para inclusión segura en una sentencia SQL como literal.


    
                    sqlEscape(string $s) : string

Solo para uso de presentación (el INSERT que muestra el script).

Parameters

$s : string

Return values

string

API Documentation

Table of Contents

Classes

Enums

Constants

Functions

Constants

CAMPOS_CONEXION_PUBLICOS

CONTEXTO_API

DIR_FRONTEND

DIR_RUTAS

ESCRIBEN_SESION

EXCLUIDOS

PAGINAS_ROL_MINIMO

PATRONES_ACCION

PERMISOS_TTL

PERMISOS_TTL_REINTENTO

PREFIJOS_ESCRITURA

RID

SESSION_TIMEOUT_SECONDS

Functions

registrarRutas()

Parameters

Tags

Return values

jsonResponse()

Parameters

Return values

requireAuthApi()

requirePermisos()

Return values

obtenerFechaActual()

Return values

writeLog()

Parameters

_agSesion()

rutaCanonica()

Parameters

Return values

_agCacheVacia()

Parameters

Return values

permisosCache()

Return values

conexionesDePagina()

Parameters

Return values

puedeAccederPagina()

Parameters

Return values

conexionesDisponibles()

Parameters

Return values

menuSidebar()

Return values

paginaPrincipal()

Return values

conexionPorDefecto()

Return values

invalidarCachePermisos()

requireAuthPage()

Parameters

sesionExpiradaPorInactividad()

Parameters

Return values

_construirCachePermisos()

Parameters

Return values

_agInsertarEnMenu()

Parameters

prompt()

Parameters

Return values

promptInt()

Parameters

Return values

promptBool()

Parameters

Return values

promptPassword()