Casos de Uso - ecosif-masterdata¶

Visão Geral¶

Este documento descreve os principais casos de uso do sistema ecosif-masterdata.

CU-001: Cadastrar Empresa¶

Descrição¶

Um usuário cadastra uma nova empresa no sistema.

Ator Principal¶

Administrador ou usuário com permissão

Pré-condições¶

Usuário está autenticado
Usuário tem permissão para cadastrar empresas
CNPJ é válido e não existe no sistema

Fluxo Principal¶

Usuário envia requisição POST /company com:

{
  "name": "Minha Empresa LTDA",
  "cnpj": "12345678000190",
  "zipCode": "01310100"
}

Sistema valida dados de entrada
Sistema valida CNPJ (formato e dígitos verificadores)
Sistema verifica se CNPJ já existe:
Se existe: Retorna 409 Conflict
Sistema cria empresa no banco de dados
Sistema retorna empresa criada com ID gerado

Pós-condições¶

Empresa cadastrada no sistema
Empresa pode receber filiais
Empresa pode ter plano de contas associado

CU-002: Cadastrar Filial¶

Descrição¶

Um usuário cadastra uma nova filial para uma empresa existente.

Ator Principal¶

Administrador ou usuário com permissão

Pré-condições¶

Empresa existe no sistema
Código de filial não existe para a empresa
Usuário está autenticado

Fluxo Principal¶

Usuário envia requisição POST /branch com:

{
  "company": "01",
  "branch": "01",
  "name": "Filial São Paulo"
}

Sistema valida que empresa existe
Sistema verifica se código de filial já existe:
Se existe: Retorna 409 Conflict
Sistema cria filial no banco de dados
Sistema cria registros necessários automaticamente:
CompanyOptions (ct_controle)
QuotaCalculationConfiguration (se aplicável)
FundSettings (se aplicável)
Sistema retorna filial criada

Pós-condições¶

Filial cadastrada
Configurações padrão criadas
Filial pode receber lançamentos contábeis

CU-003: Criar Plano de Contas¶

Descrição¶

Um usuário cria uma estrutura de plano de contas hierárquica.

Ator Principal¶

Contador ou administrador contábil

Pré-condições¶

Empresa/filial existe
Usuário está autenticado

Fluxo Principal¶

Usuário envia requisição POST /chartOfAccounts com:

{
  "plan": "10",
  "cdAccounting": "1.1.1",
  "cdReduced": "001",
  "description": "Caixa",
  "level": 3
}

Sistema valida que código não existe no plano
Sistema extrai conta pai do código ("1.1")
Sistema verifica se conta pai existe:
Se não existe: Retorna 406 Not Acceptable
Sistema verifica se conta pai já tem filhos:
Se tem e não confirmado: Retorna 406 Not Acceptable
Sistema cria conta no banco de dados
Sistema atualiza número de filhos da conta pai
Sistema retorna conta criada

Pós-condições¶

Conta adicionada ao plano de contas
Hierarquia mantida corretamente
Conta pode ser usada em lançamentos

CU-004: Registrar Lançamento Contábil¶

Descrição¶

Um usuário registra um lançamento contábil em um documento.

Ator Principal¶

Contador ou usuário autorizado

Pré-condições¶

Documento existe e está aberto
Conta existe no plano de contas
Dia está disponível no calendário
Usuário está autenticado

Fluxo Principal¶

Usuário envia requisição POST /entry com:

{
  "documentId": 1,
  "account": "1.1.1",
  "history": "10",
  "debit": 1000.00,
  "credit": 0.00
}

Sistema valida que documento existe
Sistema valida que dia está disponível no calendário
Sistema valida que conta existe no plano de contas
Sistema cria lançamento no banco de dados
Sistema retorna lançamento criado

Regras de Negócio¶

Partidas Dobradas: Soma de débitos = soma de créditos no documento
Validação de Conta: Conta deve existir e estar ativa
Validação de Dia: Dia deve estar disponível para lançamentos

Pós-condições¶

Lançamento registrado
Saldos podem ser calculados
Documento pode ser fechado quando completo

CU-005: Executar Consolidação Contábil¶

Descrição¶

Um usuário executa o processo de consolidação contábil para um período.

Ator Principal¶

Administrador contábil

Pré-condições¶

Período está fechado
Existem lançamentos no período
Usuário está autenticado

Fluxo Principal¶

Usuário envia requisição POST /runconsolidation com:

{
  "company": "01",
  "branch": "01",
  "month": "12",
  "year": "2023"
}

Sistema valida que período está fechado
Sistema inicia processamento assíncrono

Sistema retorna resposta imediata:

{
  "success": true,
  "message": "Consolidação iniciada"
}

Sistema processa em background:
Busca todos os lançamentos do período
Calcula saldos por conta
Atualiza saldos diários
Atualiza saldos mensais
Atualiza saldos consolidados

Fluxos Alternativos¶

FA-001: Período Não Fechado¶

Ação: Período não está fechado
Resultado: Retorna 400 Bad Request com mensagem apropriada

Pós-condições¶

Saldos calculados e atualizados
Dados prontos para relatórios
Consolidação disponível para consultas

CU-006: Consultar Empresas do Usuário¶

Descrição¶

Um usuário consulta empresas às quais tem acesso.

Ator Principal¶

Usuário autenticado

Pré-condições¶

Usuário está autenticado
Token JWT válido

Fluxo Principal¶

Usuário envia requisição GET /usercompanies com token JWT
Sistema valida token JWT
Sistema extrai username do token
Sistema busca associações usuário-empresa-filial
Sistema busca empresas associadas

Sistema retorna lista de empresas:

[
  {
    "id": 1,
    "name": "Empresa A",
    "cnpj": "12345678000190"
  },
  {
    "id": 2,
    "name": "Empresa B",
    "cnpj": "98765432000110"
  }
]

Pós-condições¶

Usuário visualiza empresas disponíveis
Usuário pode selecionar empresa para operar

CU-007: Encerrar contas de resultado¶

Descrição¶

Usuário executa o encerramento definitivo das contas de resultado (naturezas 2 / 3 / 6 / 7), gerando um único lote tipo Encerramento com pares D/C contra a conta partida.

Ator Principal¶

Usuário com permissão de encerramento / contabilidade

Pré-condições¶

Empresa/filial e período válidos
Contas de resultado com saldo a zerar
Período ainda não encerrado para a rotina

Fluxo Principal¶

Usuário aciona o encerramento definitivo (API masterdata / tela de encerramento).
Sistema cria 1 lote batchType = "2" e 1 documento.
Para cada conta de resultado, gera 1 lançamento lógico (2 linhas físicas D+C, mesmo número, histórico igual, contrapartida cruzada).
Sistema retorna mensagem com número do lote e orientação para consolidar manualmente o dia/mês.
Na tela de lotes/lançamentos, o tipo Encerramento aparece como "2" e o par D+C é exibido.

Pós-condições¶

Contas de resultado zeradas no lote de encerramento
Usuário orientado a consolidar (sem auto-consolidação nesta entrega)
Reexecução bloqueada se já encerrado

Refs¶

MD-ENCERRAMENTO · Issues #34–#38

Resumo dos Casos de Uso¶

ID	Nome	Tipo	Prioridade
CU-001	Cadastrar Empresa	Primário	Alta
CU-002	Cadastrar Filial	Primário	Alta
CU-003	Criar Plano de Contas	Primário	Alta
CU-004	Registrar Lançamento	Primário	Alta
CU-005	Executar Consolidação	Primário	Alta
CU-006	Consultar Empresas do Usuário	Primário	Média
CU-007	Encerrar contas de resultado	Primário	Alta