BcOk - Documentazione tecnica

Questa documentazione si rivolge agli sviluppatori che lavorano sul codice di BcOk, il sistema gestionale / CRM sviluppato da Ottomedia per il network Ufficiarredati.it

La documentazione per gli utenti finali di BcOk è disponibile su https://guida.bcok.it, e mantenuta nel bitbucket in un progetto separato: Guida BcOk

Questa documentazione tecnica è in buona parte datata e incompleta/imprecisa, ma può essere utile per avere una visione di insieme del sistema.

Si consiglia di fare riferimento alle copilot-instructions.md dei vari repository per avere indicazioni aggiornate sul codice specifico (e magari riportare qui gli aggiornamenti, sarebbe gradito...).

Per chi sviluppa BcOk

Come si sviluppa in locale, con dati inventati e mai con una copia della produzione: Ambiente di sviluppo.

Sicurezza degli accessi

Chi può entrare, come si gestiscono gli account e quali plugin sono indispensabili per la sicurezza: Sicurezza degli accessi.

Per chi integra BcOk da un'applicazione esterna

La documentazione delle API per cercare spazi disponibili e prenotarli (con Carnet o pagamento Stripe) è in Booking API.

Architettura del codice

BcOk è il sistema gestionale / CRM sviluppato da Ottomedia per il network Ufficiarredati.it

Il backend è un sistema WordPress con accesso riservato esteso con un Tema ad hoc e numerosi plugin scritti appositamente.

Il sistema è denominato Pandora, la sua installazione operativa è BcOk.it

Tema e Plugins

Tema

Utilizziamo un tema custom di WordPress che si chiama, guarda un po', "BcOk". Il repository del tema è qui: [BcOk]https://github.com/Ottomedia/pandora-theme). Il tema usa il framework e layout di AdminLTE 2.

Tutto ciò che è "form", cioè tutti gli input, comunicano con backend WP attraverso le API REST di WP, implemnentante nel tema con JQuery.

Plugins

Sviluppati ad hoc

Le funzionalità di Pandora/BcOk sono suddivise per ragioni "storiche" e di praticità in diversi plugin.

Le ragioni storiche risiedono nel fatto che le funzionalità sono state aggiunte di volta in volta, nel corso degli anni. E quando abbiamo implementato delle funzionalità sufficientemente autonome dalle altre, abbiamo realizzato un plugin a sè. Inizialmente l'idea era che BcOk avrebbe potuto funzionare anche "disattivando" uno dei plugin aggiuntivi (a patto di non disattivare il Pandora principale), rinuciando solo alle funzionalità specifiche di quel plugin.

Ora le funzioni sono molto "intrecciate", disattivando un plugin è quasi certo che BcOk crolli. Restano però le ragioni di praticità per tenerli divisi.

Si tratta di plugin piuttosto corposi: è più pratico, sicuro e maneggevole lavoare su raggruppamenti di file un po' più piccoli.

Plugin di terze parti (necessari)

Plugin di terze parti (di supporto)

Plugin che usiamo solo occasionalmente a supporto della gestione/manutenzione di BcOk

[da fare]

MU Plugin

[da fare]

Servizi esterni

Vedi Infrastruttura e GDPR per la localizzazione dei dati e dei servizi

Server: OVH & SpinupWP

Il server che ospita BcOK è su OVH, nel datacenter di Francoforte (DE). Il server è gestito attraverso un account di SpinupWP Gira un cron:

*/1 * * * * cd /sites/bcok.it/files/; /usr/local/bin/wp cron event run --due-now >/dev/null 2>&1

Lo stack del server è: - Nginx - PHP 8.4-FPM - MySQl 8.4 - Redis Vedi Migrazione, configurazione e otttimizzazione Server 2026 per i dettagli

Backup: AWS S3 e Dropbox

  • Vengono eseguiti backup giornalieri dei files da SpinupWP in un bucket di Amazon AWS S3 - cancellati dopo 10 giorni (verificato il 16/11/2026).
  • Vengono eseguiti backup orari del DB in un bucket di Amazon AWS S3 con il servizio esterno https://sqlbak.com/. Vengono eseguiti due Bakup full del DB ogni 12 ore e in mezzo backup incrementali ogni ora. Cancellati dopo 30 giorni (verificato il 16/11/2026). SQLBack accede al db con un account limitato: SqlBack - utente limitato

Email: AWS SES e SNS

L'invio delle email e la notifica del delivery è basato su Amazon AWS SES, SNS

E' implementato grazie all'uso dei plugin: - Pandora AWS SES Notification (che elabora la coda delle Notifiche Pandora e riceve i feedback di consegna) - WP Mail SES

Allegati: AWS S3

Tutti gli allegati sono salvati su Amazon AWS S3 usando il plugin S3-uploader. Il bucket ha un suo ciclo di vita e versioning abilitato: Allegati BcOk S3

Notifiche on-screen: Pusher.com

Le notifiche che appaiono nel browser durante il normale utilizzo, e gli aggiornamenti delle schermate sena ricaricare la pagina, sono gestite con un account di Pusher.com, per evitare le complessità dei Websocket.

Richieste dai siti web e dalle chat: Zapier.com

Le richieste dai siti e dalle chat vanno a un indirizzo email di Zapier.com che ne fa il parsing e poi procede a fare un HTTP POST alle API REST di BcOk.it

  • Le email che partono dai siti devono avere un sezione nel corpo dell'email formattata con un JSON specifico come documentato in questo file
  • Le email di trascrizione delle chat dei siti (di solito sono chat Tawk.to) sono parsate da Zapier usando le API OpenAI per estrarre i dati necessari a creare la richiesta in BcOk.

Architettura delle tabelle

Elementi:

Si tratta di Custom Post di WordPress

Permissions:

Funzionalità BcOk - Current_user_has()

Operativita'

Migrazione repository da BitBucket a GitHub

Logging System

BcOK implementa un sistema di logging completo per tracciare tutte le modifiche ai Custom Post Types.

Sistema di Logging dei Campi (v20.9.0+)

Architettura ottimizzata: il sistema accumula tutte le modifiche ai campi in memoria durante l'esecuzione della richiesta HTTP e scrive un unico log aggregato per post al termine (hook shutdown).

Vantaggi

  • Riduce drasticamente il numero di query al database
  • Crea log più leggibili raggruppando tutte le modifiche
  • Evita log ridondanti per modifiche multiple nello stesso ciclo di richiesta

Come Abilitare il Logging per un Custom Post Type

1. Logging dei Meta Field Personalizzati

// Abilita il logging per il post type
add_filter('post_types_per_log_campi', function($post_types) {
    $post_types[] = 'nome_cpt';  // es. 'aziende', 'acquisti'
    return $post_types;
});

// Definisci quali meta field loggare
add_filter('log_campi_nome_cpt', function($campi) {
    return array(
        'nome_meta_field' => 'Etichetta Leggibile',
        'vat'             => 'Partita IVA',
        'phone'           => 'Telefono',
        'email'           => 'Email'
    );
});

Esempio per Aziende:

add_filter('post_types_per_log_campi', function($post_types) {
    $post_types[] = 'aziende';
    return $post_types;
});

add_filter('log_campi_aziende', function($campi) {
    return array(
        'vat'   => 'Partita IVA',
        'cf'    => 'Codice Fiscale',
        'phone' => 'Telefono',
        'email' => 'Email',
        'pec'   => 'PEC'
    );
});

2. Logging dei Campi Core di WordPress

// Abilita il logging dei campi core
add_filter('post_types_per_log_core', function($post_types) {
    $post_types[] = 'nome_cpt';
    return $post_types;
});

// Definisci quali campi core loggare
add_filter('log_campi_core_nome_cpt', function($campi) {
    return array(
        'post_title'   => 'Titolo',
        'post_content' => 'Contenuto',
        'post_excerpt' => 'Estratto'
    );
});

Esempio per Richieste:

add_filter('post_types_per_log_core', function($post_types) {
    $post_types[] = 'richieste';
    return $post_types;
});

add_filter('log_campi_core_richieste', function($campi) {
    return array(
        'post_title'   => 'Titolo',
        'post_content' => 'Descrizione'
    );
});

Esclusioni Automatiche

  • Creazione iniziale: Le modifiche fatte entro 1 minuto dalla creazione del post non vengono loggate (considerate setup iniziale)
  • Campi non configurati: Solo i campi esplicitamente elencati nei filtri vengono loggati

Logging Manuale di Eventi Custom

Per eventi che non sono modifiche a campi:

// Scrive immediatamente un log
WP_Logging::add(
    'Titolo Log',           // Titolo
    'Messaggio dettagliato', // Messaggio
    $post_id,               // ID del post correlato (opzionale)
    'event'                 // Tipo di log
);

// Oppure usa la funzione helper
wp_log('system', 'Operazione completata', array('user_id' => $user_id));

Formato dei Log Generati

Il sistema genera log nel formato:

[Post 123] Modifiche ai campi: Ha modificato "Partita IVA": "12345678901" → "98765432109" | Ha modificato "Telefono": "0212345678" → "0298765432"

Nel database WordPress (CPT wp_log): - Titolo: "Modifiche ai campi" - Contenuto: Lista di tutte le modifiche (multi-riga) - Post correlato: ID del post modificato

File di Riferimento

Il sistema è implementato in: - pandora-server-api-gestione-richieste/logs/log-core-and-custom-fields.php - Funzioni principali: - pandora_write_accumulated_field_logs() - Scrive i log accumulati - pandora_log_modifica_campi_aggiuntivi() - Intercetta modifiche ai meta - pandora_log_modifica_campi_core() - Intercetta modifiche ai campi core

Il modal #DeleteObj è il componente UI generico usato in tutto il tema per cestinare o eliminare definitivamente qualunque oggetto (post di qualsiasi CPT, media, ecc.).

È definito in elements/modals/modals.php e gestito in js/wp-api-client.js.

Come aprire il modal

Qualsiasi pulsante o link con data-toggle="modal" data-target="#DeleteObj" apre il modal. I parametri vengono passati tramite attributi data-*.

<button
  data-toggle="modal"
  data-target="#DeleteObj"
  data-objid="123"
  data-objtype="aziende"
  data-action="recycle"
  data-reloadlink="/aziende/"
  data-message="Vuoi davvero cestinare questa azienda?">
  Cestina
</button>

Parametri data-* disponibili

Attributo Obbligatorio Descrizione
data-objid ✓ ID numerico del post da eliminare
data-objtype ✓ Slug del CPT WordPress (es. aziende, acquisti, prenotazioni, media)
data-action ✓ Tipo di azione — vedi tabella sotto
data-reloadlink — URL a cui reindirizzare dopo l'operazione. Se omesso e ci si trova in una pagina singola, reindirizza all'archivio del CPT. Se impostato a stop non esegue nessun redirect.
data-message — Testo personalizzato che sostituisce il messaggio predefinito nel corpo del modal

Valori di data-action e comportamento

data-action Comportamento API call
recycle Cestina l'oggetto (WordPress Trash). L'elemento è recuperabile per 30 giorni. Mostra corpo "Sei sicuro di voler cestinare...". DELETE /wp/v2/{objtype}/{objid} con force=false
delete Elimina definitivamente l'oggetto. Mostra avviso rosso e richiede spunta di conferma prima di abilitare il pulsante. DELETE /wp/v2/{objtype}/{objid} con force=true
(omesso o altro valore) Imposta a bozza (draft) lo status del post, senza spostarlo nel cestino. Mostra corpo "cestina" (stesso del recycle). POST /wp/v2/{objtype}/{objid} con status=draft

Differenze visive tra le action

  • recycle: aggiunge classe CSS modal-warning al modal (colore giallo/arancio); mostra .body-recycle.
  • delete: mostra .body-delete con alert rosso e checkbox di conferma obbligatoria; il pulsante "Procedi e Cancella" rimane disabilitato finché l'utente non spunta #check_delete_ok.
  • default (draft): stesso aspetto del recycle (.body-recycle visibile, senza classe warning).

Esempi d'uso

Cestina un'azienda e torna all'archivio:

<a href="#"
   data-toggle="modal" data-target="#DeleteObj"
   data-objid="<?php echo $post->ID ?>"
   data-objtype="aziende"
   data-action="recycle"
   data-reloadlink="/aziende/">
  <i class="fa fa-trash"></i> Cestina
</a>

Elimina definitivamente un utilizzo (senza redirect):

<button
   data-toggle="modal" data-target="#DeleteObj"
   data-objid="<?php echo $utilizzo_id ?>"
   data-objtype="utilizzi"
   data-action="delete"
   data-reloadlink="stop"
   data-message="Stai per eliminare definitivamente questo utilizzo e il relativo residuo carnet non sarà ripristinato.">
  <i class="fa fa-times-circle"></i> Elimina
</button>

Imposta a bozza (disattiva) senza cestinare:

<a href="#"
   data-toggle="modal" data-target="#DeleteObj"
   data-objid="<?php echo $post->ID ?>"
   data-objtype="persone"
   data-message="Vuoi disattivare questa persona?">
  Disattiva
</a>

File di riferimento

  • pandora-theme/elements/modals/modals.php — HTML del modal
  • pandora-theme/js/wp-api-client.js — handler JS (show.bs.modal, hidden.bs.modal, click su #deleteConfirm)

Configurazione Stripe

Chiavi e webhook secret di Pandora Planning si definiscono in wp-config.php: esempio e istruzioni.

Nascondi contenuto nelle pagine

Shortcodes

[bcok_hidecontent user_has_prod="{product ID or product slug}" denial_message="Non puoi accedere"] contenuto da nascondere all'utente che ha acquistao il prodotto [/bcok_hide_content]

[bcok_hidecontent user_has_not_prod="{product ID or product slug}"] contenuto da nascondere all'utente che ha NON acquistao il prodotto [/bcok_hide_content]

Action Hook

Card

  • Quando la card viene abilitata
#!php

do_action('card_activated', $card_id, $card->post_parent);
  • Quando la card viene revocata/disabilitata
#!php

do_action('card_deactivated', $card->ID);
  • Quando la card viene riportata in bozza o viene cancellata (non dovrebbe mai succedere)
#!php

do_action('card_reset', $card_id);

IVA

  • Prima di verificare se il numero di P.Iva corrisponde a un'azienda in database:
#!php

apply_filters( 'check_vat_before_company_exists', true, $params['vat'], $params['country'] );

qualunque valore diverso da (bool) true interrompe la validazione e viene ritornato direttamente dalla funzione

  • Dopo aver verificato se il numero P.Iva corrisponde a una azienda in database:
#!php

apply_filters( 'check_vat_after_company_exists', $vat_is_valid, $params['vat'], $params['country'] );

Se l'azienda è in database $vat_is_valid contiene l'id azienda. Sennò è semplicemente (bool) true.