commit bd8fe915f8fd137af2c052596bbdd1095692a6f7 Author: joaomiranda Date: Tue Apr 21 10:53:35 2026 +0100 first commit diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..d8ae893 Binary files /dev/null and b/.DS_Store differ diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..8608684 --- /dev/null +++ b/.env.example @@ -0,0 +1,14 @@ +# Database +DATABASE_URL="postgresql://username:password@localhost:5432/millions" + +# Supabase +NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co" +NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key" +SUPABASE_SERVICE_ROLE_KEY="your-service-role-key" + +# Next.js +NEXTAUTH_URL="http://localhost:3000" +NEXTAUTH_SECRET="your-secret-key" + +# App Configuration +NODE_ENV="development" diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000..475c4c2 Binary files /dev/null and b/docs/.DS_Store differ diff --git a/docs/00_PROJECT_BRIEF.md b/docs/00_PROJECT_BRIEF.md new file mode 100644 index 0000000..0202aa6 --- /dev/null +++ b/docs/00_PROJECT_BRIEF.md @@ -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 diff --git a/docs/01_VISION_AND_SCOPE.md b/docs/01_VISION_AND_SCOPE.md new file mode 100644 index 0000000..1a87165 --- /dev/null +++ b/docs/01_VISION_AND_SCOPE.md @@ -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 diff --git a/docs/02_BUSINESS_CONTEXT.md b/docs/02_BUSINESS_CONTEXT.md new file mode 100644 index 0000000..8d7bb4b --- /dev/null +++ b/docs/02_BUSINESS_CONTEXT.md @@ -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. diff --git a/docs/03_PROBLEM_STATEMENT.md b/docs/03_PROBLEM_STATEMENT.md new file mode 100644 index 0000000..9c5c9af --- /dev/null +++ b/docs/03_PROBLEM_STATEMENT.md @@ -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 diff --git a/docs/04_PRODUCT_GOALS.md b/docs/04_PRODUCT_GOALS.md new file mode 100644 index 0000000..5a32e39 --- /dev/null +++ b/docs/04_PRODUCT_GOALS.md @@ -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 diff --git a/docs/05_USER_WORKFLOWS.md b/docs/05_USER_WORKFLOWS.md new file mode 100644 index 0000000..91fe7ba --- /dev/null +++ b/docs/05_USER_WORKFLOWS.md @@ -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` diff --git a/docs/06_FUNCTIONAL_REQUIREMENTS.md b/docs/06_FUNCTIONAL_REQUIREMENTS.md new file mode 100644 index 0000000..d562b70 --- /dev/null +++ b/docs/06_FUNCTIONAL_REQUIREMENTS.md @@ -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 diff --git a/docs/07_NON_FUNCTIONAL_REQUIREMENTS.md b/docs/07_NON_FUNCTIONAL_REQUIREMENTS.md new file mode 100644 index 0000000..eeb398b --- /dev/null +++ b/docs/07_NON_FUNCTIONAL_REQUIREMENTS.md @@ -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 diff --git a/docs/08_DOMAIN_MODEL.md b/docs/08_DOMAIN_MODEL.md new file mode 100644 index 0000000..f839d6f --- /dev/null +++ b/docs/08_DOMAIN_MODEL.md @@ -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 diff --git a/docs/09_STATES_AND_LIFECYCLES.md b/docs/09_STATES_AND_LIFECYCLES.md new file mode 100644 index 0000000..70d4c03 --- /dev/null +++ b/docs/09_STATES_AND_LIFECYCLES.md @@ -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 diff --git a/docs/10_MVP_DEFINITION.md b/docs/10_MVP_DEFINITION.md new file mode 100644 index 0000000..6c09fc0 --- /dev/null +++ b/docs/10_MVP_DEFINITION.md @@ -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 diff --git a/docs/11_ROADMAP.md b/docs/11_ROADMAP.md new file mode 100644 index 0000000..507c518 --- /dev/null +++ b/docs/11_ROADMAP.md @@ -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. diff --git a/docs/12_UI_UX_PRINCIPLES.md b/docs/12_UI_UX_PRINCIPLES.md new file mode 100644 index 0000000..0335fb8 --- /dev/null +++ b/docs/12_UI_UX_PRINCIPLES.md @@ -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. diff --git a/docs/13_DATA_RULES.md b/docs/13_DATA_RULES.md new file mode 100644 index 0000000..4d4d977 --- /dev/null +++ b/docs/13_DATA_RULES.md @@ -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 diff --git a/docs/14_AUTOMATION_OPPORTUNITIES.md b/docs/14_AUTOMATION_OPPORTUNITIES.md new file mode 100644 index 0000000..8432785 --- /dev/null +++ b/docs/14_AUTOMATION_OPPORTUNITIES.md @@ -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 diff --git a/docs/15_OPEN_QUESTIONS.md b/docs/15_OPEN_QUESTIONS.md new file mode 100644 index 0000000..bd6a99c --- /dev/null +++ b/docs/15_OPEN_QUESTIONS.md @@ -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? diff --git a/docs/16_DECISIONS_LOG.md b/docs/16_DECISIONS_LOG.md new file mode 100644 index 0000000..eb431ae --- /dev/null +++ b/docs/16_DECISIONS_LOG.md @@ -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. diff --git a/docs/17_PROGRESS.md b/docs/17_PROGRESS.md new file mode 100644 index 0000000..e44f083 --- /dev/null +++ b/docs/17_PROGRESS.md @@ -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. diff --git a/docs/18_AGENT_HANDOFF.md b/docs/18_AGENT_HANDOFF.md new file mode 100644 index 0000000..f402bb0 --- /dev/null +++ b/docs/18_AGENT_HANDOFF.md @@ -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 diff --git a/docs/19_TECH_STACK.md b/docs/19_TECH_STACK.md new file mode 100644 index 0000000..31cc099 --- /dev/null +++ b/docs/19_TECH_STACK.md @@ -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 diff --git a/docs/20_PROJECT_STRUCTURE.md b/docs/20_PROJECT_STRUCTURE.md new file mode 100644 index 0000000..d3df129 --- /dev/null +++ b/docs/20_PROJECT_STRUCTURE.md @@ -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 diff --git a/docs/21_ENGINEERING_GUIDELINES.md b/docs/21_ENGINEERING_GUIDELINES.md new file mode 100644 index 0000000..f1a78f4 --- /dev/null +++ b/docs/21_ENGINEERING_GUIDELINES.md @@ -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 diff --git a/docs/DOC_INDEX.md b/docs/DOC_INDEX.md new file mode 100644 index 0000000..e9fef71 --- /dev/null +++ b/docs/DOC_INDEX.md @@ -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* diff --git a/docs/prompts/master_prompt.md b/docs/prompts/master_prompt.md new file mode 100644 index 0000000..758b252 --- /dev/null +++ b/docs/prompts/master_prompt.md @@ -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 diff --git a/docs/prompts/prompt_backend.md b/docs/prompts/prompt_backend.md new file mode 100644 index 0000000..1ffbb06 --- /dev/null +++ b/docs/prompts/prompt_backend.md @@ -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 diff --git a/docs/prompts/prompt_database.md b/docs/prompts/prompt_database.md new file mode 100644 index 0000000..3c39cf4 --- /dev/null +++ b/docs/prompts/prompt_database.md @@ -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 diff --git a/docs/prompts/prompt_frontend.md b/docs/prompts/prompt_frontend.md new file mode 100644 index 0000000..9551be2 --- /dev/null +++ b/docs/prompts/prompt_frontend.md @@ -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 diff --git a/docs/prompts/prompt_testing.md b/docs/prompts/prompt_testing.md new file mode 100644 index 0000000..f321305 --- /dev/null +++ b/docs/prompts/prompt_testing.md @@ -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` diff --git a/next.config.js b/next.config.js new file mode 100644 index 0000000..c0d2aa7 --- /dev/null +++ b/next.config.js @@ -0,0 +1,17 @@ +/** @type {import('next').NextConfig} */ +const nextConfig = { + experimental: { + serverComponentsExternalPackages: ['@supabase/supabase-js'], + }, + images: { + domains: ['localhost'], + remotePatterns: [ + { + protocol: 'https', + hostname: '**.supabase.co', + }, + ], + }, +} + +module.exports = nextConfig diff --git a/package.json b/package.json new file mode 100644 index 0000000..2b437be --- /dev/null +++ b/package.json @@ -0,0 +1,51 @@ +{ + "name": "millions", + "version": "0.1.0", + "private": true, + "scripts": { + "dev": "next dev", + "build": "next build", + "start": "next start", + "lint": "next lint", + "db:generate": "prisma generate", + "db:push": "prisma db push", + "db:migrate": "prisma migrate dev", + "db:studio": "prisma studio", + "db:seed": "tsx prisma/seed.ts" + }, + "dependencies": { + "next": "16.2.4", + "react": "^18.3.1", + "react-dom": "^18.3.1", + "@prisma/client": "^6.2.1", + "prisma": "^6.2.1", + "@supabase/supabase-js": "^2.48.0", + "@supabase/auth-helpers-nextjs": "^0.10.0", + "react-hook-form": "^7.54.2", + "@hookform/resolvers": "^3.10.0", + "zod": "^3.24.1", + "clsx": "^2.1.1", + "tailwind-merge": "^2.6.0", + "class-variance-authority": "^0.7.1", + "lucide-react": "^0.468.0", + "@radix-ui/react-dialog": "^1.1.3", + "@radix-ui/react-dropdown-menu": "^2.1.3", + "@radix-ui/react-label": "^2.1.1", + "@radix-ui/react-select": "^2.1.3", + "@radix-ui/react-slot": "^1.1.1", + "@radix-ui/react-toast": "^1.2.3", + "@radix-ui/react-table": "^1.1.1", + "date-fns": "^4.1.0" + }, + "devDependencies": { + "typescript": "^5.7.2", + "@types/node": "^22.10.5", + "@types/react": "^18.3.17", + "@types/react-dom": "^18.3.5", + "postcss": "^8.5.1", + "tailwindcss": "^3.4.17", + "eslint": "^8.57.1", + "eslint-config-next": "16.2.4", + "tsx": "^4.19.2" + } +} diff --git a/prisma/schema.prisma b/prisma/schema.prisma new file mode 100644 index 0000000..0d8b103 --- /dev/null +++ b/prisma/schema.prisma @@ -0,0 +1,317 @@ +// This is your Prisma schema file, +// learn more about it in the docs: https://pris.ly/d/prisma-schema + +generator client { + provider = "prisma-client-js" +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} + +// User represents the authenticated user of the application +// In V1 there may be only one admin user, but the model allows for future growth +model User { + id String @id @default(cuid()) + email String @unique + name String? + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + + // Relations + receipts Receipt[] + createdReceipts Receipt[] @relation("ReceiptCreatedBy") + statusHistories StatusHistory[] + + @@map("users") +} + +// Supplier represents a clothing supplier +model Supplier { + id String @id @default(cuid()) + name String + contactName String? @map("contact_name") + email String? + phone String? + notes String? + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + + // Relations + purchaseOrders PurchaseOrder[] + + @@map("suppliers") +} + +// PurchaseOrder represents an order placed with a supplier +model PurchaseOrder { + id String @id @default(cuid()) + supplierId String @map("supplier_id") + externalReference String? @map("external_reference") + status PurchaseOrderStatus @default(DRAFT) + orderedAt DateTime @map("ordered_at") + expectedAt DateTime? @map("expected_at") + notes String? + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + + // Relations + supplier Supplier @relation(fields: [supplierId], references: [id], onDelete: RESTRICT) + purchaseOrderItems PurchaseOrderItem[] + receipts Receipt[] + inventoryUnits InventoryUnit[] + + @@map("purchase_orders") +} + +// PurchaseOrderItem represents a line item in a purchase order +model PurchaseOrderItem { + id String @id @default(cuid()) + purchaseOrderId String @map("purchase_order_id") + productModelId String @map("product_model_id") + variantLabel String? @map("variant_label") + size String? + color String? + skuSupplier String? @map("sku_supplier") + quantityOrdered Int @map("quantity_ordered") + unitCost Decimal @map("unit_cost") @db.Decimal(10, 2) + notes String? + + // Relations + purchaseOrder PurchaseOrder @relation(fields: [purchaseOrderId], references: [id], onDelete: CASCADE) + productModel ProductModel @relation(fields: [productModelId], references: [id], onDelete: RESTRICT) + receiptItems ReceiptItem[] + + @@map("purchase_order_items") +} + +// Receipt represents a merchandise receipt event related to a purchase order +model Receipt { + id String @id @default(cuid()) + purchaseOrderId String @map("purchase_order_id") + receiptDate DateTime @map("receipt_date") + status ReceiptStatus @default(PENDING) + notes String? + createdBy String @map("created_by") + createdAt DateTime @default(now()) @map("created_at") + + // Relations + purchaseOrder PurchaseOrder @relation(fields: [purchaseOrderId], references: [id], onDelete: CASCADE) + createdByUser User @relation(fields: [createdBy], references: [id], onDelete: RESTRICT) + receiptItems ReceiptItem[] + inventoryUnits InventoryUnit[] + + @@map("receipts") +} + +// ReceiptItem represents the quantity received of each purchase order line +model ReceiptItem { + id String @id @default(cuid()) + receiptId String @map("receipt_id") + purchaseOrderItemId String @map("purchase_order_item_id") + quantityReceived Int @map("quantity_received") + quantityRejected Int @default(0) @map("quantity_rejected") + discrepancyNote String? @map("discrepancy_note") + + // Relations + receipt Receipt @relation(fields: [receiptId], references: [id], onDelete: CASCADE) + purchaseOrderItem PurchaseOrderItem @relation(fields: [purchaseOrderItemId], references: [id], onDelete: CASCADE) + inventoryUnits InventoryUnit[] + + @@map("receipt_items") +} + +// ProductModel represents the commercial article or model +model ProductModel { + id String @id @default(cuid()) + name String + brand String? + category String? + defaultSize String? @map("default_size") + defaultColor String? @map("default_color") + internalSku String? @map("internal_sku") + supplierSku String? @map("supplier_sku") + notes String? + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + + // Relations + purchaseOrderItems PurchaseOrderItem[] + inventoryUnits InventoryUnit[] + + @@map("product_models") +} + +// InventoryUnit represents a concrete or logical traceable unit in inventory +// V1 should favor unit-level traceability whenever possible +model InventoryUnit { + id String @id @default(cuid()) + productModelId String @map("product_model_id") + purchaseOrderId String @map("purchase_order_id") + receiptItemId String? @map("receipt_item_id") + inventoryStatus InventoryStatus @default(RECEIVED) + condition String? + storageLocation String? @map("storage_location") + costPrice Decimal @map("cost_price") @db.Decimal(10, 2) + readyForListingAt DateTime? @map("ready_for_listing_at") + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + + // Relations + productModel ProductModel @relation(fields: [productModelId], references: [id], onDelete: RESTRICT) + purchaseOrder PurchaseOrder @relation(fields: [purchaseOrderId], references: [id], onDelete: RESTRICT) + receiptItem ReceiptItem? @relation(fields: [receiptItemId], references: [id], onDelete: SET NULL) + listing Listing? + sale Sale? + + @@map("inventory_units") +} + +// Listing represents a published or prepared advertisement +model Listing { + id String @id @default(cuid()) + inventoryUnitId String @map("inventory_unit_id") + platform String? + externalReference String? @map("external_reference") + listingStatus ListingStatus @default(DRAFT) + listedPrice Decimal? @map("listed_price") @db.Decimal(10, 2) + listedAt DateTime? @map("listed_at") + url String? + notes String? + + // Relations + inventoryUnit InventoryUnit @relation(fields: [inventoryUnitId], references: [id], onDelete: CASCADE) + + @@map("listings") +} + +// Customer represents the buyer associated with a sale +model Customer { + id String @id @default(cuid()) + name String + platformUsername String? @map("platform_username") + shippingName String? @map("shipping_name") + shippingAddress String? @map("shipping_address") + phone String? + email String? + notes String? + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + + // Relations + sales Sale[] + + @@map("customers") +} + +// Sale represents the sale of a unit or article +model Sale { + id String @id @default(cuid()) + inventoryUnitId String @map("inventory_unit_id") + customerId String @map("customer_id") + saleChannel String? @map("sale_channel") + saleStatus SaleStatus @default(DRAFT) + salePrice Decimal @map("sale_price") @db.Decimal(10, 2) + soldAt DateTime @map("sold_at") + notes String? + createdAt DateTime @default(now()) @map("created_at") + + // Relations + inventoryUnit InventoryUnit @relation(fields: [inventoryUnitId], references: [id], onDelete: RESTRICT) + customer Customer @relation(fields: [customerId], references: [id], onDelete: RESTRICT) + shipment Shipment? + + @@map("sales") +} + +// Shipment represents the shipping associated with a sale +model Shipment { + id String @id @default(cuid()) + saleId String @map("sale_id") + shipmentStatus ShipmentStatus @default(NOT_STARTED) + shippedAt DateTime? @map("shipped_at") + trackingCode String? @map("tracking_code") + carrier String? + labelReference String? @map("label_reference") + notes String? + + // Relations + sale Sale @relation(fields: [saleId], references: [id], onDelete: CASCADE) + + @@map("shipments") +} + +// StatusHistory represents the history of relevant status transitions +model StatusHistory { + id String @id @default(cuid()) + entityType String @map("entity_type") + entityId String @map("entity_id") + fromStatus String? @map("from_status") + toStatus String @map("to_status") + changedBy String @map("changed_by") + changedAt DateTime @default(now()) @map("changed_at") + note String? + + // Relations + user User @relation(fields: [changedBy], references: [id], onDelete: RESTRICT) + + @@index([entityType, entityId]) + @@index([changedAt]) + @@map("status_histories") +} + +// Enums for status fields +enum PurchaseOrderStatus { + DRAFT + ORDERED + PARTIALLY_RECEIVED + RECEIVED + CLOSED + CANCELLED +} + +enum ReceiptStatus { + PENDING + IN_PROGRESS + COMPLETED + COMPLETED_WITH_DISCREPANCIES +} + +enum InventoryStatus { + ORDERED + RECEIVED + REGISTERED + READY_FOR_LISTING + LISTED + RESERVED + SOLD + PENDING_SHIPMENT + SHIPPED + COMPLETED + BLOCKED +} + +enum ListingStatus { + DRAFT + PUBLISHED + SOLD + REMOVED +} + +enum SaleStatus { + DRAFT + CONFIRMED + PENDING_SHIPMENT + SHIPPED + COMPLETED + CANCELLED +} + +enum ShipmentStatus { + NOT_STARTED + PENDING + SHIPPED + DELIVERED + ISSUE +} diff --git a/src/app/globals.css b/src/app/globals.css new file mode 100644 index 0000000..36a777a --- /dev/null +++ b/src/app/globals.css @@ -0,0 +1,59 @@ +@tailwind base; +@tailwind components; +@tailwind utilities; + +@layer base { + :root { + --background: 0 0% 100%; + --foreground: 222.2 84% 4.9%; + --card: 0 0% 100%; + --card-foreground: 222.2 84% 4.9%; + --popover: 0 0% 100%; + --popover-foreground: 222.2 84% 4.9%; + --primary: 222.2 47.4% 11.2%; + --primary-foreground: 210 40% 98%; + --secondary: 210 40% 96%; + --secondary-foreground: 222.2 84% 4.9%; + --muted: 210 40% 96%; + --muted-foreground: 215.4 16.3% 46.9%; + --accent: 210 40% 96%; + --accent-foreground: 222.2 84% 4.9%; + --destructive: 0 84.2% 60.2%; + --destructive-foreground: 210 40% 98%; + --border: 214.3 31.8% 91.4%; + --input: 214.3 31.8% 91.4%; + --ring: 222.2 84% 4.9%; + --radius: 0.5rem; + } + + .dark { + --background: 222.2 84% 4.9%; + --foreground: 210 40% 98%; + --card: 222.2 84% 4.9%; + --card-foreground: 210 40% 98%; + --popover: 222.2 84% 4.9%; + --popover-foreground: 210 40% 98%; + --primary: 210 40% 98%; + --primary-foreground: 222.2 47.4% 11.2%; + --secondary: 217.2 32.6% 17.5%; + --secondary-foreground: 210 40% 98%; + --muted: 217.2 32.6% 17.5%; + --muted-foreground: 215 20.2% 65.1%; + --accent: 217.2 32.6% 17.5%; + --accent-foreground: 210 40% 98%; + --destructive: 0 62.8% 30.6%; + --destructive-foreground: 210 40% 98%; + --border: 217.2 32.6% 17.5%; + --input: 217.2 32.6% 17.5%; + --ring: 212.7 26.8% 83.9%; + } +} + +@layer base { + * { + @apply border-border; + } + body { + @apply bg-background text-foreground; + } +} diff --git a/src/app/layout.tsx b/src/app/layout.tsx new file mode 100644 index 0000000..df3d32c --- /dev/null +++ b/src/app/layout.tsx @@ -0,0 +1,22 @@ +import type { Metadata } from 'next' +import { Inter } from 'next/font/google' +import './globals.css' + +const inter = Inter({ subsets: ['latin'] }) + +export const metadata: Metadata = { + title: 'Millions - Gestão Operacional de Revenda', + description: 'Aplicação de gestão operacional para revenda de roupa', +} + +export default function RootLayout({ + children, +}: { + children: React.ReactNode +}) { + return ( + + {children} + + ) +} diff --git a/src/app/page.tsx b/src/app/page.tsx new file mode 100644 index 0000000..adf18ee --- /dev/null +++ b/src/app/page.tsx @@ -0,0 +1,17 @@ +export default function Home() { + return ( +
+
+

Millions

+

+ Gestão Operacional para Revenda de Roupa +

+
+

+ Projeto em desenvolvimento - estrutura base configurada +

+
+
+
+ ) +} diff --git a/src/server/db/client.ts b/src/server/db/client.ts new file mode 100644 index 0000000..af2a01e --- /dev/null +++ b/src/server/db/client.ts @@ -0,0 +1,9 @@ +import { PrismaClient } from '@prisma/client' + +const globalForPrisma = globalThis as unknown as { + prisma: PrismaClient | undefined +} + +export const prisma = globalForPrisma.prisma ?? new PrismaClient() + +if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma diff --git a/tailwind.config.ts b/tailwind.config.ts new file mode 100644 index 0000000..ddf164c --- /dev/null +++ b/tailwind.config.ts @@ -0,0 +1,56 @@ +import type { Config } from 'tailwindcss' + +const config: Config = { + content: [ + './src/pages/**/*.{js,ts,jsx,tsx,mdx}', + './src/components/**/*.{js,ts,jsx,tsx,mdx}', + './src/app/**/*.{js,ts,jsx,tsx,mdx}', + ], + theme: { + extend: { + colors: { + border: 'hsl(var(--border))', + input: 'hsl(var(--input))', + ring: 'hsl(var(--ring))', + background: 'hsl(var(--background))', + foreground: 'hsl(var(--foreground))', + primary: { + DEFAULT: 'hsl(var(--primary))', + foreground: 'hsl(var(--primary-foreground))', + }, + secondary: { + DEFAULT: 'hsl(var(--secondary))', + foreground: 'hsl(var(--secondary-foreground))', + }, + destructive: { + DEFAULT: 'hsl(var(--destructive))', + foreground: 'hsl(var(--destructive-foreground))', + }, + muted: { + DEFAULT: 'hsl(var(--muted))', + foreground: 'hsl(var(--muted-foreground))', + }, + accent: { + DEFAULT: 'hsl(var(--accent))', + foreground: 'hsl(var(--accent-foreground))', + }, + popover: { + DEFAULT: 'hsl(var(--popover))', + foreground: 'hsl(var(--popover-foreground))', + }, + card: { + DEFAULT: 'hsl(var(--card))', + foreground: 'hsl(var(--card-foreground))', + }, + }, + borderRadius: { + lg: 'var(--radius)', + md: 'calc(var(--radius) - 2px)', + sm: 'calc(var(--radius) - 4px)', + }, + }, + }, + plugins: [], +} + +export default config diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..7b28589 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,26 @@ +{ + "compilerOptions": { + "lib": ["dom", "dom.iterable", "esnext"], + "allowJs": true, + "skipLibCheck": true, + "strict": true, + "noEmit": true, + "esModuleInterop": true, + "module": "esnext", + "moduleResolution": "bundler", + "resolveJsonModule": true, + "isolatedModules": true, + "jsx": "preserve", + "incremental": true, + "plugins": [ + { + "name": "next" + } + ], + "paths": { + "@/*": ["./src/*"] + } + }, + "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"], + "exclude": ["node_modules"] +}