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.
-
Pandora. La fondazione di BcOk. Plugin base per tutti gli altri. Implement ai Custom Post per le Richieste, le Segnalazioni, le Sedi. Implementa le tassonomie per le Aree geografiche, i servizi. Tutto ciò insieme alle leogiche di funzionamento di base. Qui si implementano anche le Notifiche, la blacklist delle email. e molto altro.
Plugin di terze parti (necessari)¶
- WP Mail SES [da fare]
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¶
- Schema in DIA [ancora tutto da fare]
- Struttura Virtuoso (vecchio schema non aggiornato)
Elementi:¶
Si tratta di Custom Post di WordPress
- Richieste
- Segnalazioni
- Sedi
- Aziende
- Persone
- Card
- Elenco Servizi
- Acquisti
- Utilizzi
- Notifiche
- Blacklist
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
Modal #DeleteObj — Eliminazione e Cestinazione Oggetti¶
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 CSSmodal-warningal modal (colore giallo/arancio); mostra.body-recycle.delete: mostra.body-deletecon 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-recyclevisibile, 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 modalpandora-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.