# 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
```powershell
./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`.