# Blueprint - Entrada de Materiais OPME via XML com Validacoes ANVISA

## 1. Objetivo
Definir a arquitetura funcional e tecnica para entrada de materiais OPME via XML, com validacoes regulatórias ANVISA, rastreabilidade por lote/serie e governanca de aprovacao de pendencias.

## 2. Escopo do MVP (fase 1)
1. Upload e parse de XML de NFe.
2. Identificacao de fornecedor e itens.
3. Validacoes basicas ANVISA e de rastreabilidade.
4. Tela de conferencia com pendencias.
5. Aprovacao manual com trilha de auditoria.
6. Geracao de entrada de estoque com vinculo ao documento.

## 3. Modelo de Dados (logico)

### 3.1 Documento de entrada
Tabela: `opme_documentos_entrada`
- `id`
- `chave_nfe` (unique)
- `numero_nfe`
- `serie_nfe`
- `cnpj_emitente`
- `razao_emitente`
- `cnpj_destinatario`
- `data_emissao`
- `data_entrada`
- `valor_total`
- `xml_hash` (controle de idempotencia)
- `xml_path` (armazenamento)
- `status` (`recebido`, `validando`, `pendente`, `aprovado`, `reprovado`, `integrado`)
- `importado_por`
- `aprovado_por` (nullable)
- `aprovado_em` (nullable)
- `created_at`, `updated_at`

### 3.2 Itens do documento
Tabela: `opme_documentos_itens`
- `id`
- `documento_id` (fk)
- `sequencia_item`
- `codprod_xml`
- `ean_xml`
- `descricao_xml`
- `quantidade`
- `valor_unitario`
- `valor_total`
- `anvisa_registro_xml` (nullable)
- `lote_xml` (nullable)
- `validade_xml` (nullable)
- `serie_xml` (nullable)
- `produto_id` (fk interno, nullable ate mapeamento)
- `status_validacao` (`ok`, `alerta`, `bloqueado`)
- `created_at`, `updated_at`

### 3.3 Cadastro regulatorio local
Tabela: `opme_produtos_regulatorio`
- `id`
- `produto_id` (fk)
- `registro_anvisa`
- `detentor_registro`
- `fabricante`
- `classe_risco`
- `registro_situacao` (`ativo`, `cancelado`, `vencido`, `desconhecido`)
- `registro_validade` (nullable)
- `exige_lote` (`S`/`N`)
- `exige_validade` (`S`/`N`)
- `exige_serie` (`S`/`N`)
- `created_at`, `updated_at`

### 3.4 Pendencias
Tabela: `opme_pendencias`
- `id`
- `documento_id` (fk)
- `item_id` (fk nullable, pendencia pode ser de cabecalho)
- `regra_codigo`
- `regra_descricao`
- `severidade` (`bloqueante`, `alerta`)
- `status` (`aberta`, `justificada`, `resolvida`, `aceita`)
- `detalhe`
- `justificativa` (nullable)
- `tratado_por` (nullable)
- `tratado_em` (nullable)
- `created_at`, `updated_at`

### 3.5 Auditoria de acoes
Tabela: `opme_auditoria`
- `id`
- `documento_id` (fk)
- `item_id` (fk nullable)
- `acao` (`importar`, `validar`, `aprovar`, `reprovar`, `integrar`)
- `payload_json`
- `usuario`
- `created_at`

### 3.6 Movimentos de estoque vinculados
Tabela: `opme_movimentos_estoque`
- `id`
- `documento_id` (fk)
- `item_id` (fk)
- `produto_id`
- `quantidade`
- `lote`
- `validade`
- `serie`
- `codlocal`
- `status_integracao` (`pendente`, `integrado`, `erro`)
- `mensagem_integracao` (nullable)
- `created_at`, `updated_at`

## 4. Regras de Validacao (ANVISA e negocio)

### 4.1 Bloqueantes
1. Registro ANVISA ausente para item que exige registro.
2. Registro ANVISA invalido/inativo.
3. Lote ausente quando `exige_lote = S`.
4. Validade ausente quando `exige_validade = S`.
5. Serie ausente quando `exige_serie = S`.
6. Chave NFe duplicada.
7. XML com assinatura/schema invalido.

### 4.2 Alertas
1. Divergencia de descricao XML x cadastro interno.
2. Divergencia de fabricante/detentor.
3. Validade menor que parametro minimo.
4. Produto sem mapeamento automatico (requer conferencia manual).

## 5. Fluxo de Processamento
1. Usuario faz upload do XML.
2. Sistema valida arquivo e hash/chave NFe.
3. Sistema parseia cabecalho e itens.
4. Sistema tenta mapear fornecedor e produtos.
5. Motor de regras executa validacoes.
6. Sistema grava pendencias e classifica status do documento.
7. Usuario revisa pendencias em tela de conferencia.
8. Usuario aprova/reprova com justificativa quando necessario.
9. Sistema gera movimentos de estoque para itens aptos.
10. Sistema registra auditoria completa.

## 6. Estrutura de Telas

### 6.1 Lista de documentos de entrada
- Filtros: periodo, status, fornecedor, chave NFe.
- Colunas: chave, fornecedor, emissao, status, total, importado por.

### 6.2 Upload de XML
- Area drag-and-drop + botao selecionar.
- Validacao imediata de duplicidade.

### 6.3 Conferencia do documento
- Cabecalho da NFe.
- Tabela de itens com badges de validacao.
- Painel lateral de pendencias por severidade.
- Acoes: aprovar, reprovar, salvar justificativas.

### 6.4 Detalhe de pendencia
- Regra, evidencias, historico de tratamento, justificativa obrigatoria (quando aplicavel).

## 7. APIs internas sugeridas
- `POST /modulos/opme/entradas/xml`
- `GET /modulos/opme/entradas`
- `GET /modulos/opme/entradas/{id}`
- `POST /modulos/opme/entradas/{id}/validar`
- `POST /modulos/opme/entradas/{id}/aprovar`
- `POST /modulos/opme/entradas/{id}/reprovar`
- `POST /modulos/opme/entradas/{id}/integrar-estoque`

## 8. Permissoes sugeridas
- `opme.entradas.visualizar`
- `opme.entradas.importar`
- `opme.entradas.validar`
- `opme.entradas.aprovar`
- `opme.entradas.integrar`

## 9. Parametrizacoes importantes
- Dias minimos de validade aceitavel.
- Regras por tipo de OPME.
- Quais alertas podem ser aprovados com justificativa.
- Alcada de aprovacao por valor/criticidade.

## 10. Roadmap de implementacao

### Sprint 1
1. Tabelas base (`documentos`, `itens`, `pendencias`, `auditoria`).
2. Upload + parser XML.
3. Lista/documento detalhe.

### Sprint 2
1. Motor de validacoes ANVISA (regras MVP).
2. Tela de conferencia com pendencias.
3. Fluxo de aprovacao/reprovacao.

### Sprint 3
1. Integracao com estoque.
2. Relatorios de conformidade.
3. Hardening de auditoria e observabilidade.

## 11. Criterios de aceite (MVP)
1. Nao permitir processar XML duplicado (chave/hash).
2. Bloquear aprovacao com pendencia bloqueante aberta.
3. Permitir aprovacao com alerta mediante justificativa.
4. Gerar rastreabilidade completa item -> pendencia -> movimento.
5. Exibir historico de todas as acoes por usuario/data.