LerNota/openspec/specs/document-competencia/spec.md

document-competencia Specification

Purpose

Define como o sistema representa e gerencia a competência (mês/ano) de um documento fiscal, substituindo a data completa de compra por dois campos inteiros (mes, ano) em toda a aplicação — persistência, extração, revisão pós-upload, cadastro manual, dashboard, listagens e migração de dados existentes.

Requirements

Requirement: Persistência de Competência (Mês/Ano)

O sistema SHALL persistir a competência de um documento fiscal como dois campos inteiros, mes (1-12) e ano (ex. 2026), em vez de uma data completa de compra. Em fiscal_documents, mes e ano SHALL ser obrigatórios (não nulos). Em detected_documents (staging), mes e ano SHALL permanecer opcionais enquanto o documento não tiver sido revisado/confirmado.

Scenario: Documento confirmado exige competência

• WHEN um documento em staging é promovido para fiscal_documents via confirmação de lote
• THEN o registro criado possui mes e ano preenchidos com valores válidos (mes entre 1 e 12, ano numérico)

Scenario: Documento em staging pode estar sem competência

• WHEN um documento acabou de ser detectado por OCR/IA e ainda não foi revisado
• THEN mes e/ou ano podem estar nulos em detected_documents até que o usuário revise e preencha a competência

Requirement: Extração Não Persiste Mais Data Completa

O sistema SHALL deixar de persistir o dia da compra em qualquer tabela. A extração via IA ou OCR pode continuar identificando uma data completa no texto/imagem do documento, mas o dia SHALL ser descartado antes da persistência, mantendo-se apenas mês e ano.

Scenario: Data completa detectada no documento

• WHEN a extração (IA ou OCR) identifica uma data completa (dia/mês/ano) no documento
• THEN o sistema armazena apenas o mês e o ano correspondentes, descartando o dia

Requirement: Confirmação Obrigatória de Competência Antes do Envio

Na tela de revisão pós-upload, o sistema SHALL exigir que o usuário confirme explicitamente a Competência (Mês/Ano) de cada documento, através de dois campos de seleção — Mês (Jan a Dez) e Ano (2026 a 2030) — antes de permitir a confirmação do lote.

Scenario: Competência pré-selecionada a partir da extração

• WHEN a extração identificou um mês/ano válido para o documento
• THEN os seletores de Mês e Ano na tela de revisão vêm pré-selecionados com esses valores, permitindo correção manual pelo usuário

Scenario: Competência ausente bloqueia confirmação do lote

• WHEN um ou mais documentos do lote não têm Mês e Ano selecionados
• THEN o sistema não permite confirmar o lote até que a competência de todos os documentos pendentes seja preenchida

Requirement: Seleção de Competência no Cadastro Manual

O formulário manual de criação/edição de documento fiscal (document_form.html) SHALL substituir o campo de data por dois seletores — Mês (Jan a Dez) e Ano (2026 a 2030) — para definir a competência do documento.

Scenario: Criação manual de documento

• WHEN o usuário cria um novo documento fiscal manualmente
• THEN o formulário exige a seleção de Mês e Ano em vez de uma data completa

Scenario: Edição de documento existente

• WHEN o usuário edita um documento fiscal existente
• THEN os seletores de Mês e Ano vêm pré-preenchidos com a competência atual do documento, podendo ser alterados

Requirement: Exibição de Competência no Dashboard e Listagens

O Dashboard e a listagem de documentos (/documents) SHALL exibir a competência de cada documento no formato "Mês abreviado/Ano com 2 dígitos" (ex. "Jun/26", "Jul/26") no lugar da antiga coluna "Data".

Scenario: Tabela "Últimos documentos" no Dashboard

• WHEN o usuário visualiza o Dashboard
• THEN cada linha da tabela "Últimos documentos" exibe a competência (mês/ano) do documento, em vez da data completa

Scenario: Coluna na listagem de documentos

• WHEN o usuário visualiza a listagem /documents
• THEN a coluna antes chamada "Data" exibe a competência (mês/ano) de cada documento, e continua ordenável

Requirement: Filtro por Competência na Listagem de Documentos

A listagem /documents SHALL permitir filtrar documentos por intervalo de competência (Mês/Ano inicial e Mês/Ano final), substituindo o filtro anterior por intervalo de datas.

Scenario: Filtro por intervalo de competência

• WHEN o usuário seleciona uma competência inicial (ex. Jan/2026) e uma competência final (ex. Jun/2026) nos filtros da listagem
• THEN apenas documentos cuja competência esteja dentro desse intervalo (inclusive) são exibidos

Scenario: Ordenação por competência

• WHEN o usuário ordena a listagem pela coluna de competência
• THEN os documentos são ordenados por ano e mês (crescente ou decrescente conforme selecionado)

Requirement: Agregação Mensal do Dashboard por Competência Nativa

O gráfico "Gastos por mês" do Dashboard SHALL agrupar os totais diretamente pelas colunas ano/mes de fiscal_documents, em vez de derivar o mês a partir de uma string de data.

Scenario: Totais mensais agrupados por competência

• WHEN o Dashboard calcula os totais mensais para exibição
• THEN o agrupamento é feito pelas colunas ano e mes, e o rótulo exibido (ex. "Jun/26") é formatado a partir desses valores nativos

Requirement: Migração de Dados Existentes para Competência

Ao atualizar para esta mudança, o sistema SHALL migrar automaticamente todos os registros existentes de fiscal_documents e detected_documents, preenchendo mes e ano a partir da data de compra anteriormente armazenada, antes de remover o campo de data.

Scenario: Migração automática na inicialização

• WHEN a aplicação inicializa contra um banco de dados que ainda contém o campo de data completa
• THEN o sistema preenche mes e ano de cada registro a partir da data existente e remove o campo de data, sem exigir intervenção manual do usuário

Scenario: Migração já aplicada não é repetida

• WHEN a aplicação inicializa contra um banco de dados que já foi migrado (campo de data já removido)
• THEN o sistema não tenta migrar novamente e opera normalmente com mes/ano