ProtheusCentroCusto (STATUS: PARCIAL)

Documentação Técnica

Histórico de Versões

Descrição

Esta biblioteca expõe um endpoint para cadastro e atualização de centros de custo e seus rateios, recebendo os dados via parâmetros e persistindo diretamente nas tabelas CTB_CENTRO_CUSTO, CTB_CENTRO_CUSTO_RATEIO e CTB_CENTRO_CUSTO_RATEIO_ITEM.

Endpoint (API)

O endpoint recebe um array de parâmetros via método run(), valida os campos obrigatórios conforme o schema definido em $fields, aplica a máscara em CENTRO_CUSTO e persiste ou atualiza os registros nas tabelas de centro de custo. Em caso de falha na validação, o processo é interrompido com exceção contendo as mensagens de erro. Quando houver RATEIOS, o fluxo persiste o centro de custo como rateio em CTB_CENTRO_CUSTO_RATEIO, remove os itens antigos de CTB_CENTRO_CUSTO_RATEIO_ITEM e insere/atualiza cada item do rateio. Quando não houver RATEIOS, persiste apenas cadastro simples em CTB_CENTRO_CUSTO. Em sucesso, retorna os parâmetros enriquecidos com Mensagem e Mensagem Detalhada.

Tabelas de banco de dados envolvidas: CTB_CENTRO_CUSTO_GRUPO (origem dos grupos de centro de custo para lista de validação), CTB_CENTRO_CUSTO (persistência do cadastro do centro de custo), CTB_CENTRO_CUSTO_RATEIO (persistência do cadastro de rateio), CTB_CENTRO_CUSTO_RATEIO_ITEM (persistência dos itens de rateio).

Estruturação de Dados

Tratamento de Dados

- Máscara de centro de custo: CENTRO_CUSTO e RATEIO_CENTRO_CUSTO são formatados via getMaskCentroCusto() antes da persistência.

- Normalização numérica: PORCENTAGEM é normalizado via getNumeric() (padrão 2 casas decimais) antes da persistência em CTB_CENTRO_CUSTO_RATEIO_ITEM.

- Reestruturação para persistência em CTB_CENTRO_CUSTO (mapeamento hydrateCtbCentroCusto): CENTRO_CUSTO recebe o valor mascarado; DESC_CENTRO_CUSTO recebe o valor de DESCRICAO; INATIVA e ID_GRUPO_CENTRO_CUSTO (de GRUPO_CENTRO_CUSTO) são repassados; DATA_PARA_TRANSFERENCIA utiliza GETDATE() em cadastro novo ou data/hora atual formatada (Y-m-d H:i:s) em atualização.

- Reestruturação para persistência em CTB_CENTRO_CUSTO_RATEIO (mapeamento hydrateCtbCentroCustoRateio): DESC_RATEIO_CENTRO_CUSTO recebe o valor de DESCRICAO; INATIVO recebe o valor de INATIVA; RATEIO_CENTRO_CUSTO recebe o valor mascarado de CENTRO_CUSTO; RATEIO_ENTRAR_EM_LISTA = 1; DATA_PARA_TRANSFERENCIA utiliza GETDATE() em cadastro novo ou data/hora atual em atualização.

- Reestruturação para persistência em CTB_CENTRO_CUSTO_RATEIO_ITEM (mapeamento hydrateCtbCentroCustoRateioItem): CENTRO_CUSTO recebe o valor mascarado de RATEIO_CENTRO_CUSTO; PORCENTAGEM recebe o valor normalizado; RATEIO_CENTRO_CUSTO recebe o valor mascarado de CENTRO_CUSTO; RATEIO_CENTRO_CUSTO_ITEM recebe o valor de ITEM.

Persistência

O endpoint não realiza chamada HTTP ao Protheus. A integração ocorre por persistência direta nas tabelas.

- Cadastro simples (sem RATEIOS): quando não existir registro com o CENTRO_CUSTO informado (após máscara), é executado INSERT em CTB_CENTRO_CUSTO; quando já existir, é executado UPDATE em CTB_CENTRO_CUSTO com DATA_PARA_TRANSFERENCIA atualizada.

- Cadastro com rateio (com RATEIOS): primeiro persiste em CTB_CENTRO_CUSTO_RATEIO (INSERT ou UPDATE). Em seguida, executa DELETE FROM CTB_CENTRO_CUSTO_RATEIO_ITEM WHERE RATEIO_CENTRO_CUSTO = ... para remover os itens antigos. Para cada item do array RATEIOS, persiste em CTB_CENTRO_CUSTO_RATEIO_ITEM (INSERT ou UPDATE).

- Transação: cada operação (setCtbCentroCusto, setCtbCentroCustoRateio, setCtbCentroCustoRateioItem) é executada dentro de transação; em caso de exceção, é realizado rollBack e a mensagem de erro é prefixada com o nome da tabela afetada.

Tratamento de retorno

- Sucesso: retorna o array de parâmetros com Mensagem = OK e Mensagem Detalhada = "Registrado com sucesso."

- Erro de validação: quando validar() retornar mensagens, o processo é interrompido com exceção contendo as mensagens concatenadas.

- Erro de persistência: em falha no INSERT, UPDATE ou DELETE, a transação é revertida e é lançada exceção com detalhes do erro.

Fluxo do Processo

Critérios de Aceitação