Templates¶

Templates prontos para copiar ao criar documentação numa aplicação. Os arquivos-fonte vivem na pasta templates/ do repositório documentacao no Forgejo — copie o arquivo, renomeie conforme a convenção e substitua o conteúdo de exemplo.

Template	Copiar para (no repo da aplicação)
Design doc	`docs/design/PROJ-AAAA-NNN-titulo-curto.md`
RD (Registro de Decisão)	`docs/rd/NNNN-titulo-curto.md`
Guia de usuário	`docs/guias/titulo-da-tarefa.md`

O frontmatter é obrigatório — campos e valores válidos estão na constituição.

Design doc¶

---
titulo: "Importação de frota a partir de planilha XLS"
tipo: design
status: rascunho
responsavel: "Fulano da Silva"
modulo: transporte
cliente: "Vantroba"
atualizado: 2026-06-09
tags: [bi, importacao, xls]
---

<!--
TEMPLATE DE DESIGN DOC — X-Adm
Copie para docs/design/PROJ-AAAA-NNN-titulo-curto.md no repo da aplicação.
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo as seções.
Seção sem conteúdo útil: apague. Seção vazia não existe.
Um design doc por feature/projeto. Detalhe que muda toda semana não entra
aqui (vai pro código); passo a passo de usuário também não (vai pro guia).
-->

# PROJ-2026-001 — Importação de frota a partir de planilha XLS

## 1. Contexto e escopo

O cliente mantém o cadastro da frota em planilhas Excel e precisa desses dados
no banco do BI para alimentar os dashboards de transporte.

**Dentro do escopo:** upload da planilha pela web, validação das linhas,
gravação na tabela de frota, relatório de erros por linha.

**Fora do escopo:** edição da frota pela web (continua na planilha);
sincronização reversa banco → planilha.

**Integrações:** banco PostgreSQL do BI (escrita); PowerSync (leitura pelos
dashboards — ver design doc do bi-transporte).

## 2. Modelo de dados

Tabelas novas/alteradas e relacionamentos que importam. Não liste toda coluna —
só o que outro dev precisa pra entender o desenho.

```mermaid
erDiagram
    IMPORTACAO ||--o{ IMPORTACAO_LINHA : contem
    IMPORTACAO_LINHA }o--|| VEICULO : "cria/atualiza"
    IMPORTACAO {
        bigint id PK
        text arquivo
        text status "PENDENTE | PROCESSANDO | SUCESSO | ERRO"
        timestamptz criado_em
    }
    VEICULO {
        bigint id PK
        text placa UK
        text categoria
    }
```

## 3. Fluxos principais

```mermaid
flowchart LR
    A[Upload do XLS] --> B{Validação}
    B -- linhas OK --> C[Grava VEICULO]
    B -- linhas com erro --> D[Relatório de erros]
    C --> E[Dashboards via PowerSync]
```

Descreva em poucas frases o caminho feliz e o que acontece nos erros.

## 4. Decisões

Resumo das decisões relevantes; o corpo de cada uma vive em `docs/rd/`.

| RD | Decisão | Status |
|---|---|---|
| [0001](../rd/0001-processamento-assincrono.md) | Processamento assíncrono com fila em banco | aprovado |

## 5. Riscos

- Planilhas fora do layout esperado → mitigação: validação por linha com
  relatório, nunca falha o lote inteiro.
- Volume acima do estimado (>50k linhas) → mitigação: processamento em batches.

## 6. Glossário

Termos novos que esta feature introduz e que ainda não estão no
`docs/glossario.md` do projeto. Se não houver, apague a seção.

RD (Registro de Decisão)¶

---
titulo: "Processamento assíncrono com fila em banco"
tipo: rd
status: aprovado
responsavel: "Fulano da Silva"
modulo: transporte
atualizado: 2026-06-09
tags: [processamento, arquitetura]
---

<!--
TEMPLATE DE RD (REGISTRO DE DECISÃO) — X-Adm
Copie para docs/rd/NNNN-titulo-curto.md no repo da aplicação
(numeração sequencial: 0001, 0002, ...).
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo as seções.
~1 página: "decidimos X porque Y, considerando Z". Não é especificação.
RD aceito NÃO se reescreve: quando mudar de ideia, crie outro RD e marque
este com status: obsoleto + superado-por: NNNN no frontmatter.
-->

# RD 0001 — Processamento assíncrono com fila em banco

## Contexto

O upload de planilhas grandes (até 50k linhas) estoura o timeout HTTP se
processado na própria requisição. Precisamos decidir como desacoplar o upload
do processamento.

## Decisão

Processar de forma assíncrona usando uma tabela de fila no próprio PostgreSQL
(status `PENDENTE → PROCESSANDO → SUCESSO/ERRO`), consumida por um job
agendado do Micronaut.

## Consequências

- O usuário recebe resposta imediata e acompanha o status pela tela de
  processamentos.
- Sem dependência nova de infraestrutura (sem RabbitMQ/Redis) — menos coisa
  pra operar no Coolify.
- Latência de até 1 ciclo do job (30s) entre upload e início do processamento —
  aceitável para o caso de uso.

## Alternativas consideradas

- **Processar na requisição HTTP:** simples, mas estoura timeout em planilhas
  grandes — descartado.
- **Fila dedicada (RabbitMQ):** mais robusto em alto volume, mas adiciona um
  serviço pra manter; volume atual não justifica.

Guia de usuário¶

---
titulo: "Como importar a planilha de frota"
tipo: guia
status: aprovado
responsavel: "time-suporte"
modulo: transporte
cliente: "Vantroba"
atualizado: 2026-06-09
tags: [importacao, frota, xls]
---

<!--
TEMPLATE DE GUIA DE USUÁRIO — X-Adm
Copie para docs/guias/titulo-da-tarefa.md no repo da aplicação.
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo o formato.
Regras de ouro:
- Título é a tarefa na voz do usuário ("Como fazer X").
- Cada seção ## responde UMA pergunta — isso alimenta a busca e o futuro
  chatbot do ERP.
- Sem jargão técnico, sem nome de tabela/coluna, sem detalhe de arquitetura.
- Screenshots em docs/img/, nomeadas pelo guia: importar-frota-01.png, ...
-->

# Como importar a planilha de frota

Use esta tela quando precisar atualizar os veículos da frota no sistema a
partir da planilha Excel.

## Antes de começar

- Tenha a planilha de frota no formato padrão (a mesma que você já usa).
- Você precisa do perfil **Operador de BI** ou superior.

## Passo a passo

1. No menu lateral, clique em **Importações → Frota**.

    ![Tela de importações](../img/importar-frota-01.png)

2. Clique em **Enviar planilha** e selecione o arquivo `.xlsx` no seu
   computador.

3. Confira o resumo (quantidade de linhas reconhecidas) e clique em
   **Confirmar importação**.

    ![Resumo da importação](../img/importar-frota-02.png)

4. Acompanhe o andamento na coluna **Status**. Quando aparecer
   **SUCESSO**, os veículos já estão atualizados nos dashboards.

## Quando der erro, faça isso

**Status ERRO com mensagem "linhas inválidas":** clique no número da
importação para ver o relatório linha a linha. Corrija as linhas apontadas na
planilha e envie de novo — as linhas corretas não são duplicadas.

**A planilha não é aceita no envio:** verifique se o arquivo é `.xlsx`
(Excel moderno). Planilhas `.xls` antigas precisam ser salvas como `.xlsx`
antes do envio.

**O status fica em PENDENTE por mais de 5 minutos:** abra um chamado para o
suporte informando o número da importação.