millions/docs/11_ROADMAP.md

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.