# GreenMart — Arquitetura da API (PHP + MySQL no cPanel)

## 1. Resumo

Uma API REST em PHP 8.2 e MySQL, hospedada no cPanel, consumida pelo app (Android e iOS) e
pelo painel web, com um único banco de dados. Há três fluxos principais:

- **PIX**: a cobrança é criada pela API, e a confirmação chega do banco (webhook), com
  conciliação pela API do banco. O banco é o que o cliente escolher.
- **Cartão de crédito**: a tokenização acontece no SDK do gateway, e a API só recebe o token.
- **Alerta de venda**: quando um pagamento é confirmado, o painel toca um som de pagamento e o
  celular do lojista recebe push com o mesmo som.

## 2. O que encontrei no app

Verificado na pasta do projeto:

- React Native 0.79 com Redux Toolkit e redux-persist. **Não há nenhuma chamada HTTP**: todos os
  dados vêm de `src/helper/Data.js` (mock).
- Moeda fixa em `$` (`src/constants/CommonConstant.js`). Para o Brasil, o padrão deve ser BRL/R$.
- Pagamento na tela de checkout é mock: "Cash On Delivery", PayPal e Google Pay. Não existe PIX nem cartão.
- Carteira ("My Wallet") e transações também são mock.
- Hierarquia do catálogo: categoria > subcategoria > subcategoria filha (`parentChildCategoryId`).
- Status de entrega do rastreio: Pedido feito, Separado, Enviado, Saiu para entrega, Entregue.
- Permissões Android: localização fina, aproximada e em segundo plano.
- iOS: `NSAllowsArbitraryLoads = true` (remover antes de publicar).

Higiene do repositório, antes de subir ao Git:

- O zip tem ~34 MB: `vendor/bundle` (gems do CocoaPods), `.DS_Store`, `ios/build` e o bundle Android gerado.
- `android/app/greenmart_key_name.keystore` é o keystore de assinatura de release. Tire do repositório
  e considere rotacionar se o arquivo já foi compartilhado.

## 3. Arquitetura

```
 App Android/iOS (RN)                    Painel web (admin)
        │  HTTPS + JSON                         │  HTTPS + JSON, polling 4 s
        ▼                                       ▼
┌──────────────────── cPanel: PHP 8.2 + MySQL ─────────────────────────┐
│ public_html/api/v1/index.php  ──► greenmart_api/ (fora do web)        │
│    Router → Auth, Catalog, Cart, Address, Orders, Payments, Notify    │
│    Pix\PixProvider  ◄──►  banco/PSP escolhido pelo cliente (Efí, …)   │
│    Fcm  ──────────────►  Firebase Cloud Messaging → celulares         │
│    MySQL (InnoDB, utf8mb4, valores em centavos)                       │
│    cron: pix_reconcile.php a cada 5 min                               │
└───────────────────────────────────────────────────────────────────────┘
 Banco/PSP ──POST webhook──► index.php?r=webhooks/pix/{segredo}
```

Um cliente = uma instalação (white-label), conforme o plano do GreenMart. Por isso não há `tenant_id`.

## 4. Restrições do cPanel e decisões

| Limitação da hospedagem | Decisão |
|---|---|
| Sem WebSocket nem processo em segundo plano | Painel faz polling a cada 4 s em `admin/alerts`. Celular recebe push FCM. Cron faz a conciliação. |
| Composer nem sempre disponível | Código puro: PDO, cURL, OpenSSL. Sem dependências. |
| `Authorization` às vezes não chega ao PHP | A API aceita também `X-Auth-Token`. |
| Sem `.htaccess` nesta fase | Rotas por `?r=caminho`. URL limpa só depois de aprovação. |
| Segredos no mesmo servidor | `greenmart_api/` fica fora do `public_html`. Certificados em pasta separada. |
| Fuso e horário de verão | Brasil sem horário de verão desde 2019. Tudo em `America/Sao_Paulo` e MySQL em `-03:00`. |

## 5. Fluxos

### 5.1 Checkout
1. App envia `PUT cart/items` (o carrinho fica no servidor, então app e web veem o mesmo).
2. `POST orders` com `Idempotency-Key`. Dentro de uma transação, a API:
   - trava o carrinho e os produtos (`SELECT … FOR UPDATE`);
   - recalcula preço, cupom, frete e total (o app nunca envia preço);
   - grava o pedido com o endereço como snapshot;
   - desconta o estoque com condição `stock_qty >= qty`;
   - limpa o carrinho.
3. Status inicial: `pending_payment`.

### 5.2 PIX
1. `POST orders/{id}/payments` com `method=pix`. A API cria a cobrança no banco com um txid de 34
   caracteres e devolve copia-e-cola e QR. Se já existe PIX válido para o pedido, devolve o mesmo.
2. O cliente paga. O banco chama `POST webhooks/pix/{segredo}`.
3. A API **não confia no corpo do webhook**: consulta a cobrança na API do banco (fonte da verdade).
4. Se confirmada, `markPaid` roda em transação com trava de linha. Idempotente. Valor diferente do
   esperado gera alerta de divergência em vez de confirmar.
5. Efeitos: pedido vai para `paid`, alerta no painel com som, push para o lojista, notificação e push para o cliente.
6. Rede de segurança: o cron `pix_reconcile` consulta os PIX pendentes a cada 5 min. O app também
   consulta `GET payments/{id}` ao abrir a tela de pagamento.
7. Expiração: PIX sem pagamento até `pix_expires_at` vira `expired`, o pedido vai para `cancelled` e o estoque volta.
8. **Pago depois de cancelado**: o pagamento fica `paid`, o pedido não muda, e o painel recebe
   `paid_after_cancel`. Decisão manual: reabrir o pedido ou reembolsar.

### 5.3 Cartão de crédito
- Não está ativo. A rota responde `501 card_gateway_not_configured` até o gateway ser definido.
- Quando definido: o app tokeniza no SDK do gateway. A API recebe só o token, cria a cobrança e
  guarda bandeira, últimos 4 dígitos e parcelas.
- **Número e CVV nunca passam pela API nem entram no banco** (exigência PCI-DSS). A Efí, o Mercado Pago e outros fazem tokenização no app.

### 5.4 Alertas e som
| Canal | Quem recebe | Como | Som |
|---|---|---|---|
| Painel web | Lojista/operador | Polling `GET admin/alerts?after=ID` a cada 4 s | `pagamento.wav` via Web Audio, após clique em "Ativar som" |
| Celular do lojista | Admin/operador com app | Push FCM (canal `pagamentos`) | `pagamento.wav` (Android res/raw, iOS bundle) |
| Cliente | Usuário | Push FCM + histórico em `notifications` | Som padrão |

Tipos de alerta em `admin_alerts`: `payment_received`, `paid_after_cancel`, `payment_amount_mismatch`.

## 6. Entidades (22 tabelas, `database/schema.sql`)

| Grupo | Tabelas | Função |
|---|---|---|
| Parâmetros | `settings` | Taxa de entrega, frete grátis, expiração do PIX (centavos) |
| Acesso | `users`, `api_tokens`, `audit_log` | Cliente, admin, operador. Token guardado como SHA-256. Auditoria de ações do painel |
| Cliente | `addresses`, `wishlist_items`, `product_reviews` | Endereços, favoritos, avaliações (moderadas) |
| Catálogo | `categories`, `products`, `product_images` | Árvore de categorias, produtos, estoque |
| Promoções | `coupons` | Percentual ou valor fixo, mínimo, validade, limite de uso |
| Compra | `carts`, `cart_items`, `orders`, `order_items`, `order_status_history` | Carrinho no servidor, pedido com snapshot, histórico de status |
| Dinheiro | `payments`, `wallet_transactions`, `bank_events` | Tentativas de pagamento, saldo da loja, caixa de entrada dos webhooks (idempotência) |
| Notificação | `admin_alerts`, `notifications`, `device_tokens` | Alertas do painel, histórico do cliente, tokens FCM |

Regras de integridade: `payments` tem `UNIQUE(provider, provider_ref)`. `bank_events` tem
`UNIQUE(provider, external_id)`. `orders` tem `UNIQUE(user_id, idempotency_key)`.

## 7. Estados

**Pedido** (`orders.status`): `pending_payment → paid → packed → shipped → out_for_delivery → delivered`.
Saídas: `cancelled` (de `pending_payment`, `paid` ou `packed`) e `refunded` (de `paid`).

Pedido `paid` só entra pelo pagamento. O painel não pode marcar pago manualmente.

**Pagamento** (`payments.status`): `pending → paid | expired | cancelled`. `failed` e `refunded` reservados.

## 8. Regras e segurança

- Preço, estoque, cupom, frete e total são calculados no servidor. Dinheiro em centavos (`INT`).
- Trava de linha e transação em estoque, pagamento e pedido. Erro = rollback.
- Idempotência em três lugares: `Idempotency-Key` no checkout, `bank_events` no webhook, `markPaid` só age em `pending`.
- Webhook: segredo no caminho (mínimo 32 caracteres, comparado com `hash_equals`) **e** revalidação na API do banco.
- Tokens opacos de 64 caracteres hex, expiração de 60 dias, hash SHA-256 no banco.
- Senhas com `password_hash` (bcrypt/argon do PHP).
- **Pendente**: limite de tentativas no login (rate limit). Recomendo antes da produção.
- HTTPS obrigatório. CORS só para o domínio do painel. App nativo não usa CORS.
- LGPD: CPF e telefone só para cobrança e entrega. Definir política de retenção e base legal antes de produção.
- Segredos (`config.php`, certificado, conta de serviço do Firebase) fora do repositório e fora do web.
- Painel: o token de admin fica em JS no navegador. Use HTTPS, expiração curta e, se possível, sessão em cookie `HttpOnly` no lugar.
- `manual` (confirmação sem banco) é bloqueado quando `app.env = production`.

## 9. O que muda no app (não feito agora)

| Tela | Hoje | Passa a usar |
|---|---|---|
| Home / categorias | `AllCategoriesData` | `GET categories` |
| Produtos | `AllproductsData`, `ProductDetailsData` | `GET products`, `GET products/{id}` |
| Carrinho | `MyCartData` | `GET cart`, `PUT cart/items` |
| Endereços | `SaveAddressData` (e endereço fixo no checkout) | `GET/POST addresses` |
| Checkout | `CheckoutPaymentMethodData` | `POST orders`, `POST orders/{id}/payments` |
| Pagamento PIX (tela nova) | não existe | QR + copia-e-cola, polling de `GET payments/{id}` |
| Pedidos e rastreio | `MyOrdersData`, passos fixos | `GET orders`, `GET orders/{id}` |
| Notificações | `NotificationData` | `GET notifications`, `POST devices` |
| Carteira | `MyWalletData` | Pendente (ver 10) |

Ajustes de app para o som: criar o canal `pagamentos` com `pagamento.wav` (Android) e incluir o
arquivo no bundle (iOS). Trocar `CURRENCY` por `R$` e formatar valores em pt-BR.

## 10. Decisões pendentes

1. **Banco/PSP do PIX** (Efí, Mercado Pago, Asaas, Banco do Brasil, Sicoob, Itaú…). Define o adaptador. O resto não muda.
2. **Gateway de cartão** (pode ser o mesmo PSP).
3. **"Crédito"**: cartão de crédito ou saldo da loja (carteira)? Modelei as duas. Só o cartão tem rota (ainda em 501). O saldo tem tabela, mas não rotas.
4. **Painel web atual** (o que está em barber.caserna360.com.br/admin): sem o código ou o schema dele, a API nasce separada. Se me enviar, unifico as tabelas.
5. **Firebase**: já existe projeto FCM e conta de serviço?
6. **Regras comerciais**: taxa de entrega, frete grátis a partir de R$ 200, expiração do PIX (1 h), cupons.

## 11. O que foi verificado

- `php -l` em todos os 23 arquivos PHP: sem erros de sintaxe.
- 27 verificações de lógica pura, sem banco: conversão de valores, totais com frete e cupom, fábrica PIX, parsing do webhook Efí, rotas. Todas passaram.
- `node --check` no JS do painel: sem erros.
- Esquema SQL: 22 tabelas, conferido estruturalmente. Os nomes de colunas dos INSERTs batem com as tabelas.

Não verificado:
- **SQL não foi executado em MySQL real** (não há servidor de banco no ambiente). Importe no cPanel e veja o retorno.
- **Adaptador Efí não foi testado** contra a API. Marcado como esqueleto no código.
- **FCM não foi testado** com projeto real.
- Fluxo HTTP completo (cadastro → pedido → PIX → webhook) precisa rodar no sandbox da hospedagem.

## 12. Próximos passos sugeridos

1. Você responde as decisões da seção 10 (principalmente 1, 3 e 4).
2. Importar o esquema e rodar o teste rápido do README.
3. Validar o PIX no sandbox do banco escolhido.
4. Eu faço a camada de API no app (cliente HTTP e Redux) e a tela de pagamento PIX, em etapas testáveis.
