# Decisoes Tecnicas

Data: 08/07/2026

## Contexto

O projeto ira sincronizar documentos fiscais de servico (NFS-e/DF-e) do ADN para um banco MySQL 5.6 novo, proprio do motor. Sistemas externos poderao consultar as tabelas multitenant geradas por municipio.

## Tecnologia definida

Tecnologia escolhida para o motor: Python 3.12.

Motivos:

- Bom suporte a rotinas batch, workers e agendamentos.
- Bibliotecas maduras para HTTP, mTLS, XML, certificados e MySQL.
- Simplicidade para rodar em VPS sem Docker.
- Facilidade para criar ambiente local com Docker sem tornar Docker requisito de producao.
- Boa ergonomia para concorrencia controlada usando `concurrent.futures`.

## Banco de dados

O banco oficial sera um MySQL 5.6 novo. Enquanto ele nao chega, o arquivo `mock.sql` representa uma base minima para testar:

- criacao das tabelas novas;
- relacionamento entre municipio, certificado e estado de sincronizacao;
- persistencia de documentos, eventos e logs;
- indices que devem existir para consulta por municipio, NSU, chave e data.

Quando o banco oficial for recebido, a migration `migrations/001_create_nfse_tables.sql` devera ser aplicada no banco real, com revisao previa de:

- charset/collation padrao;
- engine usada pelo legado;
- padrao de nomes de tabelas e indices;
- usuario de banco com permissao para `CREATE`, `ALTER`, `INDEX` e `INSERT`.

## Producao sem Docker

A VPS de producao nao tera Docker como requisito. O desenho recomendado e:

- Python instalado via pacote do sistema ou runtime isolado;
- virtualenv do projeto;
- variaveis de ambiente em arquivo protegido;
- servico `systemd` para manter o worker ativo;
- logs em stdout/stderr ou arquivo rotacionado pelo sistema;
- certificado e senha criptografados no banco;
- chave mestra fora do banco.

## Docker apenas local

O diretorio `docker/` existe para desenvolvimento local. Ele deve subir apenas dependencias de apoio, principalmente MySQL. O motor em si pode rodar no host durante o desenvolvimento para facilitar debug.

## Migration

As migrations ficam em `migrations/` e devem ser SQL puro neste primeiro momento, porque o alvo e MySQL 5.6.

Se o projeto crescer, podemos adicionar Alembic ou outra ferramenta, mas a migration SQL continua sendo o contrato principal com o banco.