-- ============================================================================ -- Migration 016 -- Propagacao do snapshot do agente para tbl_HistPedido via TRIGGER -- ============================================================================ -- PRD: docs/PRDs/PRD-0006-propagacao-snapshot-agente/PRD-0006-propagacao-snapshot-agente.md -- ADR: docs/ADRs/ADR-0006-trigger-propagacao-snapshot-histpedido.md -- (extensao do ADR-0005 -- mesmo padrao aplicado a tbl_HistPedido) -- Card: INT#4 (roadmap) -- Data: 08/05/2026 -- Decidido por: Giovanny Porto (Stakeholder Leader) em 08/05/2026 noite, -- apos sessao consolidada da squad agente-pdd-engine. -- -- ============================================================================ -- ESCOPO -- ============================================================================ -- 1. ALTER TABLE tbl_HistPedido ADD 3 colunas snapshot do agente. -- 2. ADD INDEX em tbl_HistPedido.agente_cod_snap. -- 3. CREATE TRIGGER trg_agente_snapshot_histpedido_bi (BEFORE INSERT em tbl_HistPedido). -- -- Tabela alterada eh COMPARTILHADA com newportaltefnet (controllers PHP fazem -- INSERT via setProdutos() em insertPedido.php:234 e updatePedido.php:269). -- Com trigger, ZERO edit em controller eh necessario -- snapshot eh herdado -- automaticamente de tbl_Pedido pelo cod_Pedido. -- -- ============================================================================ -- DECISAO ARQUITETURAL -- POR QUE TRIGGER (ADR-0006, extensao de ADR-0005) -- ============================================================================ -- A squad analisou 3 opcoes em 08/05/2026 noite: -- -- (A) Edit-only PHP (caminho original do roadmap) -- Vantagem: simples, explicito. -- Desvantagem: caller-fragil (mesmo erro que ADR-0005 rejeitou); precisaria -- SELECT extra em updatePedido.php pra pegar snapshot atual de -- tbl_Pedido (insertPedido tem $agCodSnap na mao, updatePedido nao). -- Amplia superficie de bugs futuros (5+ versoes .bak no diretorio). -- Veredito: descartada -- mesma fragilidade de (B) do ADR-0005. -- -- (B) TRIGGER BEFORE INSERT em tbl_HistPedido <-- ESCOLHIDA -- Vantagem: atomicidade real (mesma transacao do INSERT); -- a prova de caller (qualquer rota PHP que insira recebe snapshot); -- consistente com ADR-0005 (tbl_Faturamento usa o mesmo padrao); -- zero alteracao em insertPedido.php / updatePedido.php; -- resiliente a refactor dos controllers. -- -- (C) Trigger + edit PHP redundante -- Vantagem: defesa em profundidade dupla. -- Desvantagem: over-engineering pra ganho marginal. -- Veredito: descartada. -- -- ============================================================================ -- WORKAROUNDS APLICADOS -- ============================================================================ -- 1. SET SESSION sql_mode = ''; -- tbl_HistPedido tem dados legados; ALTER em MySQL 8 strict pode quebrar -- em qualquer linha com valor invalido em coluna NOT NULL. Padrao registrado -- em memory: feedback_pdo_runner_nao_suporta_delimiter.md. -- -- 2. Trigger usa single-statement SET ... IFNULL (sem BEGIN/END/IF): -- runner sql/migrate.php usa PDO::exec() que NAO suporta DELIMITER. -- Funcionalidade identica via IFNULL(NEW.x, (SELECT...)) em 1 statement. -- -- ============================================================================ SET SESSION sql_mode = ''; -- ---------------------------------------------------------------------------- -- 1) ALTER TABLE tbl_HistPedido -- adicionar 3 colunas snapshot -- ---------------------------------------------------------------------------- -- Tipos espelham EXATAMENTE tbl_Pedido.agente_*_snap (definidos em Migration 002 -> 008) -- e tbl_Faturamento.agente_*_snap (definidos em Migration 014). -- COMMENT em cada coluna aponta pro trigger (defesa contra "esquecimento" por dev novo). ALTER TABLE tbl_HistPedido ADD COLUMN agente_cod_snap INT NULL DEFAULT NULL COMMENT '[satelite:agente] Snapshot do agente vinculado ao pedido pai (heranca de tbl_Pedido por cod_Pedido). Populado por trigger trg_agente_snapshot_histpedido_bi (ADR-0006). FK soft -> tbl_Representante.id (idNatureza=3)', ADD COLUMN agente_pct_snap DECIMAL(8,4) NULL DEFAULT NULL COMMENT '[satelite:agente] Snapshot do percentual do agente. Populado por trigger trg_agente_snapshot_histpedido_bi (ADR-0006)', ADD COLUMN agente_modalidade_snap ENUM('pct_venda','pct_comissao','tabela_preco') NULL DEFAULT NULL COMMENT '[satelite:agente] Snapshot da modalidade do agente. Populado por trigger trg_agente_snapshot_histpedido_bi (ADR-0006)', ADD INDEX idx_histpedido_agente_cod_snap (agente_cod_snap); -- ---------------------------------------------------------------------------- -- 2) CREATE TRIGGER trg_agente_snapshot_histpedido_bi -- ---------------------------------------------------------------------------- -- BEFORE INSERT em tbl_HistPedido (unico momento em MySQL onde SET NEW.* funciona). -- Le snapshot do pedido pai via NEW.cod_Pedido e popula NEW.agente_*_snap. -- -- Naming: trg____ -- trg_ -> prefixo padrao MySQL para trigger -- agente_ -> namespace satelite (ADR-0004) -- snapshot_histpedido -> funcao do trigger -- _bi -> sufixo "before insert" -- -- IMPORTANTE -- RELACIONAMENTO tbl_HistPedido.cod_Pedido -> tbl_Pedido.cod_Pedido -- (PK de tbl_Pedido eh cod_Pedido, NAO id -- mesmo padrao do INT#5). -- tbl_HistPedido.cod_Pedido eh INT NULL (callers de transicao podem omitir); -- nesse caso o SELECT retorna NULL e as 3 colunas em HistPedido ficam NULL. -- Comportamento desejado (apuracao ignora linhas sem snapshot). -- -- Pedidos pre-AG#4 com agente_cod_snap=NULL em tbl_Pedido -> SELECT retorna NULL -> -- coluna em tbl_HistPedido fica NULL. Comportamento desejado. -- -- IFNULL(NEW.x, ...) garante OVERRIDE EXPLICITO: se caller envia o valor explicitamente, -- trigger respeita (defesa pra backfill controlado e testes). DROP TRIGGER IF EXISTS trg_agente_snapshot_histpedido_bi; CREATE TRIGGER trg_agente_snapshot_histpedido_bi BEFORE INSERT ON tbl_HistPedido FOR EACH ROW SET NEW.agente_cod_snap = IFNULL( NEW.agente_cod_snap, (SELECT p.agente_cod_snap FROM tbl_Pedido p WHERE p.cod_Pedido = NEW.cod_Pedido LIMIT 1) ), NEW.agente_pct_snap = IFNULL( NEW.agente_pct_snap, (SELECT p.agente_pct_snap FROM tbl_Pedido p WHERE p.cod_Pedido = NEW.cod_Pedido LIMIT 1) ), NEW.agente_modalidade_snap = IFNULL( NEW.agente_modalidade_snap, (SELECT p.agente_modalidade_snap FROM tbl_Pedido p WHERE p.cod_Pedido = NEW.cod_Pedido LIMIT 1) ); -- ============================================================================ -- VERIFICACAO POS-MIGRATION (rodar manualmente apos `php sql/migrate.php up`) -- ============================================================================ -- 1) Conferir colunas em tbl_HistPedido: -- SHOW COLUMNS FROM tbl_HistPedido LIKE 'agente_%'; -- -> deve retornar: agente_cod_snap, agente_pct_snap, agente_modalidade_snap -- -- 2) Conferir indice criado: -- SHOW INDEX FROM tbl_HistPedido WHERE Key_name='idx_histpedido_agente_cod_snap'; -- -> deve retornar 1 linha -- -- 3) Conferir trigger criado: -- SHOW TRIGGERS LIKE 'tbl_HistPedido'; -- -> deve listar: trg_agente_snapshot_histpedido_bi (BEFORE INSERT) -- -- 4) Smoke teste (T2 do plano da Fernanda): -- SELECT cod_Pedido, agente_cod_snap, agente_pct_snap, agente_modalidade_snap -- FROM tbl_Pedido WHERE agente_cod_snap IS NOT NULL LIMIT 1; -- -- assumir cod_Pedido = X -- INSERT INTO tbl_HistPedido (cod_Pedido, incrementoRev, cod_Cliente, cod_Sublinha, -- cod_Revenda, cod_Produto, propriedadeEquip, tipoEquip, qtd_equip, valorEquip, -- vTotalLic, vfinal, formPag, condPag, obs, altPosAtual, nameConsultor, -- cpfConsultor, nameComprador, cpfComprador, nameDiretor, cpfDiretor, dataPed, statusPed) -- VALUES (X, 0, 0, 0, 0, 0, '', 0, 0, '', '', '', 0, 0, '', 0, '', '', '', '', '', '', NOW(), 'TESTE-INT4'); -- SELECT id, cod_Pedido, agente_cod_snap, agente_pct_snap, agente_modalidade_snap -- FROM tbl_HistPedido WHERE id = LAST_INSERT_ID(); -- -- esperado: 3 colunas populadas iguais as de tbl_Pedido WHERE cod_Pedido=X -- DELETE FROM tbl_HistPedido WHERE statusPed='TESTE-INT4';