LerNota/openspec/changes/ajuste-1/design.md

Context

fiscal_documents já possui a coluna categoria_id (FK nullable para categoria), preenchida hoje apenas no fluxo de importação em lote (confirm_batch, auto-categorização por palavra-chave). O cadastro manual (/documents/new) e as duas telas de listagem (Dashboard "Últimos documentos" e /documents) não expõem categoria. Não há ORM — o acesso a dados é feito com sqlite3 puro em app/database.py. O padrão de select populado a partir de tabela já existe no filtro de categoria da Dashboard (list_categorias, ordenado por id ASC).

Goals / Non-Goals

Goals:

• Permitir escolher a categoria ao criar um documento manualmente em /documents/new.
• Persistir essa escolha em fiscal_documents.categoria_id.
• Exibir a coluna "Categoria" (nome, não id) logo após "Fornecedor" nas tabelas da Dashboard e de /documents.
• Ordenar o select de categorias por nome (categoria ASC), não por id, para facilitar a localização pelo usuário.

Non-Goals:

• Não altera o fluxo de auto-categorização por palavra-chave já existente em confirm_batch.
• Não adiciona edição de categoria em documentos já existentes fora do formulário atual (sem tela de edição dedicada nesta mudança, a menos que já exista update_fiscal chamada por uma tela de edição — nesse caso o mesmo campo é reaproveitado).
• Não altera o schema do banco (coluna já existe).

Decisions

1. Ordenação do select por nome, não por id: list_categorias atual faz ORDER BY id ASC. Para o novo select em /documents/new será usada uma consulta (nova função list_categorias_ordenadas_por_nome ou parâmetro de ordenação em list_categorias) com ORDER BY categoria ASC, conforme pedido explícito do usuário. Optamos por não alterar o ORDER BY do list_categorias existente (usado no filtro da Dashboard) para não mudar comportamento não solicitado; em vez disso adicionamos uma variante/parâmetro.
2. Exposição do nome da categoria nas listagens via LEFT JOIN: em vez de fazer uma segunda query por linha (N+1), a consulta usada por Dashboard e /documents (list_fiscal ou equivalente) passa a fazer LEFT JOIN categoria ON fiscal_documents.categoria_id = categoria.id, trazendo categoria.categoria AS categoria_nome. LEFT JOIN (não INNER) para não esconder documentos sem categoria.
3. Campo opcional no formulário: o <select name="categoria_id"> inclui uma opção vazia/"Sem categoria" para não obrigar o usuário a categorizar manualmente, mantendo compatibilidade com documentos sem categoria.
4. Reuso de create_fiscal/update_fiscal: adicionar parâmetro opcional categoria_id=None a essas funções em vez de criar novas funções, minimizando duplicação.

Risks / Trade-offs

• [Alterar list_fiscal para incluir JOIN pode impactar outros chamadores que dependem do shape atual do retorno (linha como tupla/Row)] → Mitigação: adicionar apenas colunas extras ao final do SELECT (não remover/reordenar colunas existentes) e verificar todos os call sites de list_fiscal antes de alterar.
• [Footer com colspan fixo em documents_list.html pode quebrar visualmente ao adicionar coluna] → Mitigação: ajustar o colspan do footer/total ao adicionar a nova <th>.
• [Usuário pode confundir "Sem categoria" com a categoria "Não Encontrado" (id=1) já existente] → Mitigação: usar valor vazio (NULL) para "Sem categoria" no select, distinto da categoria seedada "Não Encontrado".

Migration Plan

Sem migração de dados necessária (coluna já existe). Deploy é apenas código: rotas, templates e função de listagem. Rollback trivial (reverter os arquivos alterados), pois nenhuma escrita de schema é feita.