models

data_maxima_recebimento_pre_save(instance, *_args, **_kwargs)

ArquivoDoTipoDeDocumento

Arquivo (PDF ou imagem) anexado a um tipo de documento de recebimento. É o que efetivamente comprova o documento apresentado pelo fornecedor (ex.: o PDF do laudo laboratorial).

Regras de negócio:

• Extensões aceitas: PDF, PNG, JPG e JPEG (FileExtensionValidator).

• Tamanho máximo de 10 MB (validate_file_size_10mb).

• Ao excluir o registro, o arquivo físico também é removido do disco (override de delete).

class ArquivoDoTipoDeDocumento(id, uuid, tipo_de_documento, arquivo, nome)

Bases: TemChaveExterna

id: int

Descrição: Chave primária inteira criada automaticamente pelo Django.

uuid: uuid.UUID

Origem: dados_comuns/behaviors.py (TemChaveExterna)

Descrição: Identificador externo único do arquivo.

tipo_de_documento: TipoDeDocumentoDeRecebimento

Descrição: Tipo de documento ao qual o arquivo pertence (on_delete=CASCADE).

arquivo: django.db.models.fields.files.FieldFile

Descrição: Arquivo enviado (upload_to="documentos_de_recebimento"), aceitando PDF/PNG/JPG/JPEG até 10 MB. Recebido como base64 pela API e convertido para ContentFile no helper de criação.

nome: str

Descrição: Nome de exibição do arquivo.

exception NotUpdated

Bases: ObjectNotUpdated, DatabaseError

TipoDeDocumentoDeRecebimento

Tipo de documento exigido/apresentado no recebimento de um cronograma, com seus arquivos anexados. O mesmo tipo não pode se repetir em um mesmo documento (unique_together entre documento_recebimento e tipo_documento).

Tipos possíveis:

• LAUDO (Laudo) — obrigatório na correção de documentos.

• DECLARACAO_LEI_1512010 (Declaração de atendimento a Lei Municipal: 15.120/10).

• CERTIFICADO_CONF_ORGANICA (Certificado de conformidade orgânica).

• RASTREABILIDADE (Rastreabilidade).

• DECLARACAO_MATERIA_ORGANICA (Declaração de Matéria Láctea).

• OUTROS (Outros) — exige descricao_documento.

Regra de negócio: quando o tipo é LAUDO, o serializador de criação exige que cada arquivo tenha arquivo e nome preenchidos.

class TipoDeDocumentoDeRecebimento(id, uuid, documento_recebimento, tipo_documento, descricao_documento)

Bases: TemChaveExterna

id: int

Descrição: Chave primária inteira criada automaticamente pelo Django.

uuid: uuid.UUID

Origem: dados_comuns/behaviors.py (TemChaveExterna)

Descrição: Identificador externo único do tipo de documento.

documento_recebimento: DocumentoDeRecebimento

Descrição: Documento de recebimento ao qual o tipo pertence (on_delete=CASCADE).

tipo_documento: str

Descrição: Tipo do documento. Valores possíveis: LAUDO, DECLARACAO_LEI_1512010, CERTIFICADO_CONF_ORGANICA, RASTREABILIDADE, DECLARACAO_MATERIA_ORGANICA e OUTROS.

descricao_documento: str

Descrição: Descrição do documento. Obrigatória quando tipo_documento = OUTROS.

arquivos: django.db.models.QuerySet[ArquivoDoTipoDeDocumento]

Descrição: Relação reversa 1:N com ArquivoDoTipoDeDocumento (related_name="arquivos"). Lista os arquivos anexados a este tipo de documento.

exception NotUpdated

Bases: ObjectNotUpdated, DatabaseError

DocumentoDeRecebimento

Modelo central do submódulo. Representa o conjunto de documentos de recebimento apresentados pelo fornecedor para um cronograma de entrega, incluindo o número do laudo, o laboratório credenciado, a quantidade do laudo, o lote e as datas de fabricação/validade/prazo de recebimento.

Possui um workflow de aprovação (DocumentoDeRecebimentoWorkflow) com os estados:

• DOCUMENTO_CRIADO (Documento Criado) — estado inicial.

• ENVIADO_PARA_ANALISE (Enviado para Análise) — enviado pelo fornecedor (transição inicia_fluxo); dispara notificação e e-mail para os perfis DILOG_QUALIDADE e COORDENADOR_CODAE_DILOG_LOGISTICA.

• ENVIADO_PARA_CORRECAO (Enviado para Correção) — a CODAE solicitou correções (transição qualidade_solicita_correcao, com o texto em correcao_solicitada).

• APROVADO (Aprovado) — a CODAE aprovou (transição qualidade_aprova_analise).

O fluxo também permite fornecedor_realiza_correcao (de ENVIADO_PARA_CORRECAO para ENVIADO_PARA_ANALISE) e fornecedor_atualiza (de APROVADO para ENVIADO_PARA_ANALISE). Cada transição gera um LogSolicitacoesUsuario do tipo DOCUMENTO_DE_RECEBIMENTO.

Regras de negócio:

• Ao corrigir um documento (fornecedor), é obrigatório informar ao menos um tipo LAUDO (validado no DocumentoDeRecebimentoCorrecaoSerializer). Na criação, quando um tipo LAUDO é informado, cada arquivo deve ter arquivo e nome preenchidos.

• O laudo assinado (arquivo_laudo_assinado) é gerado a partir do log de aprovação (DOCUMENTO_APROVADO) e do arquivo de tipo LAUDO; o endpoint de download restringe a geração a documentos APROVADO.

• O saldo do laudo é calculado como quantidade_laudo menos o total recebido em fichas assinadas menos os ajustes de saldo (calcular_saldo_laudo, no serializador).

class DocumentoDeRecebimento(id, criado_em, alterado_em, uuid, status, cronograma, numero_laudo, laboratorio, quantidade_laudo, numero_lote_laudo, unidade_medida, data_final_lote, correcao_solicitada)

Bases: ModeloBase, TemIdentificadorExternoAmigavel, Logs, FluxoDocumentoDeRecebimento

id: int

Origem: dados_comuns/behaviors.py (ModeloBase)

Descrição: Chave primária inteira criada automaticamente pelo Django.

uuid: uuid.UUID

Origem: dados_comuns/behaviors.py (TemChaveExterna)

Descrição: Identificador externo único do documento de recebimento.

id_externo: str

Origem: dados_comuns/behaviors.py (TemIdentificadorExternoAmigavel)

Descrição: Identificador externo amigável composto pelos 5 primeiros caracteres maiúsculos do UUID.

cronograma: cronograma_entrega.Cronograma

Descrição: Cronograma de entrega ao qual o documento se refere (on_delete=PROTECT). Fornecedores só veem documentos dos seus próprios cronogramas.

numero_laudo: str

Descrição: Número do laudo. Obrigatório na criação.

laboratorio: qualidade.Laboratorio | None

Descrição: Laboratório credenciado responsável pelo laudo (on_delete=PROTECT, opcional).

quantidade_laudo: decimal.Decimal | None

Descrição: Quantidade total do laudo (Decimal com até 15 dígitos e 2 casas decimais). Base do cálculo do saldo do laudo.

numero_lote_laudo: str

Descrição: Número(s) do(s) lote(s) do laudo (pode conter vários, separados).

unidade_medida: base.UnidadeMedida | None

Descrição: Unidade de medida da quantidade do laudo.

data_final_lote: datetime.date | None

Descrição: Data de conclusão do laudo (data final do lote).

correcao_solicitada: str

Descrição: Texto da correção solicitada pela CODAE quando o documento foi enviado para correção. Também usado pelo serializador de análise para decidir entre aprovar ou solicitar correção.

status: str

Origem: dados_comuns/fluxo_status.py (DocumentoDeRecebimentoWorkflow)

Descrição: Status atual do workflow. Estados possíveis: DOCUMENTO_CRIADO, ENVIADO_PARA_ANALISE, ENVIADO_PARA_CORRECAO e APROVADO.

criado_em: datetime.datetime

Origem: dados_comuns/behaviors.py (CriadoEm)

Descrição: Timestamp preenchido automaticamente na criação do documento.

alterado_em: datetime.datetime

Origem: dados_comuns/behaviors.py (TemAlteradoEm)

Descrição: Timestamp preenchido automaticamente na última alteração do documento.

logs: list[LogSolicitacoesUsuario]

Origem: dados_comuns/behaviors.py (Logs)

Descrição: Lista dos registros de log de transições de status do documento, ordenados por criado_em.

log_mais_recente: LogSolicitacoesUsuario | None

Origem: dados_comuns/behaviors.py (Logs)

Descrição: Último registro de log de transição de status do documento.

tipos_de_documentos: django.db.models.QuerySet[TipoDeDocumentoDeRecebimento]

Descrição: Relação reversa 1:N com TipoDeDocumentoDeRecebimento (related_name="tipos_de_documentos"). Lista os tipos de documento apresentados (laudo, declarações, certificados, etc.), cada um com seus arquivos.

datas_fabricacao_e_prazos: django.db.models.QuerySet[DataDeFabricaoEPrazo]

Descrição: Relação reversa 1:N com DataDeFabricaoEPrazo (related_name="datas_fabricacao_e_prazos"). Lista as datas de fabricação/validade e os prazos máximos de recebimento do lote.

fichas_documentos: django.db.models.QuerySet[DocumentoFichaDeRecebimento]

Descrição: Relação reversa 1:N com DocumentoFichaDeRecebimento (related_name="fichas_documentos"). Vínculo com as fichas de recebimento que registraram quantidades recebidas contra este documento.

fichas_recebimentos: django.db.models.QuerySet[FichaDeRecebimento]

Descrição: Relação M:N com FichaDeRecebimento através de DocumentoFichaDeRecebimento (related_name="fichas_recebimentos").

ajustes_saldo: django.db.models.QuerySet[AjusteSaldo]

Descrição: Relação reversa 1:N com AjusteSaldo (related_name="ajustes_saldo"). Ajustes (descontos) de saldo do laudo registrados posteriormente.

arquivo_laudo_assinado: bytes

Descrição: Propriedade que gera o PDF do laudo assinado digitalmente: busca o log de aprovação (DOCUMENTO_APROVADO), o arquivo do tipo LAUDO e mescla o rodapé de assinatura digital na última página. Lança ValidationError se não houver log de aprovação.

salvar_log_transicao: Callable

Descrição: Registra no log uma transição de status do documento, criando um LogSolicitacoesUsuario com o tipo DOCUMENTO_DE_RECEBIMENTO.

exception NotUpdated

Bases: ObjectNotUpdated, DatabaseError

DataDeFabricaoEPrazo

Datas de fabricação e validade dos lotes do laudo, com o prazo máximo para recebimento. O prazo_maximo_recebimento é informado em dias (30/60/90/120/180) ou OUTRO (com justificativa); quando diferente de OUTRO, a data_maxima_recebimento é calculada automaticamente (signal pre_save) somando o prazo à data_fabricacao.

class DataDeFabricaoEPrazo(id, uuid, documento_recebimento, data_fabricacao, data_validade, data_maxima_recebimento, prazo_maximo_recebimento, justificativa)

Bases: TemChaveExterna

id: int

Descrição: Chave primária inteira criada automaticamente pelo Django.

uuid: uuid.UUID

Origem: dados_comuns/behaviors.py (TemChaveExterna)

Descrição: Identificador externo único do registro.

documento_recebimento: DocumentoDeRecebimento

Descrição: Documento de recebimento ao qual o registro pertence (on_delete=CASCADE).

data_fabricacao: datetime.date | None

Descrição: Data de fabricação do lote. Obrigatória na análise final.

data_validade: datetime.date | None

Descrição: Data de validade do lote. Obrigatória na análise final.

data_maxima_recebimento: datetime.date | None

Descrição: Data máxima de recebimento do lote. Calculada automaticamente no pre_save como data_fabricacao + prazo_maximo_recebimento quando o prazo é numérico (diferente de OUTRO).

prazo_maximo_recebimento: str

Descrição: Prazo máximo para recebimento em dias. Valores possíveis: 30, 60, 90, 120, 180 e OUTRO. Obrigatório na análise final; quando OUTRO, exige justificativa.

justificativa: str

Descrição: Justificativa. Obrigatória quando prazo_maximo_recebimento = OUTRO.

exception NotUpdated

Bases: ObjectNotUpdated, DatabaseError