docs: spiega la regola delle tabelle _lang nei Model e nel RecordTrait

Author: lucasalva87

src/Models/Module.php

@@ -31,6 +31,20 @@
 use Traits\ManagerTrait;
 use Traits\RecordTrait;
 
+/**
+ * Modulo installato nel gestionale.
+ *
+ * ## Campi traducibili – regola Dual Write
+ * I campi in {@see Module::$translated_fields} NON risiedono in questa tabella.
+ * Risiedono in `zz_modules_lang` (id_record, id_lang, title).
+ *
+ * Ogni INSERT su `zz_modules` DEVE essere seguito da un INSERT su `zz_modules_lang`:
+ * ```php
+ * $id = $dbo->insert('zz_modules', ['name' => 'mio_modulo', 'enabled' => 1]);
+ * $dbo->insert('zz_modules_lang', ['id_record' => $id, 'id_lang' => $id_lang, 'title' => 'Mio Modulo']);
+ * ```
+ * Per aggiornare una traduzione usa {@see \Traits\RecordTrait::setTranslation()}.
+ */
 class Module extends Model
 {
     use SimpleModelTrait;

src/Models/Setting.php

@@ -25,6 +25,20 @@
 use Traits\LocalPoolTrait;
 use Traits\RecordTrait;
 
+/**
+ * Impostazione di sistema.
+ *
+ * ## Campi traducibili – regola Dual Write
+ * I campi in {@see Setting::$translated_fields} NON risiedono in questa tabella.
+ * Risiedono in `zz_settings_lang` (id_record, id_lang, title, help).
+ *
+ * Ogni INSERT su `zz_settings` DEVE essere seguito da un INSERT su `zz_settings_lang`:
+ * ```php
+ * $id = $dbo->insert('zz_settings', ['nome' => 'mia_impostazione', 'valore' => '', 'tipo' => 'text']);
+ * $dbo->insert('zz_settings_lang', ['id_record' => $id, 'id_lang' => $id_lang, 'title' => 'Mia impostazione']);
+ * ```
+ * Per aggiornare una traduzione usa {@see \Traits\RecordTrait::setTranslation()}.
+ */
 class Setting extends Model
 {
     use SimpleModelTrait;

src/Models/View.php

@@ -25,6 +25,20 @@
 use Traits\RecordTrait;
 use Util\Query;
 
+/**
+ * Colonna/vista configurabile per le liste dei moduli.
+ *
+ * ## Campi traducibili – regola Dual Write
+ * I campi in {@see View::$translated_fields} NON risiedono in questa tabella.
+ * Risiedono in `zz_views_lang` (id_record, id_lang, title).
+ *
+ * Ogni INSERT su `zz_views` DEVE essere seguito da un INSERT su `zz_views_lang`:
+ * ```php
+ * $id = $dbo->insert('zz_views', ['id_module' => $id_module, 'name' => 'campo', 'query' => '...']);
+ * $dbo->insert('zz_views_lang', ['id_record' => $id, 'id_lang' => $id_lang, 'title' => 'Etichetta']);
+ * ```
+ * Per aggiornare una traduzione usa {@see \Traits\RecordTrait::setTranslation()}.
+ */
 class View extends Model
 {
     use SimpleModelTrait;

src/Traits/RecordTrait.php

@@ -24,6 +24,31 @@
 use Models\Module;
 use Models\Plugin;
 
+/**
+ * Gestione dei campi traducibili tramite tabelle `_lang`.
+ *
+ * ## Contratto Dual Write
+ * I Model che usano questo trait hanno campi traducibili (es. `title`, `descrizione`, `help`)
+ * che NON risiedono nella tabella principale ma in una tabella `<tabella>_lang` separata:
+ *
+ * ```
+ * Tabella principale:  zz_modules      (id, name, enabled, ...)
+ * Tabella traduzioni:  zz_modules_lang (id, id_record, id_lang, title)
+ * ```
+ *
+ * **Regola**: ogni INSERT sulla tabella principale DEVE essere seguito da un INSERT
+ * sulla tabella `_lang` corrispondente per ogni lingua disponibile.
+ * In caso contrario il campo traducibile risulterà vuoto nell'interfaccia.
+ *
+ * ## Metodi disponibili
+ * - {@see setTranslation()} – scrive/aggiorna una traduzione
+ * - {@see getTranslation()} – legge una traduzione
+ * - {@see save()}           – override: sincronizza automaticamente i `_lang` al salvataggio
+ *
+ * ## Quali Model usano questo trait
+ * Tutti i Model con la proprietà `$translated_fields` definita:
+ * `Module`, `Setting`, `View`, `Plugin`, `PrintTemplate` e i Model dei moduli in `src/`.
+ */
 trait RecordTrait
 {
     abstract public function getModuleAttribute();