api

O módulo de API do Pós-Recebimento expõe um único endpoint de criação:

• POST /pos-recebimento/termos/ — criação do Termo de Recebimento Definitivo (basename termos-recebimento-definitivo).

O payload de criação espera os uuids de empresa, contrato, cronogramas (cada um com valor_contrato e quantidade_total_recebida), fiscal_1, fiscal_2, fiscal_3 e texto_termo. Respostas: 201 com o termo serializado, 400 com os erros de validação ou 403 para usuários sem permissão.

viewsets

class TermoRecebimentoDefinitivoViewSet(**kwargs)

Bases: CreateModelMixin, GenericViewSet

Criação do Termo de Recebimento Definitivo (Salvar e Enviar).

create(request, *args, **kwargs)

Cria o termo (valida, persiste e retorna 201 com o serializador de saída).

lookup_field = 'uuid'

perform_create(serializer)

Persiste o termo com status ENVIADO e cria as linhas do modelo intermediário (cronograma + valor_contrato + quantidade total recebida) para cada cronograma do payload.

permission_classes = (<class 'src.pos_recebimento.api.permissions.PermissaoParaCadastrarTermoRecebimentoDefinitivo'>,)

queryset = <QuerySet de TermoRecebimentoDefinitivo>

serializer_class

alias of TermoRecebimentoDefinitivoCreateSerializer

O TermoRecebimentoDefinitivoViewSet implementa o fluxo “Salvar e Enviar”: a criação é feita em uma única operação e o termo é persistido com status ENVIADO, independentemente do default do modelo (RASCUNHO). O criado_por e o alterado_por são preenchidos com o usuário autenticado da requisição.

O fluxo de criação:

1. O serializador de criação valida o payload (ver serializers_create).

2. perform_create retira os cronogramas do validated_data, salva o termo com status=ENVIADO e os usuários da requisição.

3. Para cada item de cronograma é criada uma linha do modelo intermediário CronogramaTermoRecebimentoDefinitivo com o cronograma, valor_contrato e quantidade_total_recebida.

4. A resposta 201 é montada com o serializador de saída (TermoRecebimentoDefinitivoSerializer), que já traz empresa, contrato, cronogramas (com valores) e fiscais serializados pelos serializers de seus respectivos módulos.

permissions

class PermissaoParaCadastrarTermoRecebimentoDefinitivo

Bases: BasePermission

Permissão para cadastrar/visualizar Termo de Recebimento Definitivo.

Apenas os perfis DILOG_CRONOGRAMA e COORDENADOR_CODAE_DILOG_LOGISTICA (vinculados à CODAE) podem acessar as funcionalidades do módulo Pós-Recebimento.

PERFIS_PERMITIDOS = ['DILOG_CRONOGRAMA', 'COORDENADOR_CODAE_DILOG_LOGISTICA']

has_permission(request, view)

Return True if permission is granted, False otherwise.

Permissão PermissaoParaCadastrarTermoRecebimentoDefinitivo: apenas usuários autenticados, com vínculo atual ativo vinculado à CODAE (instituição Codae) e cujo perfil do vínculo atual seja DILOG_CRONOGRAMA ou COORDENADOR_CODAE_DILOG_LOGISTICA podem acessar as funcionalidades do Pós-Recebimento.

Além do endpoint de criação de termos, essa mesma permissão protege as listagens de apoio ao cadastro, implementadas em outros módulos:

• GET /terceirizadas/lista-empresas-pos-recebimento/ — empresas com ao menos uma ficha de recebimento “Assinado CODAE”.

• GET /cronogramas/lista-cronogramas-pos-recebimento/?contrato_id=<uuid> — cronogramas vinculados ao contrato selecionado.

• GET /cronogramas/<uuid>/dados-cronograma-pos-recebimento/ — dados do cronograma para preenchimento automático do cadastro.

• GET /usuarios/fiscais/ — usuários com perfil DILOG_QUALIDADE e vínculo ativo para seleção dos fiscais.

services

class TermoRecebimentoDefinitivoService

Bases: object

Regra de negócio do Pós-Recebimento referente ao modelo novo.

As listagens de empresas, contratos, cronogramas e fiscais foram movidas para os services/viewsets dos seus respectivos módulos (terceirizada, pre_recebimento e perfil). Aqui permanece apenas a regra utilizada na criação do Termo de Recebimento Definitivo.

static empresa_tem_ficha_assinada(empresa)

Verifica se uma empresa possui ficha de recebimento assinada pela CODAE.

O TermoRecebimentoDefinitivoService concentra as regras de negócio do Pós-Recebimento. Atualmente mantém apenas a regra empresa_tem_ficha_assinada: verifica se a empresa possui ao menos uma ficha de recebimento com status “Assinado CODAE” (FichaDeRecebimentoWorkflow.ASSINADA), navegando pela relação empresa -> cronogramas -> etapas -> ficha de recebimento.

serializers

class CronogramaTermoRecebimentoDefinitivoSerializer(*args, **kwargs)

Bases: ModelSerializer

Cronograma do termo com valor de contrato e quantidade recebida.

class Meta

Bases: object

fields = ('cronograma', 'valor_contrato', 'quantidade_total_recebida')

model

alias of CronogramaTermoRecebimentoDefinitivo

read_only_fields = ('cronograma', 'valor_contrato', 'quantidade_total_recebida')

class TermoRecebimentoDefinitivoSerializer(*args, **kwargs)

Bases: ModelSerializer

Serializador de saída do Termo de Recebimento Definitivo.

Os modelos já existentes (empresa, contrato, cronogramas e fiscais) são serializados pelos serializers de seus respectivos módulos. Cada cronograma possui seu próprio valor de contrato e quantidade recebida.

class Meta

Bases: object

fields = ('uuid', 'empresa', 'contrato', 'cronogramas', 'fiscal_1', 'fiscal_2', 'fiscal_3', 'texto_termo', 'status', 'criado_em', 'alterado_em')

model

alias of TermoRecebimentoDefinitivo

read_only_fields = ('uuid', 'empresa', 'contrato', 'cronogramas', 'fiscal_1', 'fiscal_2', 'fiscal_3', 'texto_termo', 'status', 'criado_em', 'alterado_em')

Serializadores de saída (somente leitura):

• CronogramaTermoRecebimentoDefinitivoSerializer: expõe o cronograma (serializado por CronogramaSimplesSerializer), o valor_contrato e a quantidade_total_recebida.

• TermoRecebimentoDefinitivoSerializer: serializa o termo com empresa (TerceirizadaSimplesSerializer), contrato (ContratoSimplesSerializer), cronogramas (via relação reversa cronogramas_termo, cada um com seus valores), fiscais (UsuarioSimplesSerializer), texto_termo, status e timestamps de criação/alteração. Todos os campos são somente leitura.

serializers_create

class CronogramaTermoRecebimentoDefinitivoCreateSerializer(*args, **kwargs)

Bases: Serializer

Item de cronograma do Termo de Recebimento Definitivo.

Cada cronograma possui seu próprio valor de contrato e quantidade total recebida.

class TermoRecebimentoDefinitivoCreateSerializer(*args, **kwargs)

Bases: ModelSerializer

Serializador de criação do Termo de Recebimento Definitivo.

Recebe os uuids de empresa, contrato, cronogramas (cada um com seu valor de contrato e quantidade recebida) e fiscais, e valida as regras de negócio:

• todos os campos obrigatórios;

• empresa com ao menos uma ficha de recebimento “Assinado CODAE”;

• contrato vinculado à empresa selecionada;

• cronogramas vinculados ao contrato/empresa selecionados;

• fiscais com perfil DILOG_QUALIDADE;

• valor do contrato e quantidade total recebida maiores que zero.

class Meta

Bases: object

fields = ('empresa', 'contrato', 'cronogramas', 'fiscal_1', 'fiscal_2', 'fiscal_3', 'texto_termo')

model

alias of TermoRecebimentoDefinitivo

validate(attrs)

validate_texto_termo(value)

Serializadores de criação (entrada):

• CronogramaTermoRecebimentoDefinitivoCreateSerializer: item de cronograma do payload, composto por cronograma (uuid via SlugRelatedField), valor_contrato e quantidade_total_recebida (decimais com até 15 dígitos e 2 casas decimais).

• TermoRecebimentoDefinitivoCreateSerializer: serializador principal do create. Recebe os uuids de empresa, contrato, cronogramas e fiscais e aplica as regras de negócio (na ordem):

  1. Campos obrigatórios: empresa, contrato, cronogramas (não pode ser vazio — allow_empty=False), fiscal_1, fiscal_2, fiscal_3 e texto_termo.

  2. Empresa com ficha assinada: a empresa deve possuir ao menos uma ficha de recebimento “Assinado CODAE”.

  3. Contrato da empresa: contrato.terceirizada deve ser a empresa selecionada.

  4. Cronogramas: não podem repetir uuid no mesmo payload; cada cronograma deve pertencer ao contrato selecionado (cronograma.contrato) e à empresa selecionada (cronograma.empresa).

  5. Fiscais: cada um deve possuir vínculo ativo com o perfil DILOG_QUALIDADE.

  6. Valores por cronograma: valor_contrato e quantidade_total_recebida devem ser maiores que zero.

  7. Texto do termo: obrigatório e deve conter conteúdo textual após a remoção das tags HTML (validate_texto_termo).

  Mensagens de erro padrão por campo não encontrado: “Empresa não encontrada.”, “Contrato não encontrado.”, “Cronograma não encontrado.” e “Fiscal N não encontrado.”.