Alterar um repositório full-stack usando os comandos e testes dele

## Ler a documentação primeiro e trabalhar em uma branch com pull request Leia as orientações gerais do repositório, a documentação dos subsistemas, os manifestos dos pacotes e as implementações próximas antes de planejar uma alteração. Identifique todas as áreas afetadas, incluindo frontend, API, SDK, CLI, banco de dados, contêineres e documentação. Trate a branch padrão protegida como somente leitura para o desenvolvimento direto. Crie uma branch com nome descritivo, faça commits significativos e abra um pull request para revisão. Não reescreva o histórico compartilhado alterando um commit existente e não faça o merge do próprio pull request quando o fluxo de trabalho atribuir essa decisão a um revisor. Mantenha a branch concentrada no comportamento solicitado. Separe limpezas não relacionadas e preserve os padrões estabelecidos, a menos que a tarefa exija uma alteração deliberada. ## Usar os comandos do repositório e as versões fixadas do ambiente Descubra os comandos documentados de desenvolvimento, formatação, lint, teste, migração e inicialização antes de executá-los. Use o comando pertencente ao pacote afetado em vez de substituí-lo por uma ferramenta aplicada a todo o repositório. Respeite as versões fixadas do ambiente de execução e os ambientes existentes; uma versão principal mais recente do ambiente de execução não tem compatibilidade automática. Instale dependências somente quando estiverem ausentes. Não inicie toda a pilha da aplicação, os contêineres nem servidores de longa duração, a menos que a tarefa ou a verificação pertinente exija isso. Execute formatadores e linters nos arquivos alterados com os modos documentados. Comece por um seletor compatível de um único teste e só então amplie para a suíte diretamente afetada. Quando um subsistema importar um pacote SDK instalado em vez da árvore de código-fonte correspondente, reinstale esse SDK depois de editá-lo e reinicie o processo que o utiliza. Verifique as portas e os pré-requisitos necessários antes de iniciar processos de desenvolvimento combinados. ## Manter separados os papéis da interface, API, serviços e migrações Mapeie as responsabilidades antes de editar: - a interface do usuário é responsável pela apresentação e pelo estado do cliente; - a API é responsável pela validação das solicitações e pelas questões de transporte; - os módulos de serviço são responsáveis pela lógica de negócios; - os pacotes de SDK e CLI são responsáveis por seus contratos públicos; - as migrações são responsáveis pela evolução do banco de dados. Leia a documentação do subsistema que será alterado e examine arquivos existentes semelhantes antes de introduzir um novo padrão. Quando uma alteração atravessar camadas, avance em pequenos passos: defina tipos ou esquemas, implemente a lógica do serviço, exponha o contrato da API, atualize o cliente e, em seguida, construa a interface. Instale cada dependência no pacote que a utiliza. Ao adicionar um pacote de workspace, atualize todos os manifestos de build de contêineres de produção e locais que copiam os metadados dos pacotes antes da instalação das dependências. ## Seguir as regras de TypeScript, Python e banco de dados Use tipos estritos de TypeScript, evite tipos irrestritos, defina com clareza os contratos dos componentes e da API e siga os padrões estabelecidos pelo repositório para componentes e gerenciamento de estado. Prefira componentes funcionais e ações explícitas de estado em vez de passar propriedades por muitas camadas. No código Python, forneça anotações de tipo em cada limite de função, use modelos de validação para serialização e mantenha a lógica de negócios nos serviços, não nos roteadores de transporte. Os roteadores devem validar solicitações, chamar serviços e formatar respostas. Siga as regras existentes de tabelas e migrações, incluindo qualquer proibição de chaves estrangeiras. Mantenha as operações de banco de dados portáveis entre todos os mecanismos compatíveis. Use a função auxiliar de UTC do repositório para campos de data e hora, em vez da hora local, de APIs obsoletas ou de conversões feitas manualmente. Respeite a decisão do repositório sobre o armazenamento em sistema de arquivos ou banco de dados. Não transfira dados sincronizados do cluster para um banco de dados apenas por conveniência. ## Testar cada alteração na camada e no conjunto de testes a que pertence Use o sistema de testes realmente configurado para cada subsistema. Se o frontend não tiver um framework de testes unitários, cubra seu comportamento com a suíte de ponta a ponta designada em vez de introduzir um executor não compatível. Coloque os testes unitários e de serviço do backend na árvore estabelecida e execute a suíte da CLI depois de alterar o código-fonte da CLI. Substitua por mocks o armazenamento externo, os provedores de computação e as interações com o sistema de arquivos para que os testes permaneçam rápidos e determinísticos. Prefira testes diretos dos serviços para regras de negócios que não exijam toda a pilha da API. Execute primeiro um teste específico e depois a suíte pertinente do subsistema. Garanta que execuções repetidas sejam seguras diante de dados existentes, use seletores estáveis e permita tempos-limite realistas para trabalhos em fila ou transições de estado. Não declare sucesso apenas com base no nome de um comando. Confirme que os arquivos de teste pretendidos foram descobertos e que o resultado exercita o comportamento alterado. ## Verificar as páginas alteradas no navegador e testar as APIs com login Use a ferramenta de navegador interativo aprovada pelo repositório para a inspeção visual. Reserve os scripts automatizados de ponta a ponta para a suíte de testes mantida ou para uma solicitação explícita. Inicie somente a aplicação de teste necessária, acesse as páginas alteradas e as diretamente relacionadas, capture evidências e corrija regressões visíveis. Prefira seletores por função, texto exato e placeholder. Lide com dados de teste repetidos sem presumir um banco de dados limpo. O conteúdo renderizado por um emulador de terminal pode não existir no DOM; quando necessário, verifique-o por meio da API subjacente. Nas verificações autenticadas da API, use a identidade de teste e o fluxo de autenticação documentados. Forneça os headers exigidos para o escopo da conta ou do tenant, diferencie endpoints protegidos de não protegidos e nunca coloque credenciais reutilizáveis no código-fonte, nos logs nem na documentação resultante. ## Adicionar dependências com cuidado e não deixar senhas nos logs Verifique os manifestos dos pacotes antes de adicionar dependências e use o fluxo de instalação do repositório. Mantenha ativos os hooks de formatação e lint anteriores ao commit quando o projeto depender deles. Trate as substituições de dependências como controles de segurança temporários, não como adereços permanentes. Ao atualizar um pacote pai, teste se a substituição pode ser removida, execute a verificação de vulnerabilidades pertinente e mantenha a substituição se a dependência resolvida ainda não for segura. Não amplie a exposição de credenciais ao testar integrações. Substitua provedores externos por mocks quando o comportamento real deles não for o objeto do teste e mantenha os logs livres de tokens, senhas e identificadores pessoais. ## Revisar as alterações e relatar as evidências antes de terminar Leia antes de planejar, faça a menor implementação coerente e verifique cada limite afetado antes de ampliar o escopo. Em alterações maiores, mantenha a sequência explícita e revisável, em vez de misturar o trabalho de backend, API, cliente e interface em uma única etapa opaca. Antes de relatar a conclusão, examine o diff e execute o formatador, o linter, a verificação de tipos, os testes, as verificações de migração e a inspeção visual pertinentes que as áreas alteradas exigirem. Não acrescente um build completo nem uma suíte não relacionada apenas para causar boa impressão. Relate o que mudou, quais verificações foram executadas, quais verificações mais amplas permaneceram fora do escopo e qualquer risco residual. A conclusão exige evidências do comportamento alterado, não apenas uma edição bem-sucedida.