Regras de importação IPL — flags ct_controle e relatórios
Público: produto, desenvolvimento, operações
Módulo: ecosif-automations (Lambdas import → entries → consolidation)
Referência legada: ImportReportDetailsServiceImpl (ecosif-moviments)
1. Flags de empresa (ct_controle)
| Campo PostgreSQL | Java (CompanyOptions) |
Significado |
|---|---|---|
documento |
useDocument |
false → um documento 000001 por lote |
loteencerra |
changeBatch |
Permite reutilizar/atualizar lote existente |
lanencerra |
changeEntry |
Permite substituir lançamento existente (por código) |
2. Convenção de nomes dos relatórios (S3)
Prefixo padrão do bucket: imported/reports/ (AWS_S3_REPORTS_FOLDER).
2.1 Relatório mensal agregado (resumo de todas as importações do fundo no mês)
| Item | Valor |
|---|---|
| Padrão | {FUNDO}_{YYYYMM}_report.csv |
| Exemplo | 003AA_202605_report.csv — todas as execuções de importação do fundo 003AA na competência 05/2026 |
| Comportamento | Ficheiro append-only: a cada fim de pipeline (sucesso ou falha parcial), acrescenta uma linha de resumo |
| Localização | s3://{bucket}/imported/reports/003AA_202605_report.csv |
YYYYMM deriva da competência contábil do processo (mês/ano do lote ou do nome do IPL — ver implementação Fase 3).
2.2 Relatório crítico do arquivo (uma linha por lançamento do IPL)
| Item | Valor |
|---|---|
| Padrão | {nome_ipl}.REPORT.csv |
| Exemplo | 003AA_20260501.IPL.REPORT.csv |
| Comportamento | Gerado por execução desse IPL; 1 linha IPL = 1 linha CSV (status por etapa) |
| Localização | s3://{bucket}/imported/reports/003AA_20260501.IPL.REPORT.csv |
2.3 Relatório de alterações (quando loteencerra e lanencerra = true)
| Item | Valor |
|---|---|
| Padrão | {nome_ipl}.CHANGES.csv (opcional, mesma pasta) |
| Exemplo | 003AA_20260504.IPL.CHANGES.csv |
| Conteúdo | Auditoria: código de lançamento, ação (REPLACE/INSERT/SKIP), dia/valor/conta anterior vs novo |
2.4 Erros rápidos (mantido)
| Item | Valor |
|---|---|
| Padrão | importError/ERRO_{nome_ipl}.csv |
| Exemplo | importError/ERRO_003AA_20260501.csv |
2.5 Depreciação
| Antigo | Novo |
|---|---|
{fileName}.report.csv |
{fileName}.REPORT.csv |
| Log agregado genérico | {FUNDO}_{YYYYMM}_report.csv |
3. Layout dos CSV
3.1 {FUNDO}_{YYYYMM}_report.csv (uma linha por execução de import)
Timestamp;FileName;ImportId;Message;CT32Status;Calendar;LotDocuments;FinalStatus;Lots;Entries;Accounts;QuotaValue
| Coluna | Descrição |
|---|---|
Timestamp |
Fim do pipeline (ou falha) |
FileName |
IPL processado (ex. 003AA_20260504.IPL) |
ImportId |
UUID da execução |
Message |
Resumo humano |
CT32Status |
CT32.LD FILE OK / NOT FOUND / … |
Calendar |
OK / ERROR / -- |
LotDocuments |
OK / ERROR / -- |
FinalStatus |
DONE / ERROR / PARTIAL |
Lots |
Lotes afetados (contagem) |
Entries |
inseridos/total (ex. 6/6) |
Accounts |
Contas na consolidação |
QuotaValue |
Valor da cota calculada |
3.2 {nome_ipl}.REPORT.csv (uma linha por lançamento do arquivo)
Timestamp;FileName;LineNo;Entry;ImportId;Company;CT32;Calendar;Account;History;Batch;Document;EntryStatus;Consolidation;Quota;Message;Status
| Coluna | Valores típicos |
|---|---|
Entry |
Código IPL (ex. 00001) |
CT32 / Calendar / Account / History |
OK, ERROR, SKIP, -- |
EntryStatus |
Resultado da gravação em ct_lancamento |
Consolidation / Quota |
-- se lote/arquivo não concluiu etapa |
Status |
OK, ERROR, DUPLICATE, SKIPPED |
Message |
Motivo operacional (ex. Entry day 04 does not match batch reference day 01) |
4. Matriz de comportamento (loteencerra × lanencerra)
Legenda: L = loteencerra, E = lanencerra.
| L | E | Lote existente | Lançamento existente | Ação |
|---|---|---|---|---|
| N | N | Sim | — | Rejeitar arquivo — lote já existe; mensagem no _report.csv mensal e no .REPORT.csv |
| N | N | Não | — | Criar lote/doc/lançamentos |
| N | N | — | Sim (mesmo doc) | Rejeitar linha — DUPLICATE / já processado (#2) |
| S | S | Sim | Sim | Substituir por código; gerar .CHANGES.csv (#1) |
| S | S | Sim | Não | Inserir novo lançamento |
| S | S | Não | — | Criar lote/doc/lançamentos |
| N | S | Sim | — | Lote não altera estrutura; só lançamentos (#3) |
| N | S | Sim | Não | Inserir se dia compatível com diareferencia do lote |
| S | N | Sim | Sim | Erro na linha — código já existe, alteração de lançamento desligada (#4) |
| S | N | Sim | Não | Zerar diareferencia do lote (00 ou vazio); inserir linhas novas (#4) |
| S | N | Não | — | Criar lote com dia conforme IPL |
5. Regras de negócio (detalhe)
5.1 Validação estrutural do IPL (Fase 1 — P0, antes de insert)
-
Uma data por arquivo
Todas as linhas do IPL devem ter a mesma data de movimento (prefixoYYMMDDnas posições 0–6).
Se houver mais de uma data distinta → erro de arquivo (nenhum insert); todas as linhas no.REPORT.csvcomStatus=ERRORe mesmaMessage. -
Coerência nome do arquivo × linhas (recomendado)
003AA_20260501.IPLdeve ter linhas com data260501. Divergência →ERRORcom mensagem explícita. -
Competência
Mês/ano do lote = derivado do IPL (nome ou data das linhas — política única documentada na implementação).
5.2 Regra #2 — Não altera lote nem lançamento (L=N, E=N)
- Lote
(empresa, filial, ano, mês, código lote)já existe → falha no nível arquivo (não processar SQS entries ou rollback). - Mensagem no mensal:
LOT already exists — update batch disabled. - Linha já existente no documento →
DUPLICATE_ENTRY — already processed.
5.3 Regra #3 — Altera lançamento, não altera lote (L=N, E=S)
- Se
ct_lote.diareferencianão é00, vazio ouNULL: cada linha deve terdiaigual ao dia de referência do lote (ou do documento, se preenchido). - Dia diferente → linha
ERROR:Entry day DD does not match batch reference day RR.
5.4 Regra #4 — Altera lote, não altera lançamento (L=S, E=N)
- Ao reabrir lote existente:
UPDATE ct_lote SET diareferencia = '00'(ouNULL, alinhar ao legado). - Não apagar lançamentos existentes.
- Código de lançamento já presente no documento → erro na linha (não substituir).
- Apenas códigos novos são inseridos.
5.5 Regra #1 — Altera lote e lançamento (L=S, E=S)
- Permitido substituir lançamentos pelo código (
DELETE+INSERTno mesmodocto_id). - Obrigatório registrar em
{nome_ipl}.CHANGES.csvcadaREPLACEcom valores/dias anteriores. - Relatório mensal deve indicar contagem de substituições (campo
Messageou coluna futuraChanges).
5.6 Cenário de teste: três IPLs, mesmo lote 000001 no arquivo
Ficheiros: 003AA_20260501.IPL, 003AA_20260504.IPL, 003AA_20260505.IPL.
Processo atual (dia = chave): cada data gera um ct_lote distinto (000001, 000002, 000003); ver processo_lote_por_dia_e_arquivo.md.
| Upload | ct_lote.lote |
diareferencia |
ct_lote.arquivo_ipl |
|---|---|---|---|
| 1 | 000001 | 01 | 003AA_20260501.IPL |
| 2 | 000002 | 04 | 003AA_20260504.IPL |
| 3 | 000003 | 05 | 003AA_20260505.IPL |
UK: (lote, empresa, filial, ano, mes). Reimport do mesmo arquivo: localiza por arquivo_ipl e aplica flags loteencerra / lanencerra.
6. Plano de implementação (ordem)
| Fase | Entrega | Ficheiros principais |
|---|---|---|
| 1 — P0 | Matriz §4 + regras §5.1–5.5 em entries_service.py |
entries_service.py, queries.py |
| 2 | {nome_ipl}.REPORT.csv por execução |
import_report_service.py, entries_handler.py |
| 3 | {FUNDO}_{YYYYMM}_report.csv append |
s3_client.append_report_line(), consolidation_handler.py |
| 4 | {nome_ipl}.CHANGES.csv quando L=S e E=S |
entries_service.py, entries_handler.py |
| 5 | Calendário, histórico, contas por linha | import_service.py |
| 6 | Testes + sequência 20260501 → 20260504 → 20260505 |
tests/, .internal_docs/automation-test/ |
7. Exemplo de evolução do relatório mensal
Após três uploads em maio/2026 com 003AA:
Timestamp;FileName;ImportId;Message;CT32Status;Calendar;LotDocuments;FinalStatus;Lots;Entries;Accounts;QuotaValue
2026-05-22 10:00:00;003AA_20260501.IPL;a1b2...;Imported 6 entries;CT32.LD FILE OK;OK;OK;DONE;1;6/6;24;0.00
2026-05-22 11:00:00;003AA_20260504.IPL;c3d4...;Replaced 7 entries;CT32.LD FILE OK;OK;OK;DONE;1;7/7;24;0.00
2026-05-22 12:00:00;003AA_20260505.IPL;e5f6...;Replaced 7 entries;CT32.LD FILE OK;OK;OK;DONE;1;7/7;24;0.00
Ficheiro único: imported/reports/003AA_202605_report.csv.
8. Referências
- deploy/operacao.md — pastas S3 e monitorização
- ../deploy/implantacao_aws.md — deploy Lambdas
- Tasks (feito / pendente): ../legacy/old-docs/docs-legacy/docs-tree/old-docs/TASKS-IMPORT-IPL.md
- Plano interno:
.internal_docs/PLANO-CORRECAO-PARIDADE-MOVIMENTS.md
Versão doc: 2026-05-22 — nomes de relatório alinhados com operação (mensal {FUNDO}_{YYYYMM}_report.csv, crítica {IPL}.REPORT.csv).