================================================================================
ASSINATURAS MADBUILDER — ANEXO DE REFERÊNCIA COMPLETO (v1.0)
Complementa o PROMPT DE GOVERNANÇA v4.1 — bloco <<<CONTEXTO_PROJETO>>>.
Uso: consultar quando precisar de assinatura detalhada não mantida inline no
prompt principal. NÃO substitui o prompt, NÃO altera regras, NÃO autoriza inferir.
Regras aplicáveis:
- R00 (anti-alucinação): ausente aqui E no código enviado → "ASSUNÇÃO: ..."
- R07: nunca inventar método/classe do framework
- R08: NÃO assumir estrutura de banco; só tabelas/campos explicitamente informados
- R38: contrato congelado de métodos compartilhados
- Se algo estiver aqui mas NÃO aparecer no código enviado, use apenas com
  "ASSUNÇÃO: <componente> conforme anexo, confirmar uso real".
================================================================================

<<<INICIO_INDICE>>>
01. Active Record (extensões)
02. TRepository / TCriteria / TFilter (extensões)
03. TTransaction (extensões)
04. Mensagens / Diálogos / Tradução
05. Sessão / Navegação
06. TWindow e parent (tela herdeira)
07. TForm (formulário)
08. Campos (TEntry, THidden, TLabel, THtmlEditor, TDate, TDateTime, TNumeric,
    TTime, TSpinner, TCombo, TDBCombo, TDBUniqueSearch, TDBSeekButton,
    TRadioGroup, TImage, TElement)
09. Botões e Ações
10. TDataGrid / BootstrapDatagridWrapper / TDataGridColumn / TDataGridAction
11. Layout (BContainer, BHelper, TVBox, TBreadCrumb, TPanelGroup, TPageNavigation)
12. Master Detail (AdiantiBaseMasterDetail)
13. Arquivos (AdiantiFileSaveTrait, TFile, MADThumbnailGallery)
14. Classes de projeto
15. Modelos conhecidos (referência; NÃO autoriza assumir estrutura)
16. Helpers JS e AJAX
17. Validações e bloqueios de campo
<<<FIM_INDICE>>>

<<<INICIO_01_ACTIVE_RECORD>>>
new Modelo();
new Modelo($key);
new Modelo($key, FALSE);
->fromArray((array) $data);
->store();
->delete();
->id;
->toArray();
->getVirtualData();
Modelo::find($id);
Modelo::where('campo','=',$v)->where(...)->first();
->last();
Modelo::where(...)->orderBy('campo','desc')->take(100)->load();
$registro->relacao->campo;
$pessoa->get_nome_cnpjcpf_idade();
<<<FIM_01_ACTIVE_RECORD>>>

<<<INICIO_02_REPOSITORY>>>
new TRepository('Modelo');
->load($criteria);
->load($criteria, FALSE);
->count($criteria);

new TCriteria;
clone $criteria;
->setProperties($param);
->setProperty('limit', $n);
->setProperty('order','campo asc');
->resetProperties();
->add($filter);
TCriteria::create(['campo' => $valor]);

new TFilter('campo','=',$valor);
new TFilter('campo','like',"%{$valor}%");
new TFilter('campo','IN',[..]);
<<<FIM_02_REPOSITORY>>>

<<<INICIO_03_TRANSACTION>>>
TTransaction::open(self::$database);
TTransaction::close();
TTransaction::rollback();
TTransaction::getDatabase();
TTransaction::isOpen(self::$database);

TTransaction::get() retorna PDO:
  ->prepare($sql);
  ->execute([':param' => $v]);
  ->fetch(PDO::FETCH_ASSOC);
  ->fetchColumn();

Padrão obrigatório (R03.3):
try {
    TTransaction::open(self::$database);
    ...
    TTransaction::close();
} catch (Exception $e) {
    if (TTransaction::isOpen(self::$database)) {
        TTransaction::rollback();
    }
    new TMessage('error', $e->getMessage());
}
<<<FIM_03_TRANSACTION>>>

<<<INICIO_04_MENSAGENS>>>
new TMessage('info' | 'warning' | 'error', $texto, $acaoOpcional, $tituloOpcional);
new TQuestion($texto, $acaoSim, $acaoNaoOpcional);
TToast::show("info", $html, "topRight", "fas:check");

AdiantiCoreTranslator::translate('Record saved');
AdiantiCoreTranslator::translate('Record deleted');
AdiantiCoreTranslator::translate('Do you really want to delete ?');

// Convenção do projeto: nome do usuário (TSession::getValue('username'))
// em negrito no INÍCIO de mensagens de erro e no TÍTULO da TMessage de sucesso.
<<<FIM_04_MENSAGENS>>>

<<<INICIO_05_SESSAO>>>
TSession::getValue('username');
TSession::getValue('userid');
TSession::getValue('userunitid');
TSession::setValue($k, $v);
TSession::delValue($k);

new TAction([$this, 'metodo'], ['static' => 1]);
new TAction([__CLASS__, 'metodo'], $param);
->setParameter($k, $v);
->setParameters($param);
->serialize(FALSE);

AdiantiCoreApplication::loadPage('Classe');
TApplication::loadPage('Classe', 'onShow');
<<<FIM_05_SESSAO>>>

<<<INICIO_06_TWINDOW>>>
TWindow::create($titulo, $largura, null);
->setProperty('class', 'window_modal');
->add($obj);
->show();
->getId();
TWindow::closeWindow($id);
TWindow::closeWindow();

// Métodos em classe que herda de TWindow (uso de parent::)
parent::setTitle($titulo);
parent::setSize(0.90, null);
parent::setProperty('class', 'window_modal');
parent::setCloseAction(new TAction([__CLASS__, 'onClose']));
parent::getId();
parent::add($form);
parent::closeWindow($id = null);
<<<FIM_06_TWINDOW>>>

<<<INICIO_07_TFORM>>>
$this->form->getData();
->setData($obj);
->validate();
->clear();
->clear(true);
->getField('campo');
->addField($campo);
->addFields([...], [...]);
->addContent([$el]);
->addAction($label, $action, $icone);
->appendPage($titulo);
->setTabFunction($js);
->setFormTitle($titulo);

TForm::sendData($formName, $objStd, $aggregate, $fireEvents);
<<<FIM_07_TFORM>>>

<<<INICIO_08_CAMPOS>>>
// TEntry
TEntry('campo');
->setSize('100%');
->setTip('...');
->setEditable(bool);
->setValue($v);
->forceUpperCase();
->setMaxLength(n);
->setMask('(99) 9 9999-9999', true);
->addValidation($label, new TRequiredValidator());
->setExitAction(new TAction([$this, 'metodo']));
->setChangeAction(new TAction([$this, 'metodo']));

// THidden
THidden('campo');

// TLabel
TLabel($texto, $cor, $tamanho, $estilo, $largura);
->setFontColor($cor);
->setFontStyle('b');
->setId();

// THtmlEditor
THtmlEditor('campo');
->setSize('100%', 250);

// TDate
TDate('campo');
->setMask('dd-mm-yyyy');
->setDatabaseMask('yyyy-mm-dd');

// TDateTime
TDateTime('campo');
->setMask('dd-mm-yyyy hh:ii');
->setDatabaseMask('yyyy-mm-dd hh:ii');

// TNumeric
TNumeric('campo', '2', '.', ',');
->setAllowNegative(false);

// TTime
TTime('campo');

// TSpinner
TSpinner('campo');
->setRange(0, 2000, 1);

// TCombo
TCombo('campo');
->addItems(['A' => 'Aberto']);
->enableSearch();
->setDefaultOption(false);

// TDBCombo
TDBCombo('campo', 'bdgestorweb', 'Modelo', 'id', '{campo}', 'campo asc', $criteria);
TDBCombo::reloadFromModel($formName, 'campo', 'bdgestorweb', 'Modelo', 'chave',
                         '{rel->campo}', 'id asc', $criteria | null, TRUE);

// TDBUniqueSearch
TDBUniqueSearch('campo', 'bdgestorweb', 'Modelo', 'id', 'coluna', 'ordem', $criteria);
->setMinLength(n);
->setFilterColumns(['col1', 'col2']);
->setMask('{id} - {name}');
->setChangeAction($action);

// TDBSeekButton
TDBSeekButton('campo', 'bdgestorweb', $formName, 'Modelo', 'campoExibido',
              'campoChave', 'campoDisplay', $criteria);
->setDisplayMask('{nome} - ...');
->setAuxiliar($campo);

// TRadioGroup
TRadioGroup('campo');
->setLayout('horizontal');
->setUseButton();
->setBreakItems(2);
->addItems([...]);

// TImage
TImage('app/images/imagem.png');
->src;
->width;
->height;
->id;

// TElement
TElement('div');
->class;
->style;
->add();
<<<FIM_08_CAMPOS>>>

<<<INICIO_09_BOTOES>>>
TButton;
->setAction(new TAction([$this, 'm'], [params]), $label);
->setImage('fas:x #000000');
->addStyleClass('btn-primary');
->setProperty('title', '...');
$button->id = '...';
<<<FIM_09_BOTOES>>>

<<<INICIO_10_DATAGRID>>>
// TDataGrid + BootstrapDatagridWrapper
new TDataGrid;
$wrapper = new BootstrapDatagridWrapper($grid);
$wrapper->generateHiddenFields();
$wrapper->setId('idGrid');
$wrapper->addColumn($column);
$wrapper->addAction($action);
$wrapper->createModel();
$wrapper->addItem($item);

// TDataGridColumn
new TDataGridColumn('campo', 'Título', 'alinhamento', 'largura');
->setVisibility(false);
->setTransformer(function($value, $object, $row, $cell = null, $last_row = null){ ... });
->enableTotal('sum', 'R$', 2, '.', ',');
->setTotalFormField('campo');

// TDataGridAction
new TDataGridAction(['Classe', 'metodo'], [params]);
->setImage('far:edit');
->setUseButton(false);
->setButtonClass(...);
->setLabel(...);

// Operações estáticas no grid
TDataGrid::replaceRowById($gridId, $rowId, $row);
TDataGrid::removeRowById($gridId, $rowId);

// TPageNavigation
new TPageNavigation($criteria);
<<<FIM_10_DATAGRID>>>

<<<INICIO_11_LAYOUT>>>
// BContainer — retorna $row; configurar layout depois
$row = new BContainer('nome');
$row->setTitle($titulo, $cor, $tamanho, $estilo, $corFundo);
$row->setBorderColor(...);
$row->addFields([...]);
$row->layout = ['col-sm-N', 'col-sm-M', ...];

// BHelper
$helper = new BHelper;
$helper->enableHover();
$helper->setSide('auto' | 'left');
$helper->setIcon(new TImage('fas:question #fa931f'));
$helper->setTitle(...);
$helper->setContent(...);
$helper->setSize('12');

// TVBox
new TVBox(...);

// TBreadCrumb
TBreadCrumb::create([...]);

// TPanelGroup
new TPanelGroup(...);
<<<FIM_11_LAYOUT>>>

<<<INICIO_12_MASTER_DETAIL>>>
// Action para chamar detalhe
new TDataGridAction(array('ClasseForm', 'onEditDetailMetodo'));
->setFields(['__row__id', '__row__data']);

// Métodos convencionados (por entidade):
onAddDetail[Entidade]();
onEditDetail[Entidade]();
onDeleteDetail[Entidade]();

// Persistência MasterDetail
->storeMasterDetailItems(...);
->loadMasterDetailItems(...);
<<<FIM_12_MASTER_DETAIL>>>

<<<INICIO_13_ARQUIVOS>>>
use Adianti\Base\AdiantiFileSaveTrait;
$this->saveFile($detailObject, $dataFile, 'campo', 'app/images/');

TFile::enableFileHandling();
TFile::setLimitUploadSize(1);
TFile::setAllowedExtensions([...]);
TFile::enableDropZone($html);

MADThumbnailGallery::render($value, [
    'enableModal' => true,
    'thumbnailWidth' => 150,
    'preventEventPropagation' => true,
    'modalOptions' => [...]
]);
<<<FIM_13_ARQUIVOS>>>

<<<INICIO_14_CLASSES_PROJETO>>>
SystemNotification::register($user_id, $titulo, $texto, $action_btn, $texto_btn,
                             $icon, $data_notificacao, $agendamento_id);
RelXxx::onGenerate(['key' => $id, ...]);
AgendamentoCalendarList02::manageRow($id);
<<<FIM_14_CLASSES_PROJETO>>>

<<<INICIO_15_MODELOS>>>
// ATENÇÃO: esta lista é APENAS referência de existência de classes no projeto.
// NÃO AUTORIZA ASSUMIR ESTRUTURA (R08). Campos sempre do código enviado.
Alergia
SystemUsers           (tipodeusuario = 'A' = administrador)
SystemUnit
SystemNotification
Pessoa
PessoaConvenioparceria
PessoaHorarios
PessoaObservacao
Orcamento
OrcamentoItem
PessoaExames
PessoaExamesitens
Produto
ProdutoFornecedorpreco
Agendamento
AgendamentoAnexos
AgendamentoTipo
Ambiente
Cobranca
Conta
Equipamento
Feriados
GuiasconvenioCab
GuiasconvenioItem
ProtocoloCab
ProtocoloItem
<<<FIM_15_MODELOS>>>

<<<INICIO_16_JS_AJAX>>>
// TScript SEMPRE em UMA linha, sem quebra, sem comentário interno,
// sem aspas duplas não escapadas. Dinâmico via json_encode(...) concatenado,
// string PHP entre aspas simples. Inteiros: (int)$valor.
// console.log de debug existentes NUNCA remover/alterar sem pedido explícito.
TScript::create("js");

__adianti_load_page(url);
__adianti_post_data(form, url);
__adianti_ajax_exec('class=X&method=Y&static=1');
__adianti_copy_to_clipboard(texto);
<<<FIM_16_JS_AJAX>>>

<<<INICIO_17_VALIDACOES>>>
new TRequiredValidator();
->addValidation($label, new TRequiredValidator());

TField::disableField($formName, 'campo');
TField::enableField($formName, 'campo');
TField::clearField($formName, 'campo');

TEntry::disableField($formName, 'campo');
TEntry::enableField($formName, 'campo');

TDateTime::disableField($formName, 'campo');

TCombo::disableField($formName, 'campo');
TCombo::enableField($formName, 'campo');
TCombo::clearField($formName, 'campo');
TCombo::reload($formName, 'campo', [$k => $v], $desabilitado = true | false);

TButton::disableField($formName, 'btn');
TButton::enableField($formName, 'btn');
<<<FIM_17_VALIDACOES>>>

<<<INICIO_REGRAS_APLICAVEIS>>>
Este anexo complementa o prompt principal. Todas as regras (R00–R38) continuam valendo.
- R00 (anti-alucinação): ausência aqui E no código enviado → "ASSUNÇÃO: ..."
- R07: nunca inventar método/classe do framework
- R08: campos sempre do código enviado; a lista de modelos em §15 NÃO autoriza inferir estrutura
- R38: contrato congelado de métodos compartilhados
- Se algo estiver aqui mas NÃO aparecer no código enviado, use com "ASSUNÇÃO: <componente>
  conforme anexo, confirmar uso real" — e liste a assinatura ao final da resposta.
- Ordem de consulta recomendada: código enviado → prompt principal → este anexo.
<<<FIM_REGRAS_APLICAVEIS>>>