# ENG-2809 — API do dashboard do separador

`GET /api/v1/stock/expedition/output/picking-order/dashboard`

Endpoint para o dashboard mobile da ENG-2773. Requer autenticação Sanctum com
perfil **ativo** de separador, administrador ou master no setor de expedição.
Outros perfis ou setores recebem `403`. Sem autenticação, retorna `401`.

## Filtros

| Parâmetro | Valores | Padrão |
| --- | --- | --- |
| `period` | `day`, `week`, `month` | `day` |
| `date` | Data de referência no formato `YYYY-MM-DD` | Data atual |

Os períodos seguem o calendário e o fuso `config('app.timezone')`: dia completo,
semana de segunda a domingo e mês completo. A data de referência permite consultar
períodos anteriores. Valores inválidos retornam `422`.

O usuário vem exclusivamente da sessão autenticada. Não há filtro para consultar
outro separador.

```http
GET /api/v1/stock/expedition/output/picking-order/dashboard?period=week&date=2026-10-16
Authorization: Bearer <token>
Accept: application/json
```

Exemplo de resposta:

```json
{
  "data": {
    "period": "week",
    "date": "2026-10-16",
    "start_date": "2026-10-12",
    "end_date": "2026-10-18",
    "sent": { "tasks": 12, "items": 140 },
    "separated": { "tasks": 9, "items": 110 },
    "updated_at": "2026-10-16T10:30:00-03:00"
  }
}
```

## Regras dos indicadores

- Considera somente saídas de pré-fatura da expedição vinculadas a tarefas cujo
  `responsible_id` é o usuário autenticado.
- `sent.tasks`: quantidade de registros de `picking_orders` criados no período,
  vinculados ao usuário, incluindo tarefas que já foram finalizadas.
- `sent.items`: quantidade de linhas de `picking_order_products` criadas no
  período, vinculadas às tarefas do usuário. Linhas adicionadas hoje a uma tarefa
  de ontem entram no total de itens de hoje.
- `separated.tasks`: quantidade de tarefas com `end_date` no período e status
  `SEPARATED` ou `CONCLUDED`, independentemente da data de criação.
- `separated.items`: quantidade de linhas com `end_date` no período e cujo item
  de origem possui `stock_io_products.picked = true`, a mesma regra do fundo verde
  nos detalhes da tarefa da expedição. Uma linha entra assim que é separada, mesmo que a
  tarefa ainda esteja em andamento. A conclusão da tarefa em outro dia não muda
  a data original da separação da linha.
- Cada tarefa conta uma vez por `picking_orders.id`, mesmo com várias pré-faturas.
  Cada linha conta uma vez por `picking_order_products.id`, independentemente de
  `product_id`, `stock_io_product_id` e `amount`. Duas linhas do mesmo produto ou
  do mesmo item de origem contam dois itens.
- Tarefas e pré-faturas canceladas são excluídas de todos os indicadores. Linhas
  canceladas na tarefa ou na pré-fatura são excluídas da contagem de itens.
- Os quatro indicadores retornam zero quando não há registros.

Exemplo: uma tarefa e suas duas linhas foram alocadas ontem. Hoje uma linha foi
separada e a tarefa permanece aberta. Hoje a resposta será `sent: {tasks: 0,
items: 0}` e `separated: {tasks: 0, items: 1}`.

## Data de separação e implantação

A migration `2026_10_16_120000_add_end_date_to_picking_order_products.php`
adiciona `end_date` e um índice para a consulta. Execute as migrations antes
de disponibilizar a API.

Quando o item de origem passa a `picked = true`, o modelo preenche `end_date` nas
linhas ativas vinculadas. Novas linhas vinculadas a um item já verde também
recebem a data. Alterações posteriores e a conclusão da tarefa preservam essa
data, sempre limitada à `picking_orders.end_date` quando a tarefa já estiver
encerrada. Apenas mudar o status da linha para `SEPARATED` ou `CONCLUDED` não basta.
Quando `picked` volta a `false`, a data é limpa; uma nova separação registra um
novo horário.

Para registros antigos, a migration preenche somente linhas cujo item de origem
tem `picked = true`, ignorando tarefas, linhas e produtos cancelados. Usa
`stock_io_products.updated_at`, com fallback para `picking_order_products.updated_at`
e `created_at`. A seleção segue o marcador verde; o horário histórico é uma
aproximação, pois o sistema não armazenava o instante original da separação.
A data estimada nunca ultrapassa `picking_orders.end_date`; uma atualização
posterior do produto não transfere os itens de uma tarefa encerrada para outro dia.
Linhas sem o marcador verde continuam sem `end_date`, mesmo com status finalizado.

A migration corretiva `2026_10_16_130000_cap_picking_order_product_end_date_at_task_finish.php`
trata bases que já receberam o preenchimento anterior: limita somente datas de
linhas posteriores ao encerramento da tarefa, preservando datas válidas e tarefas
abertas. A correção de dados não é revertida pelo rollback da migration.

As operações de leitura e marcação manual de produto separado rejeitam tarefas
com `end_date` preenchido ou status `SEPARATED`, `CONCLUDED` ou `CANCELED`. A
validação relê a tarefa com bloqueio de linha antes de alterar os produtos.

## Atualização manual

O mobile deve repetir o mesmo `GET`, preservando os filtros selecionados. Cada
requisição recalcula os indicadores; a resposta envia `Cache-Control: no-store,
private`. `updated_at` informa o horário da consulta. A criação da tela e da ação
de atualização no aplicativo permanece no escopo mobile da ENG-2773.

## Validação

`tests/Feature/PickingOrder/SeparatorDashboardTest.php` cobre autenticação,
perfis/setores, usuário autenticado, contagem de tarefas com uma ou várias
pré-faturas, contagem de linhas do mesmo produto independentemente das
quantidades, separação antes da conclusão da tarefa, preservação da data,
migration, reabertura, cancelamentos, filtros inválidos, dia/semana/mês, limites de data,
virada de ano, ano bissexto e atualização manual.
