34 lines
3.7 KiB
Markdown
34 lines
3.7 KiB
Markdown
## 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.
|