240402/dayMaker_lp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MVP

Browse Source
This commit is contained in:
Carlos Correia
2026-05-29 11:03:29 +01:00
parent 967584f083
commit fee538eebd
14 changed files with 1349 additions and 1149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
documentação/07_AGENT_BEHAVIOR.md
View File

@@ -1,184 +1,104 @@
# 🤖 Comportamento do Agente IA
# 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.**
Este ficheiro define como um agente IA de código deve comportar-se quando trabalha no projeto **DayMaker**.
---
## 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.
DayMaker é uma app Flutter com Supabase para inventário pessoal, planeamento semanal e sugestões por IA usando Ollama.
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
Antes de alterações grandes, consultar:
1. `00_PROJECT_OVERVIEW.md`
2. `01_MVP_DEFINITION.md`
3. `02_ARCHITECTURE.md`
4. `05_RECOMMENDATION_ENGINE.md`
---
## Regras de comportamento
### ✅ SEMPRE fazer
### 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.)
- Respeitar a stack atual: Flutter, Dart, Supabase e Ollama API.
- Usar os componentes e tokens de `lib/theme/app_theme.dart`.
- Manter queries Supabase filtradas por `user_id` quando os dados forem do utilizador.
- Verificar o modelo de dados antes de alterar tabelas ou campos.
- Manter a UI consistente com a navegação atual: Início, Itens, Semana, IA e Perfil.
- Usar `flutter analyze --no-pub` depois de alterações relevantes.
- Explicar ao utilizador quando uma funcionalidade exige alteração de base de dados.
### ❌ NUNCA fazer
### 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
- Reintroduzir Firebase, Firestore ou React Native.
- Assumir que Google Vision está implementado.
- Trocar o endpoint/modelo da IA sem testar ou explicar.
- Hardcodar API keys privadas.
- Enviar dados sensíveis desnecessários à IA.
- Criar categorias fora de `item_categories.dart` sem atualizar a documentação.
---
## Linguagem e comunicação
## Padrões de código
- 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)
### Flutter/Dart
- Widgets em `PascalCase`.
- Métodos privados com `_camelCase`.
- Serviços em `lib/services/`.
- Telas em `lib/Screens/` ou pasta equivalente já existente.
- Imports no topo do ficheiro.
### UI
Usar preferencialmente:
- `AppColors`
- `AppText`
- `AppRadius`
- `AppShadows`
- `AppDecorations`
- `AppButton`
- `AppChip`
- `AppSnack`
### Supabase
- Ler utilizador com `Supabase.instance.client.auth.currentUser`.
- Não executar operações de dados se `user == null`.
- Usar `.eq('user_id', user.id)` em tabelas por utilizador.
---
## Ordem de construção obrigatória
## IA e sugestões
Seguir esta ordem ao implementar. Não avançar para o próximo passo sem o anterior estar funcional:
O fluxo atual usa `AiRecommendationService`.
```
PASSO 1: 📸 Upload de fotos
└── Câmara + seleção de galeria
└── Upload para Firebase Storage
└── URL guardado no estado
- Chat livre: `sendMessage(text)`.
- Sugestão estruturada: `sendMessage(text, silent: true)`.
- Itens com imagem: `getItemsWithImages()`.
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
```
A IA deve receber contexto de inventário e responder em português.
---
## Como responder a pedidos fora do MVP
## Pedidos fora do produto atual
Quando o utilizador pede uma funcionalidade que está fora do MVP:
Se o utilizador pedir clima, notificações, visão por imagem ou calendário externo:
```
⚠️ 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?
```
1. Explicar que é funcionalidade futura.
2. Perguntar se deve implementar agora.
3. Avisar se exigir nova dependência, API key ou alteração de base de dados.
---
## Padrões de código obrigatórios
## Checklist antes de terminar uma tarefa
### 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` |
- Código compila com `flutter analyze --no-pub`.
- Não há imports não usados.
- UI segue tema atual.
- Documentação atualizada quando a funcionalidade muda comportamento.
- Resumo final indica ficheiros alterados.