492 lines
13 KiB
Markdown
492 lines
13 KiB
Markdown
# 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.
|