# Módulo de Vendas — Plano e Cronograma

Este documento descreve o cronograma, escopo funcional, integrações, validações de negócio e o fluxo de trabalho do módulo de Vendas, alinhado à arquitetura atual do projeto e aos módulos existentes (`Produtos`, `Clientes`, `Auth`, `Audit`, `Tenant`, `PDV`).

## Objetivos
- Disponibilizar orçamentos (orcamentos), pedidos de venda (pedidos) e PDV com cálculos confiáveis de preço, descontos, impostos e movimentação de estoque.
- Garantir segurança por RBAC e trilha de auditoria nas operações críticas.
- Oferecer APIs e telas consistentes para os fluxos de venda, com performance e paginação.

## Cronograma (estimativa)
- Iteração 1 (3–5 dias)
  - Modelagem e migrações de dados para Vendas (orcamentos, pedidos, itens, pagamentos, status)
  - Endpoints CRUD básicos e listagens com paginação
  - Regras de cálculo preliminares e integrações com `Produtos` e `Clientes`
- Iteração 2 (3–5 dias)
  - Validações de negócio (estoque, descontos, limites), auditoria e RBAC
  - Finalização de fluxo de pedidos (criar → aprovar → faturar) e ajustes de estoque
  - Relatórios básicos (por período, cliente, produto)
- Iteração 3 (3–5 dias)
  - PDV: finalizar fluxo de venda, pagamentos e fechamento de caixa
  - Otimizações de busca e responsividade em UI
  - Testes de integração e performance
- Iteração 4 (opcional, 3–5 dias)
  - Integrações externas (ex.: emissão de NF-e, gateways de pagamento)
  - Relatórios avançados e exportações

## Backlog principal (alto nível)
- Orçamentos (orcamentos)
  - Criar/editar/excluir orçamentos e seus itens
  - Converter orçamento em pedido
- Pedidos de venda (pedidos)
  - Criar/editar/excluir pedidos e seus itens
  - Cálculo de totais, descontos, impostos
  - Faturar/emitir (alterar status e movimentar estoque)
  - Registrar pagamentos (métodos, parcelas, troco no PDV)
- PDV
  - Busca de produtos (concluída)
  - Registrar venda, pagamentos, impressão (opcional)
  - Fechamento de caixa (já iniciado)
- Relatórios e consultas
  - Vendas por período, cliente, produto
  - Auditoria de operações
- Segurança, multi-tenant, auditoria
  - RBAC por ação (ex.: `vendas.create`, `vendas.read`)
  - AuditLogger em operações-chave
  - Migrations por tenant

## Fluxos de trabalho alvo
- Orçamento: criar rascunho → adicionar itens → aplicar descontos → aprovar → converter em pedido
- Pedido: criar → confirmar → faturar → movimentar estoque → registrar pagamento(s) → finalizar
- PDV: buscar produto → adicionar itens → registrar pagamento → gerar movimentação de estoque → fechar caixa diário

## Integrações necessárias
- `Produtos`: preço, estoque, mídia, índices de busca; movimentação via `inventory_movements`
- `Clientes`: cadastro, endereços, condições comerciais
- `Auth/RBAC`: autenticação e permissões finas
- `Audit`: log de criação, leitura, atualização e fechamento
- `Tenant`: migrations por tenant (`schema_migrations`)

## Validações de negócio
- Estoque disponível (bloquear venda quando crítico ou permitir saldo negativo conforme configuração)
- Descontos máximos por perfil (ex.: gerente pode exceder, vendedor não)
- Preço mínimo por produto (margem/markup)
- Cliente ativo e válido (CPF/CNPJ, situação de crédito se aplicável)
- Impostos por NCM/CEST (quando aplicável ao escopo)

---

## Template para documentação de cada etapa (usar ao concluir cada entrega)
- Requisitos funcionais: …
- Fluxos de trabalho: …
- Integrações necessárias: …
- Validações de negócio: …

---

## Etapas concluídas (até agora)

### 1) Busca de produtos no PDV
- Requisitos funcionais
  - Endpoint `GET /api/pdv/produtos/search` com paginação (`page`, `per_page`)
  - Retornar `id`, `codigo`, `nome`, `estoque`, `preco`, `image_url`, localização (`corredor/prateleira/posição`), `location` formatado
  - Ordenação por relevância (match exato de código/EAN > prefixo de nome > contains)
- Fluxos de trabalho
  - View `views/vendas/pdv/index.php` envia consultas com debounce → API responde com resultados → UI renderiza itens responsivos
- Integrações necessárias
  - `Produtos` (tabelas `products`, `product_media`), `Tenant` (conexão por tenant), `Auth/RBAC` (perm. `pdv.read`), `Audit` (rastros já existentes em vendas/caixa)
- Validações de negócio
  - Requer autenticação + permissão `pdv.read`
  - Parâmetros validados (`per_page ≤ 50`, `page ≥ 1`)
  - Fallback de imagem para `/assets/no-image.svg`

### 2) Localização física de produtos (apoio ao PDV)
- Requisitos funcionais
  - Exibir localização de estoque (corredor, prateleira, posição) nos resultados de busca
- Fluxos de trabalho
  - Migração adiciona colunas no `products`; API lê e formata `location`
- Integrações necessárias
  - `Produtos` (migração `016_products_location.sql`), `Tenant` (aplicação de migrations)
- Validações de negócio
- Campos opcionais, não bloqueiam venda; formato amigável na UI

### 3) Modelagem de dados de Vendas (pedidos, itens, pagamentos)
- Requisitos funcionais
  - Tabelas: `sales_orders`, `sales_order_items`, `sales_payments`
  - Campos essenciais: número do pedido, cliente, valor total, status; itens com quantidade/preço/total; pagamentos com método/valor/troco
- Fluxos de trabalho
  - Criação de pedido com número sequencial por data; inclusão opcional de itens no ato da criação
  - Consulta de pedido com itens; registro de pagamentos vinculado ao pedido
- Integrações necessárias
  - `Clientes` (validação de `cliente_id`), `Produtos` (preço/itens), `Tenant` (migrations por tenant), `Audit` (já integrado no controller)
- Validações de negócio
  - `cliente_id` obrigatório e existente; quantidade > 0; total > 0 quando itens não informados
  - Status controlado (`aberto`, `confirmado`, `faturado`, `cancelado`)

### 4) Orçamentos — CRUD e conversão para Pedido
- Requisitos funcionais
  - Endpoints: `GET/POST/PUT/DELETE /api/vendas/orcamentos` e `POST /api/vendas/orcamentos/{id}/converter`
  - Campos: `numero`, `cliente_id`, `valor_total`, `status` (`rascunho`, `aprovado`, `expirado`, `cancelado`), `validade`; itens com `product_id`, `quantidade`, `preco`, `total`
- Fluxos de trabalho
  - Criar orçamento (com itens ou total informado) → editar → aprovar/expirar → converter para pedido
  - Conversão cria `sales_orders` + `sales_order_items` e marca orçamento como `aprovado`
- Integrações necessárias
  - `Clientes` (validação de cliente), `Produtos` (preço dos itens), `Vendas` (orders para conversão), `Tenant`, `Audit`, `Auth/RBAC`
- Validações de negócio
  - `cliente_id` obrigatório e existente; itens com quantidade > 0; `valor_total > 0` quando sem itens
  - Números gerados (`SQ-YYYYMMDD-HHMMSS`); controle de `validade` opcional

### 5) Faturamento de pedidos — baixa de estoque e status
- Requisitos funcionais
  - Endpoint: `POST /api/vendas/pedidos/{id}/faturar`
  - Ação: validar itens do pedido, verificar estoque, registrar movimentação e marcar pedido como `faturado`
- Fluxos de trabalho
  - Criar pedido → adicionar itens → (opcional) confirmar → faturar → estoque baixa → status `faturado`
- Integrações necessárias
  - `Produtos` (colunas `products.estoque`, tabela `inventory_movements`), `Tenant`, `Audit`, `Auth/RBAC`
- Validações de negócio
  - Pedido deve existir e não estar `faturado` ou `cancelado`
  - Pedido precisa de itens; bloquear quando não houver
  - Estoque suficiente para cada item; bloquear se insuficiente
  - Registrar auditoria da operação de faturamento

### 6) Pagamentos de pedidos — registrar recebimentos e resumo
- Requisitos funcionais
  - Endpoints: `GET /api/vendas/pedidos/{id}/pagamentos`, `POST /api/vendas/pedidos/{id}/pagamentos`, `DELETE /api/vendas/pagamentos/{id}`
  - Criar pagamentos com `metodo`, `valor`, `troco` (opcional) e listar com resumo (total pago, troco e restante)
- Fluxos de trabalho
  - Após faturar: registrar um ou mais pagamentos; listar para conciliação; excluir lançamento se necessário
- Integrações necessárias
  - `Vendas` (orders), `Tenant`, `Audit`, `Auth/RBAC`
- Validações de negócio
  - Pedido deve existir e não estar `cancelado`
  - `valor > 0`; `metodo` obrigatório; auditoria em todas as operações

---

## Próximas entregas sugeridas
- CRUD de pedidos com cálculo e status (ajustes adicionais)
- Pagamentos e conciliação (inclui PDV)
- Relatórios essenciais de vendas
- Testes de integração dos fluxos centrais