Pular para o conteúdo principal

Padrões e Convenções Lucent Minds

Bem-vindo aos padrões de desenvolvimento e documentação da Lucent Minds. Aqui você encontra templates, convenções e boas práticas para garantir consistência e qualidade em todos os projetos.

📋 Templates de Documentação​

Template de Projeto​

Template completo para documentar novos projetos e POCs. Inclui todas as seções essenciais:

  • ✅ Visão geral e contexto de negócio
  • ✅ Stack técnico detalhado
  • ✅ Arquitetura e decisões de design
  • ✅ Setup de desenvolvimento local
  • ✅ Estrutura do projeto
  • ✅ Deploy e CI/CD
  • ✅ ADRs (Architecture Decision Records)
  • ✅ Problemas conhecidos e melhorias futuras

📖 Ver Template Completo →

🏗️ Padrões de Arquitetura​

ADRs (Architecture Decision Records)​

Documentamos todas as decisões arquiteturais importantes usando o formato ADR:

### ADR-XXX: [Título da Decisão]

**Data**: AAAA-MM-DD

**Contexto**: Por que precisamos tomar esta decisão?

**Decisão**: O que decidimos fazer?

**Consequências**:
- ✅ Positivo: Benefícios obtidos
- ❌ Negativo: Trade-offs aceitos

**Alternativas Consideradas**:
- Alternativa 1: Por que não escolhemos
- Alternativa 2: Por que não escolhemos

Princípios Arquiteturais​

  • Backend Logic Preference: Lógica de negócio no backend (Node.js/Express), não no banco de dados
  • Type Safety: TypeScript em todos os projetos para maior segurança
  • Multi-Tenancy: Isolamento forte com Row-Level Security (RLS) quando aplicável
  • API First: Design de APIs REST bem documentadas
  • Security by Default: Autenticação, autorização e criptografia como padrão

💻 Convenções de Código​

Nomenclatura​

TypeScript/JavaScript:

  • Variáveis e funções: camelCase
  • Classes e componentes: PascalCase
  • Constantes: UPPER_SNAKE_CASE
  • Arquivos de componentes: PascalCase.tsx
  • Arquivos utilitários: camelCase.ts

Python:

  • Variáveis e funções: snake_case
  • Classes: PascalCase
  • Constantes: UPPER_SNAKE_CASE

Estrutura de Diretórios​

projeto/
├── src/
│   ├── components/       # Componentes reutilizáveis
│   ├── pages/           # Páginas da aplicação
│   ├── hooks/           # Custom React hooks
│   ├── lib/             # Utilitários e helpers
│   ├── types/           # TypeScript type definitions
│   └── services/        # Lógica de negócio
├── server/              # Backend API
│   ├── src/
│   │   ├── routes/      # Endpoints da API
│   │   ├── services/    # Lógica de negócio
│   │   └── middlewares/ # Middlewares Express
├── tests/               # Testes
├── docs/                # Documentação adicional
└── .clinerules          # Padrões para IA

📝 Documentação de Código​

Comentários​

  • Evite comentários óbvios: O código deve ser auto-explicativo
  • Documente o "porquê", não o "o quê"
  • Use JSDoc/TSDoc para funções públicas
/**
 * Calcula o score de risco baseado em regras configuráveis
 *
 * @param profile - Perfil CPF/CNPJ com dados validados
 * @param rules - Regras de risco do tenant
 * @returns Score total e fatores de risco identificados
 */
export async function calculateRiskScore(
  profile: Profile,
  rules: RiskRule[]
): Promise<RiskAssessment> {
  // implementação
}

🧪 Padrões de Teste​

Cobertura​

  • Meta mínima: 80% de cobertura
  • Prioridade: Lógica de negócio crítica
  • Pirâmide de testes: Muitos unitários, alguns integração, poucos E2E

Organização​

tests/
├── unit/           # Testes unitários (funções isoladas)
├── integration/    # Testes de integração (APIs, DB)
└── e2e/           # Testes end-to-end (fluxos completos)

🔐 Segurança​

Checklist de Segurança​

  • Autenticação: JWT ou OAuth implementado
  • Autorização: Verificação de permissões por role
  • Validação de Input: Sanitização de todos os inputs do usuário
  • Secrets: Variáveis sensíveis em .env, nunca commitadas
  • Criptografia: Dados sensíveis criptografados (AES-256-GCM)
  • HTTPS: TLS/SSL em produção
  • Rate Limiting: Proteção contra abuso de APIs
  • SQL Injection: Uso de prepared statements/ORMs
  • XSS: Sanitização de HTML e inputs

🚀 CI/CD​

Pipeline Padrão​

stages:
  - install    # npm install
  - lint       # ESLint, Prettier
  - test       # Jest, Vitest
  - build      # npm run build
  - deploy     # Deploy para staging/production

Branches​

  • main - Produção (protegida)
  • dev - Desenvolvimento (branch padrão)
  • feature/* - Features (criar a partir de dev)
  • hotfix/* - Correções urgentes (criar a partir de main)

📚 Recursos Adicionais​

Templates Disponíveis​

🤝 Contribuindo​

Para sugerir novos padrões ou melhorias:

  1. Abra uma issue no repositório de documentação
  2. Descreva o padrão proposto e justificativa
  3. Aguarde review e discussão com o time
  4. Após aprovação, atualize esta documentação

Última Atualização: Janeiro 2025 Mantido Por: Equipe Lucent Minds