Aqui está o documento organizado e atualizado com as credenciais criadas via seeder:

```markdown
## Documentação do Sistema SG_STOCK

# SG_STOCK - Sistema de Gestão de Stock e Vendas


---

##  Visão Geral

O **SG_STOCK** é um sistema completo de gestão de stock e vendas desenvolvido para pequenas e médias empresas em Moçambique. O sistema permite:

- Gestão de produtos com controlo de validade e lotes
- Processamento de vendas com múltiplos métodos de pagamento
- Controlo de stock com movimentações (entradas/saídas)
- Gestão de clientes com controlo de crédito
- Gestão de fornecedores e encomendas
- Emissão de recibos PDF
- Relatórios gerenciais e fecho de caixa

---

## Tecnologias Utilizadas

### Frontend
| Tecnologia | Versão | Descrição |
|------------|--------|-----------|
| React | 18.2.0 | Biblioteca para construção da interface |
| TypeScript | 5.3.3 | Tipagem estática |
| Tailwind CSS | 3.3.0 | Framework de CSS |
| Axios | 1.16.1 | Cliente HTTP |
| React Router DOM | 7.16.0 | Roteamento |
| React Hot Toast | 2.6.0 | Notificações |
| Date-fns | 3.6.0 | Manipulação de datas |

### Backend
| Tecnologia | Versão | Descrição |
|------------|--------|-----------|
| Laravel | 12.56.0 | Framework PHP |
| MySQL | 8.0+ | Banco de dados relacional |
| Laravel Sanctum | - | Autenticação API |
| Spatie Permission | - | Controlo de permissões |
| DomPDF | - | Geração de PDF |

---

##  Estrutura do Projeto

```
SG_STOCK/
├── frontend/                      # Aplicação React
│   ├── src/
│   │   ├── components/            # Componentes reutilizáveis
│   │   │   ├── Layout/            # Layout principal e sidebar
│   │   │   ├── UI/                # Componentes de interface (Modal, Card, Loading)
│   │   │   └── Dashboard/         # Componentes específicos do dashboard
│   │   ├── pages/                 # Páginas da aplicação
│   │   │   ├── Stock/             # Gestão de stock
│   │   │   │   ├── Produtos.tsx
│   │   │   │   ├── Categorias.tsx
│   │   │   │   └── Movimentacoes.tsx
│   │   │   ├── Vendas/            # Gestão de vendas
│   │   │   │   ├── ProcessamentoVendas.tsx
│   │   │   │   └── HistoricoVendas.tsx
│   │   │   ├── Clientes.tsx       # Gestão de clientes
│   │   │   ├── Fornecedores.tsx   # Gestão de fornecedores
│   │   │   ├── Utilizadores.tsx   # Gestão de utilizadores
│   │   │   ├── Dashboard.tsx      # Painel principal
│   │   │   └── Login.tsx          # Autenticação
│   │   ├── contexts/              # Contextos React
│   │   │   ├── AuthContext.tsx    # Autenticação
│   │   │   └── ThemeContext.tsx   # Tema (claro/escuro)
│   │   ├── services/              # Serviços e API
│   │   │   └── api.ts             # Configuração Axios
│   │   ├── types/                 # Definições TypeScript
│   │   │   └── index.ts
│   │   └── styles/                # Estilos globais
│   │       └── index.css
│   ├── package.json
│   └── vite.config.ts
│
└── backend/                       # Aplicação Laravel
    ├── app/
    │   ├── Http/
    │   │   ├── Controllers/
    │   │   │   └── Api/           # Controladores da API
    │   │   │       ├── AuthController.php
    │   │   │       ├── ProductController.php
    │   │   │       ├── VendaController.php
    │   │   │       ├── ClienteController.php
    │   │   │       ├── FornecedorController.php
    │   │   │       ├── EncomendaController.php
    │   │   │       ├── StockMovementController.php
    │   │   │       ├── ReportController.php
    │   │   │       ├── ReciboController.php
    │   │   │       └── FechoCaixaController.php
    │   │   └── Middleware/        # Middlewares
    │   ├── Models/                # Modelos Eloquent
    │   │   ├── User.php
    │   │   ├── Product.php
    │   │   ├── Cliente.php
    │   │   ├── Fornecedor.php
    │   │   ├── Encomenda.php
    │   │   ├── Venda.php
    │   │   └── ...
    │   └── ...
    ├── database/
    │   ├── migrations/            # Migrações do banco
    │   └── seeders/               # Seeders para dados iniciais
    │       ├── DatabaseSeeder.php
    │       ├── UserSeeder.php
    │       └── ...
    ├── routes/
    │   └── api.php                # Rotas da API
    └── .env                       # Configurações ambiente
```

---

## Instalação e Configuração

### Pré-requisitos

- PHP >= 8.1
- Composer
- Node.js >= 18
- MySQL >= 8.0
- Git

### Passo 1: Clonar o repositório

```bash
git clone https://github.com/chelton15/SG_STOCK.git
cd SG_STOCK
```

                            ### Passo 2: Configurar o Backend (Laravel)

```bash


# Instalar dependências
composer install

# Copiar arquivo de configuração
cp .env.example .env

# Gerar key da aplicação
php artisan key:generate

# Configurar banco de dados no .env
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=sg_stock
# DB_USERNAME=root
# DB_PASSWORD=

# Executar migrations e seeders (cria as tabelas e insere dados iniciais)
php artisan migrate --seed

# Instalar Sanctum e Permissions
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

# Iniciar servidor
php artisan serve
```

### Passo 3: Configurar o Frontend (React)

```bash
# Abrir novo terminal e entrar na pasta do frontend
cd frontend

# Instalar dependências
npm install

# Iniciar servidor de desenvolvimento
npm run dev
```

### Passo 4: Acessar a aplicação

- Frontend: `http://localhost:5173`
- Backend API: `http://localhost:8000`

---

## Credenciais de Acesso

Após executar `php artisan migrate --seed`, os seguintes utilizadores são criados automaticamente no sistema:

### Utilizadores Padrão (Criados pelo Seeder)

| Perfil | Nome | Email | Senha |
|--------|------|-------|-------|
| **Administrador** | Administrador | `admin@stock.com` | `admin258` |


### Detalhes dos Perfis

#### Administrador
- **Acesso completo** a todas as funcionalidades do sistema
- Pode criar, editar e eliminar qualquer recurso
- Gerencia utilizadores e permissões
- Acesso a todos os relatórios

#### Gestor
- Gerencia produtos, fornecedores e encomendas
- Acesso a relatórios gerenciais
- Pode realizar fecho de caixa
- Visualiza todas as movimentações

#### Operador
- Processa vendas diárias
- Regista movimentações de stock
- Visualiza informações básicas
- Acesso limitado a relatórios

### Como alterar a senha padrão

1. Faça login com as credenciais fornecidas
2. Aceda ao menu de perfil (canto superior direito)
3. Clique em "Perfil" ou "Configurações"
4. Preencha os campos: Senha atual, Nova senha, Confirmar senha
5. Clique em "Atualizar"

### Criar novos utilizadores (Apenas Admin)

1. Aceda ao menu **Utilizadores**
2. Clique em **Novo Utilizador**
3. Preencha os dados (nome, email, senha)
4. Selecione o perfil (Admin, Gestor ou Operador)
5. Clique em **Salvar**

---

## Módulos do Sistema

### 1. Autenticação
- Login com email e senha
- Registro de novos utilizadores (apenas Admin)
- Logout
- Recuperação de sessão com token

### 2. Dashboard
- Cards com indicadores principais
- Gráfico de vendas dos últimos 7 dias
- Top produtos mais vendidos
- Status de validade dos produtos
- Produtos prestes a vencer
- **Fecho de caixa diário** com registo de despesas
- **Relatórios mensais e anuais** por operador

### 3. Produtos
- Cadastro, edição e exclusão de produtos
- Controlo de stock
- **Gestão de validade** (data de fabricação, validade, lote)
- Alertas de stock baixo
- Alertas de produtos a vencer
- Filtros por status de validade

### 4. Categorias
- Categorização de produtos
- Gestão completa (CRUD)
- Apenas Administrador pode gerir

### 5. Fornecedores
- Cadastro de fornecedores
- Contactos e informações fiscais (NUIT)
- **Gestão de encomendas a fornecedores**
- **Rastreamento de entregas**

### 6. Clientes
- Cadastro de clientes
- **Controlo de crédito** (limite de crédito, saldo devedor)
- Histórico de compras
- **Gestão de pagamentos** a crédito
- **Planos de pagamento** parcelado
- **Comunicações** com clientes

### 7. Vendas
- Processamento rápido de vendas
- **Múltiplos métodos de pagamento**:
  - Dinheiro (com troco)
  - Cartão de Crédito/Débito
  - M-Pesa
  - e-Mola
  - Transferência Bancária
  - **Crédito (Fiado)** - adiciona ao saldo devedor do cliente
- **Desconto automático de 5% para clientes Grossistas**
- Carrinho de compras dinâmico
- Geração de recibo PDF
- Histórico de vendas

### 8. Movimentações de Stock
- Registro de entradas e saídas
- Histórico completo com data e utilizador
- Filtros por período e produto
- Resumo de valores movimentados

### 9. Utilizadores
- Gestão de utilizadores (apenas Admin)
- Atribuição de roles (Admin, Gestor, Operador)
- Controlo de permissões via Spatie

### 10. Relatórios
- Vendas por período
- Produtos mais vendidos
- **Resumo de crédito dos clientes**
- **Fecho de caixa diário/mensal**
- **Relatórios de encomendas**
- Exportação de dados (CSV/PDF)

---

## 👥 Perfis de Utilizador

### Matriz de Permissões

| Funcionalidade | Operador | Gestor | Admin |
|----------------|----------|--------|-------|
| **Dashboard** | ✅ Básico | ✅ Completo | ✅ Completo |
| **Vendas** | | | |
| - Nova Venda | ✅ | ✅ | ✅ |
| - Histórico Vendas | ❌ | ✅ | ✅ |
| - Cancelar Venda | ❌ | ✅ | ✅ |
| **Produtos** | | | |
| - Visualizar | ✅ | ✅ | ✅ |
| - Criar/Editar | ❌ | ✅ | ✅ |
| - Excluir | ❌ | ❌ | ✅ |
| **Categorias** | ❌ | ❌ | ✅ |
| **Movimentações** | | | |
| - Visualizar próprias | ✅ | ✅ | ✅ |
| - Visualizar todas | ❌ | ✅ | ✅ |
| - Registar | ❌ | ✅ | ✅ |
| **Clientes** | ❌ | ✅ | ✅ |
| **Fornecedores** | | | |
| - Visualizar | ✅ | ✅ | ✅ |
| - Gerir | ❌ | ❌ | ✅ |
| **Encomendas** | | | |
| - Visualizar | ✅ | ✅ | ✅ |
| - Criar | ❌ | ✅ | ✅ |
| - Confirmar entrega | ❌ | ✅ | ✅ |
| **Utilizadores** | ❌ | ❌ | ✅ |
| **Relatórios** | ❌ | ✅ | ✅ |
| **Fecho de Caixa** | ❌ | ✅ | ✅ |
| **Recibos** | ✅ | ✅ | ✅ |
| **Vendas a Crédito** | ✅ | ✅ | ✅ |

---

## Funcionalidades Principais

### Vendas a Crédito (Fiado)

O sistema permite vendas a crédito para clientes cadastrados:

1. **Pré-requisitos**:
   - Cliente deve estar cadastrado
   - Cliente deve ter limite de crédito definido
   - Saldo devedor não pode exceder limite

2. **Como funciona**:
   - Cliente seleciona produtos
   - Escolhe método "Crédito (Fiado)"
   - Sistema valida crédito disponível
   - Venda é registada e saldo devedor atualizado
   - Cliente pode pagar posteriormente

3. **Gestão de Crédito**:
   - Limite de crédito por cliente
   - Saldo devedor atualizado automaticamente
   - Status de crédito (Regular/Atenção/Bloqueado)
   - Relatórios de clientes com dívidas

### Desconto para Grossistas

Clientes do tipo **Grossista** recebem automaticamente **5% de desconto** em todas as compras:
- Desconto aplicado no backend
- Visualizado no resumo da venda
- Badge informativo no checkout

### Encomendas a Fornecedores

Sistema completo de gestão de encomendas:

1. **Criação de Encomendas**:
   - Seleção de fornecedor
   - Adição de múltiplos produtos
   - Definição de data de entrega prevista
   - Escolha de método de pagamento

2. **Rastreamento**:
   - Status: Pendente → Em Trânsito → Entregue
   - Detecção automática de atrasos
   - Timeline visual da entrega

3. **Gestão de Pagamentos**:
   - Pagamentos parciais ou totais
   - Múltiplos métodos de pagamento
   - Histórico completo

### Fecho de Caixa

Funcionalidade para gestores e administradores:

- **Registo de despesas diárias** (CredELEC, água, salários, etc.)
- **Resumo de vendas do dia**
- **Cálculo automático do saldo final**
- **Identificação do operador** que realizou o fecho
- **Relatórios mensais e anuais**
- **Exportação de relatórios (CSV/PDF)**

### Controlo de Validade

- Data de fabricação e validade por produto
- Número de lote
- Dias de antecedência para aviso
- Status automático: Válido / Próximo a vencer / Vencido
- Alertas no dashboard

---

## API Endpoints

### Autenticação
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/api/login` | Login |
| POST | `/api/logout` | Logout |
| GET | `/api/user` | Dados do utilizador |

### Produtos
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/api/products` | Listar produtos |
| POST | `/api/products` | Criar produto |
| PUT | `/api/products/{id}` | Atualizar produto |
| DELETE | `/api/products/{id}` | Excluir produto |
| GET | `/api/products/buscar/codigo-barras/{codigo}` | Buscar por código |
| GET | `/api/products/resumo-validade` | Resumo de validade |
| GET | `/api/products/proximos-vencer` | Produtos próximos a vencer |

### Vendas
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/api/vendas` | Criar venda |
| GET | `/api/vendas` | Listar vendas |
| PUT | `/api/vendas/{id}/cancel` | Cancelar venda |

### Clientes
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/api/clientes` | Listar clientes |
| POST | `/api/clientes` | Criar cliente |
| POST | `/api/clientes/{id}/pagamentos` | Registrar pagamento |
| POST | `/api/clientes/{id}/planos-pagamento` | Criar plano de pagamento |
| GET | `/api/clientes/resumo-credito` | Resumo de crédito |

### Fornecedores e Encomendas
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/api/fornecedores` | Listar fornecedores |
| POST | `/api/fornecedores` | Criar fornecedor |
| GET | `/api/encomendas` | Listar encomendas |
| POST | `/api/encomendas` | Criar encomenda |
| POST | `/api/encomendas/{id}/confirmar-entrega` | Confirmar entrega |
| POST | `/api/encomendas/{id}/pagamentos` | Registrar pagamento |

### Fecho de Caixa
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/api/fechos-caixa` | Listar fechos |
| POST | `/api/fechos-caixa` | Criar fecho |
| GET | `/api/fechos-caixa/resumo` | Resumo de fechos |

### Movimentações
| Método | Endpoint | Descrição |
|--------|----------|-----------|
| GET | `/api/movements` | Listar movimentações |
| POST | `/api/movements/entrada` | Registrar entrada |
| POST | `/api/movements/saida` | Registrar saída |
| GET | `/api/movements/summary` | Resumo de movimentações |

---

## Base de Dados

### Principais Tabelas

| Tabela | Descrição |
|--------|-----------|
| `users` | Utilizadores do sistema |
| `products` | Produtos com validade e lote |
| `categories` | Categorias de produtos |
| `fornecedores` | Fornecedores |
| `encomendas` | Encomendas a fornecedores |
| `encomenda_items` | Itens das encomendas |
| `encomenda_pagamentos` | Pagamentos de encomendas |
| `clientes` | Clientes com controlo de crédito |
| `vendas` | Vendas registadas |
| `venda_itens` | Itens das vendas |
| `stock_movements` | Movimentações de stock |
| `pagamentos` | Pagamentos de clientes |
| `planos_pagamento` | Planos de pagamento parcelado |
| `parcelas` | Parcelas dos planos |
| `comunicacoes` | Comunicações com clientes |
| `fechos_caixa` | Fechos de caixa diários |
| `fecho_despesas` | Despesas do fecho de caixa |
| `model_has_roles` | Permissões de utilizadores (Spatie) |
| `roles` | Roles disponíveis (Spatie) |

### Diagrama ERD Simplificado

```
users ──┬── vendas ──┬── venda_itens ── products
        │            │
        └── fechos_caixa
                        │
clientes ──┬── vendas ──┘
           │
           ├── pagamentos
           ├── planos_pagamento ── parcelas
           └── comunicacoes

fornecedores ── encomendas ──┬── encomenda_items
                             └── encomenda_pagamentos

categories ─── products
```

---

## Guia de Utilização


### Como fazer uma venda

1. Aceda a **Nova Venda** no menu lateral
2. Pesquise produtos por nome, SKU ou código de barras
3. Clique nos produtos para adicionar ao carrinho
4. Ajuste quantidades se necessário
5. Selecione cliente (ou mantenha "Cliente Anónimo")
6. Escolha método de pagamento:
   - **Dinheiro**: Digite valor pago, sistema calcula troco
   - **Cartão**: Selecione bandeira e últimos dígitos
   - **M-Pesa/e-Mola**: Digite número da transação
   - **Crédito**: Vai para saldo devedor do cliente
7. Confirme e finalize venda
8. O recibo PDF será gerado automaticamente

### Como criar uma encomenda a fornecedor

1. Aceda a **Fornecedores** no menu lateral
2. Clique em **Nova Encomenda**
3. Selecione o fornecedor
4. Adicione produtos com quantidades e preços
5. Defina data de entrega prevista
6. Escolha condições de pagamento
7. Adicione observações se necessário
8. Clique em **Criar Encomenda**

### Como registar uma despesa no fecho de caixa

1. Aceda ao **Dashboard**
2. Clique em **Fecho de Caixa**
3. Clique em **Adicionar Despesa**
4. Selecione categoria (CredELEC, água, etc.)
5. Digite descrição e valor
6. Adicione quantas despesas necessárias
7. Finalize o fecho
8. O relatório será guardado e disponível para consulta

### Como gerir crédito de clientes

1. Aceda a **Clientes**
2. Edite um cliente existente
3. Defina **Limite de Crédito**
4. O sistema controla automaticamente:
   - Saldo devedor
   - Crédito disponível
   - Status de crédito
5. Para registrar pagamento:
   - Clique em **Registar Pagamento**
   - Digite valor e método
   - O saldo devedor será atualizado

---

## Resolução de Problemas

### Erro 500 (Internal Server Error)

**Causas comuns:**
- Base de dados não migrada
- Permissões de pasta incorretas
- Configuração `.env` incorreta

**Solução:**
```bash
php artisan migrate
php artisan cache:clear
php artisan config:clear
chmod -R 775 storage bootstrap/cache
```

### Erro 401 (Não autorizado)

**Causa:** Token expirado ou inválido

**Solução:** Faça logout e login novamente

### Erro 422 (Validação)

**Causa:** Dados enviados não passam na validação

**Solução:** Verifique os campos obrigatórios e formatos

### Erro de CORS

**Causa:** Backend e frontend em portas diferentes

**Solução:** Verifique configuração CORS no Laravel

### Página em branco no React

**Causa:** Erro de importação ou componente

**Solução:**
```bash
npm run build
rm -rf node_modules/.vite
npm run dev
```

### Erro "Table not found"

**Causa:** Migrations não executadas

**Solução:**
```bash
php artisan migrate:fresh --seed
```

---



## 📄 Licença

Este projeto está licenciado sob a licença MIT.

---

## 📞 Suporte e Contactos

- **Email**: cheltonjunior15@gmail.com
- **Telefone**: +258 655415981


---

## 👨‍💻 Equipe de Desenvolvimento

| Nome | Função | Contacto |
|------|--------|----------|
| Enginheiro Wamba | Desenvolvimento Full Stack | 855415981|

---


## 🔑 Resumo Rápido das Credenciais

| Perfil | Email | Senha |
|--------|-------|-------|
| 👑 Administrador | `admin@stock.com` | `admin258` |


> ⚠️ **Nota**: Estas credenciais são criadas automaticamente ao executar `php artisan migrate --seed`. 
---

**© 2026 SG_STOCK - Todos os direitos reservados**
```