Projeto: Controle de Acesso de Veículos
Instituição: Instituto Federal de Pernambuco — Campus Belo Jardim
Disciplina: Projeto Integrador — Práticas Reais de Software e Segurança
Equipe: José Ernandes Gonçalves Costa; Raíssa Beatriz Marinho dos Santos
Cliente inicial: Eurico Lopes — Setor de Transporte
Versão: 0.29
Status: Execução local, containers, release técnica no GHCR e baseline DAST passiva documentados; deploy e operação de produção pendentes
Data de referência: 30 de setembro de 2026
Issue relacionada: #13 — Criar guia de execução, configuração, deploy e operação
Documentos relacionados: MVP e Fluxo Digital v0.1; Requisitos e Backlog v0.3; Modelo de Dados v0.3; Arquitetura de Software — arc42 v0.2; Segurança e Privacidade v0.1; Estratégia de Testes v0.2; Decisão de Stack Tecnológica v0.2

A main utiliza 16 migrations e possui 258 testes automatizados no backend, incluindo integração com PostgreSQL real via Testcontainers, além de 432 testes automatizados no frontend. A aplicação local integrada possui frontend funcional, API e PostgreSQL em containers. O endpoint demonstrativo /weatherforecast foi removido; validações técnicas devem utilizar os health checks e endpoints reais do produto.

O backend implementa access token curto e sessão renovável no servidor por refresh token opaco em cookie HttpOnly, com rotação, revogação, CSRF e logout. O frontend integra esse ciclo sem persistir tokens no armazenamento do navegador, restaura sessões válidas, limita cada repetição após renovação e coordena o encerramento entre abas. A atividade humana renova o período local; após 15 minutos sem interação a interface encerra a sessão, enquanto o servidor mantém o limite absoluto de 12 horas. Processos em segundo plano não reiniciam esses limites. O Nginx aplica CSP e cabeçalhos defensivos no ambiente local, mas isso não substitui HTTPS, gestão de segredos e validação no ambiente institucional.

O key ring do ASP.NET Core Data Protection é persistido em volume durável compartilhável e seus XML são protegidos por certificado X.509 externo. O Compose local monta certificado e senha como segredos somente leitura; o Compose de produção exige volume externo e falha de forma fechada sem a configuração. O ensaio automatizado substitui o contêiner da API e confirma que um token antifalsificação anterior continua válido. Na OCI, o volume compartilhado e o serviço de segredos ainda precisam ser provisionados pela Issue #311.

Produção, backup externo protegido, collector, alertas, retenção, RPO, RTO e contingência continuam pendentes. As seções datadas abaixo preservam o histórico dos incrementos e não devem ser interpretadas isoladamente como o estado atual.

A Issue #227, concluída pelo PR #228, integrou o OWASP ZAP ao smoke test do workflow CI - Containers. Depois de PostgreSQL, API e frontend ficarem saudáveis, o scanner acessa somente http://frontend:8080 dentro da rede descartável do Compose, executa spider tradicional e análise passiva e preserva relatórios HTML, JSON e Markdown por 14 dias.

Uma amostra sanitizada e versionada dos relatórios preserva a evidência histórica da execução bem-sucedida 35054736853, realizada em 16 de setembro de 2026 sobre o commit e7d6f37. Naquela execução, o baseline registrou 0 alertas altos, 0 médios, 1 baixo e 3 informativos. Esses resultados descrevem apenas aquela análise passiva, não autenticada e restrita à superfície pública da stack descartável; não representam o estado atual, um teste autenticado, um pentest ou aprovação para produção.

A imagem oficial ZAP 2.17.0 está fixada por digest e executa sem capacidades Linux adicionais. A política versionada em infrastructure/security/zap-baseline.conf reprova achados classificados como FAIL, registra hipóteses e informações como WARN e também falha quando o scanner ou seus relatórios não são confiáveis. WARN não significa aprovação automática: precisa ser revisado no artefato do workflow.

O baseline atual é passivo e não autenticado. Ele verifica a superfície pública e os cabeçalhos entregues pelo Nginx, mas não substitui revisão de código, Dependency Review, Trivy, SBOM, testes autenticados, HTTPS nem pentest autorizado no ambiente de destino. A Issue #219 registrou a decisão de utilizar GitHub Code Quality e os controles nativos existentes, sem depender do SonarQube Cloud.

Fonte técnica: docs/security/dynamic-application-security-testing.md.

A Issue #112, concluída pela PR #113, adicionou o workflow CI - Demo data. Quando backend, Compose ou inicializador mudam, a CI cria credenciais efêmeras, constrói a imagem backend, inicia PostgreSQL em porta aleatória, aplica todas as migrations, provisiona o Administrador e executa duas vezes os cenários fictícios. Resultados observáveis diferentes fazem o job falhar.

O job possui somente contents: read, não publica imagem ou banco e remove containers, rede e volume mesmo após falha. Seu sucesso comprova repetibilidade técnica no Linux; não comprova usabilidade nem aceitação pelo cliente.

A Issue #110, concluída pela PR #111, registrou que o Npgsql 10 tenta por padrão negociar criptografia de sessão GSSAPI. Em ambientes Linux locais sem Kerberos, o runtime podia escrever um aviso de biblioteca ausente antes de o Npgsql fazer o fallback e conectar normalmente por usuário e senha.

O Compose e o appsettings.Development.json agora definem GSS Encryption Mode=Disable exclusivamente nos exemplos locais. A decisão remove o ruído sem instalar pacotes Kerberos desnecessários na imagem e sem alterar a autenticação PostgreSQL existente.

Essa opção não fornece criptografia de transporte. Homologação e produção devem escolher explicitamente SSL Mode=VerifyFull, com cadeia de certificados confiável, ou GSSAPI/Kerberos quando houver infraestrutura institucional para isso. A configuração local não deve ser copiada automaticamente para produção.

A Issue #108, concluída pela PR #109, adicionou um inicializador repetível para demonstração local do MVP. Ele usa somente os endpoints autenticados da API, aceita endereços de loopback e não contém credenciais nem dados pessoais reais.

Com a API saudável e o Administrador local provisionado:

./infrastructure/demo/Initialize-DemoData.ps1

O operador informa a credencial administrativa e três senhas temporárias distintas por prompts protegidos. O conjunto inclui contas de Porteiro, Vigilante e Setor de Transporte, acessos gerais aberto e encerrado, frota e motorista institucionais, usos aberto e concluído e autorização de evento. Uma segunda execução com as mesmas senhas comprova que os cenários não são duplicados. O banco deve ser exclusivamente local e descartável; o procedimento não substitui homologação com usuários nem autoriza dados institucionais.

Consulte o infrastructure/demo/README.md para pré-requisitos, proteções e limpeza.

A Issue #90, concluída pela PR #91, adicionou publicação automática no GitHub Container Registry. O workflow mantém build e scan sem publicação em Pull Requests. A política foi endurecida pela Issue #318: pushes na main também são apenas validação, e somente tags Git revisadas no formato vMAJOR.MINOR.PATCH liberam um job com packages: write. Esse job reconstrói as imagens, executa novamente o Trivy e autentica com o GITHUB_TOKEN efêmero para realizar o push.

Imagens disponíveis:

ghcr.io/ifpebj-ti/controle-acesso-veiculos-backend
ghcr.io/ifpebj-ti/controle-acesso-veiculos-frontend

Quando uma Pull Request é encerrada, o workflow de manutenção remove somente os caches associados à referência efêmera refs/pull/<número>/merge. Os caches da main e de outras referências não são atingidos. Isso reduz armazenamento obsoleto sem transformar a limpeza em uma operação ampla sobre o repositório.

Os builds de validação e release consultam as tags atuais das imagens-base antes de reutilizar o cache do BuildKit. Se uma correção Ubuntu já estiver disponível, mas a imagem oficial do runtime .NET ainda não tiver sido reconstruída, a etapa final do backend atualiza somente openssl e libssl3t64 e remove os metadados do APT. O Trivy continua bloqueando vulnerabilidades altas corrigíveis; nenhuma exceção foi criada para contornar o scan. Essa política fortalece a cadeia de entrega, mas não substitui atualização de versões, revisão nem monitoramento.

A Issue #218, concluída pelo PR #224, passou a validar e publicar backend e frontend para linux/amd64 e linux/arm64. Cada variante é construída, analisada e recebe um SBOM SPDX 2.3 antes do envio. O workflow rejeita toda vulnerabilidade crítica, inclusive sem correção publicada; vulnerabilidades altas são sempre reportadas e bloqueiam a publicação quando possuem correção.

Somente depois da aprovação das quatro variantes e do smoke test integrado, uma tag de release publica referências imutáveis por arquitetura, cria um manifesto com exatamente as duas plataformas, registra as atestações no GitHub Artifact Attestations e aplica a versão semântica ao mesmo digest. Pull Requests e pushes comuns na main continuam sem permissão de publicação.

Inspeção do manifesto:

docker buildx imagetools inspect \
  ghcr.io/ifpebj-ti/controle-acesso-veiculos-backend:0.3.0

docker buildx imagetools inspect \
  ghcr.io/ifpebj-ti/controle-acesso-veiculos-frontend:0.3.0

Na execução de release 36647783284, associada ao commit be49b67, foram verificados externamente:

backend  sha256:5c620d3c6609144c8cc0f53c1505dd3c2414d206aa29d69f96b6ab64b24d31b0
frontend sha256:cd9ed896b47327a6ca71f191284e71988411ffc608b3d1e634d1a9df01b8ddc1

Cada digest final possui uma atestação SLSA de proveniência e duas atestações SPDX 2.3, uma para cada arquitetura, mantidas no serviço GitHub Artifact Attestations. Scan, SBOM e proveniência reduzem riscos da cadeia de entrega, mas não substituem política de admissão, monitoramento, segredos, HTTPS ou homologação do ambiente institucional.

As tags sha-<commit> identificam a revisão exata de uma release. Tags antigas de main permanecem como histórico, mas não são atualizadas pela política atual. Para v0.3.0, as referências imutáveis são:

backend  sha-be49b67734a1db7d2d36525e41e892ddcd8c3247
frontend sha-be49b67734a1db7d2d36525e41e892ddcd8c3247

Exemplo:

docker pull ghcr.io/ifpebj-ti/controle-acesso-veiculos-backend:sha-be49b67734a1db7d2d36525e41e892ddcd8c3247

Pacotes privados exigem autenticação com read:packages. A visibilidade pública deve ser decidida e configurada por um responsável da organização. Registry não é ambiente de execução: HTTPS institucional, observabilidade, backups protegidos, promoção, rollback e deploy continuam pendentes.

A tag anotada v0.3.0 aponta para o commit revisado be49b67. A execução 36647783284 validou os containers, o smoke test e o ZAP antes de publicar as quatro variantes, os manifests e as tags no GHCR e registrar a proveniência e dois SBOMs por imagem no GitHub Artifact Attestations. Para consumo operacional:

docker pull ghcr.io/ifpebj-ti/controle-acesso-veiculos-backend:0.3.0
docker pull ghcr.io/ifpebj-ti/controle-acesso-veiculos-frontend:0.3.0

Os aliases semânticos resolvem para estes manifests com exatamente linux/amd64 e linux/arm64:

backend  sha256:5c620d3c6609144c8cc0f53c1505dd3c2414d206aa29d69f96b6ab64b24d31b0
frontend sha256:cd9ed896b47327a6ca71f191284e71988411ffc608b3d1e634d1a9df01b8ddc1

Os packages principais recebem novas imagens somente a partir de tags SemVer revisadas. Pushes na main executam validação, mas não publicam snapshots. A GitHub Release é adequada a demonstração e avaliação técnica; não autoriza produção institucional.

A primeira release técnica versionada foi publicada a partir da tag anotada v0.2.0, no commit de main 149c3c4. As imagens podem ser obtidas por uma tag legível e estável para essa versão:

docker pull ghcr.io/ifpebj-ti/controle-acesso-veiculos-backend:0.2.0
docker pull ghcr.io/ifpebj-ti/controle-acesso-veiculos-frontend:0.2.0

A execução 35556008849 confirmou build, scans, SBOMs, smoke test, OWASP ZAP, publicação e atestações. Os aliases 0.2.0 apontam exatamente para estes manifestos multi-arquitetura:

backend  sha256:6525113e3ae9132f4082d464cc564a393902d1d7a559a5b2b2469044261e2d97
frontend sha256:9bc8293dc0bbbf9bd83d46981dca0c33e6ecb4bf1835bf7a7fb5a1cbf7e4f8bd

Para ambientes que exigem reprodutibilidade máxima, deve-se fixar a imagem pelo digest, não apenas pela tag. A GitHub Release registra as limitações conhecidas. A versão é adequada a demonstração e avaliação técnica; não autoriza uso institucional em produção.

O GHCR também mantém referências técnicas sha-<commit> e tags por arquitetura das imagens efetivamente analisadas. As atestações assinadas permanecem no GitHub Artifact Attestations e não criam versões OCI sha256-... nos packages. Para executar uma release, use a mesma versão semântica nos dois serviços ou os digests imutáveis das notas da versão.

A Issue #104, concluída pela PR #105, adicionou atestações de proveniência SLSA v1 para cada imagem publicada. O job resolve o digest imutável depois do push, valida seu formato e solicita uma atestação vinculada ao nome e ao digest. As permissões attestations: write e id-token: write existem apenas no job de publicação da release. Depois do PR #231, somente o job que monta e atesta o manifesto também recebe artifact-metadata: write, permissão utilizada pela action oficial para registrar onde a imagem atestada está armazenada. Jobs de Pull Request, build, scan e publicação por arquitetura não recebem essa capacidade. Desde a Issue #318, somente tags SemVer revisadas publicam e atestam os manifests principais; pushes na main permanecem apenas como validação. A Issue #325 manteve essas evidências no serviço GitHub Artifact Attestations e removeu sua duplicação como referrers OCI no GHCR.

Verificação recomendada, exigindo também o workflow assinante e a origem:

gh attestation verify \
  oci://ghcr.io/ifpebj-ti/controle-acesso-veiculos-backend:0.3.0 \
  --repo ifpebj-ti/controle-acesso-veiculos \
  --signer-workflow ifpebj-ti/controle-acesso-veiculos/.github/workflows/ci-containers.yml \
  --source-ref refs/tags/v0.3.0

gh attestation verify \
  oci://ghcr.io/ifpebj-ti/controle-acesso-veiculos-frontend:0.3.0 \
  --repo ifpebj-ti/controle-acesso-veiculos \
  --signer-workflow ifpebj-ti/controle-acesso-veiculos/.github/workflows/ci-containers.yml \
  --source-ref refs/tags/v0.3.0

Na validação da release v0.3.0, backend e frontend apresentaram proveniência válida emitida para refs/tags/v0.3.0. Isso comprova origem e integridade, mas não substitui scan, SBOM, política de admissão ou deploy.

A Issue #106, concluída pela PR #107, faz o Trivy gerar e validar um documento SPDX 2.3 para backend e frontend durante Pull Requests. Na tag de release, o documento é gerado novamente para cada arquitetura e actions/attest vincula os dois SBOMs ao mesmo nome e digest imutável do manifesto. Arquivo vazio, versão inesperada, inventário sem pacotes ou tamanho superior a 16 MiB fazem o workflow falhar.

Verificação e extração do SBOM:

gh attestation verify \
  oci://ghcr.io/ifpebj-ti/controle-acesso-veiculos-backend:0.3.0 \
  --repo ifpebj-ti/controle-acesso-veiculos \
  --signer-workflow ifpebj-ti/controle-acesso-veiculos/.github/workflows/ci-containers.yml \
  --source-ref refs/tags/v0.3.0 \
  --predicate-type https://spdx.dev/Document \
  --format json \
  --jq '.[].verificationResult.statement.predicate' \
  > backend.spdx.json

Repita para a imagem do frontend. Na validação pós-merge do commit 83fdd5e, o backend apresentou 128 pacotes e o frontend 72. O inventário auxilia resposta a incidentes e análise de componentes; ele não afirma, sozinho, que não existem vulnerabilidades.

A Issue #92, concluída pela PR #93, adicionou à CI uma verificação descartável da stack completa. O job gera credenciais efêmeras e mascaradas, usa nome de projeto exclusivo e portas aleatórias, valida o Compose sem imprimir a configuração, constrói e inicia PostgreSQL, API e frontend e verifica:

• PostgreSQL saudável;
• GET /health/ready com estado Healthy;
• frontend HTTP 200 contendo o ponto de montagem da aplicação React.

Em caso de falha, a CI apresenta estado e logs dos containers. Com sucesso ou falha, docker compose down --volumes --remove-orphans é executado apenas no projeto descartável. A publicação no GHCR depende desse job, portanto uma revisão cuja stack integrada não inicia não é publicada automaticamente.

O smoke test não aplica migrations, não provisiona contas, não utiliza dados institucionais e não substitui a suíte funcional nem a homologação com usuários.

O guia foi criado antes da fundação técnica. Atualmente já existem monorepo, backend .NET 10, frontend React, PostgreSQL 16, Docker Compose, pipelines de CI, autenticação e os fluxos operacionais geral e institucional. Quando houver divergência de status nas seções históricas, esta atualização e o README versionado representam a execução disponível.

Validação básica a partir da raiz:

dotnet restore src/backend/ControleAcessoVeiculos.slnx
dotnet build src/backend/ControleAcessoVeiculos.slnx --no-restore
dotnet test src/backend/ControleAcessoVeiculos.slnx --no-build --no-restore

Os testes de integração da suíte atual de 262 testes de backend exigem Docker disponível, criam PostgreSQL 16 isolado e removem o container automaticamente. A CI publica TRX e Cobertura. Instruções operacionais atuais e comandos de migration também estão no README.

Produção, OCI, HTTPS, backup protegido externo, plataforma externa de observabilidade e resposta a incidentes continuam planejados e não devem ser apresentados como implementados.

Rastreabilidade: Issues #20, #23, #24, #29, #47, #67 e #69; PRs #21, #27, #28, #45, #46, #48, #68 e #70.

Este documento apresenta as instruções disponíveis e o planejamento de execução, configuração, deploy e operação do sistema de Controle de Acesso de Veículos do IFPE Campus Belo Jardim.

O objetivo é orientar a equipe sobre como o ambiente de desenvolvimento deverá ser organizado, como a aplicação deverá ser configurada, como o código deverá ser versionado, como as alterações deverão passar por revisão, como a conteinerização e a pipeline deverão ser planejadas e como a solução poderá ser operada após a implementação.

O desenvolvimento local, o banco, os containers e os workflows iniciais já possuem configuração no repositório. O PostgreSQL possui backup lógico, manifesto SHA-256, rejeição de adulteração e restauração isolada verificáveis localmente e na CI. Homologação, produção, deploy, monitoramento e backup externo protegido ainda não existem; instruções dessas áreas permanecem como planejamento e usam placeholders explícitos.

O documento separa explicitamente:

• Stack de aplicação.
• Decisões arquiteturais.
• Infraestrutura e entrega.
• Ferramentas ainda pendentes.
• Estruturas ainda não implementadas.

Este guia aborda preliminarmente:

• Organização do ambiente de desenvolvimento.
• Estrutura prevista do monorepo.
• Organização de pastas.
• Convenções de branch.
• Convenções de commits.
• Fluxo de Pull Request.
• Revisão de código.
• Variáveis de ambiente.
• Proteção de segredos.
• Execução local planejada.
• Testes locais planejados.
• Lint e build planejados.
• Conteinerização local.
• Pipeline inicial e sua evolução.
• Ambientes de desenvolvimento, homologação e produção.
• Estratégia preliminar de deploy.
• Operação inicial.
• Logs e monitoramento futuros.
• Backup e recuperação.
• Contingência.
• Checklist de entrega.

• Implementar casos de uso, endpoints ou telas.
• Executar deploy real.
• Configurar infraestrutura de produção.
• Criar monitoramento funcional.
• Configurar backup real.
• Publicar segredos, credenciais, tokens ou chaves.
• Definir URLs reais de homologação ou produção.
• Escolher ferramentas ainda pendentes sem discussão da equipe.

O projeto encontra-se na fase de implementação incremental, com fundação técnica, segurança inicial, fluxos geral e institucional e manutenção controlada dos catálogos de frota e motoristas implementados.

Já foram produzidos documentos relacionados a:

• Processo Atual da Portaria.
• Visão do Projeto.
• Requisitos e Backlog.
• Regras de Negócio.
• MVP e Fluxo Digital.
• Modelo de Dados.
• Arquitetura de Software — arc42.
• Segurança e Privacidade.
• Estratégia de Testes.
• Decisão de Stack Tecnológica.

A implementação inclui o monorepo, frontend funcional, backend .NET 10, modelo de domínio, persistência PostgreSQL, containers, CI, 262 testes de backend, 432 testes de frontend, autenticação com sessão renovável e encerramento por inatividade humana, ciclo administrativo de contas e consulta restrita da auditoria, controles HTTP, rate limiting e os fluxos geral e institucional. O produto ainda não está disponível para operação real.

Este guia deve ser atualizado progressivamente quando a equipe definir ou implementar:

• Funcionalidades do MVP e seus testes.
• Autenticação, autorização e auditoria operacional.
• Endurecimento dos containers e workflows.
• Infraestrutura na OCI.
• Deploy.
• Monitoramento.
• Backup.
• Procedimentos operacionais.

Para contribuir com a implementação, cada integrante deverá possuir:

• Conta GitHub com acesso ao repositório.
• Git instalado.
• Acesso ao GitHub Project.
• Acesso à Wiki do repositório.
• Conhecimento básico do fluxo de branches, commits e Pull Requests.
• Ferramenta de comunicação definida pela equipe.
• Acesso aos documentos do projeto.
• Ambiente capaz de executar containers quando a conteinerização for iniciada.

Classificação: Preliminar.

Classificação: Pendente.

O repositório deverá utilizar uma estrutura de monorepo para centralizar código, documentação versionada, automação, configurações e arquivos de infraestrutura do projeto.

A estrutura definitiva dependerá de decisões adicionais do frontend e do ambiente, mas a organização preliminar recomendada é:

controle-acesso-veiculos/
├── apps/
│   ├── frontend/
│   └── backend/
│       ├── src/
│       │   ├── ControleAcessoVeiculos.Domain/
│       │   ├── ControleAcessoVeiculos.Application/
│       │   ├── ControleAcessoVeiculos.Infrastructure/
│       │   └── ControleAcessoVeiculos.Api/
│       ├── tests/
│       │   ├── ControleAcessoVeiculos.Domain.Tests/
│       │   ├── ControleAcessoVeiculos.Application.Tests/
│       │   ├── ControleAcessoVeiculos.Infrastructure.Tests/
│       │   └── ControleAcessoVeiculos.IntegrationTests/
│       ├── ControleAcessoVeiculos.sln
│       ├── Directory.Build.props
│       └── Directory.Packages.props
├── docs/
│   ├── arquitetura/
│   ├── operacao/
│   ├── seguranca/
│   └── qualidade/
├── infrastructure/
│   ├── docker/
│   │   ├── frontend/
│   │   ├── backend/
│   │   └── docker-compose.yml
│   ├── deploy/
│   └── monitoring/
├── scripts/
├── tests/
│   ├── integration/
│   └── e2e/
├── .github/
│   └── workflows/
├── README.md
├── CHANGELOG.md
├── LICENSE
└── .gitignore

Classificação: Proposta.

A Wiki deve continuar sendo a principal fonte de documentação de leitura do projeto.

A pasta docs/ poderá conter versões técnicas ou exportáveis dos documentos mais importantes, quando a equipe decidir versioná-los por Pull Request.

A duplicação de documentação deve ser evitada. Quando houver um documento nas duas fontes, a equipe deverá identificar qual é a fonte principal e manter ambas sincronizadas.

Classificação: Proposta.

A aplicação futura poderá utilizar arquivos de configuração para diferentes ambientes.

Exemplos previstos:

.env.example
.env.local
.env.development
.env.test
.env.staging
.env.production

Para o backend ASP.NET Core, a equipe também poderá utilizar:

appsettings.json
appsettings.Development.json
appsettings.Testing.json
appsettings.Production.json

A estrutura definitiva deverá ser definida depois da criação do monorepo e da confirmação das ferramentas.

Classificação: Proposta.

O repositório poderá conter um arquivo .env.example sem valores reais de segredo.

Exemplo preliminar:

# Ambiente
APP_ENV=<development|test|staging|production>

# Aplicação
APP_NAME=controle-acesso-veiculos
APP_URL=http://localhost:<PORTA_APP>

# Backend ASP.NET Core
ASPNETCORE_ENVIRONMENT=<Development|Testing|Staging|Production>
ASPNETCORE_URLS=http://localhost:<PORTA_BACKEND>
BACKEND_PORT=<PORTA_BACKEND>
BACKEND_URL=http://localhost:<PORTA_BACKEND>

# Frontend React
FRONTEND_PORT=<PORTA_FRONTEND>
FRONTEND_URL=http://localhost:<PORTA_FRONTEND>

# PostgreSQL
POSTGRES_HOST=<HOST_BANCO>
POSTGRES_PORT=<PORTA_BANCO>
POSTGRES_DB=<NOME_BANCO>
POSTGRES_USER=<USUARIO_BANCO>
POSTGRES_PASSWORD=<SENHA_BANCO>
DATABASE_URL=<STRING_CONEXAO_BANCO>
ConnectionStrings__DefaultConnection=<STRING_CONEXAO_BANCO>

# Autenticação
AUTH_SECRET=<SEGREDO_AUTENTICACAO>
AUTH_TOKEN_EXPIRATION=<TEMPO_EXPIRACAO>

# Logs
LOG_LEVEL=<Debug|Information|Warning|Error>

# Integrações futuras
STORAGE_URL=<URL_ARMAZENAMENTO_OPCIONAL>

Os seguintes itens nunca devem ser incluídos em commits, Pull Requests, Wiki, issues públicas ou arquivos rastreados:

• Senhas.
• Tokens.
• Chaves privadas.
• Strings de conexão reais.
• Credenciais de banco de dados.
• Segredos de autenticação.
• Chaves de serviços externos.
• Certificados.
• Dados pessoais reais usados em testes.
• URLs privadas de infraestrutura.
• Credenciais OCI.
• Códigos de bypass de MFA.
• Chaves SSH privadas da VM.

O arquivo .env.example deve conter apenas placeholders.

Arquivos locais com segredos devem ser incluídos no .gitignore.

Classificação: Proposta.

A forma de armazenar segredos em homologação, produção e pipeline será definida quando a infraestrutura e as ferramentas forem escolhidas.

Possibilidades futuras incluem:

• Segredos do GitHub Actions.
• Variáveis protegidas do ambiente de deploy.
• Cofre de segredos compatível com a infraestrutura.
• Arquivos de ambiente protegidos e não versionados.
• Configurações seguras da OCI.

Classificação: Futuro.

A branch main é a branch principal do repositório.

Alterações não devem ser enviadas diretamente para main.

O merge deve ocorrer por Pull Request, após revisão e aprovação dos critérios definidos para o projeto.

Classificação: Confirmado em documento da disciplina.

A branch docs/update já foi utilizada para documentação.

Ela pode continuar sendo utilizada para atualizações documentais versionadas, quando fizer sentido criar Pull Request para documentos presentes no repositório.

A Wiki possui fluxo próprio e não depende necessariamente da branch docs/update.

Classificação: Confirmado no contexto do projeto.

A convenção proposta é:

feat/<descricao-curta>
fix/<descricao-curta>
docs/<descricao-curta>
test/<descricao-curta>
chore/<descricao-curta>
refactor/<descricao-curta>
ci/<descricao-curta>
build/<descricao-curta>
security/<descricao-curta>

Exemplos:

feat/registro-entrada-veiculo
feat/autenticacao-usuarios
fix/validacao-quilometragem
docs/estrategia-testes
test/registro-saida
chore/configurar-editorconfig
refactor/servico-registro-acesso
ci/pipeline-inicial
build/docker-compose-inicial
security/proteger-segredos

Classificação: Proposta.

A equipe adotará preliminarmente commits semânticos.

Formato:

tipo: descrição curta

Tipos sugeridos:

Exemplos:

feat: registrar entrada de veículo
fix: corrigir validação de quilometragem
docs: adicionar guia de operação v0.2
test: adicionar testes de saída de veículo
ci: criar pipeline inicial de lint e testes
build: adicionar configuração inicial do container
security: restringir acesso à correção de registros

Classificação: Proposta.

O projeto utiliza tags Git anotadas, GitHub Releases e CHANGELOG.md para incrementos relevantes e versões demonstráveis. A primeira versão publicada é v0.2.0, e a versão técnica atual é v0.3.0.

A convenção segue Semantic Versioning no formato:

v<MAJOR>.<MINOR>.<PATCH>

Exemplo atual:

v0.3.0

Não deve ser criada release antes de existir um incremento implementado, testado e demonstrável. A publicação das tags semânticas de container ocorre somente depois da validação do commit marcado e não substitui aprovação de produção.

Classificação: Implementado e verificado na release técnica v0.3.0.

Issue criada e pronta
    ↓
Branch criada a partir da main
    ↓
Implementação ou documentação realizada
    ↓
Lint, build e testes executados localmente
    ↓
Documentação atualizada
    ↓
Pull Request criado
    ↓
Revisão realizada
    ↓
Pipeline aprovada, quando existir
    ↓
Correções aplicadas, se necessárias
    ↓
Merge na main

Classificação: Proposta.

Cada Pull Request deve conter:

• Título claro.
• Referência à issue relacionada.
• Objetivo da alteração.
• Descrição das mudanças.
• Testes executados.
• Resultado local.
• Resultado da pipeline, quando existir.
• Impacto em segurança, privacidade ou dados, quando aplicável.
• Pendências conhecidas.
• Atualização de documentação, quando necessária.
• Evidência de demonstração, quando aplicável.

Classificação: Proposta alinhada à disciplina.

## Issue relacionada

Closes #<NUMERO_DA_ISSUE>

## Objetivo

Descreva o objetivo da alteração.

## Alterações realizadas

- Item 1
- Item 2
- Item 3

## Testes executados

- [ ] Testes unitários
- [ ] Testes de integração
- [ ] Testes manuais
- [ ] Lint
- [ ] Build
- [ ] Pipeline, quando disponível

## Segurança e privacidade

Descreva impactos, se houver.

## Documentação

- [ ] Wiki atualizada
- [ ] README atualizado, se necessário
- [ ] Estratégia de Testes atualizada, se necessário
- [ ] Nenhuma alteração documental necessária

## Evidências

Inclua capturas, comandos executados, logs sem segredos ou outras evidências necessárias.

## Pendências

Liste pendências conhecidas, se existirem.

Classificação: Proposta.

A revisão deve verificar, quando aplicável:

• Atendimento à issue.
• Atendimento aos critérios de aceite.
• Clareza e organização do código.
• Testes adequados.
• Tratamento de erros.
• Validações.
• Autorização.
• Auditoria.
• Segurança e privacidade.
• Ausência de segredos.
• Atualização de documentação.
• Ausência de alteração não justificada em regras pendentes.

Classificação: Proposta.

A aplicação ainda não foi implementada.

A stack principal foi definida, mas as ferramentas complementares, o monorepo real, o banco local, os containers e os comandos de execução ainda não foram criados.

Os comandos históricos desta seção devem ser comparados com a atualização operacional e o README. Placeholders só permanecem para ambientes ainda não definidos, como homologação e produção. Os comandos locais devem usar:

• .NET 10 e a solução src/backend/ControleAcessoVeiculos.slnx.
• npm e os scripts versionados em src/frontend/package.json.
• Criação da solução backend.
• Configuração do PostgreSQL.
• Configuração do Docker Compose.

Classificação: Confirmado.

Clonar repositório
    ↓
Criar arquivo de ambiente local
    ↓
Instalar dependências do frontend
    ↓
Restaurar dependências do backend
    ↓
Configurar PostgreSQL local ou containerizado
    ↓
Executar migrations, quando existirem
    ↓
Iniciar backend ASP.NET Core
    ↓
Iniciar frontend React
    ↓
Acessar aplicação local
    ↓
Executar testes

Classificação: Proposta.

# Clonar o repositório
git clone https://github.com/ifpebj-ti/controle-acesso-veiculos.git

# Entrar na pasta
cd controle-acesso-veiculos

# Criar configuração local a partir do exemplo
cp .env.example .env.local

# Instalar dependências do frontend
<COMANDO_INSTALAR_DEPENDENCIAS_FRONTEND>

# Restaurar dependências do backend
dotnet restore

# Configurar banco ou iniciar serviços locais
<COMANDO_INICIAR_POSTGRES_LOCAL>

# Executar migrations, quando existirem
dotnet ef database update

# Iniciar backend
dotnet run --project apps/backend/src/ControleAcessoVeiculos.Api

# Em outro terminal, iniciar frontend
<COMANDO_INICIAR_FRONTEND>

# Executar testes backend
dotnet test

# Executar testes frontend
<COMANDO_EXECUTAR_TESTES_FRONTEND>

# Executar lint
<COMANDO_EXECUTAR_LINT>

# Executar build backend
dotnet build

# Executar build frontend
<COMANDO_EXECUTAR_BUILD_FRONTEND>

Os comandos dotnet são executáveis com o SDK .NET 10 a partir da solução versionada. Caso um exemplo desta baseline use caminho diferente, prevalecem os comandos da atualização operacional e do README.

Classificação: Pendente de configuração.

Antes de abrir Pull Request, a equipe deverá executar os testes aplicáveis à alteração.

Exemplos previstos:

# Backend
dotnet test

# Cobertura backend
<COMANDO_COBERTURA_DOTNET>

# Integração com PostgreSQL
<COMANDO_TESTES_INTEGRACAO>

# Frontend
<COMANDO_TESTES_FRONTEND>

# Interface ou ponta a ponta
<COMANDO_TESTES_E2E>

As ferramentas complementares e os comandos reais serão definidos após a organização do monorepo e do frontend.

Classificação: Pendente.

O lint deverá verificar padrões de código, problemas básicos e possíveis inconsistências antes da abertura de Pull Request.

Exemplos previstos:

# Backend
<COMANDO_LINT_DOTNET>

# Frontend
<COMANDO_LINT_FRONTEND>

As ferramentas ainda não foram definidas.

Classificação: Pendente.

O build deverá confirmar que os componentes do projeto podem ser compilados ou empacotados.

Exemplos previstos:

# Backend
dotnet build

# Frontend
<COMANDO_BUILD_FRONTEND>

A ferramenta e os artefatos do frontend ainda não foram definidos.

Classificação: Pendente.

A equipe adotará uma meta preliminar de cobertura de 70% para componentes e fluxos críticos, sujeita à validação dos professores e às possibilidades da stack escolhida.

A cobertura real ainda não foi medida porque não existe código ou ferramenta de cobertura configurada.

Classificação: Proposta.

A aplicação deverá ser planejada para execução em containers.

A conteinerização deverá permitir que frontend, backend e banco de dados sejam executados de forma reproduzível em diferentes ambientes.

A decisão de infraestrutura considera:

• Docker.
• Docker Compose.
• Backend ASP.NET Core.
• Frontend React.
• PostgreSQL.

Classificação: Confirmada como direcionamento técnico; não implementada.

infrastructure/
└── docker/
    ├── frontend/
    │   └── Dockerfile
    ├── backend/
    │   └── Dockerfile
    ├── docker-compose.yml
    └── docker-compose.override.yml

A estrutura real deverá ser criada após a organização do monorepo.

Classificação: Futuro.

# Construir imagens
docker compose build

# Iniciar ambiente com containers
docker compose up -d

# Visualizar logs
docker compose logs -f

# Interromper ambiente
docker compose down

Os comandos são direcionamentos para Docker Compose e deverão ser validados quando o arquivo real existir.

Quando a containerização for implementada, a equipe deverá considerar:

• Imagens base atualizadas.
• Imagens oficiais compatíveis com .NET 10, PostgreSQL 16 e o frontend definido.
• Dependências sem vulnerabilidades conhecidas críticas.
• Não inclusão de segredos nas imagens.
• Usuário não privilegiado, quando aplicável.
• Arquivos mínimos necessários na imagem.
• Análise de imagem na pipeline, quando disponível.
• Atualização periódica das dependências.

Classificação: Proposta.

A pipeline deverá automatizar verificações de qualidade antes do merge e, futuramente, apoiar a geração de artefatos, imagens e deploy.

A pipeline inicial já existe para backend e frontend. Build de imagens, scanners e deploy continuam como evolução da Issue #25.

Classificação: Confirmado.

Pull Request ou push em branch permitida
    ↓
Configuração do ambiente .NET e frontend
    ↓
Instalação e restauração de dependências
    ↓
Lint
    ↓
Build do backend
    ↓
Build do frontend
    ↓
Testes unitários
    ↓
Testes de integração, quando configurados
    ↓
Relatório de cobertura, quando configurado
    ↓
Análise de dependências
    ↓
Build de imagem, quando containerizado
    ↓
Análise de imagem, quando configurada
    ↓
Publicação de artefato ou imagem, quando aprovada

Classificação: Futuro.

A pipeline futura deverá:

• Utilizar versão do .NET compatível com a decisão confirmada.
• Configurar ambiente de frontend após a definição de suas ferramentas.
• Não expor segredos em logs.
• Executar testes aplicáveis.
• Falhar quando houver erro de lint, build ou teste crítico.
• Produzir relatórios quando suportado.
• Registrar evidências de execução.
• Integrar-se ao Pull Request.
• Ser atualizada junto com a evolução do projeto.

Classificação: Proposta.

O ambiente de desenvolvimento será utilizado pela equipe para implementar, executar e testar localmente.

Características esperadas:

• React e TypeScript no frontend.
• ASP.NET Core Web API no backend.
• PostgreSQL local ou containerizado.
• Dados fictícios ou anonimizados.
• Variáveis de ambiente locais.
• Ferramentas de desenvolvimento.
• Execução de lint, build e testes.
• Sem dados reais de produção.

Classificação: Proposta.

O ambiente de homologação deverá permitir validação integrada antes do uso real.

Características esperadas:

• Acesso controlado.
• Dados fictícios, anonimizados ou aprovados.
• Aplicação conteinerizada, quando implementada.
• Execução de testes manuais.
• Demonstração para professores e stakeholders.
• Registro de erros e pendências.
• Possibilidade futura de teste básico de carga.

O ambiente de homologação ainda não existe ou não foi confirmado.

Classificação: Futuro e pendente.

O ambiente de produção poderá ser utilizado somente depois de validações, testes, definição de infraestrutura e aprovação dos responsáveis.

Características esperadas:

• Acesso protegido.
• Conexão segura por HTTPS.
• Autenticação e autorização configuradas.
• Backup.
• Logs.
• Monitoramento.
• Política de retenção.
• Processo de atualização controlado.
• Procedimento de contingência.
• VM Linux na OCI ou infraestrutura equivalente aprovada.

O ambiente de produção ainda não foi definido.

Classificação: Futuro.

Nenhum deploy foi realizado.

Não existe VM configurada, rede configurada, domínio, proxy reverso, certificado ou workflow de deploy definido. As imagens de container existem no GHCR, mas não foram promovidas nem implantadas em um ambiente de execução.

A OCI foi identificada como infraestrutura futura, mas a VM, a VCN, as regras de rede e os serviços ainda não foram criados.

Classificação: Confirmado.

A estratégia de deploy deverá considerar a stack e a infraestrutura escolhidas.

O cenário arquitetural preliminar considera:

Usuário autorizado
    ↓
Navegador
    ↓
HTTPS e proxy reverso, quando implantado
    ↓
Frontend React
    ↓
Backend ASP.NET Core
    ↓
PostgreSQL
    ↓
Backup e monitoramento

Classificação: Proposta.

O direcionamento atual é utilizar uma VM Linux na OCI.

A implantação futura deverá avaliar:

• IAM e MFA.
• Compartments.
• VM Compute.
• VCN.
• Subnets.
• Security Lists ou Network Security Groups.
• IP público.
• SSH.
• Firewall.
• Docker e Docker Compose.
• Proxy reverso.
• HTTPS.
• Backup.
• Monitoramento.
• Custos e limites.

A ADR 0004 propõe para a primeira homologação um nó único reversível, com somente HTTPS público e PostgreSQL, backend, Docker e interfaces administrativas restritos à rede interna. Essa proposta não define a topologia definitiva de produção.

Antes de conectar o Terraform à tenancy, deve ser executado o preflight da homologação OCI. O processo possui três gates separados:

1. consulta somente leitura da conta, região, limites, orçamento, DNS e responsáveis;
2. revisão humana de um terraform plan sem provisionamento;
3. terraform apply somente após autorização explícita e registro da decisão.

O preflight deve resultar em apto para planejar, bloqueado ou revisar arquitetura. Na data desta versão, o roteiro está documentado, mas a execução, o plano e o provisionamento permanecem pendentes na Issue #382. Nenhum identificador sensível, credencial, recurso ou custo deve ser publicado como evidência.

Classificação: Preliminar.

O deploy em homologação deverá ocorrer antes do deploy em produção, quando houver infraestrutura.

Exemplo futuro:

<COMANDO_DEPLOY_HOMOLOGACAO>

O deploy em produção deverá ocorrer somente após:

• Pull Request aprovado.
• Pipeline aprovada.
• Testes executados.
• Ambiente validado.
• Backup confirmado.
• Configuração de segredos validada.
• Segurança revisada.
• HTTPS configurado, quando aplicável.
• Aprovação da equipe e responsáveis aplicáveis.

Exemplo futuro:

<COMANDO_DEPLOY_PRODUCAO>

As permissões definitivas ainda dependem de validação.

O sistema deverá permitir, após implementação e validação:

• Autenticar usuário.
• Registrar entrada de veículo.
• Registrar saída de veículo.
• Consultar registros por placa, veículo, condutor, motorista ou período.
• Consultar veículos sem saída.
• Registrar saída institucional.
• Registrar retorno institucional.
• Consultar veículos institucionais sem retorno.
• Corrigir registros conforme permissão.
• Consultar histórico de alterações conforme permissão.
• Conferir registros pelo Setor de Transporte.

• Operar catraca automaticamente.
• Liberar veículo automaticamente.
• Reconhecer placa por imagem.
• Controlar estacionamento.
• Controlar todos os pedestres.
• Gerenciar todos os eventos.
• Controlar visitantes sem veículo.
• Integrar equipamentos físicos.

A aplicação futura deverá registrar logs técnicos sem expor dados sensíveis.

Os logs poderão incluir:

• Inicialização da aplicação.
• Erros técnicos.
• Falhas de conexão.
• Falhas de autenticação.
• Falhas de autorização.
• Erros de integração.
• Falhas de banco de dados.
• Eventos de backup.
• Eventos de deploy.

Logs não devem incluir:

• Senhas.
• Hashes de senha.
• Tokens.
• Strings de conexão.
• RG ou CPF completos.
• Segredos.
• Dados pessoais sem necessidade operacional.

Classificação: Logging HTTP mínimo implementado; centralização pendente.

Os sinais exportáveis já incluem métricas HTTP e do runtime. O monitoramento de homologação e produção deverá incluir:

• Disponibilidade da aplicação.
• Disponibilidade do banco de dados.
• Uso de CPU e memória.
• Espaço em disco.
• Taxa de erros.
• Falhas de autenticação.
• Falhas de backup.
• Tempo de resposta.
• Uso de recursos dos containers.

Collector, armazenamento, painéis, alertas e centralização de logs ainda não foram escolhidos.

Classificação: Instrumentação implementada; plataforma externa pendente.

A Issue #102 implementou OpenTelemetry opt-in com:

• Métricas.
• Traces.
• Exportação OTLP.
• Redação obrigatória dos valores de query.
• Exclusão dos health checks dos traces.

Use OTEL_ENABLED=true, OTEL_SERVICE_NAME e OTEL_EXPORTER_OTLP_ENDPOINT somente quando houver collector acessível. Logs centralizados, alertas e painéis continuam pendentes. Consulte Observabilidade.

Classificação: Base técnica implementada; operação externa pendente.

O ambiente local possui Backup-PostgreSql.ps1, que cria dump lógico no formato custom do PostgreSQL sem incluir credenciais no comando ou no artefato. Os dumps ficam em infrastructure/database/backups/, diretório ignorado pelo Git. Cada dump recebe um manifesto JSON com nome, tamanho, horário UTC e SHA-256.

Esse procedimento é um ensaio técnico iniciado na Issue #67 e fortalecido pela Issue #308 e pelo PR #309. A aplicação ainda deverá possuir estratégia institucional após a definição final da infraestrutura.

A estratégia deverá definir:

• Frequência.
• Retenção.
• Local de armazenamento.
• Proteção de acesso.
• Responsável.
• Monitoramento de execução.
• Testes de restauração.

Classificação: Parcialmente implementado; produção pendente.

Test-PostgreSqlRestore.ps1 verifica o manifesto antes de copiar o dump ao container, restaura em banco temporário isolado, confirma as tabelas essenciais e remove os recursos ao terminar. Ele não aceita um banco operacional como destino.

O procedimento destrutivo de recuperação real dependerá da infraestrutura escolhida, da estratégia de PostgreSQL e da política de backup aprovada.

Classificação: Ensaio local implementado; recuperação operacional pendente.

O workflow CI - Database recovery já testa com dados fictícios:

• Criação do backup.
• Geração e validação do manifesto SHA-256.
• Rejeição de uma cópia adulterada.
• Restauração em ambiente seguro.
• Conferência das tabelas essenciais restauradas.
• Limpeza dos recursos temporários.

A CI não valida o tempo real de recuperação nem a política de acesso ao armazenamento. O PR #313 definiu backup lógico diário, janela móvel de 35 dias, RPO-alvo de uma hora, RTO-alvo de quatro horas e exercício trimestral. O dump atual entrega apenas RPO técnico de até 24 horas. Object Storage privado, Vault, instance principal, separação IAM e restauração externa continuam pendentes na Issue #311; WAL/PITR permanece na Issue #312. O primeiro exercício institucional está previsto para a segunda unidade.

Consulte Retenção, Backup e Continuidade para a matriz de decisões e os critérios de encerramento.

Classificação: Implementado localmente e na CI; produção pendente.

O processo definitivo ainda precisa ser validado com a Portaria, Vigilância e o Setor de Transporte.

Fluxo preliminar:

Falha de rede identificada
    ↓
Porteiro ou Vigilante abre incidente e formulário numerado
    ↓
Registro temporário contém somente os dados mínimos
    ↓
Ocorrência é comunicada quando necessário
    ↓
Sistema retorna
    ↓
Uma pessoa digita e outra confere os dados posteriormente
    ↓
Setor de Transporte fecha a reconciliação e o descarte do papel

Os endpoints operacionais atuais não aceitam horário histórico com segurança. Até a implementação da Issue #100, eles não devem ser usados para lançar a contingência retroativamente.

Classificação: Proposta documentada; homologação e suporte técnico à reconciliação pendentes.

O procedimento futuro deverá considerar:

• Registro da indisponibilidade.
• Comunicação ao responsável técnico ou Setor de Transporte.
• Uso de procedimento temporário aprovado.
• Registro posterior no sistema.
• Auditoria do lançamento posterior.
• Verificação de duplicidade após normalização.

Classificação: Pendente.

Ainda precisa ser confirmado:

• Se existe computador ou tablet na portaria.
• Se haverá dispositivo alternativo.
• Quem realizará suporte técnico.
• Qual procedimento será seguido em caso de falha.

Classificação: Pendente.

A catraca está sem motor, empenada e quebrada.

O MVP não deve depender da catraca para operar o controle de veículos.

Classificação: Informado.

## Funcionalidade

- [ ] Issue criada e vinculada.
- [ ] Objetivo definido.
- [ ] Critérios de aceite definidos.
- [ ] Regras de negócio relacionadas identificadas.
- [ ] Fluxo revisado.
- [ ] Dados necessários identificados.
- [ ] Validações definidas.
- [ ] Permissões definidas.
- [ ] Testes planejados.
- [ ] Código implementado.
- [ ] Testes unitários executados.
- [ ] Testes de integração executados, quando aplicável.
- [ ] Testes manuais executados.
- [ ] Lint executado.
- [ ] Build executado.
- [ ] Documentação atualizada.
- [ ] Pull Request criado.
- [ ] Revisão realizada.
- [ ] Pipeline aprovada, quando existir.
- [ ] Resultado demonstrado localmente ou em homologação.
- [ ] Pendências registradas.

- [ ] Issue vinculada.
- [ ] Pull Request descrito.
- [ ] Código revisado.
- [ ] Testes executados.
- [ ] Lint aprovado.
- [ ] Build aprovado.
- [ ] Pipeline aprovada, quando existir.
- [ ] Sem segredos expostos.
- [ ] Sem dados pessoais reais em testes.
- [ ] Documentação atualizada.
- [ ] Riscos ou pendências registrados.

- [ ] Requisitos e critérios de aceite atendidos.
- [ ] Pull Request aprovado.
- [ ] Pipeline aprovada.
- [ ] Testes críticos executados.
- [ ] Backup configurado ou validado.
- [ ] Variáveis de ambiente configuradas.
- [ ] Segredos protegidos.
- [ ] Acesso HTTPS configurado, quando aplicável.
- [ ] Logs verificados.
- [ ] Monitoramento configurado, quando disponível.
- [ ] Plano de rollback definido.
- [ ] Contingência documentada.
- [ ] Responsáveis informados.

- [ ] Issue vinculada ao trabalho apresentado.
- [ ] Funcionalidade ou documento pronto para demonstrar.
- [ ] Alterações revisadas.
- [ ] Testes executados, quando aplicável.
- [ ] Resultado executado localmente ou em ambiente disponível.
- [ ] Evidências disponíveis.
- [ ] Pendências conhecidas registradas.
- [ ] Próxima etapa definida.

• Definir autenticação.
• Definir autorização.
• Definir formato de erros da API.
• Definir documentação OpenAPI.
• Definir logging.
• Definir tratamento de exceções.
• Definir padrão de DTOs.
• Definir padrão de respostas.
• Validar mudanças futuras do Modelo de Dados antes de gerar migrations.
• Revisar índices a partir dos padrões reais de consulta.
• Definir política de seed.
• Definir estratégia de migrations em Docker, homologação e OCI.

• Definir biblioteca de componentes.
• Definir gerenciamento de estado.
• Validar o cliente HTTP e a validação de formulários existentes quando houver contratos de API.
• Definir estratégia de autenticação.
• Definir testes de interface.

• Definir lint/format do backend e testes do frontend.
• Ampliar cobertura e testes PostgreSQL junto dos próximos fluxos.
• Definir scanner de dependências.
• Definir scanner de imagem Docker.
• Endurecer os workflows na Issue #25.
• Definir ambiente de homologação.
• Definir teste de carga.
• Implantar collector, painéis e alertas sobre a base OpenTelemetry existente.

• Onde será realizado o deploy?
• Haverá VM institucional, VM na OCI ou outro ambiente?
• Haverá ambiente de homologação?
• Haverá domínio e HTTPS?
• Como será configurado o proxy reverso?
• Quais recursos de CPU, memória e armazenamento estarão disponíveis?
• Como será configurada a VCN e as regras de rede na OCI?
• Quem será responsável pelo suporte técnico?
• Como será o acesso SSH à VM?
• Como serão armazenados os segredos de produção?

• Quem poderá administrar usuários?
• Quem poderá redefinir senhas?
• Quem poderá exportar registros?
• Qual será a política de retenção digital?
• Qual será a frequência de backup?
• Quem verificará os backups?
• Como será a recuperação?
• Como funcionará a contingência?
• Como serão tratados incidentes?
• Quais logs deverão ser mantidos?
• Quais métricas serão monitoradas?

Documento: Guia de Execução, Configuração, Deploy e Operação
Versão: 0.29
Status: Execução local e containers documentados; deploy e operação de produção pendentes
Issue relacionada: #13 — Criar guia de execução, configuração, deploy e operação

• Frontend: React + TypeScript.
• Backend: ASP.NET Core Web API + C#.
• Versão do .NET: .NET 10 com target net10.0.
• Banco de dados: PostgreSQL 16.
• ORM: Entity Framework Core 10 com Npgsql.
• Migrações: Entity Framework Core Migrations.

• Clean Architecture adaptada ao MVP.
• Monólito modular.
• API Web organizada em camadas.

• Docker e Docker Compose.
• GitHub Actions.
• VM Linux na OCI.
• Proxy reverso: Nginx implementado no Compose; destino institucional pendente.
• HTTPS: pendente.
• Logs estruturados, métricas e traces: base exportável implementada; operação externa pendente.
• Backup e recuperação: ensaio local automatizado; política e infraestrutura de produção pendentes.

• Código: backend e frontend do MVP integrados nos fluxos geral, institucional, eventos, resumo, auditoria e contas; homologação pendente.
• Banco: PostgreSQL integrado ao backend.
• Migrations: Dezesseis migrations versionadas.
• Ambiente local: Configurado e documentado.
• Homologação: Ainda não existe ou não foi confirmada.
• Produção: Ainda não definida.
• Containerização: Dockerfiles e Compose configurados.
• Pipeline: Workflows de código, containers, dependências e recuperação do PostgreSQL implementados.
• Lint e formatação: ESLint configurado no frontend e dotnet format --verify-no-changes aplicado ao backend na validação local.
• Build: Backend e frontend configurados na CI.
• Testes automatizados: 262 testes de backend na main, incluindo integração com PostgreSQL, além de 432 testes de frontend.
• Cobertura real: Artefato publicado pela CI; meta não definida.
• Monitoramento: Instrumentação OpenTelemetry opt-in implementada; collector, painéis e alertas pendentes.
• Backup: Dump lógico, manifesto SHA-256 e restauração isolada configurados para desenvolvimento; backup protegido de produção pendente.
• Deploy: Ainda não realizado.

• Atualizada a referência da arquitetura para a versão 0.2.
• Incluída a Decisão de Stack Tecnológica v0.2 como documento relacionado.
• Registrados React e TypeScript como stack de frontend.
• Registrados ASP.NET Core Web API e C# como stack de backend.
• Registrada a proposta histórica de .NET 8 que orientou a versão 0.2; a versão 0.3 documenta o .NET 10 implementado.
• Registrados PostgreSQL, Entity Framework Core e Migrations como direcionamentos de persistência.
• Registradas Clean Architecture adaptada e monólito modular como decisões arquiteturais.
• Registrados Docker, Docker Compose, GitHub Actions e OCI como direcionamentos de infraestrutura e entrega.
• Atualizados os placeholders e comandos previstos para refletir o backend .NET e PostgreSQL.
• Preservada a baseline anterior à implementação e separadas as pendências reais de homologação, produção, monitoramento, backup e deploy.

• Documentados monorepo, frontend, backend .NET 10, EF Core, PostgreSQL e migrations existentes.
• Registrados Dockerfiles, Compose, workflows e testes atuais.
• Mantidos como planejamento apenas os ambientes e controles ainda inexistentes.

• Documentados os scripts de backup lógico e restauração isolada da Issue #67.
• Registrado o workflow CI - Database recovery, validado em Linux.
• Separado o ensaio local das decisões institucionais de retenção, RPO, RTO e contingência da Issue #30.

• Registrado o rate limiting correlacionado da Issue #69.
• Documentados os limites globais e de login, health checks isentos e configuração por ambiente.
• Mantidos proxy confiável, controle distribuído, teste de carga e calibração como pendências de produção.

• Registrada a auditoria transacional de login bem-sucedido e bloqueio temporário da Issue #71.
• Atualizada a baseline para 113 testes, sendo 56 de integração com PostgreSQL.
• Mantidos recuperação de acesso e encerramento explícito de sessões como pendências.

• Registrado o ciclo administrativo seguro de contas da Issue #73.
• Documentadas desativação com efeito imediato, proteção do último Administrador e auditoria atômica.
• Atualizada a baseline para 124 testes, sendo 62 de integração com PostgreSQL.

• Registrada a migration que permite ator nulo somente para auditorias de sistema.
• Documentadas auditoria atômica da criação de contas e proteção do downgrade.
• Atualizada a baseline para 129 testes, sendo 64 de integração com PostgreSQL.

• Documentada a consulta GET /audits, restrita a Administrador.
• Registrados limites de período, paginação, filtros e distinção de ator de sistema.
• Atualizada a baseline para 136 testes, sendo 68 de integração com PostgreSQL.

• Documentadas supervisão da portaria, cobertura pelo Vigilante e leitura geral por Transporte.
• Registrado o papel somente como contingência após homologação, com reconciliação posterior.
• Atualizada a baseline para 137 testes, sendo 69 de integração com PostgreSQL.

• Sincronizada a proposta de retenção, backup, RPO, RTO e contingência da Issue #30.
• Registrado que os endpoints atuais não preservam com segurança o horário observado durante uma indisponibilidade.
• Vinculada a reconciliação autenticada e auditável à Issue #100 e à homologação institucional.

• Documentada a exportação OpenTelemetry opt-in de métricas e traces da Issue #102.
• Registradas redação obrigatória de query, validação do endpoint OTLP e exclusão dos health checks dos traces.
• Separada a instrumentação existente da plataforma externa, dos painéis e dos alertas ainda pendentes.

• Documentado o inicializador repetível de dados fictícios da Issue #108 e PR #109.
• Atualizada a baseline vigente para doze migrations e 175 testes, sendo 93 de integração.
• Mantida a distinção entre demonstração local, homologação e produção real.

• Registrada a causa do aviso opcional de GSSAPI observado com Npgsql 10.
• Documentada a desativação somente local, sem instalar bibliotecas Kerberos desnecessárias.
• Mantida para homologação e produção a decisão explícita entre TLS verificado e GSSAPI institucional.

• Registrado o workflow CI - Demo data da Issue #112 e PR #113.
• Documentados isolamento, credenciais efêmeras, migrations, repetição e limpeza obrigatória.
• Mantida a homologação com usuários como etapa manual e institucional.

• Atualizada a baseline para 254 testes de backend e 432 testes de frontend.
• Registrados manifesto SHA-256, validação anterior à restauração e teste negativo de adulteração da Issue #308 e do PR #309.
• Mantidas como pendentes autenticidade, criptografia, armazenamento externo, RPO, RTO e validação institucional da Issue #30.

• Registradas as decisões de retenção e continuidade incorporadas pelo PR #313.
• Separada a capacidade atual de RPO de 24 horas da meta de uma hora por WAL/PITR.
• Vinculados o backup protegido na OCI e a recuperação pontual às Issues #311 e #312.

• Registrada a release técnica v0.3.0 e seus manifests AMD64/ARM64 verificados.
• Atualizado o exemplo de verificação de proveniência para o canal de release.
• Documentado que a main valida containers sem publicar snapshots nos packages principais.

• Vinculado o roteiro versionado de preflight da homologação OCI incorporado pelo PR #395.
• Separadas a consulta somente leitura, a revisão do terraform plan e a autorização de terraform apply.
• Preservado como pendente o provisionamento real e evitadas afirmações não verificadas sobre capacidade ou custo.

1. Validar o documento com os professores.
2. Validar perfis, categorias, campos e comportamento da sessão com os usuários na Issue #162.
3. Revisar auditoria e controles transversais durante a homologação integrada.
4. Provisionar o backup protegido e o PITR das Issues #311 e #312 e exercitar recuperação e contingência na Issue #30.
5. Planejar homologação antes de qualquer produção.
6. Definir ambiente, HTTPS, segredos e operação antes de qualquer deploy institucional.