feat: criado repositório jhonny-editor no Gitea
criado repositório jhonny-editor no Gitea adicionado script admin/deploy.command com commit automático atualizado admin/DEV-NOTES.md com template limpo Resumo: - 32 arquivos alterados - 16 novos - 15 modificados - 0 removidos 16 files changed, 638 insertions(+), 61 deletions(-) Arquivos: - code/engine/skills/boas-praticas-oo.md -> .agents/skills/boas-praticas-oo/SKILL.md - AGENTS.md - code/cep-plugin/index.html - code/cep-plugin/main.js - code/cep-plugin/styles.css - code/engine/integracoes/visual/apple_vision.py - code/engine/integracoes/visual/apple_vision_runner.swift - code/engine/integracoes/visual/extrator_ffmpeg.py - code/engine/scanner/__init__.py - code/engine/scanner/configuracao_visual.py - code/engine/scanner/coordenacao/__init__.py - code/engine/scanner/retakes/adaptador_de_falas.py - code/engine/scanner/retakes/agrupador_de_takes.py - code/engine/scanner/retakes/detector_de_reinicios.py - code/engine/scanner/retakes/modelos_de_retakes.py - code/engine/scanner/visual.py - .jhonny/ - .retakes/ - CODING_STANDARDS.md - code/engine/executar_retakes.py - code/engine/persistencia/ - code/engine/scanner/retakes/__init__.py - code/engine/scanner/retakes/carregador_de_artefatos.py - code/engine/scanner/retakes/classificador_de_retakes.py - code/engine/scanner/retakes/coordenador_de_retakes.py - code/engine/scanner/retakes/deteccao_de_retakes.py - code/engine/scanner/retakes/gerador_de_evidencias.py - code/engine/scanner/retakes/repositorio_de_retakes.py - code/engine/testes/test_consultas_de_persistencia.py - code/engine/testes/test_deteccao_de_retakes.py - code/engine/testes/test_persistencia_sqlite.py - code/relatorios/audio/arquivos/92f97877259a86a8095b1eecafdefe357212a12247d04b78df60e0c0ae38b2ea/
This commit is contained in:
João Henrique
@@ -0,0 +1,68 @@
|
||||
# Padrões de código
|
||||
|
||||
Este documento consolida as convenções obrigatórias de código do projeto. Serve de fonte de verdade para revisões automáticas (eixo *Standards* do `/code-review`) e vale para qualquer agente que escreva ou altere código.
|
||||
|
||||
A fonte completa das regras de orientação a objeto é a skill **`code/engine/skills/boas-praticas-oo.md`**. O que está abaixo é o resumo normativo; em caso de dúvida, leia a skill por inteiro.
|
||||
|
||||
## Escopo
|
||||
|
||||
As regras de PT-BR e OO aplicam-se a todo **Python em `code/engine/`**. Outras linguagens seguem as convenções existentes no repositório, mas os princípios de design (responsabilidade única, baixo acoplamento, injeção de dependência, módulos profundos) são universais.
|
||||
|
||||
## Idioma — PT-BR obrigatório
|
||||
|
||||
Todos os identificadores internos usam português brasileiro:
|
||||
|
||||
- Classes, métodos, funções, variáveis, atributos, parâmetros, constantes, arquivos, pastas e módulos.
|
||||
- Docstrings, comentários, logs, mensagens de erro e documentação.
|
||||
- Nomes de testes, fixtures e exemplos.
|
||||
|
||||
Identificadores **externos** (bibliotecas, APIs, endpoints, campos de contrato, variáveis de ambiente de terceiros, protocolos) são preservados no idioma oficial **somente quando exigidos**, e isolados em adaptadores/conversores/clientes/repositórios. Não espalhar nomes externos pelo sistema; converter na fronteira para o modelo interno em PT-BR e documentar a exceção.
|
||||
|
||||
## Nomenclatura
|
||||
|
||||
- Classes: `PascalCase` — ex. `GerenciadorDeArquivos`.
|
||||
- Métodos, funções, variáveis, atributos, arquivos e pastas: `snake_case` — ex. `carregar_arquivo`, `nome_do_usuario`.
|
||||
- Constantes: `MAIÚSCULAS_COM_SUBLINHADO` — ex. `TEMPO_LIMITE_DA_OPERACAO`.
|
||||
- Evitar nomes genéricos: `Util`, `Helper`, `Manager`, `Processor`, `Data`, `Object`, `Thing`, `Temp`.
|
||||
|
||||
## Documentação
|
||||
|
||||
- Todo **módulo** tem docstring no topo: finalidade, problema que resolve, responsabilidade, o que não faz, componentes e dependências principais.
|
||||
- Toda **classe** tem docstring: o que representa, responsabilidade, dependências, o que não deve fazer, efeitos colaterais quando aplicável.
|
||||
- Todo **método/função público** tem docstring: o que faz, dados que recebe, retorno, erros possíveis, se altera estado, se realiza operações externas.
|
||||
- **Documentação viva**: docstring/comentário deve descrever o comportamento atual. Proibido manter documentação de comportamento que não existe mais.
|
||||
|
||||
## Design / orientação a objeto
|
||||
|
||||
- **Responsabilidade única**: cada classe/função/módulo tem uma responsabilidade principal.
|
||||
- **Alta coesão**: métodos da classe relacionam-se à sua responsabilidade.
|
||||
- **Baixo acoplamento**: depender do mínimo; receber dependências, não criá-las internamente.
|
||||
- **Composição antes de herança**; herança apenas com relação real de "é um".
|
||||
- **Encapsulamento**: dados e regras protegidos, alterados por operações apropriadas.
|
||||
- **Interfaces pequenas** e **injeção de dependências** explícita.
|
||||
- **Métodos pequenos e objetivos**; retornos previsíveis e consistentes.
|
||||
- **Módulos profundos**: muita funcionalidade atrás de interface pequena (ver skill `codebase-design`).
|
||||
|
||||
## Domínio e integrações
|
||||
|
||||
- Regras de negócio ficam no **domínio/aplicação**, nunca na interface, em controladores gigantes, scripts, SQL, HTTP ou camada de apresentação.
|
||||
- Integrações externas (APIs, banco, arquivos, serviços) isoladas em módulos próprios; o resto do sistema usa contratos/classes internas.
|
||||
- Não duplicar regras: centralizar em classe, função, validador, objeto de valor ou constante.
|
||||
- Evitar dependências circulares; resolver com contratos, módulo comum, inversão ou injeção de dependência.
|
||||
|
||||
## Erros e segurança
|
||||
|
||||
- Tratar erros com **exceções específicas**; nunca `except Exception: pass`.
|
||||
- Validar toda entrada externa (tipo, formato, limites, nulos, estrutura) antes de usar.
|
||||
- Não registrar senhas, tokens, chaves ou dados sensíveis em logs.
|
||||
- Configurações em componentes próprios, não espalhadas no código.
|
||||
|
||||
## Testes
|
||||
|
||||
- Toda funcionalidade relevante tem testes (unitário, integração, regressão).
|
||||
- Cobrir: entradas válidas/inválidas, casos vazios/extremos, erros, retornos, efeitos colaterais, regras de negócio.
|
||||
- Ao corrigir bug, criar/atualizar teste que impeça regressão.
|
||||
|
||||
## Checklist antes de finalizar
|
||||
|
||||
Antes de dar como concluída qualquer implementação Python em `code/engine/`, percorrer a seção 41 da skill `boas-praticas-oo.md`: requisitos, arquitetura, código, documentação e testes.
|
||||
Reference in New Issue
Block a user