Documentação Inclusa

documentação/07_AGENT_BEHAVIOR.md

@@ -0,0 +1,184 @@
+# 🤖 Comportamento do Agente IA
+
+## Propósito deste ficheiro
+
+Este ficheiro define como um agente IA (assistente de código, Cursor, Copilot, Claude, etc.) deve comportar-se quando trabalha neste projeto.  
+**Lê este ficheiro primeiro antes de qualquer tarefa.**
+
+---
+
+## Contexto do projeto
+
+Estás a trabalhar num projeto chamado **InventoryAI** — uma app móvel de gestão de inventário pessoal com sugestões contextuais.
+
+Lê os seguintes ficheiros para entender o projeto completo:
+1. `00_PROJECT_OVERVIEW.md` — visão geral e princípios
+2. `01_MVP_DEFINITION.md` — o que está incluído no MVP
+3. `02_ARCHITECTURE.md` — stack técnica e modelo de dados
+4. `03_AI_VISION_LAYER.md` — integração com Google Vision
+5. `04_CATEGORIES_AND_TAGS.md` — sistema de organização
+6. `05_RECOMMENDATION_ENGINE.md` — lógica de sugestões
+7. `06_FUTURE_FEATURES.md` — roadmap futuro
+
+---
+
+## Regras de comportamento
+
+### ✅ SEMPRE fazer
+
+- **Verificar o ficheiro MVP** antes de implementar qualquer funcionalidade — só implementar o que está em `01_MVP_DEFINITION.md`
+- **Respeitar a stack definida** em `02_ARCHITECTURE.md` — Firebase, React Native, Google Vision
+- **Usar o modelo de dados** exatamente como definido (campos, tipos, nomes)
+- **Manter o código simples** — se há duas formas, escolher a mais simples
+- **Comentar decisões de arquitetura** no código quando relevante
+- **Avisar** quando uma funcionalidade pedida está fora do MVP
+- **Perguntar** antes de alterar o modelo de dados ou a arquitetura
+- **Criar ficheiros de serviço** em `src/services/` para lógica de negócio
+- **Usar constantes** de `src/constants/` para valores fixos (categorias, contextos, etc.)
+
+### ❌ NUNCA fazer
+
+- Adicionar funcionalidades que não estão no MVP sem confirmação explícita
+- Mudar a stack tecnológica (ex: sugerir Flutter, Supabase, AWS)
+- Implementar OpenAI no MVP — fica para a Fase 2
+- Guardar a API key do Google Vision em código client-side em produção
+- Criar lógica de base de dados fora dos ficheiros `services/`
+- Usar `console.log` em produção para dados sensíveis do utilizador
+- Alterar os nomes dos campos do modelo de dados sem avisar
+
+---
+
+## Linguagem e comunicação
+
+- Comunicar em **português** (de Portugal, não do Brasil)
+- Explicações técnicas devem ser **claras e objetivas**
+- Quando há uma decisão de arquitetura, **explicar o porquê**
+- Usar **exemplos de código** sempre que possível
+- Avisos sobre o MVP devem ser **visíveis** (usar emoji ⚠️ ou bloco de nota)
+
+---
+
+## Ordem de construção obrigatória
+
+Seguir esta ordem ao implementar. Não avançar para o próximo passo sem o anterior estar funcional:
+
+```
+PASSO 1: 📸 Upload de fotos
+  └── Câmara + seleção de galeria
+  └── Upload para Firebase Storage
+  └── URL guardado no estado
+
+PASSO 2: 📦 Guardar itens
+  └── Formulário básico (nome, categoria)
+  └── Gravar no Firestore
+  └── Autenticação Firebase
+
+PASSO 3: 🏷️ Categorização
+  └── Integração Google Vision API
+  └── Mapeamento labels → categorias
+  └── UI de confirmação/edição
+
+PASSO 4: 🔍 Pesquisa e visualização
+  └── Lista de itens (grid)
+  └── Filtro por categoria
+  └── Pesquisa por nome
+
+PASSO 5: 🎯 Sugestões simples
+  └── Seleção de contexto
+  └── Lógica de filtragem por tags
+  └── Apresentação da lista sugerida
+```
+
+---
+
+## Como responder a pedidos fora do MVP
+
+Quando o utilizador pede uma funcionalidade que está fora do MVP:
+
+```
+⚠️ MVP: Esta funcionalidade não está incluída no MVP atual.
+
+Está documentada como [Fase X] em 06_FUTURE_FEATURES.md.
+
+Opções:
+1. Adiar para a Fase X (recomendado — manter foco no MVP)
+2. Priorizar agora (implica atrasar outras funcionalidades do MVP)
+
+O que preferes?
+```
+
+---
+
+## Padrões de código obrigatórios
+
+### Nomenclatura
+```javascript
+// Componentes React: PascalCase
+ItemCard.jsx
+AddItemScreen.jsx
+
+// Serviços e utilitários: camelCase
+visionApi.js
+suggestions.js
+
+// Constantes: camelCase (ficheiros), UPPER_SNAKE_CASE (valores)
+categoryMapping.js → export const LABEL_TO_CATEGORY = { ... }
+contexts.js → export const CONTEXTS = [ ... ]
+```
+
+### Estrutura de um serviço
+```javascript
+// services/exemplo.js
+
+// 1. Imports
+import { db } from './firebase';
+
+// 2. Funções puras (sem side effects)
+export function processarDados(input) { ... }
+
+// 3. Funções de base de dados
+export async function guardarItem(userId, item) { ... }
+export async function obterItens(userId) { ... }
+```
+
+### Tratamento de erros
+```javascript
+// Sempre usar try/catch em chamadas assíncronas
+try {
+  const resultado = await guardarItem(userId, novoItem);
+  // sucesso
+} catch (erro) {
+  console.error('Erro ao guardar item:', erro.message);
+  // mostrar mensagem ao utilizador (não o erro técnico)
+  Alert.alert('Erro', 'Não foi possível guardar o item. Tenta novamente.');
+}
+```
+
+---
+
+## Perguntas frequentes
+
+**P: O utilizador pediu uma funcionalidade — implemento já?**  
+R: Verificar `01_MVP_DEFINITION.md`. Se estiver no MVP, implementar. Se não, avisar e perguntar.
+
+**P: Posso usar uma biblioteca nova?**  
+R: Só se resolver um problema que não tem solução simples sem ela. Avisar antes de instalar.
+
+**P: O modelo de dados precisa de um campo novo — adiciono?**  
+R: Avisar o utilizador, explicar o impacto, aguardar confirmação.
+
+**P: A API do Google Vision não está a funcionar nos testes — o que fazer?**  
+R: Criar um mock local (`services/visionApiMock.js`) que retorna dados fixos para desenvolvimento.
+
+---
+
+## Ficheiros de referência rápida
+
+| Quero saber... | Ficheiro |
+|----------------|----------|
+| O que está no MVP? | `01_MVP_DEFINITION.md` |
+| Que tecnologias usar? | `02_ARCHITECTURE.md` |
+| Como a IA de imagem funciona? | `03_AI_VISION_LAYER.md` |
+| Que categorias existem? | `04_CATEGORIES_AND_TAGS.md` |
+| Como funcionam as sugestões? | `05_RECOMMENDATION_ENGINE.md` |
+| O que vem a seguir? | `06_FUTURE_FEATURES.md` |