diff --git a/README.md b/README.md
index 9bb399d..2fae4a4 100644
--- a/README.md
+++ b/README.md
@@ -1,428 +1,205 @@
-# MeVêUm
+# MeVeUm
 
-Sistema operacional para restaurantes — cardápio digital, checkout via WhatsApp, gestão de pedidos e painel administrativo para lojistas.
+Sistema operacional para restaurantes: cardapio digital publico, checkout com
+WhatsApp, painel administrativo, CRM, pedidos, pagamentos, entregas e metricas.
 
-O MeVêUm oferece uma solução completa para que donos de restaurantes gerenciem seu cardápio online, recebam pedidos e administrem toda a operação a partir de um único painel.
+Este repositorio e um monorepo com tres partes principais:
 
-## Índice
+- `api/` - backend Spring Boot, banco PostgreSQL e regras de negocio.
+- `web/` - frontend Next.js, painel administrativo e cardapio publico.
+- `automations/` - Playwright para contratos de API, fluxos de frontend e E2E.
 
-- [Visão geral](#visão-geral)
-- [Arquitetura](#arquitetura)
-- [Tecnologias](#tecnologias)
-- [Estrutura do repositório](#estrutura-do-repositório)
-- [Pré-requisitos](#pré-requisitos)
-- [Como rodar](#como-rodar)
-- [Domínios e funcionalidades](#domínios-e-funcionalidades)
-- [Modelo de dados](#modelo-de-dados)
-- [CI/CD](#cicd)
-- [Testes](#testes)
-- [Documentação interna](#documentação-interna)
-- [Contribuindo](#contribuindo)
-
----
-
-## Visão geral
-
-O MeVêUm é uma plataforma multi-tenant onde cada loja possui:
-
-- Cardápio digital público acessível via slug (`meveum.com.br/sua-loja`)
-- Checkout com envio para WhatsApp do lojista
-- Painel administrativo para gestão de cardápio, pedidos, clientes, entregas, pagamentos e métricas
-- Autenticação JWT com chaves RSA para segurança das rotas administrativas
-
-### Fluxo principal
-
-```mermaid
-flowchart LR
-    A["Cliente acessa cardápio"] --> B["Monta pedido"]
-    B --> C["Checkout"]
-    C --> D["WhatsApp do lojista"]
-    D --> E["Lojista gerencia pedidos via painel"]
-    E -->|"Atualiza status"| F["Novo → Em Preparo → Entrega → Finalizado"]
-```
-
----
+Os detalhes tecnicos ficam nos READMEs de cada pasta. Este arquivo e o mapa do
+projeto e o caminho mais curto para subir tudo localmente.
 
 ## Arquitetura
 
-O projeto é um monorepo dividido em três módulos independentes:
-
-```mermaid
-graph LR
-    MEVEUM["meveum/"] --> API["api/"]
-    MEVEUM --> WEB["web/"]
-    MEVEUM --> AUTO["automations/"]
-    API --- A1["Spring Boot — monolito modular por domínio"]
-    WEB --- W1["Next.js — painel admin + cardápio público"]
-    AUTO --- T1["Playwright — API + Frontend"]
-```
-
-### Backend — monolito modular
-
-O backend segue a arquitetura de monolito modular organizado por domínios, com separação clara de responsabilidades:
-
 ```mermaid
 flowchart LR
-    Controller --> Service
-    Service --> Validator
-    Service --> Repository
-    Repository --> Entity
-    Service <--> Mapper["Mapper (Entity / DTO)"]
+    Cliente["Cliente no cardapio publico"] --> Web["web/ Next.js"]
+    Lojista["Lojista no dashboard"] --> Web
+    Web --> Api["api/ Spring Boot"]
+    Api --> Db["PostgreSQL"]
+    Automations["automations/ Playwright"] --> Web
+    Automations --> Api
+    Automations --> Db
 ```
 
-Cada domínio possui controllers, services, validators, mappers, DTOs, entities e repositories próprios. Código compartilhado fica centralizado em `shared/`.
-
-### Frontend — organização por features
-
-O frontend segue uma organização modular por features com separação de:
-
-- **Pages** — telas completas
-- **Components** — UI reutilizável
-- **Services** — comunicação com API
-- **Hooks** — lógica reutilizável de tela
-- **Mocks** — dados simulados por domínio
-- **Types** — contratos de dados (espelhando DTOs do backend)
-
----
-
-## Tecnologias
-
-### Backend (`api/`)
-
-| Tecnologia | Versão | Propósito |
-|---|---|---|
-| Java | 21 | Linguagem |
-| Spring Boot | 4.0.6 | Framework principal |
-| Spring Data JPA | — | Persistência |
-| Spring Security + OAuth2 Resource Server | — | Autenticação JWT (RSA) |
-| Spring Validation | — | Validação de dados |
-| Flyway | — | Migrações de banco |
-| PostgreSQL | 16 | Banco de dados |
-| Lombok | — | Redução de boilerplate |
-| SpringDoc OpenAPI | 3.0.2 | Documentação Swagger |
-| Testcontainers | — | Testes com banco real |
-
-### Frontend (`web/`)
-
-| Tecnologia | Versão | Propósito |
-|---|---|---|
-| Next.js | 16.2.6 | Framework React |
-| React | 19.2.4 | Biblioteca UI |
-| TypeScript | 5.x | Tipagem estática |
-| Tailwind CSS | 4.x | Estilização |
-| Radix UI | — | Componentes acessíveis (Dialog, Select, Tabs, Toast, etc.) |
-| React Hook Form + Zod | — | Formulários com validação |
-| Lucide React | — | Ícones |
-| Sonner | — | Notificações toast |
-| Vitest + Testing Library | — | Testes unitários |
-
-### Automações (`automations/`)
+## Estrutura
 
-| Tecnologia | Versão | Propósito |
-|---|---|---|
-| Playwright | 1.60+ | Automação de testes |
-| JavaScript (ESM) | — | Linguagem dos testes |
-
-### Infraestrutura
-
-| Tecnologia | Propósito |
-|---|---|
-| Docker Compose | PostgreSQL local |
-| GitHub Actions | CI/CD |
-
----
-
-## Estrutura do repositório
-
-```
+```text
 meveum/
-├── .github/
-│   └── workflows/
-│       ├── ci.yml                 CI: testes da API e build da web
-│       └── automations.yml        Integração: Playwright com API + Web
-│
-├── api/                           Backend Spring Boot
-│   ├── src/main/java/br/com/meveum/
-│   │   ├── auth/                  Autenticação e autorização (JWT)
-│   │   ├── cardapio/              Categorias, produtos e complementos
-│   │   ├── crm/                   Clientes e endereços
-│   │   ├── dashboard/             Métricas e analytics
-│   │   ├── entrega/               Áreas e taxas de entrega
-│   │   ├── integracao_whatsapp/   Integração WhatsApp
-│   │   ├── lojas/                 Gestão de lojas (tenant)
-│   │   ├── pagamentos/            Formas de pagamento
-│   │   ├── pedidos/               Pedidos e status
-│   │   └── shared/                Config, exceções, validadores comuns
-│   ├── src/main/resources/
-│   │   ├── db/migration/          Migrações Flyway (V1..V9)
-│   │   ├── authz.pem / authz.pub Chaves RSA para JWT
-│   │   └── application.properties
-│   ├── docs/
-│   │   ├── database-model.md      Modelo de dados completo
-│   │   └── rf.md                  Requisitos funcionais
-│   ├── docker-compose.yml         PostgreSQL 16 Alpine
-│   └── pom.xml
-│
-├── web/                           Frontend Next.js
-│   ├── src/
-│   │   ├── app/
-│   │   │   ├── (auth)/            Login e cadastro
-│   │   │   ├── (dashboard)/       Painel administrativo
-│   │   │   ├── [slug]/            Cardápio público por loja
-│   │   │   └── page.tsx           Landing page
-│   │   ├── components/            UI, layout e componentes compartilhados
-│   │   ├── features/              Domínios (auth, cardápio, pedidos, etc.)
-│   │   ├── lib/                   API client, mocks, utils, validações
-│   │   ├── tests/                 Testes unitários
-│   │   └── types/                 Tipos compartilhados
-│   └── package.json
-│
-├── automations/                   Testes de integração
-│   ├── tests/
-│   │   ├── api/                   Testes de contrato e integração API
-│   │   └── frontend/              Testes de comportamento no browser
-│   ├── pages/                     Page Objects
-│   ├── services/                  Clients HTTP para testes
-│   ├── fixtures/                  Setup/teardown e injeção de dados
-│   ├── presets/                   Estados reutilizáveis de teste
-│   ├── data/                      Massa de dados
-│   └── playwright.config.js
-│
-├── CONTRIBUTING.md                Guia de contribuição e padrões Git
-└── .gitignore
+|-- api/                 Backend, migrations Flyway e modelo de dados
+|-- web/                 Frontend Next.js
+|-- automations/         Testes Playwright
+|-- .github/workflows/   CI e automacoes
+|-- CONTRIBUTING.md      Fluxo de contribuicao
+`-- README.md            Visao geral do monorepo
 ```
 
----
+## Pre-requisitos
 
-## Pré-requisitos
-
-- Java 21+
-- Maven 3.8+ (ou usar o Maven Wrapper incluso: `./mvnw`)
+- Java 21
 - Node.js 20+
 - npm 10+
 - Docker e Docker Compose
+- GitHub CLI (`gh`) apenas para operacoes de PR/release
 
----
-
-## Como rodar
-
-### 1. Clonar o repositório
+## Como iniciar localmente
 
-```bash
-git clone https://github.com/Asimpta/meveum.git
-cd meveum
-```
+Abra tres terminais: banco/API, web e automacoes.
 
-### 2. Subir o banco de dados
+### 1. Banco
 
 ```bash
 cd api
-docker-compose up -d
+docker compose up -d
 ```
 
-Isso inicia um PostgreSQL 16 com:
+PostgreSQL local:
 
-| Parâmetro | Valor |
+| Campo | Valor |
 |---|---|
-| Database | `meveum` |
-| User | `meveum` |
-| Password | `meveum` |
+| Host | `127.0.0.1` |
 | Porta | `5432` |
+| Database | `meveum` |
+| Usuario | `meveum` |
+| Senha | `meveum` |
+
+### 2. API
 
-### 3. Rodar o backend
+Windows:
+
+```powershell
+cd api
+.\mvnw.cmd spring-boot:run
+```
+
+Linux/macOS:
 
 ```bash
 cd api
-./mvnw spring-boot:run        # Linux/macOS
-mvnw.cmd spring-boot:run      # Windows
+./mvnw spring-boot:run
 ```
 
-A API estará disponível em `http://localhost:8080`.
+URLs:
 
-Swagger UI: `http://localhost:8080/swagger-ui.html`
+- API: `http://localhost:8080`
+- Swagger UI: `http://localhost:8080/swagger-ui.html`
+- OpenAPI JSON: `http://localhost:8080/v3/api-docs`
 
-### 4. Rodar o frontend
+### 3. Web
 
 ```bash
 cd web
+npm ci
 cp .env.local.example .env.local
-npm install
 npm run dev
 ```
 
-O frontend estará disponível em `http://localhost:3000`.
-
-### 5. Rodar os testes de integração (opcional)
+No Windows PowerShell:
 
-```bash
-cd automations
-npm install
-npx playwright install --with-deps chromium
-npm test
+```powershell
+cd web
+npm ci
+Copy-Item .env.local.example .env.local
+npm run dev
 ```
 
-Os testes de integração requerem que a API e o frontend estejam rodando.
-
----
+URL:
 
-## Domínios e funcionalidades
+- Web: `http://localhost:3000`
 
-### Gestão da loja (tenant)
+### 4. Automacoes
 
-- Cadastro e configuração da loja (nome, logo, slug, WhatsApp)
-- Grade de horário de funcionamento (múltiplos períodos por dia)
-- Botão de pausa manual
-- Multi-tenancy: cada loja é um tenant isolado
+Com API e web rodando:
 
-### Catálogo / cardápio
-
-- CRUD de categorias com ordenação
-- CRUD de produtos (nome, descrição, preço, imagem, categoria)
-- Grupos de complementos com regras de mínimo/máximo
-- Opções de complemento com preço adicional
-- Vinculação N:N entre produtos e grupos de complemento
-
-### Entrega
-
-- Áreas de entrega por bairro, faixa de CEP ou raio (km)
-- Taxa de entrega e pedido mínimo por zona
-- Tempo estimado de entrega
-
-### Pagamentos
-
-- Configuração de formas aceitas: PIX, cartão na entrega, dinheiro
-- Ativação/inativação por loja
-
-### CRM / clientes
-
-- Cadastro e consulta de clientes
-- Endereços do cliente (múltiplos)
-
-### Pedidos
+```bash
+cd automations
+npm ci
+npx playwright install chromium
+npm test
+```
 
-- Criação de pedido com cálculo automático de totais
-- Validação de loja aberta, produtos ativos e complementos válidos
-- Status: Novo, Em Preparo, Saiu para Entrega, Finalizado, Cancelado
-- Snapshot de dados no pedido (protege contra alterações futuras no cardápio)
+Tambem e possivel rodar por camada:
 
-### Dashboard
+```bash
+npm run test:api
+npm run test:frontend
+npm run test:e2e
+```
 
-- Faturamento total
-- Quantidade de pedidos
-- Produtos mais vendidos
+## Testes principais
 
-### Integração WhatsApp
+```bash
+cd api && ./mvnw test
+cd web && npm test
+cd web && npm run build
+cd automations && npm test
+```
 
-- Geração de mensagem estruturada com dados do pedido
-- Envio direto via WhatsApp Web/App
+No Windows, use `.\mvnw.cmd test` dentro de `api/`.
 
-### Autenticação
+## Banco de dados
 
-- Login e cadastro de usuários da loja (JWT com RSA)
-- Proteção de rotas administrativas
-- Endpoints públicos do cardápio liberados
+O schema e versionado por Flyway em
+`api/src/main/resources/db/migration/`.
 
----
+Estado atual:
 
-## Modelo de dados
+- migrations de `V1` a `V13`;
+- PostgreSQL 16;
+- `ddl-auto=validate`;
+- 16 tabelas de aplicacao;
+- dados locais de desenvolvimento criados pelas migrations de seed.
 
-O banco utiliza 15 tabelas com multi-tenancy por `store_id`:
+Resumo dos grupos:
 
 | Grupo | Tabelas |
 |---|---|
-| Loja | `stores`, `store_users`, `store_opening_periods`, `store_delivery_zones`, `store_payment_methods` |
-| Catálogo | `categories`, `products`, `complement_groups`, `complement_options`, `product_complement_groups` |
-| Clientes | `customers`, `customer_addresses` |
+| Loja e auth | `stores`, `store_users`, `password_reset_tokens` |
+| Operacao da loja | `store_opening_periods`, `store_delivery_zones`, `store_payment_methods` |
+| Catalogo | `categories`, `products`, `complement_groups`, `complement_options`, `product_complement_groups` |
+| CRM | `customers`, `customer_addresses` |
 | Pedidos | `orders`, `order_items`, `order_item_complements` |
 
-As migrações Flyway estão em `api/src/main/resources/db/migration/` (V1 até V9).
-
-Documentação completa do modelo: [`api/docs/database-model.md`](api/docs/database-model.md)
+Detalhes tecnicos, diagrama ER e historico de migrations ficam em
+[`api/README.md`](api/README.md) e
+[`api/docs/database-model.md`](api/docs/database-model.md).
 
----
+## CI
 
-## CI/CD
+O repositorio tem dois workflows:
 
-O projeto possui dois pipelines no GitHub Actions:
+- `CI` - roda testes da API, testes da web e build do Next.js.
+- `Automations` - sobe PostgreSQL, API, web buildada e roda Playwright.
 
-### CI (`ci.yml`)
+Checks obrigatorios na `main`:
 
-Roda em push e pull request para `main`:
+- `API - testes`
+- `Web - testes e build`
+- `Playwright - integracoes`
 
-- **API** — compila e roda testes com Maven
-- **Web** — instala dependências, roda testes com Vitest e valida build
-
-### Automations (`automations.yml`)
-
-Roda em push e pull request quando há alterações em `api/`, `web/` ou `automations/`:
-
-```mermaid
-flowchart LR
-    A["PostgreSQL"] --> B["API (Spring Boot)"]
-    B --> C["Web (Next.js)"]
-    C --> D["Playwright"]
-    D --> E["Relatórios e logs"]
-```
+## Documentacao por modulo
 
----
-
-## Testes
-
-### Testes unitários — API
-
-```bash
-cd api && ./mvnw test
-```
-
-- Testcontainers com PostgreSQL real
-- Cobertura de services, validators e mappers
-
-### Testes unitários — Web
-
-```bash
-cd web && npm test
-```
-
-- Vitest + Testing Library
-- Testes de comportamento (nunca estéticos)
-- Cobertura de componentes, hooks e services
-
-### Testes de integração — automações
-
-```bash
-cd automations && npm test
-```
-
-- **API** (`npm run test:api`): contratos, autenticação, CRUD e fluxos
-- **Frontend** (`npm run test:frontend`): comportamento observável no browser
-- Tags disponíveis: `@smoke`, `@regressao`, `@negativo`, `@contrato`
-
----
-
-## Documentação interna
-
-| Documento | Descrição |
+| Documento | Quando usar |
 |---|---|
-| [`api/AGENTS.md`](api/AGENTS.md) | Padrões de arquitetura do backend |
-| [`web/AGENTS.md`](web/AGENTS.md) | Padrões de arquitetura do frontend |
-| [`automations/AGENTS.md`](automations/AGENTS.md) | Estratégia e padrões de automação |
-| [`api/docs/database-model.md`](api/docs/database-model.md) | Modelo de dados completo com diagrama ER |
-| [`api/docs/rf.md`](api/docs/rf.md) | Requisitos funcionais (RF01 a RF24) |
-| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Guia de contribuição, GitFlow e Conventional Commits |
+| [`api/README.md`](api/README.md) | Arquitetura backend, endpoints, banco, migrations e testes Java |
+| [`web/README.md`](web/README.md) | Rotas, estrutura Next.js, API client, validacoes e testes Vitest |
+| [`automations/README.md`](automations/README.md) | Metricas, padroes Playwright, tags, fixtures, services e relatorios |
+| [`api/dados/README.md`](api/dados/README.md) | IDs fixos de desenvolvimento e collection Postman |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Fluxo Git, commits e PRs |
 
----
+## Rotina recomendada
 
-## Contribuindo
-
-O projeto segue GitFlow com Conventional Commits. Consulte o guia completo em [`CONTRIBUTING.md`](CONTRIBUTING.md).
+1. Atualize a `main`.
+2. Crie uma branch por contexto.
+3. Rode a menor suite que prova a mudanca.
+4. Se mexer em contrato compartilhado, rode API, web e automacoes afetadas.
+5. Abra PR com resumo, riscos e test plan.
 
 ```bash
-git checkout main && git pull
-git checkout -b feature/sua-funcionalidade
-
-# Desenvolva...
-git commit -m "feat: sua funcionalidade"
-git push origin feature/sua-funcionalidade
-
-# Abra um Pull Request → Code Review → Merge
+git checkout main
+git pull
+git checkout -b feature/minha-mudanca
 ```
diff --git a/api/README.md b/api/README.md
index 9b8aa0b..597cabd 100644
--- a/api/README.md
+++ b/api/README.md
@@ -1,88 +1,348 @@
-# MeVêUm API
+# MeVeUm API
 
-Backend do MeVêUm - Sistema operacional para restaurantes.
+Backend Spring Boot do MeVeUm. Este modulo concentra regras de negocio,
+autenticacao, multi-tenancy por loja, migrations Flyway, persistencia em
+PostgreSQL e contratos HTTP consumidos pelo frontend e pelas automacoes.
 
-## Estrutura do Projeto
+## Stack
 
-O backend segue uma arquitetura de **monolito modular por domínio**.
+| Tecnologia | Uso |
+|---|---|
+| Java 21 | Runtime da API |
+| Spring Boot 4.0.6 | Framework principal |
+| Spring Web MVC | Controllers HTTP |
+| Spring Data JPA | Persistencia |
+| Spring Security + OAuth2 Resource Server | JWT RSA |
+| Spring Validation | Validacao de requests |
+| Flyway | Evolucao do schema |
+| PostgreSQL 16 | Banco local e CI |
+| Lombok | Builders e boilerplate |
+| SpringDoc OpenAPI 3.0.2 | Swagger |
+| Testcontainers | Testes com PostgreSQL real |
 
-```
-src/main/java/br/com/meveum/
-├── cardapio/              ← Gestão de produtos e categorias
-│   ├── controller/
-│   ├── service/
-│   ├── repository/
-│   └── entity/
-├── pedidos/               ← Fluxo de pedidos
-│   ├── controller/
-│   ├── service/
-│   ├── repository/
-│   └── entity/
-├── pagamentos/            ← Processamento de pagamentos
-│   ├── controller/
-│   ├── service/
-│   └── repository/
-├── entrega/               ← Gestão de entregas
-│   ├── controller/
-│   └── service/
-├── crm/                   ← Gestão de clientes
-│   ├── controller/
-│   └── service/
-├── dashboard/             ← Analytics e dashboards
-│   ├── controller/
-│   └── service/
-├── integracao_whatsapp/   ← Integração com WhatsApp
-│   ├── controller/
-│   └── service/
-├── shared/                ← Código compartilhado entre domínios
-│   ├── validator/         ← Validadores genéricos
-│   ├── mapper/            ← Conversão de DTOs
-│   ├── exception/         ← Exceções customizadas
-│   ├── config/            ← Configurações da aplicação
-│   └── security/          ← Segurança e autenticação
-└── MeveumApplication.java ← Classe principal
+## Como rodar
+
+### 1. Banco
+
+```bash
+docker compose up -d
 ```
 
-## Padrões de Desenvolvimento
+O compose sobe `postgres:16-alpine` com:
 
-Consulte [AGENTS.md](./AGENTS.md) para os padrões obrigatórios de arquitetura.
+| Campo | Valor |
+|---|---|
+| Host | `127.0.0.1` |
+| Porta | `5432` |
+| Database | `meveum` |
+| Usuario | `meveum` |
+| Senha | `meveum` |
+| Volume local | `api/data/postgres` |
 
-## Como Rodar
+### 2. API
 
-### Pré-requisitos
+Windows:
 
-- Java 21+
-- Maven 3.8+
-- Docker e Docker Compose
+```powershell
+.\mvnw.cmd spring-boot:run
+```
 
-### Iniciar banco de dados
+Linux/macOS:
 
 ```bash
-docker-compose up -d
+./mvnw spring-boot:run
 ```
 
-### Rodar a aplicação
+URLs:
+
+- API: `http://localhost:8080`
+- Swagger UI: `http://localhost:8080/swagger-ui.html`
+- OpenAPI: `http://localhost:8080/v3/api-docs`
+
+### 3. Testes
+
+Windows:
+
+```powershell
+.\mvnw.cmd clean test
+```
+
+Linux/macOS:
 
 ```bash
-mvn spring-boot:run
+./mvnw clean test
+```
+
+Os testes usam Testcontainers quando precisam de PostgreSQL real. Services,
+mappers e validators devem ter testes unitarios sempre que forem criados ou
+alterados.
+
+## Configuracao local
+
+Arquivo principal: `src/main/resources/application.properties`.
+
+Configuracao atual:
+
+```properties
+spring.datasource.url=jdbc:postgresql://127.0.0.1:5432/meveum
+spring.datasource.username=meveum
+spring.datasource.password=meveum
+spring.jpa.hibernate.ddl-auto=validate
+spring.flyway.enabled=true
+spring.flyway.locations=classpath:db/migration
+jwt.public.key=classpath:authz.pub
+jwt.private.key=classpath:authz.pem
+```
+
+`ddl-auto=validate` e intencional: o Hibernate valida o schema, mas quem cria
+ou altera tabelas e o Flyway.
+
+## Arquitetura
+
+A API e um monolito modular por dominio. O padrao de fluxo e:
+
+```mermaid
+flowchart LR
+    Controller["Controller"] --> Service["Service"]
+    Service --> Validator["Validator"]
+    Service --> Mapper["Mapper"]
+    Service --> Repository["Repository"]
+    Repository --> Entity["Entity"]
+    Mapper --> DTO["DTO"]
+```
+
+Responsabilidades:
+
+| Camada | Responsabilidade |
+|---|---|
+| Controller | Rotas, status HTTP, validacao de request com `@Valid` e chamada da service |
+| Service | Caso de uso, orquestracao, transacao e regra de negocio |
+| Validator | Validacoes puras ou validacoes com banco em `validator/service` |
+| Mapper | Conversao explicita entre DTOs e entities |
+| Repository | Acesso a dados e queries calculadas |
+| Entity | Modelo persistido |
+| DTO | Contrato HTTP especifico por funcionalidade |
+
+Controllers nao devem conter regra de negocio. Services nao devem montar DTOs
+manualmente se houver mapper do dominio. Repositories nao devem conter regra de
+negocio.
+
+## Dominios
+
+```text
+src/main/java/br/com/meveum/
+|-- auth/                  Login, cadastro, JWT e recuperacao de senha
+|-- lojas/                 Loja tenant, perfil, horarios e status operacional
+|-- cardapio/
+|   |-- categorias/        CRUD de categorias
+|   |-- produtos/          CRUD, disponibilidade e remocao logica de produtos
+|   |-- complementos/      Grupos, opcoes e vinculo produto-grupo
+|   `-- entity|repository  Entidades compartilhadas do catalogo
+|-- entrega/areas/         Areas e taxas de entrega
+|-- pagamentos/formas/     Formas de pagamento aceitas pela loja
+|-- crm/clientes/          Clientes e enderecos
+|-- pedidos/               Criacao, listagem, detalhe e status de pedidos
+|-- dashboard/             Resumo, grafico, KDS, rankings e clientes recorrentes
+|-- integracao_whatsapp/   Mensagem estruturada do pedido
+`-- shared/                Config, security e exception handler
 ```
 
-A API estará disponível em `http://localhost:8080`.
+## Endpoints por dominio
 
-### Documentação da API
+| Dominio | Rotas principais |
+|---|---|
+| Auth | `POST /auth/login`, `POST /auth/registrar`, `POST /auth/esqueci-senha`, `POST /auth/redefinir-senha`, `GET /auth/me` |
+| Lojas | `GET /lojas/me`, `GET /lojas/{id}`, `GET /lojas/slug/{slug}`, `PUT /lojas/{id}`, `PATCH /lojas/{id}/pausa-manual`, `PATCH /lojas/{id}/status`, `GET/PUT /lojas/{id}/horarios` |
+| Categorias | `POST /categorias`, `GET /categorias`, `GET/PUT/DELETE /categorias/{id}` |
+| Produtos | `POST /produtos`, `GET /produtos`, `GET/PUT/DELETE /produtos/{id}`, `PATCH /produtos/{id}/toggle-disponivel` |
+| Complementos | `POST/GET /complementos/grupos`, `GET/PUT/DELETE /complementos/grupos/{id}`, `POST/GET /complementos/opcoes`, `GET/PUT/DELETE /complementos/opcoes/{id}`, vinculos em `/complementos/produtos/{produtoId}/grupos` |
+| Entrega | `POST /entrega/areas`, `GET /entrega/areas`, `GET/PUT/DELETE /entrega/areas/{id}` |
+| Pagamentos | `POST /pagamentos/formas`, `GET /pagamentos/formas`, `GET/PUT/DELETE /pagamentos/formas/{id}` |
+| Clientes | `POST /clientes`, `GET /clientes`, `GET/PUT /clientes/{id}`, enderecos em `/clientes/{id}/enderecos` |
+| Pedidos | `POST /pedidos`, `GET /pedidos`, `GET /pedidos/{id}`, `PATCH /pedidos/{id}/status` |
+| Dashboard | `GET /dashboard/resumo`, `/produtos-mais-vendidos`, `/grafico-semanal`, `/pedidos-resumo`, `/kds`, `/clientes-recorrentes` |
+| WhatsApp | `GET /integracoes/whatsapp/pedidos/{pedidoId}/mensagem` |
 
-Swagger UI: `http://localhost:8080/swagger-ui.html`
+## Banco de dados
 
-## Estrutura de Migração do Banco
+### Estado atual
 
-As migrações SQL devem estar em `src/main/resources/db/migration/`.
+O banco esta versionado de `V1` a `V13` em
+`src/main/resources/db/migration/`.
 
-O Flyway gerencia automaticamente a evolução do schema.
+| Versao | Objetivo |
+|---|---|
+| `V1` | Schema inicial com lojas, catalogo, clientes e pedidos |
+| `V2` | Loja e usuario de desenvolvimento |
+| `V3` | Produto/categoria de desenvolvimento |
+| `V4` | Complementos de desenvolvimento |
+| `V5` | Area de entrega de desenvolvimento |
+| `V6` | Forma de pagamento de desenvolvimento |
+| `V7` | Cliente e endereco de desenvolvimento |
+| `V8` | Pedido completo de desenvolvimento |
+| `V9` | Usuario autenticavel para testes |
+| `V10` | Vinculo do grupo de complemento ao produto de teste |
+| `V11` | Tabela `password_reset_tokens` |
+| `V12` | Campos de perfil da loja: `phone`, `address`, `description`, `pix_key` |
+| `V13` | Campo `products.available` para disponibilidade operacional |
+
+O schema atual tem 16 tabelas:
+
+| Grupo | Tabelas |
+|---|---|
+| Loja e auth | `stores`, `store_users`, `password_reset_tokens` |
+| Operacao | `store_opening_periods`, `store_delivery_zones`, `store_payment_methods` |
+| Catalogo | `categories`, `products`, `complement_groups`, `complement_options`, `product_complement_groups` |
+| CRM | `customers`, `customer_addresses` |
+| Pedidos | `orders`, `order_items`, `order_item_complements` |
+
+### Diagrama ER resumido
+
+```mermaid
+erDiagram
+    STORES ||--o{ STORE_USERS : possui
+    STORES ||--o{ STORE_OPENING_PERIODS : configura
+    STORES ||--o{ STORE_DELIVERY_ZONES : atende
+    STORES ||--o{ STORE_PAYMENT_METHODS : aceita
+    STORES ||--o{ CATEGORIES : organiza
+    STORES ||--o{ PRODUCTS : vende
+    STORES ||--o{ COMPLEMENT_GROUPS : define
+    STORES ||--o{ CUSTOMERS : atende
+    STORES ||--o{ ORDERS : recebe
+
+    STORE_USERS ||--o{ PASSWORD_RESET_TOKENS : gera
+    CATEGORIES ||--o{ PRODUCTS : contem
+    COMPLEMENT_GROUPS ||--o{ COMPLEMENT_OPTIONS : contem
+    PRODUCTS ||--o{ PRODUCT_COMPLEMENT_GROUPS : usa
+    COMPLEMENT_GROUPS ||--o{ PRODUCT_COMPLEMENT_GROUPS : vincula
+    CUSTOMERS ||--o{ CUSTOMER_ADDRESSES : possui
+    CUSTOMERS ||--o{ ORDERS : faz
+    ORDERS ||--o{ ORDER_ITEMS : contem
+    ORDER_ITEMS ||--o{ ORDER_ITEM_COMPLEMENTS : possui
+
+    STORES {
+        uuid id PK
+        varchar name
+        varchar slug UK
+        varchar logo_url
+        varchar whatsapp_number
+        varchar phone
+        varchar address
+        varchar description
+        varchar pix_key
+        varchar status
+        boolean manually_paused
+    }
+
+    PRODUCTS {
+        uuid id PK
+        uuid store_id FK
+        uuid category_id FK
+        varchar name
+        numeric base_price
+        varchar image_url
+        boolean active
+        boolean available
+    }
+
+    ORDERS {
+        uuid id PK
+        uuid store_id FK
+        uuid customer_id FK
+        varchar fulfillment_type
+        varchar status
+        varchar payment_method
+        numeric subtotal
+        numeric delivery_fee
+        numeric total
+        jsonb delivery_address_snapshot
+    }
+
+    PASSWORD_RESET_TOKENS {
+        uuid id PK
+        uuid store_user_id FK
+        varchar token
+        timestamptz expires_at
+        timestamptz used_at
+    }
+```
+
+### Decisoes de modelagem
+
+- `store_id` e a fronteira de tenant.
+- Dados financeiros e indicadores do dashboard sao calculados por query; nao
+  existem colunas agregadas como `saldo_total`.
+- `orders` e itens salvam snapshot de produto/complemento para preservar o
+  historico mesmo se o cardapio mudar.
+- `products.active` representa remocao logica; `products.available` representa
+  disponibilidade operacional.
+- `stores.manually_paused` fecha temporariamente a loja sem alterar `status`.
+- `password_reset_tokens` guarda ciclo de recuperacao de senha com expiracao e
+  uso.
+
+Documento completo do modelo: [`docs/database-model.md`](docs/database-model.md).
+
+## Dados locais de desenvolvimento
+
+As migrations `V2` a `V10` criam uma massa fixa para desenvolvimento local.
+Os IDs estao documentados em [`dados/README.md`](dados/README.md).
+
+Essa massa existe para facilitar Postman, Playwright e testes manuais. Para
+testes automatizados novos, prefira factories/services criando dados dinamicos
+quando o cenario exigir independencia.
+
+## Dashboard e metricas
+
+As metricas do dashboard sao derivadas de consultas:
+
+- resumo: faturamento, pedidos, ticket medio e tempo medio de cozinha;
+- grafico semanal: faturamento agregado por dia;
+- produtos mais vendidos: ranking por quantidade/receita;
+- pedidos resumo/KDS: recortes operacionais de pedidos recentes;
+- clientes recorrentes: recorrencia e gasto calculados a partir de pedidos.
+
+Regra importante: agregados devem ser calculados em query ou service a partir
+do dado fonte. Nao criar coluna persistida de totalizador sem necessidade clara
+de performance e sem plano de consistencia.
+
+## Padroes de implementacao
+
+Checklist para novo caso de uso:
+
+1. Criar DTOs especificos de request/response.
+2. Criar ou atualizar validator do dominio.
+3. Criar service pequena, com nome de caso de uso.
+4. Usar mapper para conversoes.
+5. Usar repository apenas para acesso a dados.
+6. Criar endpoint no controller sem regra de negocio.
+7. Criar testes de service, mapper e validator.
+8. Atualizar automacoes se o contrato HTTP mudou.
+
+Padrao de nomes:
+
+- `CriarProdutoService`
+- `AtualizarStatusPedidoService`
+- `DetalharMinhaLojaService`
+- `ValidarProdutoExisteService`
+- `ProdutoMapper`
+- `CriarProdutoRequest`
+- `CriarProdutoResponse`
+
+## Qualidade e CI
+
+Comandos principais:
+
+```bash
+./mvnw test
+./mvnw clean test
+./mvnw spring-boot:run
+```
 
-## Escalabilidade Futura
+No CI, o job `API - testes` roda `./mvnw test`.
 
-Esta estrutura de monolito modular permite fácil escalabilidade:
+Antes de abrir PR que toca API:
 
-- Se um domínio crescer muito, pode ser extraído em um microserviço independente
-- A separação clara por domínio facilita testes e manutenção
-- Código compartilhado fica centralizado em `shared/`
+- rode os testes da API;
+- confira se migrations novas sobem do zero;
+- confirme que DTOs/automacoes foram atualizados;
+- nao commite `.env`, `target/`, dumps, logs ou dados locais.
diff --git a/api/dados/README.md b/api/dados/README.md
index 88a31c6..528d354 100644
--- a/api/dados/README.md
+++ b/api/dados/README.md
@@ -1,12 +1,27 @@
 # Dados de desenvolvimento
 
-Esta pasta guarda arquivos auxiliares para desenvolvimento local. Nao confundir
-com `data/`, que e o volume local do PostgreSQL.
+Esta pasta guarda arquivos auxiliares para desenvolvimento local, como
+collections Postman. Nao confundir com `api/data/postgres`, que e o volume local
+do PostgreSQL criado pelo Docker Compose.
 
-## Dados de teste
+## Dados criados pelo Flyway
 
-O Flyway cria/atualiza os dados de teste pelas migrations `V2`, `V3`, `V4`,
-`V5`, `V6`, `V7` e `V8`.
+As migrations de seed (`V2` a `V10`) criam uma massa fixa para desenvolvimento,
+testes manuais e Postman.
+
+| Versao | Conteudo |
+|---|---|
+| `V2` | Loja base e usuario Bruno |
+| `V3` | Categoria e produto base |
+| `V4` | Grupo e opcao de complemento |
+| `V5` | Area de entrega |
+| `V6` | Forma de pagamento |
+| `V7` | Cliente e endereco |
+| `V8` | Pedido, item e complemento de pedido |
+| `V9` | Usuario autenticavel para automacoes |
+| `V10` | Vinculo entre produto e grupo de complemento |
+
+## IDs fixos
 
 ```txt
 lojaId: 11111111-1111-1111-1111-111111111111
@@ -25,13 +40,24 @@ complementoItemPedidoId: dddddddd-dddd-dddd-dddd-dddddddddddd
 
 ## Collection Postman
 
-Para importar no Postman, use o arquivo:
+Arquivo:
 
 ```txt
 dados/postman/meveum-api.postman_collection.json
 ```
 
-Fluxo sugerido com os dados de teste:
+Fluxo sugerido:
+
+1. Suba o banco com `docker compose up -d`.
+2. Suba a API com `./mvnw spring-boot:run` ou `.\mvnw.cmd spring-boot:run`.
+3. Use os requests de login/cadastro para obter JWT.
+4. Use os IDs fixos para listar, detalhar, atualizar e excluir.
+5. Para criacao, prefira nomes novos para evitar duplicidade.
+
+## Observacoes
 
-1. Rode listar, detalhar, atualizar e excluir usando os IDs fixos de teste.
-2. Para criacao, use os requests com nomes `Nova` para evitar duplicidade.
+- A massa fixa e util para testes manuais.
+- Automacoes novas devem preferir dados dinamicos via services/presets quando
+  precisarem ser independentes.
+- Se uma migration de seed mudar algum ID fixo, atualize este README e a
+  collection Postman na mesma PR.
diff --git a/api/docs/database-model.md b/api/docs/database-model.md
index 3a024dd..747e0b0 100644
--- a/api/docs/database-model.md
+++ b/api/docs/database-model.md
@@ -1,146 +1,117 @@
-# Modelo de banco inicial - Meveum
-
-Objetivo: suportar um cardapio digital e sistema de pedidos no estilo Anota Ai,
-com multi-tenancy por loja, checkout via WhatsApp e painel de controle para o
-lojista.
-
-## Decisoes principais
-
-- Cada loja e um tenant. Quase todas as tabelas de negocio carregam `store_id`.
-- O slug da loja e unico e usado para carregar o cardapio publico.
-- Produto, categoria e complementos usam `active` para esconder sem perder
-  historico.
-- Pedido salva snapshot de nome, preco e complementos, porque o cardapio pode
-  mudar depois que o pedido foi feito.
-- Horario de funcionamento aceita varios periodos por dia para permitir pausa
-  entre almoco e jantar.
-- Entrega comeca flexivel: bairro, faixa de CEP ou raio.
-- Pagamento aceito pela loja fica separado da forma escolhida no pedido.
-
-## Tabelas base
-
-### stores
-
-Representa o tenant/loja.
-
-Campos principais:
+# Modelo de dados - MeVeUm
+
+Modelo relacional atual da API, baseado nas migrations Flyway de
+`V1__create_initial_schema.sql` a `V13__add_product_available_field.sql`.
+
+## Principios
+
+- Cada loja e um tenant; `store_id` separa os dados de negocio.
+- O slug da loja carrega o cardapio publico.
+- Catalogo usa remocao logica com `active`.
+- Produto tem `available` separado de `active` para pausar venda sem excluir.
+- Pedido salva snapshots de produto, complemento, endereco e mensagem para
+  preservar historico.
+- Agregados de dashboard sao calculados por query/service, nao persistidos em
+  colunas totalizadoras.
+- Flyway e a unica fonte de evolucao do schema; Hibernate roda em
+  `ddl-auto=validate`.
+
+## Historico de migrations
+
+| Versao | Objetivo |
+|---|---|
+| `V1` | Cria schema inicial |
+| `V2` | Insere loja e usuario base |
+| `V3` | Insere categoria/produto base |
+| `V4` | Insere complementos base |
+| `V5` | Insere area de entrega |
+| `V6` | Insere forma de pagamento |
+| `V7` | Insere cliente/endereco |
+| `V8` | Insere pedido completo |
+| `V9` | Insere usuario autenticavel |
+| `V10` | Vincula grupo de complemento ao produto |
+| `V11` | Cria `password_reset_tokens` |
+| `V12` | Adiciona `phone`, `address`, `description`, `pix_key` em `stores` |
+| `V13` | Adiciona `available` em `products` |
+
+## Tabelas
+
+### Loja e autenticacao
+
+| Tabela | Papel |
+|---|---|
+| `stores` | Tenant/loja, perfil publico e status operacional |
+| `store_users` | Usuarios administrativos da loja |
+| `password_reset_tokens` | Tokens de recuperacao de senha |
+
+### Operacao da loja
+
+| Tabela | Papel |
+|---|---|
+| `store_opening_periods` | Periodos de funcionamento por dia |
+| `store_delivery_zones` | Areas, taxas, pedido minimo e prazo |
+| `store_payment_methods` | Formas de pagamento aceitas |
+
+### Catalogo
+
+| Tabela | Papel |
+|---|---|
+| `categories` | Categorias do cardapio |
+| `products` | Produtos e disponibilidade |
+| `complement_groups` | Grupos de complementos |
+| `complement_options` | Opcoes dentro dos grupos |
+| `product_complement_groups` | Vinculo N:N entre produtos e grupos |
+
+### CRM e pedidos
+
+| Tabela | Papel |
+|---|---|
+| `customers` | Cliente final por loja |
+| `customer_addresses` | Enderecos do cliente |
+| `orders` | Pedido e snapshots principais |
+| `order_items` | Itens do pedido com snapshot do produto |
+| `order_item_complements` | Complementos escolhidos no item |
+
+## Campos principais
+
+### `stores`
 
 - `id`
 - `name`
 - `slug`
 - `logo_url`
 - `whatsapp_number`
-- `status`
+- `phone`
+- `address`
+- `description`
+- `pix_key`
+- `status`: `ACTIVE`, `INACTIVE`
 - `manually_paused`
 - `created_at`
 - `updated_at`
 
-Observacoes:
-
-- `slug` deve ser unico.
-- `status`: `ACTIVE`, `INACTIVE`.
-- `manually_paused` atende o botao de pausa da loja.
-
-### store_users
-
-Usuarios administrativos da loja.
-
-Campos principais:
+### `store_users`
 
 - `id`
 - `store_id`
 - `name`
 - `email`
 - `password_hash`
-- `role`
+- `role`: `OWNER`, `MANAGER`, `STAFF`
 - `active`
 - `created_at`
 - `updated_at`
 
-Observacoes:
-
-- `email` deve ser unico globalmente no MVP.
-- `role`: `OWNER`, `MANAGER`, `STAFF`.
-
-### store_opening_periods
-
-Periodos de funcionamento.
-
-Campos principais:
-
-- `id`
-- `store_id`
-- `day_of_week`
-- `opens_at`
-- `closes_at`
-- `active`
-
-Observacoes:
-
-- `day_of_week`: 1 a 7, seguindo ISO: segunda=1, domingo=7.
-- Permite mais de um periodo no mesmo dia.
-
-### store_delivery_zones
-
-Areas e taxas de entrega.
-
-Campos principais:
-
-- `id`
-- `store_id`
-- `name`
-- `type`
-- `neighborhood`
-- `zip_code_start`
-- `zip_code_end`
-- `radius_km`
-- `fee`
-- `minimum_order_value`
-- `estimated_minutes`
-- `active`
-
-Observacoes:
-
-- `type`: `NEIGHBORHOOD`, `ZIP_RANGE`, `RADIUS`.
-- Nem todos os campos sao obrigatorios para todos os tipos.
-
-### store_payment_methods
-
-Formas de pagamento aceitas pela loja.
-
-Campos principais:
-
-- `id`
-- `store_id`
-- `method`
-- `active`
-
-Observacoes:
-
-- `method`: `PIX`, `CREDIT_CARD_DELIVERY`, `DEBIT_CARD_DELIVERY`, `CASH`.
-
-## Catalogo
-
-### categories
-
-Categorias do cardapio.
-
-Campos principais:
+### `password_reset_tokens`
 
 - `id`
-- `store_id`
-- `name`
-- `description`
-- `sort_order`
-- `active`
+- `store_user_id`
+- `token`
+- `expires_at`
+- `used_at`
 - `created_at`
-- `updated_at`
-
-### products
-
-Produtos do cardapio.
 
-Campos principais:
+### `products`
 
 - `id`
 - `store_id`
@@ -151,120 +122,20 @@ Campos principais:
 - `image_url`
 - `sort_order`
 - `active`
+- `available`
 - `created_at`
 - `updated_at`
 
-Observacoes:
-
-- Produto pertence a uma categoria.
-- `store_id` tambem fica no produto para consultas rapidas por loja.
-
-### complement_groups
-
-Grupos de complementos, como "Adicionais" ou "Escolha o ponto".
-
-Campos principais:
-
-- `id`
-- `store_id`
-- `name`
-- `description`
-- `min_quantity`
-- `max_quantity`
-- `sort_order`
-- `active`
-- `created_at`
-- `updated_at`
-
-Observacoes:
-
-- `min_quantity > 0` torna o grupo obrigatorio.
-- `max_quantity` controla limite de selecao.
-
-### complement_options
-
-Opcoes dentro de um grupo de complementos.
-
-Campos principais:
-
-- `id`
-- `store_id`
-- `complement_group_id`
-- `name`
-- `description`
-- `additional_price`
-- `sort_order`
-- `active`
-
-### product_complement_groups
-
-Vinculo N:N entre produto e grupo de complemento.
-
-Campos principais:
-
-- `id`
-- `product_id`
-- `complement_group_id`
-- `sort_order`
-- `active`
-
-Observacoes:
-
-- Permite reutilizar o mesmo grupo em varios produtos.
-
-## Checkout e pedidos
-
-### customers
-
-Cliente final. Pode ser simples no MVP.
-
-Campos principais:
-
-- `id`
-- `store_id`
-- `name`
-- `phone`
-- `created_at`
-- `updated_at`
-
-Observacoes:
-
-- Mesmo telefone pode existir em lojas diferentes.
-
-### customer_addresses
-
-Enderecos salvos ou usados em pedidos.
-
-Campos principais:
-
-- `id`
-- `customer_id`
-- `label`
-- `street`
-- `number`
-- `complement`
-- `neighborhood`
-- `city`
-- `state`
-- `zip_code`
-- `reference`
-- `latitude`
-- `longitude`
-
-### orders
-
-Pedido gerado no checkout e usado no painel do lojista.
-
-Campos principais:
+### `orders`
 
 - `id`
 - `store_id`
 - `customer_id`
 - `customer_name`
 - `customer_phone`
-- `fulfillment_type`
-- `status`
-- `payment_method`
+- `fulfillment_type`: `DELIVERY`, `PICKUP`
+- `status`: `NEW`, `PREPARING`, `OUT_FOR_DELIVERY`, `DONE`, `CANCELED`
+- `payment_method`: `PIX`, `CREDIT_CARD_DELIVERY`, `DEBIT_CARD_DELIVERY`, `CASH`
 - `subtotal`
 - `delivery_fee`
 - `discount_total`
@@ -277,55 +148,41 @@ Campos principais:
 - `created_at`
 - `updated_at`
 
-Observacoes:
-
-- `fulfillment_type`: `DELIVERY`, `PICKUP`.
-- `status`: `NEW`, `PREPARING`, `OUT_FOR_DELIVERY`, `DONE`, `CANCELED`.
-- `delivery_address_snapshot` pode ser `jsonb` no PostgreSQL.
-- `whatsapp_message` guarda o texto enviado/gerado para auditoria.
-
-### order_items
-
-Itens do pedido com snapshot do produto.
-
-Campos principais:
-
-- `id`
-- `order_id`
-- `product_id`
-- `product_name`
-- `unit_price`
-- `quantity`
-- `total`
-- `note`
-
-### order_item_complements
-
-Complementos escolhidos em um item do pedido.
+## Diagrama ER
 
-Campos principais:
+```mermaid
+erDiagram
+    STORES ||--o{ STORE_USERS : possui
+    STORES ||--o{ STORE_OPENING_PERIODS : configura
+    STORES ||--o{ STORE_DELIVERY_ZONES : atende
+    STORES ||--o{ STORE_PAYMENT_METHODS : aceita
+    STORES ||--o{ CATEGORIES : organiza
+    STORES ||--o{ PRODUCTS : vende
+    STORES ||--o{ COMPLEMENT_GROUPS : define
+    STORES ||--o{ CUSTOMERS : atende
+    STORES ||--o{ ORDERS : recebe
+    STORE_USERS ||--o{ PASSWORD_RESET_TOKENS : gera
 
-- `id`
-- `order_item_id`
-- `complement_group_id`
-- `complement_group_name`
-- `complement_option_id`
-- `complement_option_name`
-- `unit_price`
-- `quantity`
-- `total`
+    CATEGORIES ||--o{ PRODUCTS : contem
+    COMPLEMENT_GROUPS ||--o{ COMPLEMENT_OPTIONS : contem
+    PRODUCTS ||--o{ PRODUCT_COMPLEMENT_GROUPS : usa
+    COMPLEMENT_GROUPS ||--o{ PRODUCT_COMPLEMENT_GROUPS : vincula
 
-## Modelo visual simplificado
+    CUSTOMERS ||--o{ CUSTOMER_ADDRESSES : possui
+    CUSTOMERS ||--o{ ORDERS : faz
+    ORDERS ||--o{ ORDER_ITEMS : contem
+    ORDER_ITEMS ||--o{ ORDER_ITEM_COMPLEMENTS : possui
 
-```mermaid
-```mermaid
-erDiagram
     STORES {
         uuid id PK
         varchar name
         varchar slug UK
         varchar logo_url
         varchar whatsapp_number
+        varchar phone
+        varchar address
+        varchar description
+        varchar pix_key
         varchar status
         boolean manually_paused
         timestamptz created_at
@@ -342,6 +199,15 @@ erDiagram
         boolean active
     }
 
+    PASSWORD_RESET_TOKENS {
+        uuid id PK
+        uuid store_user_id FK
+        varchar token
+        timestamptz expires_at
+        timestamptz used_at
+        timestamptz created_at
+    }
+
     STORE_OPENING_PERIODS {
         uuid id PK
         uuid store_id FK
@@ -361,6 +227,8 @@ erDiagram
         varchar zip_code_end
         numeric radius_km
         numeric fee
+        numeric minimum_order_value
+        integer estimated_minutes
         boolean active
     }
 
@@ -375,6 +243,7 @@ erDiagram
         uuid id PK
         uuid store_id FK
         varchar name
+        varchar description
         integer sort_order
         boolean active
     }
@@ -389,12 +258,14 @@ erDiagram
         varchar image_url
         integer sort_order
         boolean active
+        boolean available
     }
 
     COMPLEMENT_GROUPS {
         uuid id PK
         uuid store_id FK
         varchar name
+        varchar description
         integer min_quantity
         integer max_quantity
         integer sort_order
@@ -406,6 +277,7 @@ erDiagram
         uuid store_id FK
         uuid complement_group_id FK
         varchar name
+        varchar description
         numeric additional_price
         integer sort_order
         boolean active
@@ -424,13 +296,17 @@ erDiagram
         uuid store_id FK
         varchar name
         varchar phone
+        timestamptz created_at
+        timestamptz updated_at
     }
 
     CUSTOMER_ADDRESSES {
         uuid id PK
         uuid customer_id FK
+        varchar label
         varchar street
         varchar number
+        varchar complement
         varchar neighborhood
         varchar city
         varchar state
@@ -448,6 +324,7 @@ erDiagram
         varchar payment_method
         numeric subtotal
         numeric delivery_fee
+        numeric discount_total
         numeric total
         boolean needs_change
         numeric change_for
@@ -463,6 +340,7 @@ erDiagram
         numeric unit_price
         integer quantity
         numeric total
+        varchar note
     }
 
     ORDER_ITEM_COMPLEMENTS {
@@ -476,58 +354,21 @@ erDiagram
         integer quantity
         numeric total
     }
+```
 
-    STORES ||--o{ STORE_USERS : possui
-    STORES ||--o{ STORE_OPENING_PERIODS : configura
-    STORES ||--o{ STORE_DELIVERY_ZONES : atende
-    STORES ||--o{ STORE_PAYMENT_METHODS : aceita
-    STORES ||--o{ CATEGORIES : organiza
-    STORES ||--o{ PRODUCTS : vende
-    STORES ||--o{ COMPLEMENT_GROUPS : define
-    STORES ||--o{ CUSTOMERS : atende
-    STORES ||--o{ ORDERS : recebe
+## Indices e restricoes importantes
 
-    CATEGORIES ||--o{ PRODUCTS : contem
-    COMPLEMENT_GROUPS ||--o{ COMPLEMENT_OPTIONS : contem
-    PRODUCTS ||--o{ PRODUCT_COMPLEMENT_GROUPS : usa
-    COMPLEMENT_GROUPS ||--o{ PRODUCT_COMPLEMENT_GROUPS : vincula
-
-    CUSTOMERS ||--o{ CUSTOMER_ADDRESSES : possui
-    CUSTOMERS ||--o{ ORDERS : faz
+- `stores.slug` unico.
+- `store_users.email` unico globalmente no MVP.
+- `customers (store_id, phone)` unico.
+- `store_payment_methods (store_id, method)` unico.
+- `product_complement_groups (product_id, complement_group_id)` unico.
+- Indices por `store_id`, `status`, `created_at`, `category_id`, `phone` e
+  relacionamentos de pedido otimizam listagens e dashboard.
 
-    ORDERS ||--o{ ORDER_ITEMS : contem
-    ORDER_ITEMS ||--o{ ORDER_ITEM_COMPLEMENTS : possui
+## Seeds de desenvolvimento
 
-```
-```
+Os dados fixos estao documentados em [`../dados/README.md`](../dados/README.md).
 
-## MVP recomendado
-
-Comecar com:
-
-- `stores`
-- `store_users`
-- `store_opening_periods`
-- `store_delivery_zones`
-- `store_payment_methods`
-- `categories`
-- `products`
-- `complement_groups`
-- `complement_options`
-- `product_complement_groups`
-- `customers`
-- `customer_addresses`
-- `orders`
-- `order_items`
-- `order_item_complements`
-
-Deixar para depois:
-
-- cupons/descontos avancados
-- promocoes por horario
-- estoque
-- impressao de pedido
-- integracao com pagamento online
-- notificacoes reais por WhatsApp API
-- multi-filial
-- plano/assinatura da loja
+Esses dados ajudam em Postman e testes manuais, mas automacoes novas devem criar
+dados dinamicos quando precisarem de isolamento.
diff --git a/automations/README.md b/automations/README.md
new file mode 100644
index 0000000..9ec1c5c
--- /dev/null
+++ b/automations/README.md
@@ -0,0 +1,266 @@
+# MeVeUm Automations
+
+Automacoes Playwright do MeVeUm. Este modulo cobre contratos de API,
+comportamento observavel no frontend e jornadas E2E criticas com validacao de
+banco quando ha escrita de dados.
+
+## Stack
+
+| Tecnologia | Uso |
+|---|---|
+| Playwright 1.60+ | Browser, APIRequestContext, traces e relatorios |
+| JavaScript ESM | Specs, pages, fixtures e services |
+| `pg` | Validacao direta no PostgreSQL em fluxos E2E |
+
+## Metricas atuais
+
+Estado da suite nesta revisao:
+
+| Camada | Specs | Testes | Objetivo |
+|---|---:|---:|---|
+| API | 12 | 41 | Contratos HTTP, CRUD, negativos e isolamento |
+| Frontend | 9 | 23 | Comportamento observavel no browser |
+| E2E | 4 | 6 | Jornada completa browser + API + banco |
+| Total | 25 | 70 | Suite completa |
+
+Ao adicionar ou remover cenarios relevantes, atualize esta tabela.
+
+## Como rodar
+
+Com API e web ja rodando:
+
+```bash
+npm ci
+npx playwright install chromium
+npm test
+```
+
+Por camada:
+
+```bash
+npm run test:api
+npm run test:frontend
+npm run test:e2e
+```
+
+Por tag:
+
+```bash
+npm run test:smoke
+npm run test:regressao
+npm run test:negativo
+npm run test:contrato
+```
+
+Abrir o relatorio local:
+
+```bash
+npm run report
+```
+
+## URLs e variaveis
+
+`playwright.config.js` usa:
+
+| Variavel | Default | Uso |
+|---|---|---|
+| `WEB_BASE_URL` | `http://localhost:3000` | Projetos `chrome` e `e2e` |
+| `API_BASE_URL` | `http://127.0.0.1:8080` | Projeto `rest` |
+| `PGHOST` ou `DB_HOST` | `127.0.0.1` | PostgreSQL |
+| `PGPORT` ou `DB_PORT` | `5432` | PostgreSQL |
+| `PGDATABASE` ou `DB_NAME` | `meveum` | PostgreSQL |
+| `PGUSER` ou `DB_USER` | `meveum` | PostgreSQL |
+| `PGPASSWORD` ou `DB_PASSWORD` | `meveum` | PostgreSQL |
+| `DB_ASSERT_TIMEOUT` | `10000` | Retry das validacoes de banco |
+
+## Projetos Playwright
+
+| Projeto | `testMatch` | O que cobre |
+|---|---|---|
+| `rest` | `tests/api/**/*.spec.js` | API via `request` |
+| `chrome` | `tests/frontend/**/*.spec.js` | Browser em Desktop Chrome |
+| `e2e` | `tests/e2e/**/*.spec.js` | Browser + API + banco |
+
+Configuracao padrao:
+
+- `fullyParallel: true`;
+- `retries: 2`;
+- `workers: 1` no CI;
+- `trace: on`;
+- `screenshot: on`;
+- `video: on-first-retry`;
+- timeout de teste: 120s;
+- timeout de expect: 10s.
+
+## Estrutura
+
+```text
+automations/
+|-- tests/
+|   |-- api/        Specs de contrato e integracao HTTP
+|   |-- frontend/   Specs de comportamento no browser
+|   `-- e2e/        Jornadas criticas completas
+|-- pages/          Page Objects: DOM e interacoes
+|-- services/       HTTP, banco e fluxos reutilizaveis
+|-- fixtures/       Injecao de pages, services e presets
+|-- presets/        Estados prontos de teste via API/fluxos reais
+|-- data/           Builders e massa previsivel
+`-- playwright.config.js
+```
+
+## Padrao de responsabilidade
+
+| Pasta | Pode fazer | Nao pode fazer |
+|---|---|---|
+| `tests/` | Orquestrar cenario e chamar fixtures/pages/services | Montar payload complexo, SQL, DOM solto |
+| `pages/` | Clicar, preencher, navegar, validar DOM | Chamar API, banco ou montar regra de negocio |
+| `services/` | Chamar API, banco, preparar massa, validar contratos | Acessar DOM |
+| `fixtures/` | Instanciar dependencias e controlar setup/teardown | Ter assercao de negocio grande |
+| `presets/` | Criar estado reutilizavel por fluxo real | Depender de seed fixa quando precisa isolamento |
+| `data/` | Builders de payload e valores previsiveis | Chamadas HTTP ou SQL |
+
+## Metodos padrao
+
+### Page Objects
+
+Use nomes orientados a comportamento:
+
+```js
+async abrir() {}
+async validarLista() {}
+async abrirCriacao() {}
+async salvar(payload) {}
+async buscar(termo) {}
+```
+
+Regras:
+
+- locators ficam no constructor;
+- specs nao usam `page.getBy...` diretamente;
+- validacoes de tela ficam em metodos `validar*`;
+- acoes ficam em metodos verbais;
+- nao usar `waitForTimeout`.
+
+### Services de API
+
+Services encapsulam endpoints e retornam response/body pronto:
+
+```js
+async criarProduto(payload) {}
+async listarProdutos(params) {}
+async detalharProduto(id) {}
+```
+
+Use helpers de `contract.service.js`:
+
+- `esperarStatus`
+- `esperarStatusEJson`
+- `esperarCampos`
+- `esperarCamposPresentes`
+- `esperarListaComItem`
+- `esperarListaNaoVazia`
+- `esperarErro`
+
+### DatabaseService
+
+Toda validacao direta de banco fica em `services/database.service.js`.
+
+Padrao atual:
+
+- `validarComRetry` usa `expect(...).toPass`;
+- intervalos: `100ms`, `250ms`, `500ms`, `1000ms`;
+- timeout configuravel por `DB_ASSERT_TIMEOUT`;
+- consultas usam `buscarUm` e `buscarTodos`;
+- specs nunca escrevem SQL direto.
+
+Use retry quando a validacao depende de escrita assincrona ou de propagacao
+entre UI, API e banco.
+
+## Tags obrigatorias
+
+Toda spec deve declarar tags no segundo argumento do `test`:
+
+```js
+test('cria pedido pickup', { tag: ['@e2e', '@smoke', '@regressao'] }, async ({}) => {})
+```
+
+Tags usadas:
+
+| Tag | Uso |
+|---|---|
+| `@api` | Contrato/integracao HTTP |
+| `@frontend` | Browser sem validacao direta de banco |
+| `@e2e` | Jornada completa |
+| `@smoke` | Sinal principal de saude |
+| `@regressao` | Cobertura de comportamento existente |
+| `@contrato` | Contrato HTTP ou DOM/fluxo estavel |
+| `@negativo` | Erro, bloqueio ou validacao |
+
+## Estrategia de cenarios
+
+Evite explosao combinatoria. Cubra cada variacao no nivel mais barato.
+
+Exemplo:
+
+- API cobre combinacoes de payload, validacao e status HTTP.
+- Frontend cobre renderizacao, navegacao e validacao visivel.
+- E2E cobre poucos caminhos que provam a integracao ponta a ponta.
+
+Se uma pagina tem cenarios A, B e C, nao gere todas as permutacoes por reflexo.
+Monte caminhos que exercitem os comportamentos sem duplicar o que a camada de
+baixo ja provou.
+
+## Validacao de banco
+
+Fluxos E2E que criam ou alteram dados devem validar persistencia:
+
+- usuario e loja criados;
+- token de recuperacao gerado/usado;
+- produto criado, indisponibilizado ou removido;
+- cliente e endereco persistidos;
+- pedido, itens e status persistidos;
+- dados de configuracao da loja persistidos.
+
+SQL pertence a `DatabaseService`. Specs chamam metodos de dominio, por exemplo:
+
+```js
+await databaseService.validarPedidoCriado({ lojaId, checkout, tipo, produtoId });
+```
+
+## Seletores e contrato visual
+
+`data-testid` e contrato entre frontend e automacao. Nao renomeie nem remova sem
+migracao coordenada.
+
+Tambem nao e permitido validar elemento invisivel apenas para manter teste
+verde. Se o usuario nao enxerga ou nao consegue usar o elemento, ele nao faz
+parte do contrato ativo. Documente a pendencia e reative quando o elemento
+voltar visivel.
+
+## Relatorios e artefatos
+
+Localmente, Playwright gera:
+
+- `playwright-report/`
+- `test-results/`
+- traces, screenshots e videos quando configurado.
+
+Esses arquivos nao devem ser commitados.
+
+No GitHub Actions:
+
+- `playwright-report` e publicado sempre;
+- `playwright-test-results` e publicado em falha;
+- logs da API e web sao publicados em falha.
+
+## Checklist antes de PR
+
+- Specs usam fixtures locais.
+- Specs nao contem SQL, DOM solto ou payload grande.
+- Page Objects centralizam locators.
+- Services centralizam API/banco.
+- E2E valida banco quando escreve dado.
+- Tags estao no formato `{ tag: [...] }`.
+- Nao ha `test.skip`, `test.fail` ou bypass silencioso.
+- Nao ha `waitForTimeout`.
+- Nao ha dependencia de conta hardcoded para novos cenarios.
diff --git a/web/README.md b/web/README.md
index e215bc4..a46c9bf 100644
--- a/web/README.md
+++ b/web/README.md
@@ -1,36 +1,224 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# MeVeUm Web
 
-## Getting Started
+Frontend Next.js do MeVeUm. Este modulo entrega a landing page, fluxos de
+autenticacao, painel administrativo do lojista e cardapio publico por slug.
 
-First, run the development server:
+## Stack
+
+| Tecnologia | Uso |
+|---|---|
+| Next.js 16.2.6 | App Router, build e server |
+| React 19.2.4 | UI |
+| TypeScript 5 | Tipagem |
+| Tailwind CSS 4 | Estilizacao |
+| Radix UI | Componentes acessiveis |
+| React Hook Form + Zod | Formularios e validacao |
+| Lucide React | Icones |
+| Sonner | Toasts |
+| Vitest + Testing Library | Testes unitarios/comportamentais |
+
+## Como rodar
 
 ```bash
+npm ci
+cp .env.local.example .env.local
+npm run dev
+```
+
+No Windows PowerShell:
+
+```powershell
+npm ci
+Copy-Item .env.local.example .env.local
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+URL local:
+
+- `http://localhost:3000`
+
+Variavel principal:
+
+```env
+NEXT_PUBLIC_API_URL=http://localhost:8080
+```
+
+## Scripts
+
+| Script | Uso |
+|---|---|
+| `npm run dev` | Sobe o Next em desenvolvimento |
+| `npm run build` | Valida TypeScript e gera build de producao |
+| `npm run start` | Sobe a build produzida |
+| `npm test` | Roda Vitest uma vez |
+| `npm run test:watch` | Roda Vitest em watch |
+| `npm run lint` | Roda ESLint |
+
+## Rotas
+
+| Rota | Descricao |
+|---|---|
+| `/` | Landing page |
+| `/login` | Login |
+| `/register` | Cadastro |
+| `/esqueci-senha` | Solicitacao de recuperacao |
+| `/redefinir-senha` | Redefinicao de senha |
+| `/dashboard` | Resumo operacional |
+| `/dashboard/cardapio` | Produtos do cardapio |
+| `/dashboard/cardapio/categorias` | Categorias |
+| `/dashboard/cardapio/complementos` | Complementos |
+| `/dashboard/clientes` | CRM |
+| `/dashboard/configuracoes` | Dados da loja, horarios e entrega |
+| `/dashboard/configuracoes/pagamentos` | Formas de pagamento |
+| `/dashboard/pedidos` | Pedidos |
+| `/[slug]` | Cardapio publico da loja |
+| `/termos-de-uso` | Termos |
+| `/politica-de-privacidade` | Politica |
+
+## Estrutura
+
+```text
+src/
+|-- app/                         Rotas App Router
+|   |-- (auth)/                  Login, cadastro e recuperacao
+|   |-- (dashboard)/dashboard/   Painel administrativo
+|   |-- [slug]/                  Cardapio publico
+|   `-- page.tsx                 Landing
+|-- components/
+|   |-- layout/                  Sidebar e Topbar
+|   |-- shared/                  Componentes reutilizaveis do produto
+|   `-- ui/                      Primitivos de UI
+|-- features/
+|   |-- auth/                    Sessao autenticada e carousel
+|   |-- cardapio-publico/        Carrinho, vitrine e checkout publico
+|   `-- dashboard/               Componentes do dashboard
+|-- lib/
+|   |-- api/                     Clients por dominio
+|   |-- utils/                   Helpers puros
+|   `-- validations/             Schemas Zod
+|-- tests/                       Testes Vitest
+`-- types/                       Tipos compartilhados
+```
+
+## Cliente HTTP
+
+Arquivo base: `src/lib/api/client.ts`.
+
+Responsabilidades:
+
+- resolver `BASE_URL` via `NEXT_PUBLIC_API_URL`;
+- padronizar `Content-Type`;
+- extrair mensagens de erro da API;
+- persistir/remover sessao em `localStorage`;
+- anexar `Authorization: Bearer <token>` em chamadas autenticadas;
+- resolver `lojaId` a partir do usuario salvo.
+
+Services por dominio ficam em `src/lib/api/*.api.ts`:
+
+| Arquivo | Dominio |
+|---|---|
+| `auth.api.ts` | Login, cadastro, recuperacao e usuario atual |
+| `cardapio.api.ts` | Produtos e categorias administrativas |
+| `cardapio-publico.api.ts` | Loja publica e produtos por slug |
+| `clientes.api.ts` | Clientes e enderecos |
+| `complementos.api.ts` | Grupos/opcoes de complemento |
+| `configuracoes.api.ts` | Loja, horarios e areas de entrega |
+| `dashboard.api.ts` | Resumo, grafico, KDS e rankings |
+| `pagamentos.api.ts` | Formas de pagamento |
+| `pedidos.api.ts` | Listagem, detalhe e status |
+
+Regra: componente/page nao deve chamar `fetch` direto. Chamada HTTP passa por
+service de `lib/api`.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## Estado de sessao
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Chaves usadas no browser:
 
-## Learn More
+| Chave | Conteudo |
+|---|---|
+| `meveum_token` | JWT retornado pelo login/cadastro |
+| `meveum_usuario` | Usuario autenticado serializado |
 
-To learn more about Next.js, take a look at the following resources:
+`SessaoAutenticadaContext` centraliza restauracao da sessao, logout e protecao
+do dashboard.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Formularios e validacao
+
+Schemas Zod ficam em `src/lib/validations`.
+
+Padrao esperado:
+
+- schema separado por dominio;
+- mensagem de erro por campo;
+- `data-testid` em input, botao, form e erro relevante;
+- estado de loading/submitting;
+- feedback de sucesso/erro;
+- teste cobrindo validacao comportamental.
+
+## Componentes e layout
+
+Padrao de UI:
+
+- componentes de `components/ui` sao pequenos e reutilizaveis;
+- componentes de `components/shared` carregam semantica do produto;
+- `features/*/components` contem UI especifica de uma jornada;
+- pages montam a tela, mas nao devem concentrar regra complexa.
+
+Evite teste estetico. Testes devem validar comportamento observavel: item
+aparece, botao chama acao, formulario bloqueia dado invalido, estado vazio
+renderiza, navegacao ocorre.
+
+## `data-testid`
+
+`data-testid` e contrato publico com automacoes e testes. Nao renomeie nem
+remova sem migracao coordenada.
+
+Tambem e proibido manter `data-testid` em elemento invisivel ou fora da jornada
+real apenas para a automacao passar. Se a funcionalidade ainda nao esta pronta:
+
+1. remova o elemento do contrato ativo;
+2. deixe TODO/issue descrevendo o contrato futuro;
+3. reative o `data-testid` quando o elemento voltar visivel e utilizavel.
+
+## Testes
+
+```bash
+npm test
+```
+
+Estado atual:
+
+- Vitest com ambiente `jsdom`;
+- setup em `src/tests/setup.ts`;
+- aliases `@/*` configurados no `vitest.config.ts`;
+- testes de componentes compartilhados, schemas e clients de API.
+
+Para mudancas de UI:
+
+- rode `npm test`;
+- rode `npm run build` quando tocar rota, tipo, schema, client ou config;
+- rode Playwright afetado em `automations/` se mudar comportamento usado por
+  usuario.
+
+## Build
+
+```bash
+npm run build
+npm run start
+```
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+No CI, o job `Web - testes e build` executa:
 
-## Deploy on Vercel
+1. `npm ci`
+2. `npm test`
+3. `npm run build`
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## Checklist antes de PR
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+- API client atualizado se o endpoint mudou.
+- Tipo em `src/types` alinhado ao DTO da API.
+- Formulario com schema e mensagens.
+- Estado loading/erro/vazio quando aplicavel.
+- `data-testid` apenas em elemento real da jornada.
+- Teste unitario/comportamental atualizado.
+- Build local passando quando houver mudanca estrutural.