first commit
This commit is contained in:
BIN
docs/.DS_Store
vendored
Normal file
BIN
docs/.DS_Store
vendored
Normal file
Binary file not shown.
44
docs/00_PROJECT_BRIEF.md
Normal file
44
docs/00_PROJECT_BRIEF.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Project Brief
|
||||
|
||||
## Nome provisório
|
||||
App de Gestão Operacional para Revenda de Roupa
|
||||
|
||||
## Resumo
|
||||
Aplicação web para gerir o ciclo operacional de um pequeno negócio de revenda de roupa, desde a encomenda ao fornecedor até ao envio ao cliente final.
|
||||
|
||||
## Objetivo principal
|
||||
Reduzir o tempo e os erros na gestão de encomendas, receção de mercadoria, controlo de stock, preparação de artigos para venda, registo de vendas e gestão de envios.
|
||||
|
||||
## Público-alvo
|
||||
Pequeno negócio de revenda de roupa com operação manual e necessidade de controlo simples, rápido e rastreável.
|
||||
|
||||
## Problemas principais
|
||||
- Dificuldade em controlar o que foi encomendado e o que falta receber
|
||||
- Dificuldade em registar stock após receção
|
||||
- Dificuldade em saber que artigos estão prontos para venda
|
||||
- Dificuldade em controlar vendas e perceber rapidamente para quem enviar
|
||||
|
||||
## Objetivo da V1
|
||||
Criar um MVP operacional que permita controlar:
|
||||
1. encomendas ao fornecedor
|
||||
2. receções parciais e totais
|
||||
3. inventário por estado
|
||||
4. vendas e envios pendentes
|
||||
|
||||
## Stack tecnológica selecionada
|
||||
- Next.js 16 com App Router
|
||||
- TypeScript
|
||||
- PostgreSQL
|
||||
- Prisma ORM
|
||||
- Supabase (database, auth, storage)
|
||||
- Tailwind CSS
|
||||
- shadcn/ui
|
||||
- React Hook Form
|
||||
- Zod
|
||||
|
||||
## Princípios técnicos
|
||||
- Uma única codebase full-stack na V1
|
||||
- Backend implementado dentro do projeto Next.js
|
||||
- Arquitetura simples, modular e orientada ao domínio
|
||||
- Documentação Markdown como fonte de verdade
|
||||
- Projeto preparado para desenvolvimento assistido por agentes de IA
|
||||
32
docs/01_VISION_AND_SCOPE.md
Normal file
32
docs/01_VISION_AND_SCOPE.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# Vision and Scope
|
||||
|
||||
## Visão do produto
|
||||
Criar uma aplicação simples, rápida e operacional para gerir todo o ciclo de revenda de roupa, desde a encomenda ao fornecedor até ao envio ao cliente final, reduzindo erros e dependência de controlo manual.
|
||||
|
||||
## Proposta de valor
|
||||
A aplicação deve funcionar como sistema operacional do negócio e não apenas como inventário. O foco é dar visibilidade total sobre o que foi pedido, recebido, preparado, vendido e expedido.
|
||||
|
||||
## Objetivo principal
|
||||
Permitir ao utilizador saber, em qualquer momento, o estado exato de cada encomenda, artigo e venda.
|
||||
|
||||
## Âmbito da V1
|
||||
- Gestão de fornecedores
|
||||
- Criação de encomendas
|
||||
- Receção total e parcial de mercadoria
|
||||
- Registo de inventário
|
||||
- Gestão de estados operacionais dos artigos
|
||||
- Registo manual de vendas
|
||||
- Gestão de envios pendentes
|
||||
- Dashboard operacional
|
||||
- Autenticação básica
|
||||
- Estrutura técnica preparada para crescimento
|
||||
|
||||
## Fora de âmbito na V1
|
||||
- Contabilidade
|
||||
- Faturação certificada
|
||||
- Integração automática com Vinted
|
||||
- Gestão financeira avançada
|
||||
- Multiempresa
|
||||
- Business intelligence avançada
|
||||
- App mobile nativa
|
||||
- Backend separado em microserviços
|
||||
27
docs/02_BUSINESS_CONTEXT.md
Normal file
27
docs/02_BUSINESS_CONTEXT.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Business Context
|
||||
|
||||
## Modelo de negócio
|
||||
Pequeno negócio de venda de roupa.
|
||||
|
||||
## Processo atual
|
||||
1. A roupa é encomendada a fornecedores
|
||||
2. Após receção, é necessário conferir o material recebido
|
||||
3. Os artigos têm de ser registados no inventário
|
||||
4. Os artigos são preparados para venda
|
||||
5. A venda é feita através da plataforma Vinted
|
||||
6. Após venda, é necessário identificar rapidamente o comprador e preparar o envio
|
||||
|
||||
## Fornecedor referido
|
||||
Hacco
|
||||
|
||||
## Canal de venda
|
||||
Vinted
|
||||
|
||||
## Limitações atuais
|
||||
- Processo muito manual
|
||||
- Baixa visibilidade sobre encomendas incompletas
|
||||
- Dificuldade em distinguir stock recebido, stock preparado e stock vendido
|
||||
- Gestão de envios morosa e sujeita a erro
|
||||
|
||||
## Oportunidade
|
||||
Estruturar digitalmente o processo de ponta a ponta para reduzir tempo operacional, aumentar controlo e preparar futuras automações.
|
||||
23
docs/03_PROBLEM_STATEMENT.md
Normal file
23
docs/03_PROBLEM_STATEMENT.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# Problem Statement
|
||||
|
||||
## Problema central
|
||||
O negócio depende de controlo manual em várias etapas operacionais, gerando perda de tempo, falta de visibilidade e maior probabilidade de erro.
|
||||
|
||||
## Problemas específicos
|
||||
- Ao receber encomendas com muitos artigos, é difícil perceber o que chegou e o que ainda falta receber
|
||||
- O registo no inventário consome demasiado tempo
|
||||
- Não existe uma visão clara do estado operacional de cada artigo
|
||||
- Após uma venda, é moroso perceber para quem deve ser preparado o envio
|
||||
- A informação está dispersa e não existe um fluxo único de controlo
|
||||
|
||||
## Impacto no negócio
|
||||
- Perda de tempo operacional
|
||||
- Risco de erros na receção
|
||||
- Risco de falhas no controlo de stock
|
||||
- Risco de atrasos ou erros no envio
|
||||
|
||||
## O que a app deve resolver
|
||||
- Centralizar a informação operacional
|
||||
- Tornar a receção controlada e auditável
|
||||
- Dar visibilidade ao estado do stock
|
||||
- Simplificar o registo de vendas e o processo de envio
|
||||
27
docs/04_PRODUCT_GOALS.md
Normal file
27
docs/04_PRODUCT_GOALS.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Product Goals
|
||||
|
||||
## Objetivos principais
|
||||
- Centralizar a operação do negócio numa única aplicação
|
||||
- Reduzir o tempo necessário para receção e conferência de encomendas
|
||||
- Melhorar a visibilidade do stock em cada fase
|
||||
- Tornar simples o controlo de vendas e envios pendentes
|
||||
|
||||
## Objetivos secundários
|
||||
- Garantir rastreabilidade mínima por artigo ou unidade
|
||||
- Preparar o projeto para futuras automações
|
||||
- Reduzir dependência de memória e controlo informal
|
||||
|
||||
## Resultado esperado
|
||||
O utilizador deve conseguir saber, em qualquer momento:
|
||||
- o que foi encomendado
|
||||
- o que já foi recebido
|
||||
- o que ainda falta receber
|
||||
- o que está pronto para venda
|
||||
- o que foi vendido
|
||||
- o que está pendente de envio
|
||||
|
||||
## Indicadores de sucesso desejáveis
|
||||
- Menos tempo gasto na conferência de receções
|
||||
- Menos erros no controlo de stock
|
||||
- Menos tempo para identificar vendas por enviar
|
||||
- Maior previsibilidade operacional
|
||||
43
docs/05_USER_WORKFLOWS.md
Normal file
43
docs/05_USER_WORKFLOWS.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# User Workflows
|
||||
|
||||
## Workflow 1 — Criar encomenda ao fornecedor
|
||||
1. Selecionar fornecedor
|
||||
2. Criar nova encomenda
|
||||
3. Adicionar artigos e quantidades
|
||||
4. Guardar encomenda com estado `ordered`
|
||||
|
||||
## Workflow 2 — Receber mercadoria
|
||||
1. Abrir encomenda pendente
|
||||
2. Visualizar lista de artigos esperados
|
||||
3. Registar quantidade recebida por artigo
|
||||
4. Marcar discrepâncias ou faltas
|
||||
5. Fechar receção
|
||||
6. Atualizar estado da encomenda para:
|
||||
- `received`
|
||||
- `partially_received`
|
||||
- `pending`
|
||||
|
||||
## Workflow 3 — Registar inventário
|
||||
1. Ver artigos recebidos e ainda não registados
|
||||
2. Confirmar entrada no inventário
|
||||
3. Criar unidades ou stock registado
|
||||
4. Definir estado inicial operacional
|
||||
|
||||
## Workflow 4 — Preparar artigo para venda
|
||||
1. Ver artigos registados e ainda não preparados
|
||||
2. Marcar como preparado
|
||||
3. Marcar como publicado/anunciado
|
||||
4. Guardar referência do anúncio, se aplicável
|
||||
|
||||
## Workflow 5 — Registar venda
|
||||
1. Selecionar artigo vendido
|
||||
2. Introduzir dados da venda
|
||||
3. Associar comprador
|
||||
4. Alterar estado para `sold` ou `pending_shipment`
|
||||
|
||||
## Workflow 6 — Gerir envio
|
||||
1. Ver lista de vendas pendentes de envio
|
||||
2. Abrir venda
|
||||
3. Confirmar destinatário
|
||||
4. Marcar envio como concluído
|
||||
5. Atualizar estado para `shipped`
|
||||
41
docs/06_FUNCTIONAL_REQUIREMENTS.md
Normal file
41
docs/06_FUNCTIONAL_REQUIREMENTS.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Functional Requirements
|
||||
|
||||
## Fornecedores e encomendas
|
||||
- O sistema deve permitir registar fornecedores
|
||||
- O sistema deve permitir criar encomendas por fornecedor
|
||||
- O sistema deve permitir adicionar múltiplos artigos a cada encomenda
|
||||
- O sistema deve permitir editar estados de encomenda
|
||||
- O sistema deve manter histórico básico da encomenda
|
||||
|
||||
## Receção de mercadoria
|
||||
- O sistema deve permitir registar receções totais e parciais
|
||||
- O sistema deve permitir comparar quantidade encomendada com quantidade recebida
|
||||
- O sistema deve sinalizar divergências
|
||||
- O sistema deve manter encomendas abertas enquanto existirem artigos por receber
|
||||
|
||||
## Inventário
|
||||
- O sistema deve permitir criar inventário a partir de artigos recebidos
|
||||
- O sistema deve permitir consultar stock por estado
|
||||
- O sistema deve permitir filtrar por fornecedor, lote, artigo, tamanho e estado
|
||||
- O sistema deve impedir dupla disponibilidade do mesmo artigo vendido
|
||||
|
||||
## Preparação e venda
|
||||
- O sistema deve permitir marcar artigos como preparados para venda
|
||||
- O sistema deve permitir marcar artigos como publicados
|
||||
- O sistema deve permitir registar vendas manualmente
|
||||
- O sistema deve permitir associar comprador à venda
|
||||
- O sistema deve permitir listar vendas pendentes de envio
|
||||
- O sistema deve permitir guardar referência manual ao anúncio Vinted
|
||||
|
||||
## Envios
|
||||
- O sistema deve permitir marcar vendas como enviadas
|
||||
- O sistema deve manter histórico do estado do envio
|
||||
|
||||
## Dashboard
|
||||
- O sistema deve apresentar indicadores operacionais essenciais
|
||||
- O sistema deve destacar tarefas pendentes do dia
|
||||
|
||||
## Administração e autenticação
|
||||
- O sistema deve exigir autenticação para acesso à aplicação
|
||||
- O sistema deve suportar pelo menos um utilizador administrador na V1
|
||||
- O sistema deve registar timestamps de criação e atualização nas entidades principais
|
||||
37
docs/07_NON_FUNCTIONAL_REQUIREMENTS.md
Normal file
37
docs/07_NON_FUNCTIONAL_REQUIREMENTS.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# Non-Functional Requirements
|
||||
|
||||
## Usabilidade
|
||||
- A aplicação deve ser simples de usar por uma única pessoa
|
||||
- As ações principais devem exigir poucos cliques
|
||||
- A navegação deve ser clara e centrada em tarefas operacionais
|
||||
- A interface deve ser adequada a desktop e utilizável em tablet/mobile
|
||||
|
||||
## Performance
|
||||
- O sistema deve responder rapidamente em operações correntes
|
||||
- Listagens e filtros devem ser imediatos em contexto de pequeno negócio
|
||||
- O dashboard principal deve carregar sem sensação de lentidão
|
||||
|
||||
## Fiabilidade
|
||||
- O sistema deve preservar integridade dos estados
|
||||
- O sistema deve reduzir risco de erro humano em processos repetitivos
|
||||
- As mutações críticas devem ser validadas no servidor
|
||||
|
||||
## Rastreabilidade
|
||||
- Alterações importantes devem ficar registadas
|
||||
- O utilizador deve conseguir compreender o histórico operacional
|
||||
|
||||
## Portabilidade
|
||||
- A aplicação deve ser web-first
|
||||
- O sistema deve correr numa única stack full-stack baseada em Next.js
|
||||
- O projeto deve poder ser desenvolvido localmente e deployado sem arquitetura distribuída
|
||||
|
||||
## Segurança
|
||||
- O acesso deve ser autenticado
|
||||
- Deve existir mecanismo básico de backup e recuperação
|
||||
- Devem existir regras de acesso mínimas para dados e ficheiros
|
||||
- Os segredos devem ser geridos por variáveis de ambiente
|
||||
|
||||
## Manutenibilidade
|
||||
- O código deve ser modular, tipado e documentado
|
||||
- A estrutura do projeto deve favorecer trabalho com agentes de IA
|
||||
- As regras de negócio devem estar separadas da camada de apresentação
|
||||
195
docs/08_DOMAIN_MODEL.md
Normal file
195
docs/08_DOMAIN_MODEL.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Domain Model
|
||||
|
||||
## Abordagem de modelação
|
||||
O domínio deve ser modelado em torno do fluxo operacional do negócio e não apenas em torno de produtos abstratos. A unidade principal de controlo é a encomenda ao fornecedor, a receção, a unidade de inventário e o ciclo de venda/envio.
|
||||
|
||||
## Entidades principais
|
||||
|
||||
### User
|
||||
Representa o utilizador autenticado da aplicação.
|
||||
Na V1 pode existir apenas um utilizador administrador, mas a modelação deve admitir crescimento futuro.
|
||||
|
||||
### Supplier
|
||||
Representa um fornecedor de roupa.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- name
|
||||
- contact_name
|
||||
- email
|
||||
- phone
|
||||
- notes
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
### PurchaseOrder
|
||||
Representa uma encomenda feita a um fornecedor.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- supplier_id
|
||||
- external_reference
|
||||
- status
|
||||
- ordered_at
|
||||
- expected_at
|
||||
- notes
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
### PurchaseOrderItem
|
||||
Representa uma linha da encomenda, com artigo, variante e quantidade.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- purchase_order_id
|
||||
- product_model_id
|
||||
- variant_label
|
||||
- size
|
||||
- color
|
||||
- sku_supplier
|
||||
- quantity_ordered
|
||||
- unit_cost
|
||||
- notes
|
||||
|
||||
### Receipt
|
||||
Representa um evento de receção de mercadoria relativo a uma encomenda.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- purchase_order_id
|
||||
- receipt_date
|
||||
- status
|
||||
- notes
|
||||
- created_by
|
||||
- created_at
|
||||
|
||||
### ReceiptItem
|
||||
Representa a quantidade recebida de cada linha da encomenda.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- receipt_id
|
||||
- purchase_order_item_id
|
||||
- quantity_received
|
||||
- quantity_rejected
|
||||
- discrepancy_note
|
||||
|
||||
### ProductModel
|
||||
Representa o artigo ou modelo comercial.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- name
|
||||
- brand
|
||||
- category
|
||||
- default_size
|
||||
- default_color
|
||||
- internal_sku
|
||||
- supplier_sku
|
||||
- notes
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
### InventoryUnit
|
||||
Representa uma unidade concreta ou unidade lógica rastreável no inventário.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- product_model_id
|
||||
- purchase_order_id
|
||||
- receipt_item_id
|
||||
- inventory_status
|
||||
- condition
|
||||
- storage_location
|
||||
- cost_price
|
||||
- ready_for_listing_at
|
||||
- created_at
|
||||
- updated_at
|
||||
|
||||
Nota:
|
||||
A V1 deve favorecer rastreabilidade por unidade sempre que possível. Caso existam cenários de stock agregado, essa decisão deve ser explícita e documentada.
|
||||
|
||||
### Listing
|
||||
Representa um anúncio publicado ou preparado para publicação.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- inventory_unit_id
|
||||
- platform
|
||||
- external_reference
|
||||
- listing_status
|
||||
- listed_price
|
||||
- listed_at
|
||||
- url
|
||||
- notes
|
||||
|
||||
### Customer
|
||||
Representa o comprador associado a uma venda.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- name
|
||||
- platform_username
|
||||
- shipping_name
|
||||
- shipping_address
|
||||
- phone
|
||||
- email
|
||||
- notes
|
||||
|
||||
### Sale
|
||||
Representa a venda de uma unidade ou artigo.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- inventory_unit_id
|
||||
- customer_id
|
||||
- sale_channel
|
||||
- sale_status
|
||||
- sale_price
|
||||
- sold_at
|
||||
- notes
|
||||
- created_at
|
||||
|
||||
### Shipment
|
||||
Representa o envio associado a uma venda.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- sale_id
|
||||
- shipment_status
|
||||
- shipped_at
|
||||
- tracking_code
|
||||
- carrier
|
||||
- label_reference
|
||||
- notes
|
||||
|
||||
### StatusHistory
|
||||
Representa o histórico de transições de estado relevantes.
|
||||
|
||||
Campos indicativos:
|
||||
- id
|
||||
- entity_type
|
||||
- entity_id
|
||||
- from_status
|
||||
- to_status
|
||||
- changed_by
|
||||
- changed_at
|
||||
- note
|
||||
|
||||
## Relações principais
|
||||
- Um User pode criar Receipts e alterar estados
|
||||
- Um Supplier pode ter muitas PurchaseOrders
|
||||
- Uma PurchaseOrder tem muitos PurchaseOrderItems
|
||||
- Uma PurchaseOrder pode ter muitas Receipts
|
||||
- Uma Receipt tem muitos ReceiptItems
|
||||
- Um ProductModel pode existir em muitos PurchaseOrderItems
|
||||
- Um InventoryUnit resulta de receção e registo
|
||||
- Um InventoryUnit pode originar um Listing
|
||||
- Um InventoryUnit pode estar associado a uma Sale
|
||||
- Uma Sale pode gerar um Shipment
|
||||
- As entidades críticas podem gerar StatusHistory
|
||||
|
||||
## Observações de implementação
|
||||
- O modelo de dados deve ser implementado em PostgreSQL
|
||||
- O acesso à base de dados deve ser feito através de Prisma ORM
|
||||
- As regras de domínio não devem ficar dispersas em componentes de interface
|
||||
48
docs/09_STATES_AND_LIFECYCLES.md
Normal file
48
docs/09_STATES_AND_LIFECYCLES.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# States and Lifecycles
|
||||
|
||||
## Estados de encomenda
|
||||
- `draft`
|
||||
- `ordered`
|
||||
- `partially_received`
|
||||
- `received`
|
||||
- `closed`
|
||||
- `cancelled`
|
||||
|
||||
## Estados de receção
|
||||
- `pending`
|
||||
- `in_progress`
|
||||
- `completed`
|
||||
- `completed_with_discrepancies`
|
||||
|
||||
## Estados de inventário/unidade
|
||||
- `ordered`
|
||||
- `received`
|
||||
- `registered`
|
||||
- `ready_for_listing`
|
||||
- `listed`
|
||||
- `reserved`
|
||||
- `sold`
|
||||
- `pending_shipment`
|
||||
- `shipped`
|
||||
- `completed`
|
||||
- `blocked`
|
||||
|
||||
## Estados de venda
|
||||
- `draft`
|
||||
- `confirmed`
|
||||
- `pending_shipment`
|
||||
- `shipped`
|
||||
- `completed`
|
||||
- `cancelled`
|
||||
|
||||
## Estados de envio
|
||||
- `not_started`
|
||||
- `pending`
|
||||
- `shipped`
|
||||
- `delivered`
|
||||
- `issue`
|
||||
|
||||
## Observações
|
||||
- Uma unidade vendida não deve voltar a ficar disponível sem operação explícita
|
||||
- Uma encomenda parcialmente recebida deve manter-se aberta
|
||||
- Estados finais devem ser reduzidos e claros para evitar ambiguidade
|
||||
47
docs/10_MVP_DEFINITION.md
Normal file
47
docs/10_MVP_DEFINITION.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# MVP Definition
|
||||
|
||||
## Objetivo do MVP
|
||||
Resolver as dores operacionais principais com o mínimo de complexidade possível.
|
||||
|
||||
## Funcionalidades obrigatórias
|
||||
- Gestão de fornecedores
|
||||
- Criação de encomendas
|
||||
- Receção parcial e total
|
||||
- Registo de inventário
|
||||
- Gestão de estados dos artigos
|
||||
- Registo manual de vendas
|
||||
- Gestão de envios pendentes
|
||||
- Dashboard operacional básico
|
||||
- Autenticação base
|
||||
- Estrutura para anexar referência manual de anúncio
|
||||
|
||||
## Funcionalidades desejáveis
|
||||
- Histórico de alterações
|
||||
- Filtros avançados
|
||||
- Gestão simples de localização física do artigo
|
||||
- Upload de imagens em fase posterior do MVP, se não complicar a entrega
|
||||
|
||||
## Funcionalidades adiadas
|
||||
- Integração automática com Vinted
|
||||
- Gestão financeira
|
||||
- Faturação
|
||||
- Multiutilizador avançado
|
||||
- Relatórios complexos
|
||||
- App mobile nativa
|
||||
- Backend separado
|
||||
- Automações avançadas
|
||||
|
||||
## Critério de sucesso do MVP
|
||||
O utilizador consegue controlar sem folhas dispersas:
|
||||
- o que falta receber
|
||||
- o que existe em stock por estado
|
||||
- o que foi vendido
|
||||
- o que falta enviar
|
||||
|
||||
## Critério técnico do MVP
|
||||
O MVP deve ser entregue numa única aplicação full-stack com:
|
||||
- frontend em Next.js
|
||||
- backend dentro do projeto Next.js
|
||||
- base de dados PostgreSQL
|
||||
- ORM Prisma
|
||||
- autenticação e storage suportados por Supabase
|
||||
491
docs/11_ROADMAP.md
Normal file
491
docs/11_ROADMAP.md
Normal file
@@ -0,0 +1,491 @@
|
||||
# 11_ROADMAP.md
|
||||
|
||||
## Objetivo deste documento
|
||||
Este documento define o roadmap de implementação do projeto, com foco em execução faseada, controlo de dependências, clareza para agentes de IA e redução de retrabalho.
|
||||
|
||||
O roadmap deve ser lido em conjunto com:
|
||||
- `00_PROJECT_BRIEF.md`
|
||||
- `04_PRODUCT_GOALS.md`
|
||||
- `05_USER_WORKFLOWS.md`
|
||||
- `08_DOMAIN_MODEL.md`
|
||||
- `09_STATES_AND_LIFECYCLES.md`
|
||||
- `10_MVP_DEFINITION.md`
|
||||
- `16_DECISIONS_LOG.md`
|
||||
- `17_PROGRESS.md`
|
||||
- `18_AGENT_HANDOFF.md`
|
||||
- `19_TECH_STACK.md`
|
||||
- `20_PROJECT_STRUCTURE.md`
|
||||
- `21_ENGINEERING_GUIDELINES.md`
|
||||
|
||||
---
|
||||
|
||||
## Princípios de execução
|
||||
|
||||
1. Implementar por fases curtas e controladas.
|
||||
2. Não avançar para fases dependentes sem a base anterior consolidada.
|
||||
3. Priorizar sempre valor operacional real.
|
||||
4. Evitar complexidade desnecessária na V1.
|
||||
5. Atualizar `16_DECISIONS_LOG.md`, `17_PROGRESS.md` e `18_AGENT_HANDOFF.md` no final de cada fase ou subfase relevante.
|
||||
6. Não introduzir funcionalidades fora do MVP sem registo explícito.
|
||||
|
||||
---
|
||||
|
||||
## Visão geral das fases
|
||||
|
||||
O projeto deve ser implementado em 7 fases principais:
|
||||
|
||||
1. Consolidação funcional
|
||||
2. Preparação técnica
|
||||
3. Fundação do projeto
|
||||
4. Núcleo operacional do MVP
|
||||
5. Dashboard e produtividade
|
||||
6. Qualidade, robustez e lançamento
|
||||
7. Evolução pós-MVP
|
||||
|
||||
---
|
||||
|
||||
## Fase 1 — Consolidação funcional
|
||||
|
||||
### Objetivo
|
||||
Fechar a lógica do negócio antes do desenvolvimento técnico.
|
||||
|
||||
### Resultados esperados
|
||||
No final desta fase deve estar claramente definido:
|
||||
- o que a aplicação faz;
|
||||
- quais são os fluxos principais;
|
||||
- quais são os estados do sistema;
|
||||
- o que entra no MVP;
|
||||
- o que fica fora do MVP;
|
||||
- quais são as regras de negócio críticas.
|
||||
|
||||
### Tarefas
|
||||
- rever a documentação base do projeto;
|
||||
- consolidar o modelo de domínio;
|
||||
- consolidar os estados e ciclos de vida;
|
||||
- validar os workflows principais;
|
||||
- fechar a definição do MVP;
|
||||
- listar regras críticas de integridade de dados;
|
||||
- registar decisões em aberto;
|
||||
- atualizar os ficheiros de continuidade do projeto.
|
||||
|
||||
### Entregáveis
|
||||
- `08_DOMAIN_MODEL.md`
|
||||
- `09_STATES_AND_LIFECYCLES.md`
|
||||
- `10_MVP_DEFINITION.md`
|
||||
- `13_DATA_RULES.md`
|
||||
- `15_OPEN_QUESTIONS.md` atualizado
|
||||
- `16_DECISIONS_LOG.md` atualizado
|
||||
|
||||
### Critério de conclusão
|
||||
Nenhum agente deve começar a implementar funcionalidades sem esta fase estabilizada.
|
||||
|
||||
---
|
||||
|
||||
## Fase 2 — Preparação técnica
|
||||
|
||||
### Objetivo
|
||||
Traduzir a visão funcional numa base técnica clara e consistente.
|
||||
|
||||
### Resultados esperados
|
||||
A stack, organização do projeto, convenções de engenharia e abordagem de desenvolvimento devem estar fechadas.
|
||||
|
||||
### Tarefas
|
||||
- consolidar a stack tecnológica escolhida;
|
||||
- definir a estrutura de diretórios do projeto;
|
||||
- definir convenções de nomenclatura;
|
||||
- definir abordagem para autenticação, base de dados e storage;
|
||||
- definir fluxo de migrations com Prisma;
|
||||
- definir abordagem de validação com Zod;
|
||||
- definir regras de organização por feature/domain;
|
||||
- definir princípios de tratamento de erros e logging;
|
||||
- definir estratégia de testes para o MVP.
|
||||
|
||||
### Entregáveis
|
||||
- `19_TECH_STACK.md`
|
||||
- `20_PROJECT_STRUCTURE.md`
|
||||
- `21_ENGINEERING_GUIDELINES.md`
|
||||
- prompts técnicos atualizados para agentes
|
||||
|
||||
### Critério de conclusão
|
||||
O projeto técnico está pronto para scaffolding sem improviso.
|
||||
|
||||
---
|
||||
|
||||
## Fase 3 — Fundação do projeto
|
||||
|
||||
### Objetivo
|
||||
Criar a base real do repositório e da aplicação.
|
||||
|
||||
### Resultados esperados
|
||||
Projeto funcional, organizado e pronto para receber funcionalidades.
|
||||
|
||||
### Tarefas
|
||||
- inicializar projeto com Next.js 16 e TypeScript;
|
||||
- configurar Tailwind CSS;
|
||||
- integrar shadcn/ui;
|
||||
- configurar Prisma ORM;
|
||||
- ligar a aplicação ao Supabase;
|
||||
- configurar autenticação base;
|
||||
- configurar storage base;
|
||||
- criar `.env.example`;
|
||||
- criar estrutura inicial de `src/`;
|
||||
- criar layout base da aplicação;
|
||||
- configurar linting e formatação;
|
||||
- preparar tratamento base de erros;
|
||||
- criar schema inicial Prisma com entidades nucleares;
|
||||
- criar seed opcional para ambiente de desenvolvimento.
|
||||
|
||||
### Entregáveis
|
||||
- repositório inicial funcional;
|
||||
- autenticação mínima operacional;
|
||||
- ligação à base de dados funcional;
|
||||
- schema Prisma inicial;
|
||||
- estrutura técnica estabilizada.
|
||||
|
||||
### Critério de conclusão
|
||||
A aplicação corre localmente e está pronta para começar a implementar módulos de negócio.
|
||||
|
||||
---
|
||||
|
||||
## Fase 4 — Núcleo operacional do MVP
|
||||
|
||||
### Objetivo
|
||||
Construir o coração operacional da aplicação.
|
||||
|
||||
### Módulos desta fase
|
||||
1. fornecedores
|
||||
2. encomendas ao fornecedor
|
||||
3. receção de mercadoria
|
||||
4. inventário
|
||||
5. preparação para venda
|
||||
6. vendas e envios
|
||||
|
||||
---
|
||||
|
||||
## Fase 4.1 — Fornecedores e encomendas
|
||||
|
||||
### Objetivo
|
||||
Permitir criar e gerir encomendas ao fornecedor.
|
||||
|
||||
### Tarefas
|
||||
- implementar CRUD de fornecedores;
|
||||
- implementar criação de encomendas;
|
||||
- implementar linhas de encomenda;
|
||||
- implementar estados da encomenda;
|
||||
- implementar listagem de encomendas;
|
||||
- implementar detalhe da encomenda;
|
||||
- implementar filtros por fornecedor, estado e data.
|
||||
|
||||
### Resultados esperados
|
||||
O utilizador consegue registar uma encomenda completa ao fornecedor e consultá-la com clareza.
|
||||
|
||||
### Critério de conclusão
|
||||
Existe um fluxo estável para criação, consulta e gestão básica de encomendas.
|
||||
|
||||
---
|
||||
|
||||
## Fase 4.2 — Receção de mercadoria
|
||||
|
||||
### Objetivo
|
||||
Resolver a dor principal da receção: perceber o que chegou e o que ainda falta receber.
|
||||
|
||||
### Tarefas
|
||||
- criar ecrã de receção por encomenda;
|
||||
- permitir receção parcial;
|
||||
- permitir receção total;
|
||||
- permitir registo de discrepâncias;
|
||||
- calcular automaticamente quantidades em falta;
|
||||
- guardar histórico de receções;
|
||||
- atualizar automaticamente o estado da encomenda.
|
||||
|
||||
### Resultados esperados
|
||||
O utilizador consegue perceber rapidamente:
|
||||
- o que foi encomendado;
|
||||
- o que já foi recebido;
|
||||
- o que continua em falta;
|
||||
- se existem diferenças entre o pedido e a receção.
|
||||
|
||||
### Critério de conclusão
|
||||
É possível receber uma encomenda parcialmente e manter visibilidade exata do saldo pendente.
|
||||
|
||||
---
|
||||
|
||||
## Fase 4.3 — Inventário
|
||||
|
||||
### Objetivo
|
||||
Registar os artigos recebidos e dar visibilidade ao stock real.
|
||||
|
||||
### Tarefas
|
||||
- criar unidades de inventário a partir das receções;
|
||||
- associar unidades a encomendas e receções;
|
||||
- implementar estados operacionais das unidades;
|
||||
- implementar listagem de inventário;
|
||||
- implementar filtros por estado, fornecedor, artigo e lote;
|
||||
- implementar detalhe da unidade;
|
||||
- implementar histórico básico de alterações relevantes.
|
||||
|
||||
### Resultados esperados
|
||||
O utilizador consegue saber o que foi recebido, o que já foi registado e o que ainda não está pronto para venda.
|
||||
|
||||
### Critério de conclusão
|
||||
O inventário representa o estado real da operação e não apenas quantidades abstratas.
|
||||
|
||||
---
|
||||
|
||||
## Fase 4.4 — Preparação para venda
|
||||
|
||||
### Objetivo
|
||||
Controlar os artigos que já estão em condições de ser anunciados ou vendidos.
|
||||
|
||||
### Tarefas
|
||||
- permitir marcar artigo como registado;
|
||||
- permitir marcar artigo como preparado;
|
||||
- permitir marcar artigo como publicado/anunciado;
|
||||
- guardar referência do anúncio, se aplicável;
|
||||
- permitir listar artigos por estado operacional;
|
||||
- facilitar transições rápidas de estado.
|
||||
|
||||
### Resultados esperados
|
||||
O utilizador consegue distinguir claramente:
|
||||
- artigos recebidos;
|
||||
- artigos registados;
|
||||
- artigos preparados;
|
||||
- artigos publicados.
|
||||
|
||||
### Critério de conclusão
|
||||
Existe visibilidade operacional completa da fase intermédia entre receção e venda.
|
||||
|
||||
---
|
||||
|
||||
## Fase 4.5 — Vendas e envios
|
||||
|
||||
### Objetivo
|
||||
Eliminar a dificuldade em perceber para quem deve ser feito o envio.
|
||||
|
||||
### Tarefas
|
||||
- implementar registo de venda;
|
||||
- associar venda a unidade de inventário;
|
||||
- guardar dados do comprador;
|
||||
- alterar estado do artigo para vendido;
|
||||
- marcar venda como pendente de envio;
|
||||
- marcar envio como concluído;
|
||||
- implementar lista de vendas pendentes de envio;
|
||||
- implementar detalhe da venda com destinatário e estado.
|
||||
|
||||
### Resultados esperados
|
||||
O utilizador consegue ver rapidamente tudo o que está por enviar e respetivo destinatário.
|
||||
|
||||
### Critério de conclusão
|
||||
Existe um painel simples e fiável para gestão de envios pendentes.
|
||||
|
||||
---
|
||||
|
||||
## Fase 5 — Dashboard e produtividade
|
||||
|
||||
### Objetivo
|
||||
Transformar a aplicação numa ferramenta diária de operação.
|
||||
|
||||
### Resultados esperados
|
||||
Ao abrir a aplicação, o utilizador deve perceber imediatamente o estado da operação e o que precisa de fazer.
|
||||
|
||||
### Tarefas
|
||||
- implementar dashboard principal;
|
||||
- criar métricas operacionais resumidas;
|
||||
- criar blocos de ações pendentes;
|
||||
- mostrar encomendas por receber;
|
||||
- mostrar artigos por registar;
|
||||
- mostrar artigos por preparar;
|
||||
- mostrar artigos por publicar;
|
||||
- mostrar vendas por enviar;
|
||||
- criar filtros rápidos e atalhos de navegação;
|
||||
- implementar ações rápidas diretamente no dashboard.
|
||||
|
||||
### Critério de conclusão
|
||||
O dashboard permite orientar o trabalho diário com poucos cliques.
|
||||
|
||||
---
|
||||
|
||||
## Fase 6 — Qualidade, robustez e lançamento
|
||||
|
||||
### Objetivo
|
||||
Passar de uma aplicação funcional para uma aplicação confiável para uso diário.
|
||||
|
||||
### Tarefas
|
||||
- implementar testes unitários para regras críticas;
|
||||
- implementar testes de integração para fluxos principais;
|
||||
- validar coerência dos estados;
|
||||
- reforçar proteção contra inconsistências;
|
||||
- melhorar UX de formulários, tabelas e feedback visual;
|
||||
- implementar loading states e empty states;
|
||||
- reforçar tratamento de erros;
|
||||
- rever permissões mínimas e segurança básica;
|
||||
- rever backups e recuperação;
|
||||
- criar documentação de setup e execução;
|
||||
- preparar checklist de lançamento;
|
||||
- configurar ambiente de produção.
|
||||
|
||||
### Critério de conclusão
|
||||
A aplicação pode ser usada em contexto real com confiança operacional.
|
||||
|
||||
---
|
||||
|
||||
## Fase 7 — Evolução pós-MVP
|
||||
|
||||
### Objetivo
|
||||
Expandir a aplicação com base no uso real e em necessidades confirmadas.
|
||||
|
||||
### Possíveis evoluções
|
||||
- importação semiautomática de vendas;
|
||||
- notificações e alertas;
|
||||
- automações com IA;
|
||||
- lista de trabalho automática do dia;
|
||||
- deteção de discrepâncias mais inteligente;
|
||||
- relatórios operacionais;
|
||||
- métricas por fornecedor;
|
||||
- métricas por categoria de artigo;
|
||||
- gestão mais avançada de imagens;
|
||||
- múltiplos utilizadores e perfis;
|
||||
- PWA ou versão mobile;
|
||||
- integrações futuras com plataformas externas.
|
||||
|
||||
### Regra de controlo
|
||||
Nenhuma funcionalidade desta fase deve entrar antes do núcleo operacional do MVP estar sólido.
|
||||
|
||||
---
|
||||
|
||||
## Ordem prática de implementação
|
||||
|
||||
### Bloco 1 — Fechar documentação
|
||||
- domínio
|
||||
- estados
|
||||
- MVP
|
||||
- regras de dados
|
||||
|
||||
### Bloco 2 — Montar base técnica
|
||||
- projeto
|
||||
- autenticação
|
||||
- base de dados
|
||||
- estrutura
|
||||
- UI base
|
||||
|
||||
### Bloco 3 — Implementar compras e receção
|
||||
- fornecedores
|
||||
- encomendas
|
||||
- receções
|
||||
|
||||
### Bloco 4 — Implementar inventário
|
||||
- unidades
|
||||
- estados
|
||||
- filtros
|
||||
|
||||
### Bloco 5 — Implementar vendas e envios
|
||||
- venda
|
||||
- comprador
|
||||
- pendentes de envio
|
||||
|
||||
### Bloco 6 — Implementar dashboard
|
||||
- visão central da operação
|
||||
- tarefas do dia
|
||||
- atalhos rápidos
|
||||
|
||||
### Bloco 7 — Hardening
|
||||
- testes
|
||||
- UX
|
||||
- produção
|
||||
|
||||
---
|
||||
|
||||
## Roadmap em formato de sprints
|
||||
|
||||
### Sprint 1 — Definição funcional
|
||||
- fechar domínio
|
||||
- fechar estados
|
||||
- fechar MVP
|
||||
- fechar regras de dados
|
||||
|
||||
### Sprint 2 — Base técnica
|
||||
- setup do projeto
|
||||
- autenticação
|
||||
- base de dados
|
||||
- estrutura
|
||||
- UI base
|
||||
|
||||
### Sprint 3 — Fornecedores e encomendas
|
||||
- CRUD de fornecedores
|
||||
- criação de encomendas
|
||||
- listagem e detalhe de encomendas
|
||||
|
||||
### Sprint 4 — Receção
|
||||
- receção parcial
|
||||
- receção total
|
||||
- discrepâncias
|
||||
- atualização de estados da encomenda
|
||||
|
||||
### Sprint 5 — Inventário
|
||||
- unidades
|
||||
- estados
|
||||
- registo operacional
|
||||
- filtros
|
||||
|
||||
### Sprint 6 — Vendas e envios
|
||||
- registo de venda
|
||||
- comprador
|
||||
- pendentes de envio
|
||||
- envio concluído
|
||||
|
||||
### Sprint 7 — Dashboard
|
||||
- tarefas do dia
|
||||
- indicadores
|
||||
- ações rápidas
|
||||
|
||||
### Sprint 8 — Qualidade e lançamento
|
||||
- testes
|
||||
- correções
|
||||
- preparação de produção
|
||||
|
||||
---
|
||||
|
||||
## Dependências entre fases
|
||||
|
||||
- inventário depende de receção;
|
||||
- venda depende de inventário;
|
||||
- envio depende de venda;
|
||||
- dashboard depende dos módulos principais já estarem implementados;
|
||||
- automações dependem da estabilidade do MVP.
|
||||
|
||||
---
|
||||
|
||||
## Riscos principais
|
||||
|
||||
### 1. Começar a desenvolver cedo demais
|
||||
Sem estados e regras fechadas, o risco de retrabalho é elevado.
|
||||
|
||||
### 2. Complicar demasiado a V1
|
||||
A V1 deve focar-se em controlo operacional simples e eficaz.
|
||||
|
||||
### 3. UX lenta ou demasiado pesada
|
||||
Se as operações do dia a dia exigirem muitos passos, a aplicação perde valor.
|
||||
|
||||
### 4. Falta de disciplina documental
|
||||
Se `DECISIONS_LOG`, `PROGRESS` e `AGENT_HANDOFF` não forem atualizados, os agentes vão divergir.
|
||||
|
||||
---
|
||||
|
||||
## Instruções para o agente
|
||||
|
||||
Ao usar este roadmap:
|
||||
1. Ler primeiro a documentação base do projeto.
|
||||
2. Trabalhar apenas na fase atual ou na subfase indicada.
|
||||
3. Não saltar dependências.
|
||||
4. Não introduzir funcionalidades fora do MVP sem sinalização explícita.
|
||||
5. No final de cada entrega relevante:
|
||||
- atualizar `16_DECISIONS_LOG.md`;
|
||||
- atualizar `17_PROGRESS.md`;
|
||||
- atualizar `18_AGENT_HANDOFF.md`.
|
||||
|
||||
---
|
||||
|
||||
## Estado atual esperado
|
||||
Este documento assume que o projeto está entre a fase de consolidação funcional e a fase de preparação técnica.
|
||||
|
||||
O próximo passo recomendado é confirmar que os documentos de domínio, estados, MVP e regras de dados estão suficientemente sólidos para iniciar a fundação técnica do projeto.
|
||||
24
docs/12_UI_UX_PRINCIPLES.md
Normal file
24
docs/12_UI_UX_PRINCIPLES.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# UI/UX Principles
|
||||
|
||||
## Princípios gerais
|
||||
- Priorizar rapidez operacional
|
||||
- Mostrar sempre o estado atual de forma clara
|
||||
- Reduzir o número de cliques
|
||||
- Evitar ecrãs demasiado densos
|
||||
|
||||
## Dashboard
|
||||
- O dashboard deve ser orientado a tarefas
|
||||
- Deve destacar pendentes, faltas, vendas por enviar e stock por estado
|
||||
|
||||
## Formulários
|
||||
- Devem ser curtos e diretos
|
||||
- Devem evitar campos desnecessários
|
||||
- Devem validar rapidamente erros óbvios
|
||||
|
||||
## Listagens
|
||||
- Devem permitir filtros rápidos
|
||||
- Devem ter estados visuais claros
|
||||
- Devem facilitar ações em contexto
|
||||
|
||||
## Experiência desejada
|
||||
A app deve parecer uma ferramenta de trabalho diária e não um ERP pesado.
|
||||
16
docs/13_DATA_RULES.md
Normal file
16
docs/13_DATA_RULES.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# Data Rules
|
||||
|
||||
## Regras de integridade
|
||||
- Uma receção não deve ultrapassar a quantidade encomendada sem sinalização
|
||||
- Uma encomenda parcialmente recebida mantém-se aberta
|
||||
- Um artigo vendido não pode aparecer como disponível
|
||||
- Uma venda deve estar associada a um artigo ou unidade concreta
|
||||
- Um envio deve estar associado a uma venda
|
||||
|
||||
## Regras de rastreabilidade
|
||||
- Transições relevantes de estado devem ser registadas
|
||||
- Alterações críticas devem deixar histórico
|
||||
|
||||
## Regras de consistência
|
||||
- O stock disponível deve refletir apenas artigos aptos para venda
|
||||
- O sistema deve distinguir stock físico de stock vendável
|
||||
16
docs/14_AUTOMATION_OPPORTUNITIES.md
Normal file
16
docs/14_AUTOMATION_OPPORTUNITIES.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# Automation Opportunities
|
||||
|
||||
## Curto prazo
|
||||
- Alertas de encomendas parcialmente recebidas
|
||||
- Lista automática de vendas por enviar
|
||||
- Dashboard com tarefas pendentes do dia
|
||||
|
||||
## Médio prazo
|
||||
- Sugestão automática do que falta receber por encomenda
|
||||
- Sinalização de discrepâncias recorrentes por fornecedor
|
||||
- Fluxo guiado de preparação de artigos
|
||||
|
||||
## Longo prazo
|
||||
- Possível integração ou importação de dados de plataformas de venda
|
||||
- Regras automáticas de priorização operacional
|
||||
- Apoio por IA para deteção de anomalias no processo
|
||||
16
docs/15_OPEN_QUESTIONS.md
Normal file
16
docs/15_OPEN_QUESTIONS.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# Open Questions
|
||||
|
||||
## Produto e operação
|
||||
- O inventário será gerido por unidade individual em todos os cenários ou haverá stock agregado nalguns casos?
|
||||
- Será necessário guardar custo por artigo?
|
||||
- Será necessário guardar preço de venda e margem?
|
||||
- A app será usada por um único utilizador ou poderá haver mais utilizadores?
|
||||
- Haverá necessidade de anexar fotografias dentro da app?
|
||||
- O anúncio Vinted ficará apenas como referência manual ou haverá integração futura?
|
||||
- Será necessário controlar devoluções numa fase seguinte?
|
||||
|
||||
## Técnica e implementação
|
||||
- As imagens devem ser guardadas logo no Supabase Storage ou adiadas para uma fase posterior?
|
||||
- O primeiro deploy será feito em Vercel + Supabase ou noutro ambiente?
|
||||
- Haverá necessidade de ambientes distintos de dev, staging e produção logo no início?
|
||||
- Será necessário seed inicial com dados reais ou dados fictícios?
|
||||
133
docs/16_DECISIONS_LOG.md
Normal file
133
docs/16_DECISIONS_LOG.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Decisions Log
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Posicionar a solução como app de gestão operacional de revenda de roupa e não apenas como app de inventário.
|
||||
|
||||
### Motivo
|
||||
O principal valor está no controlo do fluxo completo: encomenda, receção, registo, preparação, venda e envio.
|
||||
|
||||
### Impacto
|
||||
A arquitetura funcional será orientada a estados e workflows operacionais.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Excluir integração automática com Vinted da V1.
|
||||
|
||||
### Motivo
|
||||
A prioridade é resolver as dores operacionais principais sem aumentar complexidade técnica inicial.
|
||||
|
||||
### Impacto
|
||||
As vendas serão registadas manualmente na primeira versão.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Documentar o projeto em múltiplos ficheiros Markdown curtos e temáticos.
|
||||
|
||||
### Motivo
|
||||
Facilitar continuidade entre sessões e colaboração com agentes de IA.
|
||||
|
||||
### Impacto
|
||||
A documentação passa a ser a fonte de verdade do projeto.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Adotar uma stack full-stack baseada em Next.js 16, TypeScript, PostgreSQL, Prisma ORM, Supabase, Tailwind CSS, shadcn/ui, React Hook Form e Zod.
|
||||
|
||||
### Motivo
|
||||
Esta combinação maximiza velocidade de desenvolvimento, simplicidade arquitetural, boa compatibilidade com agentes de IA e capacidade de crescimento sem infraestrutura excessiva.
|
||||
|
||||
### Impacto
|
||||
O MVP será desenvolvido numa única codebase full-stack com frontend e backend no mesmo projeto.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Não criar backend separado na V1.
|
||||
|
||||
### Motivo
|
||||
A operação inicial não justifica microserviços nem uma API separada. O foco é reduzir complexidade e acelerar entrega.
|
||||
|
||||
### Impacto
|
||||
As rotas, ações no servidor, serviços e acesso à base de dados ficam dentro do projeto Next.js.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Usar PostgreSQL como base de dados principal e Prisma ORM como camada de acesso aos dados.
|
||||
|
||||
### Motivo
|
||||
É uma combinação robusta, legível, type-safe e adequada ao domínio operacional da aplicação.
|
||||
|
||||
### Impacto
|
||||
O schema do domínio será modelado em Prisma e evoluído por migrations.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Implementar rastreabilidade por unidade de inventário em vez de stock agregado.
|
||||
|
||||
### Motivo
|
||||
A documentação do domínio especifica que a V1 deve favorecer rastreabilidade por unidade sempre que possível para dar visibilidade operacional completa.
|
||||
|
||||
### Impacto
|
||||
O schema Prisma foi modelado com InventoryUnit como entidade principal, permitindo rastrear cada artigo individualmente desde a receção até à venda.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Criar DOC_INDEX.md como registo centralizado da documentação do projeto.
|
||||
|
||||
### Motivo
|
||||
Facilitar a navegação e continuidade entre sessões de desenvolvimento com agentes de IA, garantindo que todos os documentos nucleares são facilmente encontráveis.
|
||||
|
||||
### Impacto
|
||||
O projeto tem agora um índice completo com 27 ficheiros documentais, todos classificados por status e função.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Modelar todos os estados definidos na documentação como enums no schema Prisma.
|
||||
|
||||
### Motivo
|
||||
Garantir consistência entre a documentação de estados e a implementação técnica, evitando ambiguidades nos ciclos de vida das entidades.
|
||||
|
||||
### Impacto
|
||||
Os enums PurchaseOrderStatus, ReceiptStatus, InventoryStatus, ListingStatus, SaleStatus e ShipmentStatus foram implementados exatamente conforme definido em `09_STATES_AND_LIFECYCLES.md`.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Corrigir problemas de integridade relacional no schema Prisma.
|
||||
|
||||
### Motivo
|
||||
Validação do schema revelou relações em falta e inconsistências que poderiam causar problemas de integridade de dados.
|
||||
|
||||
### Impacto
|
||||
- Adicionada relação User.createdReceipts para Receipt.created_by
|
||||
- Corrigida relação StatusHistory com índices para performance
|
||||
- Mantida integridade referencial em todas as relações
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-21
|
||||
### Decisão
|
||||
Criar estrutura completa do projeto Next.js com stack aprovada.
|
||||
|
||||
### Motivo
|
||||
Estabelecer base técnica sólida para desenvolvimento do MVP seguindo exatamente a stack definida na documentação.
|
||||
|
||||
### Impacto
|
||||
Projeto configurado com Next.js 16, TypeScript, Tailwind CSS, Prisma, estrutura de pastas conforme `20_PROJECT_STRUCTURE.md`, pronto para instalação de dependências e início de desenvolvimento.
|
||||
57
docs/17_PROGRESS.md
Normal file
57
docs/17_PROGRESS.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Progress
|
||||
|
||||
## Estado atual
|
||||
Fase de scaffolding técnico concluída. Schema Prisma validado e estrutura base do projeto criada com stack aprovada.
|
||||
|
||||
## Já concluído
|
||||
- Reflexão inicial sobre o problema
|
||||
- Definição do posicionamento da app como sistema operacional
|
||||
- Definição da estrutura documental base
|
||||
- Criação da primeira versão dos ficheiros nucleares
|
||||
- Seleção da stack tecnológica principal
|
||||
- Decisão de manter arquitetura full-stack numa única codebase
|
||||
- Criação do DOC_INDEX.md com registo completo da documentação
|
||||
- Análise completa da documentação existente
|
||||
- Criação do schema Prisma inicial baseado no modelo de domínio
|
||||
- Validação e correção do schema Prisma contra documentação
|
||||
- Criação da estrutura completa do projeto Next.js
|
||||
- Configuração de package.json com todas as dependências necessárias
|
||||
- Criação de ficheiros de configuração (next.config.js, tsconfig.json, tailwind.config.ts)
|
||||
- Configuração de ambiente (.env.example)
|
||||
- Estrutura de pastas conforme documentação técnica
|
||||
- Ficheiros base da aplicação (layout, page, globals.css)
|
||||
- Configuração inicial do cliente Prisma
|
||||
|
||||
## Em curso
|
||||
- Preparação para instalação de dependências
|
||||
- Validação final da estrutura técnica
|
||||
|
||||
## Próximos passos
|
||||
1. Instalar dependências do projeto
|
||||
2. Configurar ambiente Supabase
|
||||
3. Implementar primeira migration Prisma
|
||||
4. Testar configuração base da aplicação
|
||||
5. Iniciar desenvolvimento das funcionalidades do MVP
|
||||
|
||||
## Bloqueios
|
||||
- Dependências precisam de ser instaladas para resolver erros TypeScript
|
||||
- Ambiente Supabase precisa de configuração
|
||||
- Ainda não está decidida a modelação futura de integração com plataformas
|
||||
- Ainda não está decidido o fluxo exato de imagens e storage
|
||||
|
||||
## Ficheiros criados/alterados nesta iteração
|
||||
- `/prisma/schema.prisma` (corrigido e validado)
|
||||
- `/package.json` (criado)
|
||||
- `/next.config.js` (criado)
|
||||
- `/tsconfig.json` (criado)
|
||||
- `/tailwind.config.ts` (criado)
|
||||
- `/.env.example` (criado)
|
||||
- `/src/app/layout.tsx` (criado)
|
||||
- `/src/app/page.tsx` (criado)
|
||||
- `/src/app/globals.css` (criado)
|
||||
- `/src/server/db/client.ts` (criado)
|
||||
- Estrutura completa de pastas em `/src/` (criada)
|
||||
- `/docs/16_DECISIONS_LOG.md` (atualizado)
|
||||
|
||||
## Última atualização
|
||||
2026-04-21 - Schema Prisma validado, estrutura técnica completa criada, projeto pronto para instalação de dependências e início de desenvolvimento do MVP.
|
||||
91
docs/18_AGENT_HANDOFF.md
Normal file
91
docs/18_AGENT_HANDOFF.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# Agent Handoff
|
||||
|
||||
## Ler primeiro
|
||||
Antes de produzir qualquer código ou proposta, ler obrigatoriamente:
|
||||
1. `00_PROJECT_BRIEF.md`
|
||||
2. `03_PROBLEM_STATEMENT.md`
|
||||
3. `04_PRODUCT_GOALS.md`
|
||||
4. `05_USER_WORKFLOWS.md`
|
||||
5. `08_DOMAIN_MODEL.md`
|
||||
6. `09_STATES_AND_LIFECYCLES.md`
|
||||
7. `10_MVP_DEFINITION.md`
|
||||
8. `16_DECISIONS_LOG.md`
|
||||
9. `17_PROGRESS.md`
|
||||
10. `19_TECH_STACK.md`
|
||||
11. `20_PROJECT_STRUCTURE.md`
|
||||
12. `21_ENGINEERING_GUIDELINES.md`
|
||||
13. `DOC_INDEX.md` (índice completo da documentação)
|
||||
|
||||
## Fonte de verdade
|
||||
As decisões do projeto estão documentadas em:
|
||||
- `16_DECISIONS_LOG.md`
|
||||
- `10_MVP_DEFINITION.md`
|
||||
- `09_STATES_AND_LIFECYCLES.md`
|
||||
- `19_TECH_STACK.md`
|
||||
- `20_PROJECT_STRUCTURE.md`
|
||||
- `prisma/schema.prisma` (schema inicial criado)
|
||||
|
||||
## Regras para o agente
|
||||
- Não inventar funcionalidades fora do MVP sem sinalização explícita
|
||||
- Não alterar estados do sistema sem registo em `16_DECISIONS_LOG.md`
|
||||
- Não introduzir complexidade desnecessária
|
||||
- Priorizar rapidez operacional e simplicidade de uso
|
||||
- Respeitar a stack escolhida
|
||||
- Não propor backend separado, microserviços ou GraphQL para a V1
|
||||
- Manter separação entre UI, validação, serviços e acesso a dados
|
||||
|
||||
## Objetivo da última iteração
|
||||
Validar tecnicamente o schema.prisma contra a documentação e preparar a base real do projeto para desenvolvimento.
|
||||
|
||||
## O que foi feito
|
||||
- Validado schema Prisma contra documentação completa (domínio, estados, MVP, regras de dados)
|
||||
- Corrigidos problemas de integridade relacional no schema (relação User.createdReceipts, índices StatusHistory)
|
||||
- Criada estrutura completa do projeto Next.js com stack aprovada
|
||||
- Configurado package.json com todas as dependências necessárias
|
||||
- Criados ficheiros de configuração (next.config.js, tsconfig.json, tailwind.config.ts)
|
||||
- Configurado ambiente (.env.example)
|
||||
- Criada estrutura de pastas conforme `20_PROJECT_STRUCTURE.md`
|
||||
- Implementados ficheiros base da aplicação (layout, page, globals.css)
|
||||
- Configurado cliente Prisma inicial
|
||||
|
||||
## Ficheiros alterados nesta iteração
|
||||
- `/prisma/schema.prisma` (validado e corrigido)
|
||||
- `/package.json` (criado)
|
||||
- `/next.config.js` (criado)
|
||||
- `/tsconfig.json` (criado)
|
||||
- `/tailwind.config.ts` (criado)
|
||||
- `/.env.example` (criado)
|
||||
- `/src/app/layout.tsx` (criado)
|
||||
- `/src/app/page.tsx` (criado)
|
||||
- `/src/app/globals.css` (criado)
|
||||
- `/src/server/db/client.ts` (criado)
|
||||
- Estrutura completa de pastas em `/src/` (criada)
|
||||
- `/docs/16_DECISIONS_LOG.md` (atualizado)
|
||||
- `/docs/17_PROGRESS.md` (atualizado)
|
||||
|
||||
## Decisões tomadas
|
||||
- Schema Prisma validado e corrigido para garantir integridade relacional
|
||||
- Estrutura técnica criada seguindo exatamente a stack e convenções definidas
|
||||
- Mantida abordagem de rastreabilidade por unidade conforme documentação
|
||||
- Configurado projeto para desenvolvimento com Next.js 16, TypeScript, Tailwind CSS
|
||||
|
||||
## Limitações e dúvidas
|
||||
- Dependências precisam de ser instaladas para resolver erros TypeScript
|
||||
- Ambiente Supabase precisa de configuração
|
||||
- Fluxo de imagens e storage ainda não definido
|
||||
- Modelação futura de integração com plataformas pendente
|
||||
|
||||
## Próxima missão sugerida
|
||||
Finalizar setup técnico e iniciar desenvolvimento:
|
||||
1. Instalar dependências do projeto (npm install)
|
||||
2. Configurar ambiente Supabase
|
||||
3. Implementar primeira migration Prisma
|
||||
4. Testar configuração base da aplicação
|
||||
5. Iniciar desenvolvimento da primeira feature (suppliers)
|
||||
|
||||
## Riscos e cuidados especiais
|
||||
- Instalar dependências antes de prosseguir com desenvolvimento
|
||||
- Configurar Supabase corretamente para evitar problemas de conexão
|
||||
- Manter foco no MVP definido, evitar funcionalidades fora do âmbito
|
||||
- Seguir rigorosamente a estrutura de pastas e convenções estabelecidas
|
||||
- Testar migrations Prisma antes de implementar funcionalidades
|
||||
103
docs/19_TECH_STACK.md
Normal file
103
docs/19_TECH_STACK.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Tech Stack
|
||||
|
||||
## Stack selecionada
|
||||
|
||||
### Aplicação
|
||||
- Next.js 16
|
||||
- React
|
||||
- TypeScript
|
||||
|
||||
### Estilo e UI
|
||||
- Tailwind CSS
|
||||
- shadcn/ui
|
||||
- Lucide Icons
|
||||
|
||||
### Dados e backend
|
||||
- PostgreSQL
|
||||
- Prisma ORM
|
||||
- Zod
|
||||
- React Hook Form
|
||||
|
||||
### Plataforma e serviços
|
||||
- Supabase Database
|
||||
- Supabase Auth
|
||||
- Supabase Storage
|
||||
|
||||
### Deploy recomendado
|
||||
- Vercel para a aplicação web
|
||||
- Supabase para base de dados, autenticação e ficheiros
|
||||
|
||||
## Justificação da stack
|
||||
A stack foi escolhida para maximizar:
|
||||
- rapidez de desenvolvimento
|
||||
- simplicidade arquitetural
|
||||
- boa legibilidade para agentes de IA
|
||||
- facilidade de manutenção
|
||||
- boa experiência para construir dashboards, formulários, listagens e workflows operacionais
|
||||
|
||||
## Princípios da arquitetura técnica
|
||||
- Uma única codebase full-stack
|
||||
- Frontend e backend no mesmo projeto
|
||||
- Regras de negócio isoladas da camada visual
|
||||
- Base de dados relacional como fonte de verdade
|
||||
- Validação partilhada e explícita
|
||||
- Preparação para crescer sem reescrever a base
|
||||
|
||||
## Decisões associadas
|
||||
- Não usar backend separado na V1
|
||||
- Não usar microserviços na V1
|
||||
- Não usar GraphQL na V1
|
||||
- Não desenvolver app mobile nativa na V1
|
||||
|
||||
## Componentes por responsabilidade
|
||||
|
||||
### Next.js
|
||||
Responsável por:
|
||||
- interface da aplicação
|
||||
- routing
|
||||
- páginas
|
||||
- server components
|
||||
- route handlers
|
||||
- server actions, quando fizer sentido
|
||||
|
||||
### Prisma
|
||||
Responsável por:
|
||||
- schema de dados
|
||||
- migrations
|
||||
- acesso type-safe à base de dados
|
||||
|
||||
### PostgreSQL
|
||||
Responsável por:
|
||||
- persistência principal
|
||||
- integridade relacional
|
||||
- consultas operacionais e relatórios simples
|
||||
|
||||
### Supabase
|
||||
Responsável por:
|
||||
- alojamento da base de dados PostgreSQL
|
||||
- autenticação base
|
||||
- storage para ficheiros e imagens, quando ativado
|
||||
|
||||
### Tailwind + shadcn/ui
|
||||
Responsáveis por:
|
||||
- consistência visual
|
||||
- rapidez na criação de UI
|
||||
- componentes reutilizáveis
|
||||
|
||||
### Zod + React Hook Form
|
||||
Responsáveis por:
|
||||
- validação
|
||||
- formulários previsíveis
|
||||
- redução de erros de input
|
||||
|
||||
## Dependências candidatas adicionais
|
||||
- TanStack Table para tabelas operacionais
|
||||
- date-fns para datas
|
||||
- clsx / tailwind-merge para composição de classes
|
||||
|
||||
## Itens adiados
|
||||
- filas assíncronas
|
||||
- Redis
|
||||
- serviços de eventos
|
||||
- arquitetura multi-tenant
|
||||
- monitorização avançada
|
||||
162
docs/20_PROJECT_STRUCTURE.md
Normal file
162
docs/20_PROJECT_STRUCTURE.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Project Structure
|
||||
|
||||
## Objetivo
|
||||
Definir uma estrutura de projeto clara, previsível e adequada a desenvolvimento assistido por agentes de IA.
|
||||
|
||||
## Estrutura de alto nível
|
||||
|
||||
```text
|
||||
app/
|
||||
components/
|
||||
features/
|
||||
lib/
|
||||
server/
|
||||
prisma/
|
||||
docs/
|
||||
public/
|
||||
```
|
||||
|
||||
## Estrutura recomendada detalhada
|
||||
|
||||
```text
|
||||
src/
|
||||
app/
|
||||
(dashboard)/
|
||||
api/
|
||||
login/
|
||||
layout.tsx
|
||||
page.tsx
|
||||
|
||||
components/
|
||||
ui/
|
||||
shared/
|
||||
layout/
|
||||
tables/
|
||||
forms/
|
||||
status/
|
||||
|
||||
features/
|
||||
suppliers/
|
||||
components/
|
||||
actions/
|
||||
schemas/
|
||||
utils/
|
||||
purchase-orders/
|
||||
components/
|
||||
actions/
|
||||
schemas/
|
||||
utils/
|
||||
receipts/
|
||||
components/
|
||||
actions/
|
||||
schemas/
|
||||
utils/
|
||||
inventory/
|
||||
components/
|
||||
actions/
|
||||
schemas/
|
||||
utils/
|
||||
listings/
|
||||
components/
|
||||
actions/
|
||||
schemas/
|
||||
utils/
|
||||
sales/
|
||||
components/
|
||||
actions/
|
||||
schemas/
|
||||
utils/
|
||||
shipments/
|
||||
components/
|
||||
actions/
|
||||
schemas/
|
||||
utils/
|
||||
dashboard/
|
||||
components/
|
||||
queries/
|
||||
utils/
|
||||
|
||||
lib/
|
||||
auth/
|
||||
utils/
|
||||
constants/
|
||||
validators/
|
||||
|
||||
server/
|
||||
db/
|
||||
client.ts
|
||||
repositories/
|
||||
services/
|
||||
queries/
|
||||
permissions/
|
||||
audit/
|
||||
|
||||
prisma/
|
||||
schema.prisma
|
||||
migrations/
|
||||
seeds/
|
||||
|
||||
docs/
|
||||
*.md
|
||||
|
||||
public/
|
||||
images/
|
||||
icons/
|
||||
```
|
||||
|
||||
## Regras de organização
|
||||
- `app/` contém rotas, layouts e entry points do Next.js
|
||||
- `components/` contém componentes reutilizáveis sem lógica de negócio forte
|
||||
- `features/` organiza a aplicação por domínio funcional
|
||||
- `server/` concentra lógica do lado do servidor
|
||||
- `prisma/` concentra schema, migrations e seeds
|
||||
- `docs/` contém a documentação do projeto
|
||||
|
||||
## Padrão por feature
|
||||
Cada feature deve, idealmente, conter:
|
||||
- `components/`
|
||||
- `actions/`
|
||||
- `schemas/`
|
||||
- `utils/`
|
||||
|
||||
Opcionalmente:
|
||||
- `queries/`
|
||||
- `types/`
|
||||
- `tests/`
|
||||
|
||||
## Separação recomendada de responsabilidades
|
||||
|
||||
### UI
|
||||
Componentes visuais, tabelas, formulários, badges, cards, filtros.
|
||||
|
||||
### Actions / handlers
|
||||
Entradas da aplicação para mutações e operações ligadas ao utilizador.
|
||||
|
||||
### Schemas
|
||||
Validação com Zod.
|
||||
|
||||
### Services
|
||||
Regras de negócio e fluxos operacionais.
|
||||
|
||||
### Repositories
|
||||
Acesso aos dados e queries Prisma.
|
||||
|
||||
### Queries
|
||||
Leituras complexas e agregações para dashboard e listagens.
|
||||
|
||||
## Convenções de naming
|
||||
- kebab-case para nomes de pastas de features
|
||||
- PascalCase para componentes React
|
||||
- camelCase para funções e variáveis
|
||||
- nomes explícitos e orientados ao domínio
|
||||
- evitar abreviações ambíguas
|
||||
|
||||
## Estrutura inicial mínima da V1
|
||||
- auth
|
||||
- suppliers
|
||||
- purchase-orders
|
||||
- receipts
|
||||
- inventory
|
||||
- sales
|
||||
- shipments
|
||||
- dashboard
|
||||
66
docs/21_ENGINEERING_GUIDELINES.md
Normal file
66
docs/21_ENGINEERING_GUIDELINES.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# Engineering Guidelines
|
||||
|
||||
## Objetivo
|
||||
Garantir consistência técnica no desenvolvimento com agentes de IA e reduzir deriva arquitetural entre sessões.
|
||||
|
||||
## Regras gerais
|
||||
- Usar TypeScript em todo o projeto
|
||||
- Preferir server-side validation para mutações críticas
|
||||
- Manter regras de negócio fora dos componentes visuais
|
||||
- Manter o domínio explícito e nomeado
|
||||
- Evitar abstrações prematuras
|
||||
|
||||
## Backend dentro do Next.js
|
||||
Na V1, o backend deve viver dentro do projeto Next.js.
|
||||
|
||||
Usar:
|
||||
- Route Handlers quando for necessário expor endpoints
|
||||
- Server Actions quando fizer sentido para mutações simples ligadas à UI
|
||||
- camada `server/services` para regras de negócio
|
||||
- camada `server/repositories` para acesso aos dados
|
||||
|
||||
## Prisma
|
||||
- Modelar entidades do domínio com nomes claros
|
||||
- Usar migrations versionadas
|
||||
- Evitar queries complexas diretamente em componentes
|
||||
- Centralizar acesso à base de dados em repositórios ou queries server-side
|
||||
|
||||
## Validação
|
||||
- Usar Zod para validar inputs e payloads
|
||||
- Reutilizar schemas entre UI e servidor quando fizer sentido
|
||||
- Nunca confiar apenas na validação do cliente
|
||||
|
||||
## UI
|
||||
- Usar Tailwind CSS
|
||||
- Usar shadcn/ui como base de componentes
|
||||
- Criar componentes reutilizáveis para estados, tabelas, filtros e formulários
|
||||
- Priorizar rapidez operacional sobre efeitos visuais
|
||||
|
||||
## Estado e dados
|
||||
- Preferir dados carregados no servidor
|
||||
- Evitar estado global desnecessário na V1
|
||||
- Só introduzir state management adicional se surgir necessidade clara
|
||||
|
||||
## Segurança
|
||||
- Usar Supabase Auth para autenticação base
|
||||
- Proteger rotas privadas
|
||||
- Gerir segredos por `.env`
|
||||
- Não expor chaves sensíveis no cliente
|
||||
|
||||
## Storage
|
||||
- Usar Supabase Storage apenas quando a funcionalidade de imagens/anexos estiver confirmada
|
||||
- Definir políticas mínimas de acesso antes de ativar uploads reais
|
||||
|
||||
## Qualidade de código
|
||||
- Cada feature deve ser desenvolvida com documentação mínima
|
||||
- Atualizar `16_DECISIONS_LOG.md` quando houver decisões relevantes
|
||||
- Atualizar `17_PROGRESS.md` no fim de marcos importantes
|
||||
- Atualizar `18_AGENT_HANDOFF.md` no fim de cada sessão relevante
|
||||
|
||||
## O que evitar
|
||||
- microserviços
|
||||
- backend separado na V1
|
||||
- GraphQL
|
||||
- lógica de negócio espalhada por componentes
|
||||
- modelos demasiado genéricos
|
||||
- dependências pesadas sem necessidade clara
|
||||
64
docs/DOC_INDEX.md
Normal file
64
docs/DOC_INDEX.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# Documentation Index
|
||||
|
||||
## Core Project Documentation
|
||||
|
||||
| File | Path | Purpose | Status |
|
||||
|------|------|---------|---------|
|
||||
| Project Brief | `00_PROJECT_BRIEF.md` | High-level project overview | **Active** |
|
||||
| Vision and Scope | `01_VISION_AND_SCOPE.md` | Product vision and boundaries | **Active** |
|
||||
| Business Context | `02_BUSINESS_CONTEXT.md` | Business environment and constraints | **Active** |
|
||||
| Problem Statement | `03_PROBLEM_STATEMENT.md` | Core problem being solved | **Active** |
|
||||
| Product Goals | `04_PRODUCT_GOALS.md` | Success criteria and objectives | **Active** |
|
||||
| User Workflows | `05_USER_WORKFLOWS.md` | User journey and interactions | **Active** |
|
||||
| Functional Requirements | `06_FUNCTIONAL_REQUIREMENTS.md` | System functionality specifications | **Active** |
|
||||
| Non-Functional Requirements | `07_NON_FUNCTIONAL_REQUIREMENTS.md` | Performance, security, etc. | **Active** |
|
||||
| Domain Model | `08_DOMAIN_MODEL.md` | Core entities and relationships | **Active** |
|
||||
| States and Lifecycles | `09_STATES_AND_LIFECYCLES.md` | System states and transitions | **Active** |
|
||||
| MVP Definition | `10_MVP_DEFINITION.md` | Minimum viable product scope | **Active** |
|
||||
| Roadmap | `11_ROADMAP.md` | Development timeline and phases | **Active** |
|
||||
| UI/UX Principles | `12_UI_UX_PRINCIPLES.md` | Design guidelines and principles | **Active** |
|
||||
| Data Rules | `13_DATA_RULES.md` | Data validation and constraints | **Active** |
|
||||
| Automation Opportunities | `14_AUTOMATION_OPPORTUNITIES.md` | Potential automation areas | **Active** |
|
||||
| Open Questions | `15_OPEN_QUESTIONS.md` | Unresolved issues and decisions | **Active** |
|
||||
| Decisions Log | `16_DECISIONS_LOG.md` | Historical decisions and rationale | **Active** |
|
||||
| Progress | `17_PROGRESS.md` | Current project status and achievements | **Active** |
|
||||
| Agent Handoff | `18_AGENT_HANDOFF.md` | Session handoff information | **Active** |
|
||||
| Tech Stack | `19_TECH_STACK.md` | Technology choices and architecture | **Active** |
|
||||
| Project Structure | `20_PROJECT_STRUCTURE.md` | Code organization and layout | **Active** |
|
||||
| Engineering Guidelines | `21_ENGINEERING_GUIDELINES.md` | Development standards and practices | **Active** |
|
||||
|
||||
## Agent Prompts
|
||||
|
||||
| File | Path | Purpose | Status |
|
||||
|------|------|---------|---------|
|
||||
| Master Prompt | `prompts/master_prompt.md` | Primary agent instructions | **Active** |
|
||||
| Backend Prompt | `prompts/prompt_backend.md` | Backend development guidelines | **Active** |
|
||||
| Database Prompt | `prompts/prompt_database.md` | Database development guidelines | **Active** |
|
||||
| Frontend Prompt | `prompts/prompt_frontend.md` | Frontend development guidelines | **Active** |
|
||||
| Testing Prompt | `prompts/prompt_testing.md` | Testing strategy and guidelines | **Active** |
|
||||
|
||||
## Required Reading Before Implementation
|
||||
|
||||
The following files are **mandatory** reading before any implementation:
|
||||
|
||||
1. `00_PROJECT_BRIEF.md`
|
||||
2. `01_VISION_AND_SCOPE.md`
|
||||
3. `03_PROBLEM_STATEMENT.md`
|
||||
4. `04_PRODUCT_GOALS.md`
|
||||
5. `05_USER_WORKFLOWS.md`
|
||||
6. `08_DOMAIN_MODEL.md`
|
||||
7. `09_STATES_AND_LIFECYCLES.md`
|
||||
8. `10_MVP_DEFINITION.md`
|
||||
9. `11_ROADMAP.md`
|
||||
10. `13_DATA_RULES.md`
|
||||
11. `16_DECISIONS_LOG.md`
|
||||
12. `17_PROGRESS.md`
|
||||
13. `18_AGENT_HANDOFF.md`
|
||||
14. `19_TECH_STACK.md`
|
||||
15. `20_PROJECT_STRUCTURE.md`
|
||||
16. `21_ENGINEERING_GUIDELINES.md`
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-06-17*
|
||||
*Total documentation files: 27*
|
||||
51
docs/prompts/master_prompt.md
Normal file
51
docs/prompts/master_prompt.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Master Prompt
|
||||
|
||||
És um agente de desenvolvimento a trabalhar numa aplicação de gestão operacional para revenda de roupa.
|
||||
|
||||
## Objetivo do produto
|
||||
Construir uma aplicação web para gerir:
|
||||
- encomendas ao fornecedor
|
||||
- receção de mercadoria
|
||||
- inventário por estado
|
||||
- preparação para venda
|
||||
- registo manual de vendas
|
||||
- envios pendentes
|
||||
|
||||
## Stack obrigatória
|
||||
- Next.js 16
|
||||
- TypeScript
|
||||
- PostgreSQL
|
||||
- Prisma ORM
|
||||
- Supabase Auth / Database / Storage
|
||||
- Tailwind CSS
|
||||
- shadcn/ui
|
||||
- React Hook Form
|
||||
- Zod
|
||||
|
||||
## Restrições
|
||||
- Não criar backend separado
|
||||
- Não usar microserviços
|
||||
- Não introduzir GraphQL
|
||||
- Não sair do MVP sem sinalização explícita
|
||||
- Priorizar rapidez operacional e simplicidade de uso
|
||||
|
||||
## Documentos fonte de verdade
|
||||
Ler antes de agir:
|
||||
1. `00_PROJECT_BRIEF.md`
|
||||
2. `05_USER_WORKFLOWS.md`
|
||||
3. `08_DOMAIN_MODEL.md`
|
||||
4. `09_STATES_AND_LIFECYCLES.md`
|
||||
5. `10_MVP_DEFINITION.md`
|
||||
6. `16_DECISIONS_LOG.md`
|
||||
7. `17_PROGRESS.md`
|
||||
8. `18_AGENT_HANDOFF.md`
|
||||
9. `19_TECH_STACK.md`
|
||||
10. `20_PROJECT_STRUCTURE.md`
|
||||
11. `21_ENGINEERING_GUIDELINES.md`
|
||||
|
||||
## Forma de trabalhar
|
||||
- Explica o que vais alterar
|
||||
- Faz alterações pequenas e consistentes
|
||||
- Mantém naming claro e orientado ao domínio
|
||||
- Não inventes requisitos
|
||||
- Atualiza documentação relevante quando necessário
|
||||
19
docs/prompts/prompt_backend.md
Normal file
19
docs/prompts/prompt_backend.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Prompt Backend
|
||||
|
||||
Usa a documentação do projeto como fonte de verdade. O backend deve refletir fielmente:
|
||||
- workflows operacionais
|
||||
- estados definidos
|
||||
- regras de dados
|
||||
- âmbito do MVP
|
||||
|
||||
Prioridades:
|
||||
1. integridade dos estados
|
||||
2. simplicidade do modelo
|
||||
3. rastreabilidade mínima
|
||||
4. API clara para frontend operacional
|
||||
|
||||
Evitar:
|
||||
- abstrações excessivas
|
||||
- microserviços
|
||||
- complexidade desnecessária
|
||||
- funcionalidades fora do MVP
|
||||
13
docs/prompts/prompt_database.md
Normal file
13
docs/prompts/prompt_database.md
Normal file
@@ -0,0 +1,13 @@
|
||||
# Prompt Database
|
||||
|
||||
Modela a base de dados de acordo com:
|
||||
- `08_DOMAIN_MODEL.md`
|
||||
- `09_STATES_AND_LIFECYCLES.md`
|
||||
- `13_DATA_RULES.md`
|
||||
- `10_MVP_DEFINITION.md`
|
||||
|
||||
Prioridades:
|
||||
- integridade referencial
|
||||
- consistência entre encomendas, receções, inventário, vendas e envios
|
||||
- suporte a histórico mínimo de estados
|
||||
- modelo simples e sustentável para MVP
|
||||
15
docs/prompts/prompt_frontend.md
Normal file
15
docs/prompts/prompt_frontend.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Prompt Frontend
|
||||
|
||||
Usa a documentação do projeto como fonte de verdade. O frontend deve ser extremamente simples, rápido e orientado a tarefas.
|
||||
|
||||
Prioridades:
|
||||
1. dashboard claro
|
||||
2. fluxos operacionais com poucos cliques
|
||||
3. estados visuais evidentes
|
||||
4. formulários curtos
|
||||
5. filtros rápidos
|
||||
|
||||
Evitar:
|
||||
- interfaces demasiado densas
|
||||
- navegação complexa
|
||||
- elementos decorativos sem valor operacional
|
||||
16
docs/prompts/prompt_testing.md
Normal file
16
docs/prompts/prompt_testing.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# Prompt Testing
|
||||
|
||||
Cria testes com base nos workflows e regras do projeto.
|
||||
|
||||
Prioridades:
|
||||
- receção parcial de encomendas
|
||||
- controlo de stock por estado
|
||||
- prevenção de dupla disponibilidade
|
||||
- transições de estado válidas
|
||||
- vendas pendentes de envio
|
||||
- consistência entre venda e envio
|
||||
|
||||
Fonte de verdade:
|
||||
- `05_USER_WORKFLOWS.md`
|
||||
- `09_STATES_AND_LIFECYCLES.md`
|
||||
- `13_DATA_RULES.md`
|
||||
Reference in New Issue
Block a user