Documentação Inclusa

documentação/AI_AGENTS_LOG.md

@@ -0,0 +1,70 @@
+# 📝 AI Agents Log
+
+## Propósito
+
+Este ficheiro regista toda a atividade do agente de recomendação.  
+Cada execução gera uma entrada neste log.
+
+---
+
+## Formato de Entrada
+
+### Data:
+YYYY-MM-DD
+
+### Agente:
+Recommender-MVP
+
+### Tipo:
+- recomendacao
+- erro
+- melhoria
+
+### Descrição:
+O que foi feito
+
+### Itens afetados:
+Lista de itens usados
+
+### Ação tomada:
+O que se decidiu
+
+### Notas:
+Observações úteis
+
+---
+
+## Regras de Logging
+
+1. **SEMPRE** registar após cada execução
+2. Tipo `recomendacao` → quando sugestões são geradas com sucesso
+3. Tipo `erro` → quando lista vazia, pedido ambíguo ou dados incompletos
+4. Tipo `melhoria` → quando se detetam problemas no sistema
+5. Nunca omitir entradas de erro — são tão importantes como sucessos
+
+---
+
+## Histórico
+
+### Data:
+2026-04-24
+
+### Agente:
+Recommender-MVP
+
+### Tipo:
+recomendacao
+
+### Descrição:
+Implementação inicial do motor de recomendações MVP. Sistema de regras estáticas com 6 contextos, parser por palavras-chave, logging e deteção de melhorias.
+
+### Itens afetados:
+T-shirt preta, Portátil, Nintendo Switch, Fones de ouvido, Passaporte, Carregador USB-C, Jeans azul, Sapatilhas brancas, Mochila, Fato de treino
+
+### Ação tomada:
+Criado APPprojetoLP.dart com modelo de dados alinhado com 02_ARCHITECTURE.md, contextos de 05_RECOMMENDATION_ENGINE.md, e tags de 04_CATEGORIES_AND_TAGS.md
+
+### Notas:
+- Parser de pedidos é básico (palavras-chave). Fase 2 usará OpenAI API.
+- Clima e formalidade são detetados mas não filtram itens no MVP.
+- Duração "medium" (ex: 4 horas) não tem regras específicas ainda.