@fontdata/ai-harness 4.3.0 → 4.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.claude-plugin/plugin.json +2 -2
  2. package/README.md +80 -2
  3. package/dist/config/config.js +37 -3
  4. package/dist/contratos/artefatos.js +13 -5
  5. package/dist/delphi/command.js +102 -1
  6. package/dist/delphi/encoding.js +112 -0
  7. package/dist/init.js +8 -2
  8. package/dist/install/perfis.js +14 -0
  9. package/dist/install/plan.js +29 -2
  10. package/dist/install/settings.js +40 -3
  11. package/dist/update/update.js +69 -7
  12. package/package.json +1 -1
  13. package/templates/catalog.json +3 -0
  14. package/templates/perfis/delphi/hooks/encoding.mjs +317 -0
  15. package/templates/perfis/delphi/rules/build-e-verificacao.md +59 -0
  16. package/templates/perfis/delphi/rules/dados/cnpj-alfanumerico-nao-extrair-so-numeros.md +65 -0
  17. package/templates/perfis/delphi/rules/dados/data-hora-sql-nunca-round-trip-textual.md +78 -0
  18. package/templates/perfis/delphi/rules/dados/datestyle-sessao-firedac-postgres.md +60 -0
  19. package/templates/perfis/delphi/rules/dados/ddl-tabela-nova-exige-trigger-de-log.md +68 -0
  20. package/templates/perfis/delphi/rules/dados/divisao-e-conversao-numerica.md +53 -0
  21. package/templates/perfis/delphi/rules/dados/fieldbyname-value-variant-cru-em-aritmetica.md +73 -0
  22. package/templates/perfis/delphi/rules/dados/filtro-condicional-sql-par-add-parambyname.md +72 -0
  23. package/templates/perfis/delphi/rules/dados/firedac.md +51 -0
  24. package/templates/perfis/delphi/rules/dados/macro-firedac-exige-entrada-macrodata.md +96 -0
  25. package/templates/perfis/delphi/rules/dados/sql-qualificacao-colunas.md +36 -0
  26. package/templates/perfis/delphi/rules/dados/tmeminifile-getstrings-nao-limpa-destino.md +89 -0
  27. package/templates/perfis/delphi/rules/encoding-eol.md +130 -0
  28. package/templates/perfis/delphi/rules/linguagem/dataset-nao-se-le-depois-do-laco-eof.md +56 -0
  29. package/templates/perfis/delphi/rules/linguagem/existencia-nunca-se-testa-por-campo-formatado.md +60 -0
  30. package/templates/perfis/delphi/rules/linguagem/float-nunca-comparado-por-igualdade-com-literal.md +55 -0
  31. package/templates/perfis/delphi/rules/linguagem/literal-enum-de-dfm-exige-unit-no-uses.md +84 -0
  32. package/templates/perfis/delphi/rules/linguagem/reaproveitar-funcao-existente-antes-de-criar.md +172 -0
  33. package/templates/perfis/delphi/rules/linguagem/sem-clipboard-debug.md +43 -0
  34. package/templates/perfis/delphi/rules/linguagem/validacao-em-onexit-nao-protege-a-gravacao.md +65 -0
  35. package/templates/perfis/delphi/rules/linguagem/variavel-inline-sai-de-escopo-ao-envolver-bloco.md +69 -0
  36. package/templates/perfis/delphi/rules/telas/foco-decisao-por-canfocus-nao-tabstop.md +40 -0
  37. package/templates/perfis/delphi/rules/telas/form-dinamico-liberar-em-toda-saida.md +80 -0
  38. package/templates/perfis/delphi/rules/telas/heranca-de-form-e-grade-de-selecao.md +58 -0
  39. package/templates/perfis/delphi/rules/threads-e-timers.md +131 -0
  40. package/templates/perfis/delphi/rules/try-finally-e-vazamento.md +109 -0
  41. package/templates/perfis/delphi/skills/conhecimento-delphi/SKILL.md +64 -0
  42. package/templates/perfis/delphi/skills/conhecimento-delphi/references/ATRIBUICAO.md +29 -0
  43. package/templates/perfis/delphi/skills/conhecimento-delphi/references/acbr-nfce-integracao.md +60 -0
  44. package/templates/perfis/delphi/skills/conhecimento-delphi/references/build-via-bat-com-log.md +86 -0
  45. package/templates/perfis/delphi/skills/conhecimento-delphi/references/class-var-vaza-para-campos-de-instancia.md +73 -0
  46. package/templates/perfis/delphi/skills/conhecimento-delphi/references/componentes-designer-vs-runtime.md +47 -0
  47. package/templates/perfis/delphi/skills/conhecimento-delphi/references/console-writeln-sem-flush-nao-loga.md +47 -0
  48. package/templates/perfis/delphi/skills/conhecimento-delphi/references/conversao-numerica-locale.md +47 -0
  49. package/templates/perfis/delphi/skills/conhecimento-delphi/references/delphi13-breaking-changes.md +41 -0
  50. package/templates/perfis/delphi/skills/conhecimento-delphi/references/dpr-uses-project-manager.md +62 -0
  51. package/templates/perfis/delphi/skills/conhecimento-delphi/references/dproj-dcc-debuginformation-nao-booleano.md +78 -0
  52. package/templates/perfis/delphi/skills/conhecimento-delphi/references/dproj-projectguid-valido.md +38 -0
  53. package/templates/perfis/delphi/skills/conhecimento-delphi/references/firedac-registro-drivers.md +94 -0
  54. package/templates/perfis/delphi/skills/conhecimento-delphi/references/horse-gbswagger-rotas-jwt.md +61 -0
  55. package/templates/perfis/delphi/skills/conhecimento-delphi/references/msb6003-command-line-too-long.md +52 -0
  56. package/templates/perfis/delphi/skills/conhecimento-delphi/references/recursos-rcdata.md +67 -0
  57. package/templates/skills/resolver-bug/SKILL.md +8 -2
@@ -0,0 +1,78 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): data/hora em SQL se compõe por aritmética de tipos
11
+
12
+ Nunca por round-trip textual (`to_char` + `CAST`). Aplica-se a todo SQL, montado em código ou gravado no
13
+ `SQL.Strings` de um `.dfm`, que **reconstrói** um `date`/`time`/`timestamp` a partir de texto. O caso
14
+ típico é juntar data e hora guardadas em duas colunas numa única coluna "Data/Hora" de relatório.
15
+ Complementa `datestyle-sessao-firedac-postgres.md`.
16
+
17
+ ## `CAST(to_char(...) || ... AS timestamp)` fica à mercê do `DateStyle`
18
+
19
+ Formatar uma data para texto e reconverter o texto para data descarta a tipagem e entrega a interpretação
20
+ ao `DateStyle` da sessão. `'DD/MM/YYYY'` só volta a ser aquela data se a sessão estiver em `DMY`:
21
+
22
+ ```sql
23
+ -- ERRADO: depende do DateStyle; em sessão MDY, dia 19 vira mês 19
24
+ CAST(to_char(pedidos.data_emissao, 'DD/MM/YYYY') || ' ' ||
25
+ to_char(pedidos.hora_emissao, 'HH24:MI:SS') AS timestamp without time zone)
26
+
27
+ -- CERTO: aritmética de tipos, date + time = timestamp, sem texto no meio
28
+ pedidos.data_emissao::date + pedidos.hora_emissao::time
29
+ ```
30
+
31
+ As duas expressões produzem `timestamp without time zone`, então alias, tipo do `TField` e layout do
32
+ relatório não mudam. A troca é segura em relatório já em produção.
33
+
34
+ Vale para todas as formas: `to_date(to_char(...))`, `CAST(<texto> AS date)`, `<coluna>::text::date`.
35
+ Formatar para **exibir** (`to_char` que termina em texto) continua correto. O defeito é formatar e
36
+ **voltar** a um tipo temporal.
37
+
38
+ ## Defeito assimétrico: não estoura, mente
39
+
40
+ Com dia **≤ 12**, a string é ambígua mas válida: `05/08/2026` é lido como 8 de maio, o relatório imprime
41
+ normalmente e a data sai trocada. Só a partir do dia **13** o `CAST` estoura:
42
+
43
+ ```
44
+ ERRO: valor do campo date/time está fora do intervalo: "19/08/2026 15:11:05".
45
+ Talvez você necessite de uma definição diferente para "datestyle"
46
+ ```
47
+
48
+ > Ao investigar `date/time field value out of range` / `date/time está fora do intervalo`, a **primeira**
49
+ > busca é por `to_char` seguido de `CAST` na query que falhou, antes de suspeitar do dado, da coluna ou do
50
+ > `postgresql.conf`. A mensagem sugere reconfigurar o `datestyle`: é o mecanismo, não a causa.
51
+
52
+ Não presuma que os dias ≤ 12 estavam certos: se o defeito viveu numa sessão MDY, eles saíam com dia e mês
53
+ invertidos, em silêncio. Ao corrigir, teste os dois lados do limiar: dia > 12 (o que estourava) **e**
54
+ dia ≤ 12 (o que "funcionava").
55
+
56
+ ## Fixar o `DateStyle` da sessão não dispensa esta regra
57
+
58
+ Fixar `SET SESSION DateStyle TO 'ISO, DMY'` no `AfterConnect` (ver `datestyle-sessao-firedac-postgres.md`)
59
+ é salvaguarda de ambiente, não licença para escrever SQL que dependa dela. Basta um executável antigo em
60
+ campo, uma conexão que não passou pelo handler ou uma ferramenta externa rodando a mesma query para o
61
+ valor voltar a depender de configuração. SQL que não precisa do `DateStyle` não quebra em nenhum desses
62
+ casos.
63
+
64
+ ## Antes de fechar
65
+
66
+ - `grep -n "to_char" <Unit>.dfm <Unit>.pas`: nenhuma ocorrência pode terminar em
67
+ `CAST(... AS date|time|timestamp)` nem alimentar `to_date`/`to_timestamp`.
68
+ - Corrija as queries gêmeas juntas. Relatório com par runtime + design-time copia o mesmo SELECT;
69
+ corrigir só uma deixa a outra quebrada.
70
+ - Valide executando, com a sessão no pior cenário:
71
+
72
+ ```sql
73
+ SET SESSION DateStyle TO 'ISO, MDY';
74
+ SELECT <a nova expressão>, pg_typeof(<a nova expressão>);
75
+ ```
76
+
77
+ Confira o valor e o `pg_typeof`: o tipo tem de ser idêntico ao da expressão anterior, senão o `TField`
78
+ do dataset e o layout mudam junto.
@@ -0,0 +1,60 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): garantir `DateStyle 'ISO, DMY'` na sessão FireDAC/PostgreSQL
11
+
12
+ Aplica-se à conexão principal PostgreSQL do projeto e a qualquer literal de data montado em SQL.
13
+ Complementa `firedac.md` e `data-hora-sql-nunca-round-trip-textual.md`.
14
+
15
+ ## A sessão FireDAC não herda o `DateStyle` do servidor: force-o no `AfterConnect`
16
+
17
+ Mesmo com `datestyle = 'ISO, DMY'` no `postgresql.conf` (e `SHOW datestyle` confirmando no servidor), a
18
+ sessão aberta pelo driver PostgreSQL do FireDAC pode assumir **MDY**. Nesse caso, todo literal de data em
19
+ `dd/mm/yyyy` no SQL (ex.: `CAST(COALESCE(precos.data_validade, '31/12/2050') AS date)`) é rejeitado:
20
+
21
+ ```
22
+ ERROR: date/time field value out of range: "31/12/2050". Perhaps you need a different "DateStyle" setting.
23
+ ```
24
+
25
+ porque `31` é lido como **mês**. Ajustar só o `postgresql.conf` não resolve: a sessão do cliente
26
+ sobrescreve o padrão do servidor. Overrides por banco (`pg_database.datconfig`) ou por role
27
+ (`pg_roles.rolconfig`) também não são o remédio, porque a sessão FireDAC ainda pode divergir.
28
+
29
+ ### Padrão obrigatório
30
+
31
+ O `AfterConnect` da conexão principal fixa o `DateStyle` da sessão logo no início, antes de qualquer
32
+ outra query:
33
+
34
+ ```pascal
35
+ procedure TDmConexao.FDConnectionAfterConnect(Sender: TObject);
36
+ begin
37
+ FDConnection.ExecSQL('SET SESSION DateStyle TO ''ISO, DMY''');
38
+ // ... demais inicializações da sessão ...
39
+ end;
40
+ ```
41
+
42
+ - **`ISO, DMY` é o par certo:** a **saída** fica em ISO (`2050-12-31`, lida sem ambiguidade pelo FireDAC)
43
+ e a **entrada** em DMY (aceita `dd/mm/yyyy` do locale brasileiro).
44
+ - **Idempotente e barato:** roda a cada conexão física (login, conexões auxiliares, reconexão automática
45
+ por `OnRecover`/`faRetry`). Rodar mais de uma vez não tem efeito colateral.
46
+ - Deixa o sistema imune ao `datestyle` padrão de qualquer servidor de cliente.
47
+ - Use `ExecSQL` direto na conexão, não uma `TFDQuery` avulsa.
48
+
49
+ ## Prefira parâmetro ou ISO a literal de data localizado
50
+
51
+ Em SQL **novo**, monte data com `:Param` (o FireDAC envia o valor tipado, sem depender de `DateStyle`) ou
52
+ com literal ISO `yyyy-mm-dd` (sem ambiguidade em qualquer `DateStyle`). **Nunca** concatene `dd/mm/yyyy`
53
+ contando com o `DateStyle` do servidor. A fixação da sessão tolera o literal localizado que já existe; não
54
+ é motivo para escrever mais.
55
+
56
+ ## Antes de fechar
57
+
58
+ - Confirme que a fixação está no `AfterConnect`, que dispara em toda sessão física nova.
59
+ - O erro só aparece em runtime, ao conectar num servidor cuja sessão não esteja em DMY; nunca na
60
+ compilação. Teste reconectando e reproduzindo um fluxo que monte literal `dd/mm/yyyy`.
@@ -0,0 +1,68 @@
1
+ ---
2
+ descricao: "Script que cria tabela também cria a trigger de auditoria/log que o banco já usa nas outras tabelas"
3
+ paths:
4
+ - "**/*.sql"
5
+ - "**/*.pas"
6
+ ---
7
+
8
+ # Regra (camada de dados): toda tabela nova ganha a trigger de log que o banco já usa
9
+
10
+ Aplica-se a todo script SQL (e a todo DDL montado em `.pas`) que cria tabela com `CREATE TABLE`, quando o banco do
11
+ projeto registra alterações por trigger de auditoria/log nas tabelas existentes.
12
+
13
+ ## Descubra o padrão antes de escrever
14
+
15
+ Não invente nome nem função de trigger. Consulte o banco (ou um dump do esquema) e repita o que as outras tabelas
16
+ já têm:
17
+
18
+ ```sql
19
+ -- nome de trigger mais comum e a função que ele chama (PostgreSQL)
20
+ SELECT trigger_name, action_statement, count(DISTINCT event_object_table) AS tabelas
21
+ FROM information_schema.triggers
22
+ GROUP BY trigger_name, action_statement
23
+ ORDER BY tabelas DESC;
24
+
25
+ -- alternativa pelo catálogo
26
+ SELECT t.tgname, p.proname, count(*) AS tabelas
27
+ FROM pg_trigger t
28
+ JOIN pg_proc p ON p.oid = t.tgfoid
29
+ WHERE NOT t.tgisinternal
30
+ GROUP BY t.tgname, p.proname
31
+ ORDER BY tabelas DESC;
32
+ ```
33
+
34
+ Se nenhuma trigger aparece em várias tabelas, o projeto não tem esse padrão e esta regra não se aplica. Se aparecem
35
+ padrões concorrentes, pergunte ao usuário qual vale para tabela nova.
36
+
37
+ ## Padrão obrigatório
38
+
39
+ Logo depois das tabelas do script, uma trigger por tabela criada, com o mesmo nome, o mesmo evento (`AFTER UPDATE`,
40
+ `AFTER INSERT OR UPDATE OR DELETE`, o que o banco já usa) e a mesma função. Num banco que usa a trigger `eventos_log`
41
+ com a função `grava_log_tabelas()`, fica assim:
42
+
43
+ ```sql
44
+ CREATE OR REPLACE TRIGGER eventos_log
45
+ AFTER UPDATE ON <tabela>
46
+ FOR EACH ROW EXECUTE FUNCTION grava_log_tabelas();
47
+ ```
48
+
49
+ - `CREATE OR REPLACE TRIGGER` deixa o script reaplicável, como o `CREATE TABLE IF NOT EXISTS` das tabelas. Exige
50
+ PostgreSQL 14 ou mais novo; em versão anterior, use `DROP TRIGGER IF EXISTS` seguido de `CREATE TRIGGER`.
51
+ - Vale também para tabela filha (itens, pagamentos, eventos), não só para a principal.
52
+
53
+ ## Por que escapa
54
+
55
+ O script cria a tabela, a tela grava e nada falha. A falta da trigger só aparece quando o suporte precisa saber quem
56
+ alterou um registro e o log daquela tabela está vazio.
57
+
58
+ ## Antes de fechar
59
+
60
+ Conte as tabelas criadas e as triggers no script, com o nome da função descoberta:
61
+
62
+ ```bash
63
+ grep -ci "CREATE TABLE" <script>.sql
64
+ grep -ci "EXECUTE FUNCTION <funcao_de_log>()" <script>.sql
65
+ ```
66
+
67
+ As duas contagens são iguais. Se validar o script num banco de teste que não tem a função de log, crie antes uma
68
+ versão vazia dela só para o teste.
@@ -0,0 +1,53 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados/cálculo): divisão segura e conversão numérica de campos
11
+
12
+ Aplica-se a todo cálculo que (a) divide valores e atribui o resultado a um campo `Currency`/BCD de
13
+ `TFDQuery`/`TFDMemTable`, ou (b) lê campos numéricos de dataset. Complementa
14
+ `fieldbyname-value-variant-cru-em-aritmetica.md`.
15
+
16
+ ## 1. Nunca dividir sem proteger o divisor
17
+
18
+ Antes de qualquer divisão cujo resultado vá para um campo numérico (`AsCurrency`, `AsFloat`, `AsBCD`),
19
+ garanta que o divisor não é zero nem Null:
20
+
21
+ - divisor **zero** produz `NaN`/infinito, e ao atribuir em campo BCD/Currency o Delphi lança
22
+ `NAN is not a valid BCD value`;
23
+ - agregado (`TAggregateField`) ou campo **sem registros** devolve **Null**, e a divisão lança
24
+ `Could not convert variant of type (Null) into type (Currency)`.
25
+
26
+ ```pascal
27
+ if LDivisor <> 0 then
28
+ LResultado := LDividendo / LDivisor
29
+ else
30
+ LResultado := 0; // ou o fallback semanticamente correto
31
+ ```
32
+
33
+ - Ao usar `TAggregateField.Value` (ou qualquer `.Value` Variant), trate o Null **antes** de calcular: leia
34
+ em variável local tratando Null como 0 (ex.: `VarIsNull`).
35
+ - Os dois erros só aparecem em runtime, nunca na compilação. Surgem nas bordas (grid vazia, primeiro item,
36
+ quantidade 0) e com muitos itens, onde a chance de um divisor zerado cresce.
37
+
38
+ ## 2. Não truncar valores fracionários com `.AsInteger`
39
+
40
+ Quantidade, peso, volume, custo e percentual são fracionários (`TFloatField`, `TCurrencyField`,
41
+ `TBCDField`). Leia com `.AsFloat` ou `.AsCurrency`, nunca `.AsInteger`: ele trunca (12,365 kg vira 12),
42
+ pode zerar divisores e distorce cálculos como custo médio.
43
+
44
+ - Confira o tipo do campo e o do parâmetro ou destino, e use o acessor compatível e consistente com os
45
+ demais acessos ao mesmo campo na unit.
46
+
47
+ ```pascal
48
+ // ERRADO: trunca o peso e pode zerar o divisor
49
+ LQtd := Query.FieldByName('quantidade').AsInteger;
50
+
51
+ // CERTO
52
+ LQtd := Query.FieldByName('quantidade').AsFloat;
53
+ ```
@@ -0,0 +1,73 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): `FieldByName(...).Value` em aritmética estoura com NULL
11
+
12
+ Use acessor tipado. Aplica-se a todo código que lê campo de dataset (`TFDQuery`, `TFDMemTable`,
13
+ `TClientDataSet` legado) e usa o valor em conta: soma, subtração, multiplicação, divisão ou comparação com
14
+ número. Complementa `divisao-e-conversao-numerica.md`.
15
+
16
+ ## `.Value` devolve Variant cru, e Variant `Null` em conta lança exceção
17
+
18
+ `System.Variants.NullStrictConvert` é `True` por padrão. Com isso, um Variant `Null` numa operação
19
+ aritmética não vira `Null` nem `0`: lança `EVariantTypeCastError` com a mensagem
20
+
21
+ ```
22
+ Could not convert variant of type (Null) into type (Double)
23
+ ```
24
+
25
+ Os acessores tipados não têm o problema: `.AsFloat`, `.AsCurrency`, `.AsInteger` e `.AsString` já
26
+ convertem campo NULL para `0` / `''`.
27
+
28
+ ```pascal
29
+ // ERRADO: qualquer um dos três campos NULL derruba a rotina inteira
30
+ if (FieldByName('TOTAL').Value + FieldByName('DESCONTO').Value + FieldByName('ACRESCIMO').Value) > 0 then
31
+
32
+ // CERTO: lido uma vez, em variável local tipada
33
+ LTotal := FieldByName('TOTAL').AsFloat;
34
+ LDesconto := FieldByName('DESCONTO').AsFloat;
35
+ LAcrescimo := FieldByName('ACRESCIMO').AsFloat;
36
+ if (LTotal + LDesconto + LAcrescimo) > 0 then
37
+ ```
38
+
39
+ Escolha do acessor: quantidade, peso, volume e percentual → `.AsFloat`; valor monetário → `.AsCurrency`;
40
+ nunca `.AsInteger` em campo fracionário (trunca; ver `divisao-e-conversao-numerica.md`).
41
+
42
+ `.Value` continua legítimo em variável de componente (variável de relatório, `TParam.Value`) e quando o
43
+ Variant é o próprio tipo desejado. O critério é: **este valor vai entrar numa conta?**
44
+
45
+ ## O sintoma engana: parece problema de dado
46
+
47
+ O erro só aparece quando **um** registro NULL entra no resultado. Como relatórios filtram por período, o
48
+ efeito é "um mês funciona, o outro não" ou "a partir de tal dia quebra". Isso empurra a investigação para
49
+ o banco, à caça do "registro com problema", em vez de para o código.
50
+
51
+ Pior: numa expressão como `total - desconto - imposto - frete`, **qualquer** operando NULL quebra a conta.
52
+ Corrigir o campo suspeito não resolve se o NULL está em outro operando, e a hipótese certa é descartada
53
+ por parecer refutada.
54
+
55
+ > Ao investigar `Could not convert variant of type (Null) into type (<tipo>)`, a **primeira** hipótese é
56
+ > esta. Rode `grep -n "FieldByName(.*)\.Value" <Unit>.pas` na unit da tela antes de procurar o registro
57
+ > culpado no banco.
58
+
59
+ ## Corrigir no Pascal basta; `COALESCE` no SQL é escolha
60
+
61
+ Com acessores tipados, o NULL já vira 0 em todos os pontos de leitura. `COALESCE(..., 0)` no SELECT é
62
+ defesa extra opcional, com custo próprio: envolver em `coalesce(...)` uma coluna sem alias faz o
63
+ PostgreSQL renomeá-la para `coalesce`, o que quebra todo `FieldByName('<NOME>')`. Cada coluna tocada
64
+ precisa ganhar `AS <nome_original>`.
65
+
66
+ Antes de propor o `COALESCE`, veja se ainda resta consumidor sem proteção (somatórios, cópia para
67
+ `TFDMemTable`, campos calculados do relatório). Se todos já usam acessor tipado, o `COALESCE` é cosmético.
68
+
69
+ ## Antes de fechar
70
+
71
+ - `grep -n "FieldByName(.*)\.Value"` na unit inteira: **zero** ocorrências em expressão aritmética.
72
+ - Teste o caso que reproduzia o erro **e** um que já funcionava. O segundo é o teste de regressão que
73
+ importa, porque a leitura mudou de Variant para tipo fixo.
@@ -0,0 +1,72 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): filtro condicional em SQL montado em código
11
+
12
+ `SQL.Add` e `ParamByName` são um par indivisível, e queries gêmeas recebem o filtro juntas.
13
+
14
+ Aplica-se a toda `TFDQuery` cujo SQL é montado em código com filtros condicionais, o padrão comum das
15
+ telas de relatório e consulta: cada filtro preenchido na tela vira um `if <preenchido> then SQL.Add(...)`.
16
+ Complementa `sql-qualificacao-colunas.md`.
17
+
18
+ ## O par é indivisível e mora em dois blocos distantes
19
+
20
+ A montagem separa o SQL dos parâmetros em dois blocos, muitas vezes a dezenas de linhas um do outro:
21
+
22
+ ```pascal
23
+ if EditCodCliente.Text <> '000000' then
24
+ SQL.Add(' AND pedidos.cod_cliente = :cod_cliente ');
25
+ // ... 20+ linhas de GROUP BY / ORDER BY ...
26
+ if EditCodCliente.Text <> '000000' then
27
+ ParamByName('cod_cliente').AsInteger := StrToInt(EditCodCliente.Text);
28
+ ```
29
+
30
+ Um filtro novo exige **duas** edições, em dois lugares. Nada no compilador liga uma à outra, e o
31
+ esquecimento quebra nos dois sentidos:
32
+
33
+ - `SQL.Add` **sem** `ParamByName`: o FireDAC chega ao `Prepare`/`Execute` com um parâmetro sem tipo nem
34
+ valor:
35
+ `[FireDAC][Phys][PG]-335. Parameter [X] data type is unknown. Hint: specify TFDParam.DataType or assign TFDParam value before Prepare/Execute call`
36
+ - `ParamByName` **sem** `SQL.Add`: `Parameter 'X' not found` quando a condição do parâmetro é verdadeira e
37
+ a do SQL não.
38
+
39
+ **As duas guardas têm de ser idênticas**: mesma expressão, mesmo literal de "vazio" (`'0000'`,
40
+ `'000000'`). Guardas divergentes funcionam no caminho testado e estouram na borda.
41
+
42
+ ## Checklist antes de fechar
43
+
44
+ ```bash
45
+ grep -n ":<nome_do_parametro>" <Unit>.pas
46
+ ```
47
+
48
+ Deve retornar **exatamente 2 ocorrências por query**: a do `SQL.Add` e a do `ParamByName`. Uma só é o
49
+ defeito desta regra. Numa unit com query de detalhe e de totais, espere 4.
50
+
51
+ ## Queries gêmeas do mesmo relatório recebem o filtro juntas
52
+
53
+ Um relatório costuma ter mais de uma query: a do detalhe e a de totais (ou de sub-relatório), cada uma
54
+ com sua cópia dos mesmos filtros. Pôr o filtro só no detalhe produz um defeito pior que um erro, porque
55
+ não há erro:
56
+
57
+ - o detalhe mostra só o recorte filtrado;
58
+ - o rodapé de totais soma o universo inteiro do período;
59
+ - o usuário lê aquele total como sendo o do filtro que escolheu.
60
+
61
+ Ao acrescentar um filtro, `grep -n "SQL.Add" <Unit>.pas` e confirme quantas queries a unit monta. O
62
+ filtro entra em **todas** as que alimentam o mesmo relatório. Se alguma ficar de fora de propósito,
63
+ registre o motivo no documento do trabalho: divergência sem registro entre queries gêmeas é bug latente.
64
+
65
+ ## Ao investigar `[FireDAC][Phys][PG]-335 ... data type is unknown`
66
+
67
+ A primeira hipótese é esta: procure o `ParamByName` daquele parâmetro. Se não houver nenhum, o problema
68
+ não é do driver, do tipo da coluna nem de `TFDParam.DataType` (que a mensagem sugere e levaria a
69
+ "consertar" o sintoma). É a atribuição que nunca foi escrita.
70
+
71
+ O sintoma aparece só em runtime e só quando o filtro é preenchido. O caminho "todos" nunca declara o
72
+ parâmetro e sempre funciona, o que esconde o defeito de qualquer teste que não use o filtro específico.
@@ -0,0 +1,51 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): FireDAC
11
+
12
+ Aplica-se a DataModules e a todo código que abre conexão, monta query ou grava dados com FireDAC.
13
+
14
+ ## `TFDQuery` com `CachedUpdates` substitui o `TClientDataSet`
15
+
16
+ Com `CachedUpdates` ativo, o `TFDQuery` guarda as alterações em memória e as grava com
17
+ `ApplyUpdates`/`CommitUpdates`. Ele faz o papel do antigo par `TDataSetProvider` + `TClientDataSet`.
18
+
19
+ - **Não** introduza `TDataSetProvider`/`TClientDataSet` em código novo. Código legado que ainda os usa
20
+ não é modelo a copiar.
21
+ - **Use a conexão central do projeto** (o DataModule que guarda a `TFDConnection` principal). Não crie
22
+ `TFDConnection` avulsa: ela foge da configuração de sessão feita no `AfterConnect` (ver
23
+ `datestyle-sessao-firedac-postgres.md`) e do controle de transação.
24
+ - **Exceção: thread de fundo.** A `TFDConnection` não é thread-safe, então thread de fundo usa uma
25
+ conexão própria, criada e liberada dentro da thread (ver `threads-e-timers.md`). Essa conexão replica a
26
+ inicialização de sessão que o `AfterConnect` da conexão central faz (ex.: o `DateStyle` de
27
+ `datestyle-sessao-firedac-postgres.md`), seja ligando o mesmo handler, seja chamando a mesma rotina.
28
+ - **Sempre parâmetros `:Param`** no SQL. Nunca concatene valores na string: abre injeção de SQL, impede
29
+ o reaproveitamento do plano e torna data e número dependentes do locale.
30
+ - Siga a língua e o padrão de nomes do schema existente nos nomes de campos e aliases.
31
+
32
+ ```pascal
33
+ // ERRADO
34
+ Query.SQL.Text := 'SELECT * FROM pedidos WHERE cod_cliente = ' + IntToStr(LCodigo);
35
+
36
+ // CERTO
37
+ Query.SQL.Text := 'SELECT * FROM pedidos WHERE cod_cliente = :cod_cliente';
38
+ Query.ParamByName('cod_cliente').AsInteger := LCodigo;
39
+ ```
40
+
41
+ ## DataModule é unit de alto fan-in
42
+
43
+ DataModules costumam ser usados por dezenas de telas. Antes de mudar a `interface` de um DM (assinatura
44
+ de método, nome de componente publicado, campo persistente), mapeie **todos** os chamadores com `grep`
45
+ no projeto inteiro. Renomear um componente quebra também os `.dfm` e o código que o referencia por nome.
46
+
47
+ ## Acoplamento invertido existente
48
+
49
+ Em código legado, DataModules às vezes abrem diálogos de confirmação ou seleção no meio de uma gravação.
50
+ É um desenho ruim, mas o fluxo depende dele: preserve-o e não o "conserte" sem que isso tenha sido
51
+ pedido.
@@ -0,0 +1,96 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): macro nova no SQL de um `.dfm` exige entrada em `MacroData`
11
+
12
+ Aplica-se a toda inclusão de macro FireDAC (`!nome`) no `SQL.Strings` de um `TFDQuery` que mora em
13
+ `.dfm`. O scan automático do SQL **não** basta. Complementa `filtro-condicional-sql-par-add-parambyname.md`
14
+ e `sql-qualificacao-colunas.md`.
15
+
16
+ ## O `MacroData` do `.dfm` substitui as macros criadas pelo scan
17
+
18
+ O FireDAC cria macros ao varrer o `SQL.Text`. Mas, quando o `.dfm` traz um bloco `MacroData` explícito,
19
+ esse bloco é lido **depois** do `SQL.Strings` no stream do DFM e **redefine a coleção**. Macro que não
20
+ estiver declarada ali não existe em runtime, e o `MacroByName` do `BeforeOpen` estoura:
21
+
22
+ ```
23
+ [FireDAC][Stan]-706. Macro [filtro_extra] is not found
24
+ ```
25
+
26
+ Formato da entrada (copie de uma macro vizinha do mesmo bloco):
27
+
28
+ ```
29
+ item
30
+ Value = Null
31
+ Name = 'FILTRO_EXTRA'
32
+ end
33
+ ```
34
+
35
+ - Nome em **maiúsculas**, como as demais (a busca ignora caixa, mas o arquivo tem padrão).
36
+ - `Value = Null`: o valor real é atribuído em runtime, no `BeforeOpen`.
37
+
38
+ ## As macros irmãs que funcionam não provam a autocriação
39
+
40
+ É a armadilha central. Ao investigar, é natural olhar as macros que já existem, ver que "funcionam" e
41
+ concluir que o FireDAC as cria sozinho a partir do `!nome`. A observação está invertida: elas funcionam
42
+ **porque estão declaradas** no `MacroData` de cada query que as usa.
43
+
44
+ Antes de concluir que a autocriação basta, verifique se existe o bloco:
45
+
46
+ ```bash
47
+ grep -n "MacroData" <Unit>.dfm
48
+ grep -in "Name = '<MACRO_IRMA>'" <Unit>.dfm
49
+ ```
50
+
51
+ Se as irmãs aparecem nesse `grep`, a sua também precisa aparecer.
52
+
53
+ ## Um `BeforeOpen` costuma servir mais de uma query
54
+
55
+ É comum duas queries compartilharem o mesmo handler `BeforeOpen`. Um caso frequente em relatórios: uma
56
+ query de runtime e uma de design-time, que alimenta o designer de layout do gerador de relatórios com o
57
+ mesmo SELECT. O `MacroByName` roda para todas as queries do handler, então:
58
+
59
+ 1. a query sem a macro estoura ao abrir;
60
+ 2. mesmo sem erro, a coluna nova que só existe numa das queries não aparece no designer, e o layout não
61
+ consegue usá-la.
62
+
63
+ Levante o mapeamento antes de editar:
64
+
65
+ ```bash
66
+ grep -n "BeforeOpen = " <Unit>.dfm # quais queries usam cada handler
67
+ grep -n "object .*: TFDQuery" <Unit>.dfm # limites de cada bloco
68
+ ```
69
+
70
+ Toda query servida por um handler que atribui a macro precisa da macro no SQL **e** da entrada no
71
+ `MacroData`.
72
+
73
+ ## Checklist antes de fechar
74
+
75
+ ```bash
76
+ grep -c "!<nome_da_macro>" <Unit>.dfm # usos no SQL
77
+ grep -c "Name = '<NOME_DA_MACRO>'" <Unit>.dfm # declarações
78
+ ```
79
+
80
+ As duas contagens têm de ser iguais e bater com o número de queries servidas pelo handler. Contagens
81
+ diferentes são exatamente o defeito desta regra.
82
+
83
+ Ao inserir várias entradas no mesmo arquivo, trabalhe do bloco de maior número de linha para o menor,
84
+ para que as inserções não desloquem as posições ainda não editadas. Preserve o EOL do `.dfm` (ver
85
+ `encoding-eol.md`).
86
+
87
+ ## Ao investigar `-706. Macro [x] is not found`
88
+
89
+ Ordem de hipóteses:
90
+
91
+ 1. a macro não está declarada no `MacroData` daquela query (comece aqui);
92
+ 2. outra query servida pelo mesmo `BeforeOpen` não tem a macro no SQL;
93
+ 3. o SQL é reescrito em runtime (`SQL.Text := ...`) antes do `Open`, refazendo o scan.
94
+
95
+ Compare com um DataModule que já faça a mesma coisa e funcione. A divergência entre o que funciona e o
96
+ que quebra é o diagnóstico.
@@ -0,0 +1,36 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ - "**/*.sql"
8
+ ---
9
+
10
+ # Regra (camada de dados): qualificação de colunas em SQL
11
+
12
+ Aplica-se a todo SQL de `TFDQuery` (relatórios, telas, consultas). Complementa `firedac.md`.
13
+
14
+ **Toda coluna qualificada (`tabela.coluna` ou `alias.coluna`) tem de apontar para a tabela ou alias que
15
+ de fato contém a coluna**, de forma consistente em todas as cláusulas da query (`SELECT`, `JOIN`, `WHERE`,
16
+ `GROUP BY`, `ORDER BY`, `HAVING`).
17
+
18
+ - Antes de pôr ou mudar uma coluna no `ORDER BY`/`GROUP BY`/`WHERE`, confirme em que tabela ela existe:
19
+ veja como o `SELECT` e os `JOIN` da própria query já a qualificam e **repita o mesmo prefixo**. O
20
+ PostgreSQL falha em runtime com `column <tabela>.<coluna> does not exist`, não na compilação; o erro só
21
+ aparece ao executar.
22
+ - Em queries com tabela mestre e tabela de detalhe por filial, atenção às colunas que existem numa e não
23
+ na outra. Exemplo: `cod_localizacao` pertence a `produtos_filial`, não a `produtos`.
24
+ - Ao copiar um bloco de ordenação ou quebra de outro ramo (`if ItemIndex = N`), revise cada prefixo. O
25
+ prefixo do bloco copiado não necessariamente serve para a coluna nova.
26
+
27
+ ```sql
28
+ -- ERRADO: SELECT e JOIN usam produtos_filial, o ORDER BY usa produtos
29
+ SELECT produtos.descricao, produtos_filial.cod_localizacao
30
+ FROM produtos
31
+ JOIN produtos_filial ON produtos_filial.cod_produto = produtos.codigo
32
+ ORDER BY produtos.cod_localizacao
33
+
34
+ -- CERTO
35
+ ORDER BY produtos_filial.cod_localizacao
36
+ ```