Refatoração e Modernização da Arquitetura (Fases 0 a 7)

[YannLeao]

Resumo

Esta PR consolida a modernização completa do repositório MedTrack-IA. O objetivo principal foi transformar a base de código em um serviço reproduzível, testável, conteinerizado e pronto para deploy em ambiente de staging, garantindo a compatibilidade dos contratos existentes com o aplicativo mobile.

O que foi feito (Visão Geral por Etapas)

Fases 0 & 1 — Fundação e Gerenciamento de Dependências

• uv + pyproject.toml + uv.lock: Substituição de requirements.txt por uma fonte única, rápida e totalmente reproduzível de dependências (com separação entre grupos de api, training e dev).

• Layout src/: Migração do código para a estrutura src/medtrack_ai/.

• Garantia de Qualidade Local: Adotados Ruff (lint e formatação), Pyright (tipagem estática), .pre-commit-config.yaml e fixação da versão Python em .python-version (3.11).

• Configurações: Centralização de variáveis via Pydantic Settings (settings.py) e .env.example.

Fase 2 — Desacoplamento entre API e Inferência

• Arquitetura Limpa: FastAPI separada do motor de inferência (YOLO + EasyOCR). A API depende agora de uma interface/adaptador mockável (YoloOcrInferenceService).

• Testabilidade sem GPU/Peso: A API agora pode ser importada e testada instantaneamente sem carregar bibliotecas pesadas ou pesos de modelo na RAM.

• Endpoints Operacionais:

• GET /healthz: Checagem de liveness (processo no ar).

• GET /readyz: Checagem de readiness (modelo .pt totalmente carregado na RAM).

Fase 3 — Gestão de Artefatos e Modelos

• Modelo fora do Git: Remoção de caminhos locais rígidos (runs/.../best.pt).

• Manifesto + Checksum: Implementado o script scripts/fetch_model.py que baixa o peso de uma GitHub Release imutável e valida a integridade via SHA-256 antes do boot.

Fase 4 — Estratégia de Testes

• Suíte configurada com pytest dividida por marcadores (unit, integration, model).

• Testes de integração usam adaptadores falsos para garantir CI/CD rápida sem dependência de GPU/download pesado.

• Documentação de testes adicionada em docs/TESTING.md.

Fase 5 — Conteinerização e Execução Local

• Dockerfile Multi-Stage: Otimizado com uv, sem incluir pesos no binary e rodando com usuário não-root (app) por segurança.

• Docker Compose: Criado compose.yaml com volume montado para o modelo local e suporte a healthchecks.

• Documentação de execução em docs/CONTAINER.md.

Fase 6 — Workflows de CI/CD (GitHub Actions)

• quality.yml: Validação automática de uv.lock, lint, tipagem, testes e docker build em PRs e main.

• codeql.yml: Análise de segurança estática (SAST) em Python.

• release-image.yml: Publicação automatizada de imagem OCI imutável no GitHub Container Registry (GHCR) ao criar tags api-v*.

• model-artifact-smoke.yml: Workflow manual para validar download e checksum do modelo.

• ADR 0004: Separação entre tags de modelo (v1.0.0) e tags de aplicação/API (api-v1.0.0).

Fase 7 — Suporte a Deploy Staging (Railway)

• Preparado o arquivo railway.toml e o fluxo para staging.

• Configurado o boot para baixar o peso automaticamente no volume persistente (/data) apenas se o checksum não for atendido.

• Integração com /readyz para garantir zero-downtime deployments (Railway aguarda o modelo estar pronto na RAM antes de direcionar tráfego).

• Documentação do ambiente registrada em docs/RAILWAY.md.

🔍 Como Validar/Testar Esta PR

1. Testes e Qualidade Local:

uv sync --frozen --group dev
uv run ruff check src tests
uv run pyright src/medtrack_ai tests
uv run pytest

2. Execução via Docker:

docker compose up --build
curl http://localhost:8000/healthz
curl http://localhost:8000/readyz

3. Verificação de CI:

• Garantir que as Status Checks (Quality e CodeQL) estejam verdes nesta PR.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.