first commit
This commit is contained in:
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.
|
||||
Reference in New Issue
Block a user