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

1. Usuário envia requisição POST /company com: json { "name": "Minha Empresa LTDA", "cnpj": "12345678000190", "zipCode": "01310100" }

2. Sistema valida dados de entrada

3. Sistema valida CNPJ (formato e dígitos verificadores)

4. Sistema verifica se CNPJ já existe: - Se existe: Retorna 409 Conflict

5. Sistema cria empresa no banco de dados

6. 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

1. Usuário envia requisição POST /branch com: json { "company": "01", "branch": "01", "name": "Filial São Paulo" }

2. Sistema valida que empresa existe

3. Sistema verifica se código de filial já existe: - Se existe: Retorna 409 Conflict

4. Sistema cria filial no banco de dados

5. Sistema cria registros necessários automaticamente: - CompanyOptions (ct_controle) - QuotaCalculationConfiguration (se aplicável) - FundSettings (se aplicável)

6. 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

1. Usuário envia requisição POST /chartOfAccounts com: json { "plan": "10", "cdAccounting": "1.1.1", "cdReduced": "001", "description": "Caixa", "level": 3 }

2. Sistema valida que código não existe no plano

3. Sistema extrai conta pai do código ("1.1")

4. Sistema verifica se conta pai existe: - Se não existe: Retorna 406 Not Acceptable

5. Sistema verifica se conta pai já tem filhos: - Se tem e não confirmado: Retorna 406 Not Acceptable

6. Sistema cria conta no banco de dados

7. Sistema atualiza número de filhos da conta pai

8. 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

1. Usuário envia requisição POST /entry com: json { "documentId": 1, "account": "1.1.1", "history": "10", "debit": 1000.00, "credit": 0.00 }

2. Sistema valida que documento existe

3. Sistema valida que dia está disponível no calendário

4. Sistema valida que conta existe no plano de contas

5. Sistema cria lançamento no banco de dados

6. 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

1. Usuário envia requisição POST /runconsolidation com: json { "company": "01", "branch": "01", "month": "12", "year": "2023" }

2. Sistema valida que período está fechado

3. Sistema inicia processamento assíncrono

4. Sistema retorna resposta imediata: json { "success": true, "message": "Consolidação iniciada" }

5. 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

1. Usuário envia requisição GET /usercompanies com token JWT

2. Sistema valida token JWT

3. Sistema extrai username do token

4. Sistema busca associações usuário-empresa-filial

5. Sistema busca empresas associadas

6. Sistema retorna lista de empresas: json [ { "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

Resumo dos Casos de Uso