# 🤖 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` |