# WMS Mobile Collector API

Objetivo: habilitar integração com app mobile coletor de dados de inventário, com ingestão, validação, confirmação e processamento assíncrono em fila.

## Autenticação
- JWT: enviar `Authorization: Bearer <token>` (requer permissões `wms.read`/`wms.update` conforme endpoint).
- X-API-Key: enviar `x-api-key: <chave>` para endpoints de coleta (`ingest`, `confirm`), útil para dispositivos móveis com conexão intermitente. Dispositivos são registrados em `wms_mobile_devices(api_key)`.

## Endpoints

1) POST `/api/wms/mobile/inventory/ingest`
- Permissões: `wms.update` (JWT ou `x-api-key`)
- Body:
```
{
  "batch_id": "BATCH-123",
  "items": [
    { "product_id": 10, "bin_code": "A-01-01", "quantity": 5 },
    { "product_code": "SKU-001", "bin_id": 3, "quantity": 2.5 }
  ]
}
```
- Resposta: `202` se validado, `207` se parcialmente inválido
```
{ "status": "validated|received", "batch_id": "...", "valid_count": 1, "received_count": 2, "errors": ["Linha 2: bin não encontrado"] }
```
- Efeitos: grava em `wms_inventory_raw` (staging) e `wms_inventory_queue` (fila).

2) POST `/api/wms/mobile/inventory/validate`
- Permissões: `wms.read` (JWT)
- Body: igual ao `ingest`
- Resposta: `200` ou `207` com `valid_items[]` e `errors[]`.

3) POST `/api/wms/mobile/inventory/confirm`
- Permissões: `wms.update` (JWT ou `x-api-key`)
- Body:
```
{ "batch_id": "BATCH-123", "session_id": 42 }
```
- Resposta: `200` com `{ status: "confirmed" }`; marca fila como confirmada.

4) GET `/api/wms/mobile/inventory/queue/pending`
- Permissões: `wms.read` (JWT)
- Lista itens pendentes na fila (`received|validated|confirmed`).

5) POST `/api/wms/mobile/inventory/queue/process`
- Permissões: `wms.update` (JWT)
- Body: `{ "limit": 10, "session_id": 42 }`
- Processa até `limit` itens da fila; valida e persiste em `wms_inventory_entries`.

## Esquema de Dados
- `wms_inventory_queue`: fila de lotes (`status`: received, validated, confirmed, processing, done, error; `payload_json`).
- `wms_inventory_raw`: staging por item, status `received|validated|invalid`.
- `wms_inventory_entries`: persistência definitiva por sessão.
- `wms_mobile_devices`: dispositivos registrados com `api_key` e `last_seen`.

## Logs/Auditoria
- Auditoria em `wms.mobile` e `wms.inventory.queue` para ações `ingest`, `validate`, `confirm`, `process`.

## Escalabilidade
- Índices em `wms_inventory_queue` (`idx_status_locked`, `idx_batch`) para consumo concorrente.
- Lock por `locked_at` e `attempt_count` para reprocesso seguro.

## Boas Práticas do App Mobile
- Enviar `batch_id` único por lote para idempotência.
- Incluir `product_id` quando possível; caso contrário, usar `product_code` (`products.codigo`).
- Usar `bin_id` ou `bin_code` (`bins.code`).
- Em conexão instável, repetir `ingest` com mesmo `batch_id`; o backend aceitará múltiplos registros e o processamento cuidará de deduplicação na camada futura.

## Exemplo de Fluxo
1. App valida localmente o lote → opcionalmente chama `/validate`.
2. App envia `/ingest` com `x-api-key`.
3. Backend marca lote como `validated` se possível; operador confirma o lote em `/confirm` com `session_id`.
4. Serviço de backend chama `/queue/process` com `session_id` para persistir definitivo.

## Testes
- `tests/WmsMobileCollectorTest.php` cobre ingestão parcial (207), confirmação, processamento da fila e persistência em sessão.