AGENTS.md

TestManager - guia de colaboracao para IA

Objetivo do sistema

Manter e evoluir o TestManager, uma aplicacao web em .NET 8 voltada para gestao interna de bugs, dashboard operacional, integracao com Azure DevOps On-Premises e execucao isolada de testes sob demanda.

Estado atual implementado

• dashboard principal em /dashboard
• listagem de bugs (Azure DevOps) em /bugs → /bugs/ado
• bugs persistidos no SQL Server continuam alimentando o dashboard; API REST /api/bugs e telas CRUD de bugs locais foram removidas
• integracao Azure DevOps em /integracoes/azuredevops
• modulo de testes isolado em /testing
• SQL Server com EF Core e migrations versionadas
• scripts locais para execucao e testes em scripts/

Regras obrigatorias

1. Usar Portugues do Brasil em textos de interface, mensagens e documentacao funcional.
2. Preservar a separacao entre Domain, Application, Infrastructure e Web.
3. Nao colocar acesso a banco, HTTP externo ou regras de negocio diretamente em views ou controllers.
4. Toda alteracao de endpoint, tela, regra, script ou configuracao deve atualizar a documentacao correspondente.
5. O modulo de testes deve continuar isolado e removivel sem quebrar o restante da aplicacao.
6. A integracao com Azure DevOps deve continuar centralizada e desacoplada da UI.

Estrutura principal

• src/TestManager.Web
• src/TestManager.Application
• src/TestManager.Domain
• src/TestManager.Infrastructure
• tests/TestManager.UnitTests
• tests/TestManager.IntegrationTests
• tests/TestManager.E2E
• docs
• scripts

Convenios arquiteturais

• Domain contem entidades, enums, filtros e invariantes
• Application contem DTOs, contratos e servicos de aplicacao
• Infrastructure contem DbContext, configuracoes Fluent API, migrations, repositorios e integracoes externas
• Web contem composicao, controllers, endpoints, view models, views e assets
• o bootstrap da aplicacao fica centralizado em TestManagerBootstrapExtensions
• rotulos repetidos de bugs devem reaproveitar RotulosBug
• formatacoes visuais recorrentes da Web devem reaproveitar FormatadorApresentacaoBug

Modulo de bugs

• Bug e o agregado raiz
• comentarios, anexos e historico sao subordinados ao bug
• filtros, paginacao e ordenacao passam pela camada de aplicacao
• a UI atual permite criar, editar, detalhar, comentar, anexar metadados e vincular Azure DevOps

Modulo de testes

• ativado por Features:ModuloTestesHabilitado
• rotas dedicadas GET /testing, GET /testing/state, GET /testing/last-result e POST /testing/run
• DI centralizado em AddModuloTestes
• execucao real encapsulada em ExecutorProcessoModuloTestes
• script dedicado em scripts/testing/run-suite.ps1
• scripts centrais scripts/run-local.ps1, scripts/run-local.cmd, scripts/test-all.ps1 e scripts/test-all.cmd

Integracao Azure DevOps

• a interface publica atual e IAzureDevOpsService
• o cliente HTTP centralizado e AzureDevOpsHttpClient
• a autenticacao atual aceita Usuario e Senha ou TokenAcesso
• a configuracao de runtime atual vem de appsettings
• a entidade IntegracaoAzureDevOpsConfig existe no dominio e na persistencia, mas ainda nao ha tela ou fluxo de runtime usando esse repositorio

Banco de dados

• TestManagerDbContext fica em src/TestManager.Infrastructure/Persistence
• migrations atuais InicialCreate, ExpandirDominioBugs e CorrigirDefaultsClassificacaoBug
• o projeto esta preparado para SQL Server

Quando alterar a documentacao

• ao criar ou remover endpoint
• ao alterar payload ou filtro de API
• ao mudar fluxo de tela
• ao mexer em scripts de execucao ou testes
• ao mudar configuracao de banco, feature flag ou Azure DevOps
• ao alterar a forma de desligar ou remover o modulo de testes

Checklist minimo por entrega

1. revisar impacto visual
2. revisar impacto na API
3. revisar impacto no banco
4. revisar impacto em testes
5. revisar impacto em documentacao

Arquivos de documentacao obrigatorios

• README.md
• docs/ARCHITECTURE.md
• docs/API.md
• docs/TESTING.md
• docs/DEPLOY.md
• docs/CHANGELOG.md
• docs/DECISIONS.md

Execucao local e correcoes

• Antes de aplicar correcoes que exijam recompilar a Web, encerre o processo dotnet em execucao para o TestManager (evita bloqueio de DLL e falhas MSB3026). No PowerShell: filtrar Win32_Process com dotnet.exe e CommandLine contendo TestManager, depois Stop-Process.
• Apos a correcao e dotnet build, execute de novo com ./scripts/run-local.ps1 (ou -SemRestore -SemBuild -SemCssBuild se ja compilou e nao mudou CSS).
• Ao terminar uma entrega que altere codigo, views, estilos ou scripts de execucao da aplicacao, o agente deve sempre subir o TestManager com ./scripts/run-local.ps1 (em segundo plano quando fizer sentido), para validar que compila e inicia; se ja existir instancia em execucao na mesma porta, encerrar antes ou usar -SemBuild conforme o caso.

Comandos uteis

./scripts/run-local.ps1 -AplicarMigracoes
./scripts/test-all.ps1
dotnet build TestManager.sln --no-restore -m:1
dotnet test TestManager.sln --no-build -m:1

Os scripts run-local.ps1 e test-all.ps1 executam npm run css:build via scripts/build-web-css.ps1 salvo com -SemCssBuild.