82 lines
5.9 KiB
Markdown
82 lines
5.9 KiB
Markdown
## ADDED 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`
|