[SCRUM-52] Pipeline de auto-apply de sugestoes de relatorio

[notsogreatdavi]

🎯 Objetivo

Implementa o pipeline completo de auto-apply para a SCRUM-52: permite aplicar sugestoes de melhoria (geradas por relatorio IA) diretamente nos dados da empresa e do cardapio, tanto de forma individual quanto em lote a partir de um relatorio existente.

---

📁 Arquivos Criados

Arquivo	Propósito
app/core/exceptions.py	Exceções de domínio: FieldNotAllowed, InvalidFieldValue, AutoApplyPersistence, SuggestionExtraction
app/schemas/auto_apply.py	Schemas Pydantic v2: AutoApplyRequest/Response, Suggestion, SuggestionResult, ReportAutoApplyResponse
app/services/auto_apply_service.py	Service com whitelist de campos, mapeamento lógico para coluna real, coerção de tipos e parsing de horário
app/services/report_auto_apply_service.py	Service que extrai sugestões do relatório via Gemini Flash e aplica em lote com commit unico
app/routers/auto_apply.py	Router dedicado para POST /auto-apply (aplicação individual)
tests/test_auto_apply_service.py	16 testes BDD para AutoApplyService (cobertura 100%)
tests/test_report_auto_apply_service.py	12 testes BDD para ReportAutoApplyService (cobertura 100%)
tests/test_auto_apply_router.py	5 smoke tests para POST /auto-apply

---

✏️ Arquivos Alterados

Arquivo	O que mudou
app/main.py	Registra router auto_apply, handlers para novas exceções, handler 500 com mensagem genérica
app/routers/reports.py	Adiciona endpoint POST /{report_id}/auto-apply com DI do ReportAutoApplyService
app/services/report_service.py	Enriquece system prompt com diretrizes para sugestões acionáveis com valores concretos
tests/test_reports_router.py	Adiciona 4 smoke tests para POST /{report_id}/auto-apply

---

🧪 Como Testar

Pré-requisitos

1. Abrir o deploy do PR: https://mandaca-backend-staging-pr-37.onrender.com/docs
2. Ter no banco uma empresa cadastrada com pelo menos um item de cardapio e um relatorio IA gerado

Teste 1: Auto-apply individual (POST /auto-apply)

1. No Swagger, localizar a seção auto-apply e expandir POST /auto-apply
2. Clicar em Try it out
3. Preencher o body com um campo permitido de empresa:

{
  "enterprise_id": "<UUID da empresa>",
  "target": "enterprise",
  "campo_para_alterar": "historia",
  "novo_valor": "Restaurante familiar fundado em 2010 no sertao pernambucano"
}

4. Clicar em Execute
5. Esperado: status 200 com body {"campo_alterado": "historia", "status": "aplicado"}
6. Verificar no GET /enterprises/{id} que o campo historia foi atualizado

Teste 2: Auto-apply de item do cardapio (POST /auto-apply)

1. Repetir o fluxo acima, mas agora com target menu_item:

{
  "enterprise_id": "<UUID da empresa>",
  "target": "menu_item",
  "menu_item_id": "<UUID do item de cardapio>",
  "campo_para_alterar": "preco",
  "novo_valor": "25.90"
}

2. Esperado: status 200 com {"campo_alterado": "preco", "status": "aplicado"}

Teste 3: Campo nao permitido (POST /auto-apply)

1. Enviar um campo fora da whitelist (ex: "campo_para_alterar": "owner_id")
2. Esperado: status 422 com mensagem "Campo não permitido para alteração automática: owner_id"

Teste 4: Auto-apply em lote a partir de relatorio (POST /reports/{report_id}/auto-apply)

1. Primeiro, gerar um relatorio via POST /reports/generate/{empresa_id} e copiar o id_relatorio retornado
2. No Swagger, localizar a seção reports e expandir POST /reports/{report_id}/auto-apply
3. Clicar em Try it out e colar o report_id
4. Clicar em Execute
5. Esperado: status 200 com body contendo:
   • report_id: UUID do relatorio
   • total: quantidade de sugestoes extraidas pela IA
   • aplicadas: quantas foram aplicadas com sucesso
   • rejeitadas: quantas falharam (campo invalido, entidade nao encontrada, etc.)
   • resultados: lista detalhada com cada sugestao, seu status (aplicado/rejeitado) e mensagem de erro quando rejeitada
6. Verificar nos endpoints GET /enterprises/{id} e GET /menus/{id} que os campos aplicados foram atualizados

Teste 5: Relatorio inexistente (POST /reports/{report_id}/auto-apply)

1. Enviar um UUID que nao existe como report_id
2. Esperado: status 404 com mensagem "Relatório IA não encontrado: <UUID>"

Testes automatizados

pytest tests/test_auto_apply_service.py tests/test_report_auto_apply_service.py tests/test_auto_apply_router.py tests/test_reports_router.py -v

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
main.py	67	1	98%	127
core
config.py	13	0	100%
exceptions.py	96	2	97%	142–143
session.py	12	0	100%
supabase_client.py	3	0	100%
models
__init__.py	10	0	100%
assessment.py	21	0	100%
business_context.py	15	0	100%
chat_message.py	15	0	100%
enterprise.py	28	0	100%
menu.py	23	0	100%
notification.py	16	0	100%
photo.py	11	0	100%
report.py	20	0	100%
reservation.py	15	0	100%
user.py	20	0	100%
routers
assessments.py	26	0	100%
auto_apply.py	11	0	100%
business_context.py	25	0	100%
chat.py	17	0	100%
enterprises.py	29	0	100%
menus.py	26	0	100%
notifications.py	27	0	100%
photos.py	97	67	30%	32, 38–40, 44, 50–52, 57, 68–70, 75–76, 81, 83–85, 90–91, 93–94, 96, 105, 107, 112–113, 115–117, 122, 124–125, 127, 137–139, 144–145, 150–158, 163–164, 166–167, 169, 178, 180–182, 184, 186–188, 197–199, 204–205, 207
reports.py	26	0	100%
transcriptions.py	11	0	100%
users.py	88	57	35%	27, 47–49, 53, 65–67, 72, 74–76, 81–82, 85, 87, 89, 98, 100–101, 103, 110–113, 126–128, 133–134, 142–143, 147, 149–150, 152–153, 155–157, 162–163, 166, 168, 170, 179, 183–184, 186–187, 189, 195, 197–198, 203–205
schemas
__init__.py	0	0	100%
assessments.py	19	0	100%
auto_apply.py	38	0	100%
business_contexts.py	16	0	100%
chat.py	18	0	100%
enterprises.py	51	0	100%
menus.py	28	0	100%
notification.py	19	0	100%
reports.py	24	0	100%
transcriptions.py	11	0	100%
services
__init__.py	0	0	100%
assessment_service.py	83	52	37%	24, 51–53, 57, 60–61, 64–66, 71–73, 78–81, 86, 93–96, 104, 106–109, 113, 115–118, 122, 124–128, 132–133, 135–137, 140–143, 146–148, 153–154
auto_apply_service.py	73	0	100%
business_context_builder_service.py	39	27	30%	20–22, 24, 26–35, 39–40, 45–47, 51–53, 62, 67–68, 71, 75
business_context_service.py	54	4	92%	76–78, 80
chat_context_service.py	41	0	100%
chat_service.py	44	0	100%
context_validation_service.py	32	0	100%
enterprise_service.py	78	0	100%
geocoding_service.py	39	0	100%
menu_service.py	52	0	100%
notification.py	27	0	100%
report_auto_apply_service.py	57	0	100%
report_service.py	57	1	98%	92
transcription_service.py	90	0	100%
TOTAL	1758	211	88%

[Guilherme-leo]

Assim como conversado na última reunião, será necessário bloquearmos essa task por enquanto, devido às funcionalidades, entidades e informações que serão adicionadas nos épicos posteriores, bem como às possíveis alterações nos épicos já desenvolvidos quando integrados ao frontend.