@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,43 @@
1
+ ---
2
+ descricao: "Regra incondicional: nunca deixar escrita de debug no Clipboard em código de produção"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ ---
9
+
10
+ # Regra incondicional: nunca deixar escrita de debug no Clipboard em código de produção
11
+
12
+ Aplica-se a toda unit `.pas` do projeto. É proibido deixar, em código entregue, escrita no
13
+ clipboard usada como apoio de depuração — tipicamente o SQL de uma `TFDQuery` copiado para a
14
+ área de transferência durante a montagem/execução de uma consulta.
15
+
16
+ ## O que é proibido
17
+
18
+ Linhas como estas, dentro de rotinas de montagem/execução de query (ou qualquer fluxo de
19
+ negócio), são **debug** e não podem ser commitadas:
20
+
21
+ ```pascal
22
+ Clipboard.AsText := SQL.Text; // copia o SELECT para o clipboard — PROIBIDO em produção
23
+ Clipboard.SetTextBuf(...); // idem, qualquer escrita de depuração no clipboard
24
+ ```
25
+
26
+ - Elas sobrescrevem silenciosamente o que o usuário tinha copiado — o cliente cola o SELECT
27
+ sem entender o porquê. O erro só aparece em runtime, para o usuário final.
28
+ - O sintoma típico: o usuário digita num campo de filtro de uma tela e, sem pedir, o texto do
29
+ SELECT montado vai parar no clipboard.
30
+
31
+ ## O que continua permitido
32
+
33
+ Escrita/limpeza de clipboard que faz parte de uma **funcionalidade real** pedida pelo usuário
34
+ (ex.: botão "Copiar chave", `Clipboard.Clear` para proteger um dado sensível). O critério é:
35
+ a operação de clipboard pertence ao fluxo de negócio (acionada por um controle/intenção do
36
+ usuário) e não a uma inspeção de SQL/variável de desenvolvimento.
37
+
38
+ ## Antes de fechar a alteração
39
+
40
+ - Faça `Grep` (sem diferenciar caixa) por `Clipboard.AsText :=` e `Clipboard.SetTextBuf` na unit
41
+ alterada e confirme que nenhuma escrita de clipboard foi introduzida como apoio de debug.
42
+ - Se precisar inspecionar o SQL durante o desenvolvimento, use o debugger/log temporário e
43
+ **remova antes do commit** — nunca o clipboard.
@@ -0,0 +1,65 @@
1
+ ---
2
+ descricao: "Regra incondicional: validação no `OnExit` NÃO protege a gravação — revalide no ponto de gravação o que não pode ser gravado"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ - "**/*.dfm"
9
+ ---
10
+
11
+ # Regra incondicional: validação no `OnExit` NÃO protege a gravação — revalide no ponto de gravação o que não pode ser gravado
12
+
13
+ Aplica-se a toda validação de campo-chave de documento feita no `OnExit` (série, filial, número,
14
+ código fiscal, fornecedor) que **impede** um documento inválido: série de outra filial, série
15
+ desativada, combinação de tipos incompatível, etc. Complementa
16
+ [../telas/foco-decisao-por-canfocus-nao-tabstop.md](../telas/foco-decisao-por-canfocus-nao-tabstop.md).
17
+
18
+ ## O `Exit` do handler só sai do handler
19
+
20
+ Várias telas preenchem outra tela **por código**, chamando os eventos dela em sequência:
21
+
22
+ ```pascal
23
+ FormDocumento.DocumentoProprio := True;
24
+ FormDocumento.EditSerie.Text := EditSerieOrigem.Text;
25
+ FormDocumento.EditSerieExit(Self); // mostra "Série não permitida" e dá Exit...
26
+ FormDocumento.EditNumeroExit(Self); // ...e o chamador segue normalmente
27
+ // lança itens, ShowModal — a série bloqueada continua no campo
28
+ ```
29
+
30
+ A mensagem aparece, o teste manual "vê o bloqueio" e dá o caso por aprovado. O documento **grava
31
+ mesmo assim**, porque:
32
+
33
+ - o `Exit` não se propaga para quem chamou o evento;
34
+ - o estado que o bloqueio desfaz na digitação manual (ex.: `DocumentoProprio := False`) costuma
35
+ ser **preservado de propósito** no fluxo automatizado (`if not FLancamentoAutomatico then`);
36
+ - o botão de gravar confia que o `OnExit` já validou.
37
+
38
+ ## Padrão obrigatório
39
+
40
+ 1. **Toda validação que impede documento inválido é repetida no ponto de gravação**, antes de
41
+ `StartTransaction` e de qualquer reserva de número. A validação no `OnExit` serve para dar
42
+ feedback ao usuário. A barreira de verdade fica na gravação.
43
+ 2. **Antes de fechar**, procure quem chama o handler por código:
44
+ `grep -rn "<Form>\.<Campo>Exit(" --include="*.pas" .`. Se houver chamador, a revalidação na
45
+ gravação é obrigatória. Se possível, valide também **no chamador**, antes de criar a tela.
46
+ 3. **`SetFocus` em validação de handler que pode rodar por código** exige `CanFocus`: o chamador
47
+ costuma disparar o evento antes do `ShowModal`.
48
+ 4. **O roteiro de teste do fluxo automatizado vai até a gravação.** "A mensagem apareceu" não
49
+ prova nada: confirme que o documento **não foi gravado** e que a numeração não avançou.
50
+
51
+ ## Caso irmão: `OnColExit` de `TDBGrid`
52
+
53
+ A validação no `OnColExit` só roda quando muda a **coluna**. O ENTER costuma passar por ela, mas a seta muda de
54
+ **linha** e o `TDBGrid` faz o `Post` implícito sem `ColExit`. A trava de verdade fica no `BeforePost` do dataset (com
55
+ `Abort`) e é repetida no OK da tela. Teste ENTER, seta, clique em outra linha e OK.
56
+
57
+ ## Caso recorrente: restrição por filial
58
+
59
+ Quando um cadastro auxiliar (série, tabela de preço, depósito) pode ser restrito a uma filial, toda
60
+ tela que o usa compara a filial do cadastro com a do documento, no mesmo idioma que o projeto já usa
61
+ para isso. Uma pesquisa (F2/lookup) que não filtra filial não substitui essa validação.
62
+
63
+ E a restrição só vale onde faz sentido: se o campo pode guardar um dado de terceiro (a série da nota
64
+ do fornecedor, por exemplo), bloqueie a outra filial só quando o documento for **próprio**, senão um
65
+ documento de terceiro com código coincidente é barrado.
@@ -0,0 +1,69 @@
1
+ ---
2
+ descricao: "Regra incondicional: envolver código existente num bloco novo muda o escopo das variáveis inline"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dpr"
6
+ - "**/*.dpk"
7
+ - "**/*.inc"
8
+ ---
9
+
10
+ # Regra incondicional: envolver código existente num bloco novo muda o escopo das variáveis inline
11
+
12
+ Aplica-se a toda edição que **envolve trecho já existente** de um `.pas` num bloco novo — `try..finally`
13
+ para uma flag, `try..except`, `begin..end` de um `if`, laço `for`/`while` — em units que usam
14
+ **variáveis inline** (`var LX := …`, Delphi 10.3 em diante).
15
+
16
+ ## A variável inline vive até o `end` do bloco onde foi DECLARADA
17
+
18
+ Uma variável da seção `var` da rotina vale no corpo inteiro. Uma **inline** vale só do ponto da
19
+ declaração até o fim do **bloco que a contém**. Envolver um trecho num bloco novo muda o dono
20
+ dessa declaração sem mudar nenhuma linha dela:
21
+
22
+ ```pascal
23
+ // ANTES — compila: LQuantidadeGerada pertence ao begin..end do if
24
+ begin
25
+ ...
26
+ var LQuantidadeGerada := 0;
27
+ ... Inc(LQuantidadeGerada) ...
28
+ if LQuantidadeGerada > 0 then ...
29
+ end;
30
+
31
+ // DEPOIS — E2003: a declaração passou a pertencer ao try..finally
32
+ begin
33
+ FSuspenderAtualizacao := True;
34
+ try
35
+ ...
36
+ var LQuantidadeGerada := 0;
37
+ ... Inc(LQuantidadeGerada) ...
38
+ finally
39
+ FSuspenderAtualizacao := False;
40
+ end;
41
+ if LQuantidadeGerada > 0 then ... // [dcc32 Error] E2003 Undeclared identifier
42
+ end;
43
+ ```
44
+
45
+ ## Por que escapa da revisão
46
+
47
+ Lendo o código, a variável **parece** estar em escopo: a declaração continua ali, algumas linhas
48
+ acima, com o mesmo recuo — o novo `try` costuma ser inserido **sem reindentar** o corpo, justamente
49
+ para manter o diff pequeno. O executor e o revisor leem o diff, e o diff não mostra a declaração nem
50
+ o uso posterior, só as linhas `try`/`finally` acrescentadas. O erro só aparece no **build**, que o
51
+ agente não faz — um ciclo inteiro de build desperdiçado.
52
+
53
+ ## Procedimento obrigatório
54
+
55
+ Ao inserir `try`, `begin` ou início de laço envolvendo código existente:
56
+
57
+ 1. **Liste as inline declaradas dentro do trecho envolvido:**
58
+ ```bash
59
+ awk 'NR>=<linha_try> && NR<=<linha_finally> && /^[[:space:]]*var L[A-Za-z]+/' <unit>.pas
60
+ ```
61
+ 2. **Para cada uma, procure uso DEPOIS do fim do bloco** (entre o `end` do bloco novo e o `end` da
62
+ rotina). Se houver, **mova a declaração para antes do bloco**, preservando o valor inicial —
63
+ desde que nada entre o ponto antigo e o novo leia a variável.
64
+ 3. **Não migre para a seção `var`** da rotina se o projeto preserva as inline existentes. Basta subir a
65
+ declaração inline.
66
+ 4. Registre na resposta ao revisor quais inline foram verificadas — "nenhuma" só vale acompanhado do
67
+ comando que produziu a lista vazia.
68
+
69
+ Vale igualmente para `for var LI := …`: o contador inline não existe depois do laço.
@@ -0,0 +1,40 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ ---
8
+
9
+ # Regra (camada de UI): decidir `SetFocus` por `CanFocus`, nunca por `TabStop`
10
+
11
+ Aplica-se a todo código que decide **para qual controle mover o foco** (`SetFocus`) a partir de uma
12
+ condição sobre outro controle, tipicamente em `OnExit`/`OnKeyPress` de telas de lançamento que testam se
13
+ um campo "está disponível" antes de focá-lo.
14
+
15
+ ## `TabStop` não diz se o controle pode receber foco agora
16
+
17
+ `TabStop` só controla se a tecla **Tab** alcança o controle na navegação. Não indica se ele está apto a
18
+ receber foco neste momento. Um controle pode ter `TabStop = False` (valor de design, nunca ajustado em
19
+ runtime) e estar `Visible = True` e `Enabled = True`, perfeitamente focável por `SetFocus`.
20
+
21
+ Um `if <Campo>.TabStop then <Campo>.SetFocus else <Outro>.SetFocus` que dependa de `TabStop` sem que o
22
+ código jamais ajuste a propriedade **sempre cai no `else`** e manda o foco para o controle errado. Em
23
+ silêncio: não lança exceção, não aparece na compilação, só o usuário percebe ao navegar pela tela.
24
+
25
+ ## Padrão obrigatório
26
+
27
+ Use `CanFocus` (de `TWinControl`): ele já considera `Visible`, `Enabled` e a hierarquia de exibição
28
+ (`Showing`):
29
+
30
+ ```pascal
31
+ if EditCondicaoPagamento.CanFocus then
32
+ EditCondicaoPagamento.SetFocus
33
+ else
34
+ EditCarteira.SetFocus;
35
+ ```
36
+
37
+ - Se a intenção for também permitir a navegação por Tab até o controle, ajuste `TabStop` à parte: é uma
38
+ decisão de navegação, independente da decisão de `SetFocus`.
39
+ - Um handler costuma repetir o mesmo bloco de decisão de foco para várias mensagens de validação. Corrija
40
+ **todas** as ocorrências de uma vez, e as dos handlers semelhantes de outras telas.
@@ -0,0 +1,80 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dfm"
5
+ - "**/*.dpr"
6
+ - "**/*.inc"
7
+ ---
8
+
9
+ # Regra (camada de UI): form criado dinamicamente sem dono, toda saída da rotina libera o form
10
+
11
+ Aplica-se a toda rotina que cria um form auxiliar em runtime sem dono (`TFormX.Create(nil)`, ou um helper
12
+ do projeto que faça isso por baixo) para exibi-lo e **ler os seus campos depois do `ShowModal`**. É o caso
13
+ das telas orquestradoras que abrem, em sequência, forms de pagamento, parcelas ou confirmação.
14
+
15
+ ## Sem dono, só o `Free` explícito libera
16
+
17
+ Form criado com `Create(nil)` não tem dono: nem a tela que o criou nem a aplicação o liberam ao fechar. Um
18
+ `Free` escrito no fim da rotina só roda no caminho de sucesso. Qualquer `Exit` depois da criação deixa o
19
+ form na memória: cancelamento, botão "Retornar", validação que falha, `except` que mostra mensagem e sai.
20
+
21
+ Quando a referência é uma **variável global** (a que o IDE declara na unit do form), a próxima execução
22
+ sobrescreve a variável e a instância anterior fica órfã. Nada denuncia na hora: o sintoma aparece só ao
23
+ fechar o sistema, como "Unexpected Memory Leak" do FastMM, sem indicar a tela que o causou.
24
+
25
+ ## Padrão obrigatório
26
+
27
+ Prefira variável local e `try`/`finally`. O `finally` roda também no `Exit`, então cobre toda saída:
28
+
29
+ ```pascal
30
+ var
31
+ LFormParcelas: TFormParcelas;
32
+ begin
33
+ LFormParcelas := TFormParcelas.Create(nil);
34
+ try
35
+ if LFormParcelas.ShowModal = mrCancel then
36
+ Exit;
37
+ LEnviarEmail := LFormParcelas.CheckBoxEnviarEmail.Checked;
38
+ finally
39
+ LFormParcelas.Free;
40
+ end;
41
+ end;
42
+ ```
43
+
44
+ Em rotina legada longa que cria vários forms em pontos diferentes e não comporta `try`/`finally`
45
+ aninhados sem reescrita, centralize a liberação numa rotina privada e chame-a antes de **toda** saída
46
+ posterior à primeira criação e no fim do caminho de sucesso:
47
+
48
+ ```pascal
49
+ procedure TFormPedido.LiberarFormsAuxiliares;
50
+ begin
51
+ FreeAndNil(FFormPagamento);
52
+ FreeAndNil(FFormParcelas);
53
+ end;
54
+
55
+ if FFormPagamento.ShowModal = mrCancel then
56
+ begin
57
+ LiberarFormsAuxiliares;
58
+ Exit;
59
+ end;
60
+ ```
61
+
62
+ - `FreeAndNil` aceita variável `nil` e a zera depois do `Free`, então pode ser chamado sem `Assigned`,
63
+ inclusive para forms que aquela execução não chegou a criar.
64
+ - `if ... then Exit;` de uma linha vira `begin`/`end` em linhas separadas.
65
+ - No caminho de sucesso, a liberação vem **depois** da última leitura do form.
66
+ - Se o form não precisa ser lido depois do `ShowModal`, use o helper do projeto que cria, exibe e libera
67
+ numa chamada só, ou o `try`/`finally` acima.
68
+
69
+ ## Antes de fechar
70
+
71
+ ```bash
72
+ grep -niE "create\(nil\)|\.free\b|freeandnil|\bexit\b" <Unit>.pas # -i: Delphi não diferencia caixa
73
+ ```
74
+
75
+ Em cada rotina que cria form sem dono, todo `Exit` posterior à primeira criação precisa estar dentro de um
76
+ `try`/`finally` ou ter a liberação antes dele. Rotinas irmãs nascem de cópia: corrija todas na mesma
77
+ passagem.
78
+
79
+ Teste cancelando **cada** form auxiliar isoladamente e depois feche o sistema. O caminho de sucesso nunca
80
+ mostra o vazamento.
@@ -0,0 +1,58 @@
1
+ ---
2
+ descricao: "Form novo herda da classe-base do projeto; grade com coluna de seleção e filtro \"todos\" seguem o padrão da casa"
3
+ paths:
4
+ - "**/*.pas"
5
+ - "**/*.dfm"
6
+ - "**/*.dpr"
7
+ - "**/*.inc"
8
+ ---
9
+
10
+ # Regra (camada de UI): form novo herda da classe-base do projeto e grade de seleção segue o padrão da casa
11
+
12
+ Aplica-se a toda tela nova ou alterada num projeto VCL que tem classe-base de forms (cadastro, consulta,
13
+ movimentação, relatório).
14
+
15
+ ## Descubra a classe-base antes de criar o form
16
+
17
+ Não suponha. Veja de onde as telas do projeto herdam e onde a base mora (muitas vezes numa biblioteca comum,
18
+ fora da pasta do sistema e somente leitura):
19
+
20
+ ```bash
21
+ # classes de que os forms do projeto herdam, da mais usada para a menos usada
22
+ grep -rhoiE "^\s*T\w+\s*=\s*class\s*\(T\w+\)" --include="*.pas" . | sed -E 's/.*\((T\w+)\).*/\1/' | sort | uniq -c | sort -rn | head
23
+ # .dfm que já nascem herdados
24
+ grep -rlE "^inherited " --include="*.dfm" . | head
25
+ ```
26
+
27
+ Se o projeto tem base, o form novo herda dela — `TFormBase`, `TFormBaseCadastro`, `TFormBaseRelatorio`, conforme o
28
+ tipo de tela —, nunca direto de `TForm`. Na dúvida entre duas bases, siga a tela existente mais parecida com a nova.
29
+
30
+ - O `.dfm` começa com `inherited`, não com `object`.
31
+ - Os eventos que a base já implementa (`FormCreate`, `FormShow`, `FormKeyDown`, `OnDrawColumnCell`) chamam
32
+ `inherited`.
33
+ - A base costuma tratar ENTER como TAB, fonte e negrito dos botões, ordenação pelo título da grade e zebrado.
34
+ Tela que herda de `TForm` perde esse comportamento sem nenhum erro de compilação.
35
+
36
+ ## Grade com coluna de seleção
37
+
38
+ - A coluna de seleção é a **última** da grade.
39
+ - Marca e desmarca com **barra de espaço** ou **duplo clique** na linha. Clique simples e ENTER não marcam.
40
+ - Se a base já pinta a grade zebrada, não repita o zebrado no form.
41
+ - Só implemente o `OnDrawColumnCell` no próprio form quando a grade tiver pintura personalizada, como linha marcada
42
+ ou linha bloqueada em outra cor. Nesse caso, nas linhas sem cor própria, reproduza o padrão da base (a mesma cor e
43
+ a mesma condição, por exemplo `RecNo` par fora de `gdSelected`) e termine com `DefaultDrawColumnCell`.
44
+ - Coluna calculada no SQL (`CASE`, `||`, `COALESCE` de texto) vira `text` no PostgreSQL, e o FireDAC a mostra como
45
+ `(WIDEMEMO)` na grade. Faça `CAST(... AS varchar(n))` na coluna calculada.
46
+ - Se a base aplica negrito em todo `TButton`/`TBitBtn`, o caption dos botões precisa caber **em negrito**: confira
47
+ a largura no form aberto, não no designer da tela sem herança.
48
+
49
+ ## Filtro "todos"
50
+
51
+ Campo de código usado como filtro, quando vazio, significa "todos". Siga a convenção que o projeto já usa nas outras
52
+ telas de filtro, por exemplo:
53
+
54
+ - código vazio vira zeros no `OnExit` (`'000000'` significa todos);
55
+ - o nome ao lado mostra um texto fixo como `* TODOS OS CLIENTES *`;
56
+ - o SQL só aplica o filtro quando o código é maior que zero.
57
+
58
+ Procure uma tela de filtro existente e repita o mesmo comportamento, em vez de inventar outro.
@@ -0,0 +1,131 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dpr"
5
+ - "**/*.dpk"
6
+ - "**/*.inc"
7
+ - "**/*.dfm"
8
+ ---
9
+
10
+ # Threads e timers
11
+
12
+ ## `TTimer` não pode reentrar
13
+
14
+ O `OnTimer` roda na thread principal a partir da mensagem `WM_TIMER`. Um handler longo que não bombeia mensagens
15
+ não reentra (o próximo disparo só é tratado depois que ele termina), mas basta o handler bombear mensagens
16
+ (`Application.ProcessMessages`, diálogo modal, `ShowMessage`, rotina de terceiro que faz isso por dentro) para o
17
+ evento disparar de novo antes de terminar. Como é difícil garantir que nada no caminho bombeia mensagens, desligue o
18
+ timer durante o processamento e proteja com uma flag; religue no `finally`, senão uma exceção deixa o timer parado
19
+ para sempre.
20
+
21
+ Errado:
22
+
23
+ ```pascal
24
+ procedure TFrmMonitor.TmrSincronizarTimer(Sender: TObject);
25
+ begin
26
+ SincronizarPedidos; // pode rodar duas vezes ao mesmo tempo
27
+ end;
28
+ ```
29
+
30
+ Certo:
31
+
32
+ ```pascal
33
+ procedure TFrmMonitor.TmrSincronizarTimer(Sender: TObject);
34
+ begin
35
+ if FProcessando then
36
+ Exit;
37
+ FProcessando := True;
38
+ TmrSincronizar.Enabled := False;
39
+ try
40
+ SincronizarPedidos;
41
+ finally
42
+ FProcessando := False;
43
+ TmrSincronizar.Enabled := True;
44
+ end;
45
+ end;
46
+ ```
47
+
48
+ ## VCL só na thread principal
49
+
50
+ Componente visual (form, label, grid, dataset ligado a tela) não é thread-safe. Código em `TThread` ou `TTask` que
51
+ precisa tocar a tela passa por `TThread.Synchronize` ou `TThread.Queue`:
52
+
53
+ - `Synchronize` bloqueia a thread de fundo até a thread principal executar o bloco: use quando precisa do
54
+ resultado antes de continuar.
55
+ - `Queue` enfileira e segue sem esperar: use para progresso e notificação. Variável local capturada pela closure é
56
+ segura (a captura vive num frame no heap, contado por referência, como `LTotal` abaixo). O perigo é a thread
57
+ terminar antes de o bloco rodar: campo de um `TThread` com `FreeOnTerminate := True` ou objeto que a thread libera
58
+ ao sair já não existe quando o bloco executa. Copie o valor para uma variável local antes do `Queue`.
59
+
60
+ ```pascal
61
+ TTask.Run(
62
+ procedure
63
+ var
64
+ LTotal: Integer;
65
+ begin
66
+ LTotal := ImportarArquivo(LCaminho);
67
+ TThread.Queue(nil,
68
+ procedure
69
+ begin
70
+ LblStatus.Caption := Format('%d registros importados', [LTotal]);
71
+ end);
72
+ end);
73
+ ```
74
+
75
+ ## Conexão FireDAC própria por thread
76
+
77
+ `TFDConnection` e as queries ligadas a ela não podem ser usadas por duas threads ao mesmo tempo. A thread de fundo
78
+ cria a própria conexão (de preferência por uma connection definition com pooling) e a libera no fim; nunca usa a
79
+ conexão do DataModule da tela.
80
+
81
+ A conexão criada na thread não executa o `AfterConnect` do DataModule, então perde a inicialização de sessão que
82
+ ele faz (por exemplo `SET SESSION DateStyle TO 'ISO, DMY'` no PostgreSQL). Replique essa inicialização na conexão da
83
+ thread, com um `AfterConnect` próprio ou pelos parâmetros da connection definition. Detalhes nas rules
84
+ `dados/firedac.md` e `dados/datestyle-sessao-firedac-postgres.md` deste perfil.
85
+
86
+ ```pascal
87
+ procedure TImportador.Execute;
88
+ var
89
+ LConexao: TFDConnection;
90
+ begin
91
+ LConexao := TFDConnection.Create(nil);
92
+ try
93
+ LConexao.ConnectionDefName := 'Principal';
94
+ LConexao.Connected := True;
95
+ InicializarSessao(LConexao); // o mesmo que o AfterConnect do DataModule faz
96
+ GravarLote(LConexao);
97
+ finally
98
+ LConexao.Free;
99
+ end;
100
+ end;
101
+ ```
102
+
103
+ Estado compartilhado entre threads (lista, contador, cache) fica atrás de `TCriticalSection` (ou `TMonitor`), com
104
+ `Enter` seguido de `try ... finally Leave`.
105
+
106
+ ## `TTask` não captura variável de laço
107
+
108
+ A closure captura a **variável**, não o valor: quando a task roda, o laço já mudou a variável e todas as tasks
109
+ podem ver o último valor. Passe o valor por uma função que cria a closure com um parâmetro próprio.
110
+
111
+ Errado:
112
+
113
+ ```pascal
114
+ for LId in LIds do
115
+ TTask.Run(procedure begin ProcessarId(LId); end);
116
+ ```
117
+
118
+ Certo:
119
+
120
+ ```pascal
121
+ function TProcessador.CriarTarefa(const AId: Integer): TProc;
122
+ begin
123
+ Result := procedure begin ProcessarId(AId); end;
124
+ end;
125
+
126
+ for LId in LIds do
127
+ TTask.Run(CriarTarefa(LId));
128
+ ```
129
+
130
+ Copiar para uma variável local declarada fora do laço não resolve: ela também é única e é capturada pela
131
+ referência. O parâmetro de `CriarTarefa` é uma variável nova a cada chamada.
@@ -0,0 +1,109 @@
1
+ ---
2
+ paths:
3
+ - "**/*.pas"
4
+ - "**/*.dpr"
5
+ - "**/*.dpk"
6
+ - "**/*.inc"
7
+ - "**/*.dfm"
8
+ ---
9
+
10
+ # `try/finally` e vazamento de memória
11
+
12
+ ## `Create` e, na linha seguinte, `try`
13
+
14
+ Objeto criado sem dono é liberado num `finally` que começa logo depois do `Create`. Nada entre os dois: se uma
15
+ linha no meio levantar exceção, o objeto vaza. E o `Create` fica fora do `try`: se o construtor falhar, a variável
16
+ não foi atribuída e o `Free` no `finally` operaria sobre lixo.
17
+
18
+ Errado:
19
+
20
+ ```pascal
21
+ LLista := TStringList.Create;
22
+ LLista.LoadFromFile(ACaminho); // exceção aqui vaza LLista
23
+ try
24
+ Processar(LLista);
25
+ finally
26
+ LLista.Free;
27
+ end;
28
+ ```
29
+
30
+ Certo:
31
+
32
+ ```pascal
33
+ LLista := TStringList.Create;
34
+ try
35
+ LLista.LoadFromFile(ACaminho);
36
+ Processar(LLista);
37
+ finally
38
+ LLista.Free;
39
+ end;
40
+ ```
41
+
42
+ Dois objetos: inicialize o segundo com `nil` antes do `try` e libere os dois no mesmo `finally` (`Free` em `nil`
43
+ não faz nada), ou aninhe um `try/finally` por objeto.
44
+
45
+ ```pascal
46
+ LOrigem := nil;
47
+ LDestino := TStringList.Create;
48
+ try
49
+ LOrigem := TStringList.Create;
50
+ LOrigem.LoadFromFile(ACaminho);
51
+ LDestino.Assign(LOrigem);
52
+ finally
53
+ LOrigem.Free;
54
+ LDestino.Free;
55
+ end;
56
+ ```
57
+
58
+ ## `FreeAndNil` em campo e variável que sobrevive
59
+
60
+ Campo de classe, variável global ou variável que ainda é testada depois (`if Assigned(...)`) é liberada com
61
+ `FreeAndNil`: o `Free` sozinho deixa o ponteiro apontando para memória liberada, e o `Assigned` seguinte responde
62
+ `True`. Variável local que morre no `finally` pode usar `Free`.
63
+
64
+ ```pascal
65
+ destructor TGerenciador.Destroy;
66
+ begin
67
+ FreeAndNil(FCache);
68
+ inherited;
69
+ end;
70
+ ```
71
+
72
+ ## Dono do objeto (Owner)
73
+
74
+ Componente criado com dono (`TFDQuery.Create(Self)`, `TForm.Create(Application)`) é liberado pelo dono quando o
75
+ dono é destruído. Isso não é liberação no fim do uso:
76
+
77
+ - objeto criado com dono dentro de um método chamado muitas vezes acumula até o form fechar; para uso local, crie
78
+ com `nil` e libere no `finally`;
79
+ - liberar antes um componente com dono é seguro com `Free`/`FreeAndNil`, que o tiram da lista do dono; o que não
80
+ pode é guardar a referência e usá-la depois que o dono foi destruído;
81
+ - objeto sem dono que fica num campo é liberado no `destructor` da classe que o criou.
82
+
83
+ Form criado em tempo de execução para uso modal é criado e liberado no mesmo método:
84
+
85
+ ```pascal
86
+ LForm := TFrmBuscaCliente.Create(nil);
87
+ try
88
+ if LForm.ShowModal = mrOk then
89
+ SelecionarCliente(LForm.ClienteId);
90
+ finally
91
+ LForm.Free;
92
+ end;
93
+ ```
94
+
95
+ ## `ReportMemoryLeaksOnShutdown` em DEBUG
96
+
97
+ Ligue o relatório de vazamento no `.dpr`, só no build de depuração, para o vazamento aparecer ao fechar a
98
+ aplicação durante o teste do usuário:
99
+
100
+ ```pascal
101
+ begin
102
+ {$IFDEF DEBUG}
103
+ ReportMemoryLeaksOnShutdown := True;
104
+ {$ENDIF}
105
+ Application.Initialize;
106
+ ```
107
+
108
+ Fora do `{$IFDEF DEBUG}` a mensagem aparece para o usuário final. Vazamento relatado ao fechar é defeito a
109
+ corrigir, não ruído: siga a classe listada até o `Create` sem `Free` correspondente.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: conhecimento-delphi
3
+ description: "Base de armadilhas Delphi consultada sob demanda. Use quando aparecer erro de compilação estranho (F1026 File not found 'true.dpr', E2356 Property accessor must be an instance field, E2003 em Delphi 13, E1026/E2606 de .dres, MSB6003/MSB6002 command line too long), .dproj que o IDE não abre (ProjectGuid inválido), unit que não aparece no Project Manager, driver FireDAC não encontrado (Object factory is missing, -314 Cannot load vendor library), log/Writeln que não aparece em saída redirecionada, acento quebrado ou valor zerado ao converter número (StrToFloat, vírgula/ponto), Horse com Swagger (gbswagger) e JWT dando 401 ou rota sumindo, integração ACBr NFC-e, recurso RCDATA não encontrado, componente criado em runtime em vez do designer, migração para Delphi 13 ou build por .bat com log no Windows."
4
+ ---
5
+
6
+ # Conhecimento Delphi
7
+
8
+ Coleção de armadilhas reais de Delphi, cada uma no formato **sintoma → causa → correção → exemplo**. Não fica
9
+ carregada no contexto: leia só o artigo que casa com o problema relatado.
10
+
11
+ ## Como usar
12
+
13
+ 1. Compare o que o usuário relatou (mensagem de erro, código do erro, comportamento) com o índice abaixo.
14
+ 2. Leia o artigo correspondente em `references/` e aplique a correção ao código do projeto.
15
+ 3. Se nenhum artigo casar, siga a investigação normal; não force um artigo que não explica o sintoma.
16
+
17
+ Encoding/BOM, `try/finally` e threads não estão aqui: são regras do perfil, já carregadas ao editar fonte Delphi.
18
+
19
+ ## Índice
20
+
21
+ ### Projeto, `.dproj` e `.dpr`
22
+
23
+ - `references/dproj-dcc-debuginformation-nao-booleano.md` — `F1026 File not found: 'true.dpr'`: `DCC_DebugInformation`
24
+ é enum numérico, não booleano.
25
+ - `references/dproj-projectguid-valido.md` — IDE recusa abrir o projeto: "is not a valid GUID value" no `ProjectGuid`.
26
+ - `references/dpr-uses-project-manager.md` — unit não aparece no Project Manager ou o Designer diz "No form found".
27
+ - `references/msb6003-command-line-too-long.md` — `MSB6003`/`MSB6002`: linha de comando do compilador longa demais.
28
+ - `references/recursos-rcdata.md` — embutir arquivos como RCDATA; `E1026 ... .dres`, `E2606 Duplicate resource`,
29
+ "Resource not found".
30
+ - `references/build-via-bat-com-log.md` — para quem compila no Windows/VM: `build.bat` que grava log e devolve o
31
+ código certo.
32
+
33
+ ### Linguagem e compilação
34
+
35
+ - `references/class-var-vaza-para-campos-de-instancia.md` — `E2356 Property accessor must be an instance field or
36
+ method`: `class var` contamina os campos seguintes.
37
+ - `references/delphi13-breaking-changes.md` — migração para Delphi 13: `E2003 Undeclared identifier: 'Interval'`
38
+ em `AniCalculations`.
39
+ - `references/conversao-numerica-locale.md` — `StrToFloat`/`StrToCurr` devolvendo 0 ou exceção por causa da
40
+ vírgula/ponto do locale.
41
+ - `references/componentes-designer-vs-runtime.md` — controle fixo criado em `FormCreate` que não aparece no
42
+ Designer.
43
+
44
+ ### Dados (FireDAC)
45
+
46
+ - `references/firedac-registro-drivers.md` — "Object factory for class ... is missing", driver FireDAC não
47
+ encontrado, SQLite `-314` no mobile.
48
+
49
+ ### Servidor e console
50
+
51
+ - `references/console-writeln-sem-flush-nao-loga.md` — log/`Writeln` que não aparece em saída redirecionada e some
52
+ quando o processo é morto.
53
+ - `references/horse-gbswagger-rotas-jwt.md` — Horse + gbswagger + JWT: rota que muda ou some, 401 no Swagger,
54
+ `W1074 Unknown custom attribute`.
55
+
56
+ ### Fiscal
57
+
58
+ - `references/acbr-nfce-integracao.md` — ACBr NFC-e: units, SSL em simulação, `IdCSC`, chave de 44 dígitos,
59
+ `ForceDirectories`.
60
+
61
+ ## Origem e licença
62
+
63
+ Os artigos são adaptações do plugin `delphi-dev` (licença MIT). Aviso de copyright e texto da licença em
64
+ `references/ATRIBUICAO.md`.