# Plano de implementação: ENG-1262 — Auditoria de leituras da separação

## Visão geral

Implementar uma trilha de auditoria exclusiva para as leituras enviadas com uma
separação confirmada. Os registros ficam vinculados à tarefa, produto da tarefa,
movimentação, usuário e endereço, permanecem 12 meses consultáveis no PostgreSQL
e depois são arquivados em `JSONL.gz`. O dashboard Tempo de Execução passa a
consultá-los por tarefa sem alterar o payload do Rex-Estoque.

## Decisões arquiteturais

- A tabela `picking_read_logs` será particionada por `received_at`, com chave
  primária composta por `id, received_at` e relacionamentos sem cascata.
- A migração inicial criará todas as partições que podem cobrir a janela móvel
  de 12 meses, a partição corrente e duas futuras; uma rotina agendada manterá
  as futuras disponíveis.
- O picking deixará de encaminhar seus logs ao serviço genérico e fará uma única
  inserção em lote depois de resolver o `picking_order_product`, ainda dentro da
  transação existente.
- A API será `GET /api/v1/report/picking-order/{pickingOrder}/reading-logs`, com
  `page` e `per_page`, recurso paginado padrão do Laravel e metadado indicando
  se o período da tarefa está fora da retenção imediata.
- A autorização reutilizará a policy do dashboard Tempo de Execução e o escopo
  `PickingOrder::visibleToCurrentUser()`. Uma tarefa invisível responderá como
  inexistente, evitando revelar sua presença.
- O arquivo terá versão de esquema `1`; cada linha conterá os campos persistidos
  e fotografias descritivas somente do momento da exportação. O SHA-256 será do
  `JSONL.gz` publicado.
- Restaurações serão auditadas em tabela permanente. O comando exigirá mês,
  motivo e operador; a cópia no PostgreSQL expirará em sete dias sem remover o
  arquivo original.
- A janela de associação da migração legada será configurável, com padrão de
  cinco minutos e limite de análise de 60 dias. Somente uma cadeia com exatamente
  uma movimentação, um produto da pré-fatura e um produto de tarefa será apta.

## Contrato da consulta

Entrada:

- rota: `GET /api/v1/report/picking-order/{id}/reading-logs`;
- query: `page` inteiro positivo e `per_page` entre 1 e 100 (padrão 30).

Saída:

- `data[]`: `id`, `received_at`, `read_at`, `data`, `format`, `type`,
  `is_valid`, `user`, `address` e `product`;
- `links` e `meta`: paginação padrão do Laravel;
- `meta.task_outside_retention`: informa se o período da tarefa antecede a
  janela imediatamente consultável.

Erros seguem o comportamento JSON já usado pelo Laravel: validação 422,
autenticação 401 e tarefa não autorizada/inexistente 404.

## Fases e tarefas

### Fase 1: Fundação

#### Tarefa 1 — Persistência particionada

**Descrição:** criar tabela pai, relacionamentos, partições mensais e índices.

**Critérios de aceitação:**

- A tabela preserva todos os campos do design e não possui exclusões em cascata.
- A partição correta recebe cada `received_at`, inclusive na virada do mês.
- Os índices por tarefa/data/id e por origem legada existem nas partições.

**Verificação:** Pest de migração/partições e inspeção do catálogo PostgreSQL.

**Dependências:** nenhuma.

**Arquivos prováveis:** migration, modelo, serviço de partições, testes.

#### Tarefa 2 — Gravação atômica do picking

**Descrição:** retirar somente o picking do armazenamento genérico e persistir
os logs dedicados em lote dentro da transação da separação.

**Critérios de aceitação:**

- Separações com e sem logs continuam válidas e preservam o payload atual.
- Os vínculos de tarefa, produto, movimentação, usuário e endereço são exatos.
- Uma falha de auditoria reverte movimentação, item, embalagem e todos os logs.

**Verificação:** Pest cobrindo tipos/formatos/validade, lote, ausência de logs,
rollback e regressão de outro fluxo que ainda usa `reading_logs`.

**Dependências:** Tarefa 1.

**Arquivos prováveis:** serviço de picking, serviço de auditoria, modelo e testes.

### Checkpoint: Fundação

- Migrações sobem e descem em PostgreSQL.
- Testes das tarefas 1 e 2 passam e cada incremento está commitado.

### Fase 2: Consulta e interface

#### Tarefa 3 — Consulta paginada e autorizada

**Descrição:** expor leituras de uma única tarefa usando a visibilidade do
dashboard Tempo de Execução.

**Critérios de aceitação:**

- Resultado ordenado por `received_at desc, id desc`, com paginação limitada.
- Tarefas invisíveis não podem ser consultadas e IDs nunca vazam entre tarefas.
- O recurso resolve os dados atuais de usuário, endereço e produto.

**Verificação:** Pest de autorização, isolamento, ordenação, paginação e
`EXPLAIN`/catálogo para confirmar o índice.

**Dependências:** Tarefa 1.

**Arquivos prováveis:** rota, controller/request, resource, testes.

#### Tarefa 4 — Histórico da tarefa no frontend

**Descrição:** transformar o painel atual em Histórico da tarefa com as abas
Pausas e Leituras, preservando a apresentação e comportamento de Pausas.

**Critérios de aceitação:**

- Leituras exibem todos os campos, rótulos de enums e resultado textual.
- Loading, vazio, erro com retry, aviso de retenção e paginação funcionam.
- Pausas permanecem funcionais e nenhuma tela de pré-fatura é criada.

**Verificação:** testes Node dos estados/rótulos, ESLint, build Vite e validação
no navegador nos tamanhos relevantes.

**Dependências:** Tarefa 3.

**Arquivos prováveis:** serviço HTTP, histórico, componente de leituras, CSS e
helpers/testes.

### Checkpoint: Consulta ponta a ponta

- Backend e frontend concordam com o contrato.
- Fluxo do dashboard funciona em navegador sem erros de console.

### Fase 3: Ciclo operacional

#### Tarefa 5 — Partições futuras e arquivamento seguro

**Descrição:** agendar manutenção e arquivar partições completas fora da
retenção por streaming, manifesto e publicação atômica.

**Critérios de aceitação:**

- Arquivo e manifesto validam versão, período, contagem e SHA-256.
- A partição só é removida depois da validação dos artefatos publicados.
- Falhas preservam a origem e uma reexecução conclui sem perda.

**Verificação:** Pest de sucesso, falhas, checksum, reexecução, virada mensal e
comandos `--help`.

**Dependências:** Tarefa 1.

**Arquivos prováveis:** config, serviços de arquivo/partição, comandos, Kernel e
testes.

#### Tarefa 6 — Restauração auditada e expiração

**Descrição:** restaurar um mês mediante operador e motivo, auditar o resultado
e remover a cópia consultável após sete dias.

**Critérios de aceitação:**

- Manifesto e checksum são validados antes de qualquer importação.
- Resultado, operador, motivo, período, horário e validade ficam auditados.
- Arquivamento não remove restauração ativa; limpeza não remove os arquivos.

**Verificação:** Pest de checksum inválido, sucesso, auditoria, proteção ativa e
expiração.

**Dependências:** Tarefa 5.

**Arquivos prováveis:** migration/modelo de restauração, serviço, comandos,
agendamento e testes.

#### Tarefa 7 — Migração legada determinística

**Descrição:** analisar até 60 dias em lotes, sob lock administrativo, migrando
somente associações unívocas.

**Critérios de aceitação:**

- `--dry-run` não escreve e relata todos os contadores/motivos.
- Casos ausentes ou ambíguos são ignorados sem heurísticas extras.
- Reexecução reconhece `source_reading_log_id` e não duplica.

**Verificação:** Pest de cadeia determinística, ambiguidades em cada etapa,
dry-run, reexecução e concorrência; dry-run local se o banco estiver disponível.

**Dependências:** Tarefas 1 e 5.

**Arquivos prováveis:** comando, serviço de associação, relatório e testes.

### Fase 4: Fechamento

#### Tarefa 8 — Operação, compatibilidade e revisão

**Descrição:** documentar configuração/runbook, validar o aplicativo sem
alterações e aplicar a definição de pronto.

**Critérios de aceitação:**

- Variáveis, diretório persistente, backup, monitoramento e comandos documentados.
- Payload e comportamento do Rex-Estoque permanecem compatíveis.
- Diffs e commits contêm somente ENG-1262, sem segredos ou artefatos.

**Verificação:** Pest backend relevante/completo, testes Node, ESLint, build Vite,
Pint somente nos arquivos da tarefa, revisão de cinco eixos e `git status`.

**Dependências:** Tarefas 1 a 7.

## Riscos e mitigações

| Risco | Impacto | Mitigação |
|---|---|---|
| Partição ausente na virada do mês | Alto | Migração cobre a janela inicial, rotina diária antecipa partições e falha de escrita reverte o picking. |
| Arquivo em diretório de release ou sem espaço | Alto | Caminho absoluto obrigatório, health check no comando, publicação temporária no mesmo filesystem e documentação de backup/monitoramento. |
| Associação legada falsa | Alto | Contagens exatas em cada elo, janela curta configurável e descarte explícito de qualquer ambiguidade. |
| Vazamento entre tarefas/equipes | Alto | Escopo de visibilidade antes da consulta e filtro obrigatório por `picking_order_id`, cobertos por testes. |
| Volume degradar consulta/exportação | Médio | Índice composto, paginação, inserção em lote, cursor/streaming e validação com EXPLAIN. |
| Alterações locais existentes | Alto | Worktrees e branches exclusivas; staging por caminhos específicos e revisão staged antes de cada commit. |

## Questões resolvidas por configuração

- `PICKING_READ_LOG_ARCHIVE_PATH`: caminho absoluto persistente (obrigatório em
  produção).
- `PICKING_READ_LOG_FUTURE_MONTHS`: `2` por padrão.
- `PICKING_READ_LOG_RETENTION_MONTHS`: `12`, conforme o design.
- `PICKING_READ_LOG_LEGACY_DAYS`: máximo/padrão `60`.
- `PICKING_READ_LOG_LEGACY_WINDOW_MINUTES`: `5` por padrão.
- `PICKING_READ_LOG_RESTORE_DAYS`: `7`, conforme o design.