Anexo

O upload, ponta a ponta, em cinco passos

1. A tela chama POST /attachments/upload-intent com ownerType, ownerId, attachmentTypeId, nome, tipo e tamanho declarados. O Nexio resolve a empresa do dono, confere permissão, confere que o tipo é aceito naquele dono, resolve a retenção e só então chama o POST /files do GrydFiles com o perfil nexio.attachment. A recusa cara acontece antes de gastar rede.

2. O navegador faz o PUT direto no storage, com a URL e os cabeçalhos devolvidos. Nenhum byte passa pela API.

3. A tela chama POST /attachments com o fileId. O Nexio cria o Attachment e confirma no GrydFiles (POST /files/{id}/complete) declarando o par pendente ownerScope = "nexio.attachment" · ownerKey = attachment.id. Nenhuma FileReference é criada aqui — revisto em 09/09/2026. O anexo existe, aparece na lista e mostra o estado real; o que ele ainda não é, é referenciável, baixável ou propagável. A resposta volta com o arquivo em Scanning.

4. O antivírus roda no GrydFiles. O anexo já existe, já aparece na lista, e a lista mostra o estado real — não um spinner que some quando o usuário troca de aba.

5. Available é a liberação: o GrydFiles cria a FileReference do par pendente e chama o contrato de veredito do Nexio na mesma transação. Só então o anexo libera download, envio ao fornecedor, propagação e submissão para aprovação. Infected e a reprovação por tipo (Purged) chegam pelo mesmo contrato, sem referência nenhuma para desfazer: o anexo é descartado — revogado com motivo próprio e sem direito a arquivo —, e a tela e o aviso dizem o que aconteceu.

O que a inversão comprou. Até 08/09/2026 este passo 3 criava a referência sobre um arquivo em Scanning, e isso tornava falsa a invariante central do módulo de arquivo — a que diz que nada é referenciável antes do veredito. Pior: as duas saídas negativas ficavam inconsistentes por construção. Reprovação por tipo apagava um objeto com referência ativa apontando para ele; Infected deixava uma referência viva apontando para blob em quarentena. Nenhuma das duas tinha regra escrita, porque nenhuma das duas deveria ser possível.

Por que o Attachment nasce antes do veredito, e a referência não

A alternativa seria criar o vínculo só quando o arquivo ficasse Available. Ela parece mais limpa e é pior em três frentes: o usuário não vê o que acabou de anexar; a falha do antivírus vira um arquivo órfão que ninguém consegue nomear na tela; e a segunda tentativa de subir o mesmo arquivo não tem como ser reconhecida como repetida. Criar cedo e deixar o estado à mostra é o que torna a espera honesta — e é o que permite a decisão 8 ser sobre submeter, não sobre anexar.

A referência é outra coisa, e ela espera. Revisto em 09/09/2026. Criar o vínculo cedo é decisão de produto; criar a FileReference cedo era violação da regra de quem guarda o arquivo. As duas foram separadas: o Attachment continua nascendo no passo 3, e a referência nasce sozinha na liberação. Para o usuário nada muda — ele vê o anexo e vê "verificando". O que muda é que o estado intermediário deixou de ser uma promessa sobre um arquivo que ainda podia ser recusado.

A alternativa que foi recusada, e por quê

A opção com integridade referencial seria uma tabela de ligação por dono — requisition_attachments, purchase_order_attachments, e assim por diante. Ela dá FK de verdade e recusa a decisão de arquitetura do produto: "cada bounded context tem suas tabelas, sem chaves estrangeiras cruzando contextos". Também multiplica por seis o número de tabelas, de repositórios e de telas, e faz "liste todos os anexos deste fornecedor" virar uma união de seis consultas que ninguém lembra de atualizar quando a sétima aparece.

O precedente interno decide: o módulo mais transversal do framework, o AuditLog, amarra em EntityType + EntityId sem FK. E o GrydFiles faz o mesmo em FileReference. Fazer diferente aqui seria o Nexio contrariar duas camadas abaixo dele.

O preço, dito com todas as letras

Sem FK, o banco não impede um anexo apontar para um documento que não existe mais. É um preço real, e ele é pago com três mitigações obrigatórias — nenhuma delas opcional, nenhuma delas "a fazer depois". Sem as três, esta decisão não se sustenta e o desenho vira dívida.

Duas evidências, dois donos: a que o aprovador junta e a que sustenta a proposta

Novo em 09/09/2026. As duas usam APPROVAL_EVIDENCE e não são a mesma coisa, e confundi-las é o jeito mais fácil de perder prova.

A que sustenta a proposta nasce antes da decisão, e o dono é o próprio agregado. O comprovante de titularidade da conta é parte da proposta de alteração bancária; a ata que aprovou a verba é parte da revisão orçamentária. Existiriam mesmo que ninguém precisasse aprovar nada — são o porquê que o autor apresenta. Ficam em ownerType = BankAccountChangeProposal e Budget, e entram na conta da decisão 8: enquanto o anexo não tiver veredito, o documento não é submetido, porque o aprovador não pode receber uma proposta cuja prova ele não consegue abrir.

A que o aprovador junta nasce depois da submissão, e o dono é a instância. Parecer, cotação de terceiro, autorização por fora: só existem porque alguém teve de decidir. Não cabem no documento — ele já não aceita alteração —, e é para isso que o ownerType = ApprovalRequest existe. Nenhuma regra bloqueia a decisão por causa delas; o que vale é a RN-ATT-26, e enquanto o arquivo não liberar o aprovador simplesmente não o abre.

O teste, quando a fronteira ficar dúbia: este arquivo existiria se não houvesse instância de aprovação? Se sim, o dono é o agregado. Se ele só nasceu porque alguém precisou decidir, o dono é a instância. As duas convivem na mesma aprovação, e é comum que convivam — a proposta traz o comprovante, o aprovador junta o parecer, e a auditoria de daqui a três anos precisa dos dois, com os mesmos cinco anos de guarda.

Certidão de fornecedor não é anexo — ela vive no SupplierDocument

Novo em 09/09/2026, e é correção: até a tabela acima ser escrita, a linha do Supplier dizia "certidão, contrato social, cartão de CNPJ", o que contraria a decisão 1 desta própria página e o que a spec de Fornecedor já dizia. Certidão tem número, órgão emissor, emissão e vencimento, e o status dela é derivado da data — alguém digita esses campos, alguém filtra por eles, e o sistema avisa antes de vencer. Isso é entidade de domínio, com ownerScope = "nexio.supplier-document", FileReference própria e liberação quando o documento é substituído.

O que sobra para o ownerType = Supplier é a evidência sem campo para digitar: ata de visita técnica, correspondência, e-mail de negociação, parecer solto. O mesmo corte vale para o Item — laudo com número e órgão é ItemDocument, e foto e ficha técnica são entidade do catálogo, com perfil próprio no GrydFiles.

O teste é o mesmo de sempre: alguém vai ter de digitar um campo sobre este arquivo e depois filtrar por ele? Se sim, é entidade e não anexo. E a passagem entre os dois lados já está escrita: a certidão que chega anexada numa cotação pode ser promovida a documento de cadastro, porque o supplierId do anexo do portal diz de quem ela é.

companyId nulo é resposta, não falta de resposta

Novo em 09/09/2026. Três dos seis donos novos não têm empresa: Item e Supplier são vocabulário e cadastro do tenant, não da empresa, e BankAccountChangeProposal pende de um fornecedor, que também é do tenant. O companyId denormalizado do anexo nasce nulo nesses casos, e nulo tem significado declarado: anexo do tenant, visível em qualquer empresa que o usuário enxergue — não anexo de empresa nenhuma.

É a mesma forma que GLAccountCompany e BudgetPolicy já usam (linha sem empresa vale para todas) e a mesma lição do escopo por empresa: ele restringe escrita, nunca apaga leitura. Sem esta linha escrita, o filtro por UserCompanyScope decidiria sozinho, e das duas maneiras possíveis: comparação estrita faz a ata de visita ao fornecedor sumir para todo mundo; comparação frouxa a faz aparecer para todo mundo, empresa alheia inclusive. As duas falham em silêncio, que é o pior modo de falhar de um filtro de linha.

E a resposta do ApprovalRequest é condicional, o que é o caso mais fácil de errar. A instância herda a empresa do documento que ela aprova: requisição, pedido e orçamento têm empresa; fornecedor e item não têm. O mesmo ownerType devolve Guid em três processos e nulo em dois, e isso é correto — o descritor pergunta ao alvo, não a uma tabela de de-para.

Instância de aprovação não é documento submetível

Novo em 09/09/2026. O SubmitPolicyOf do ApprovalRequest responde "não submete", e responde isso explicitamente — não é um método sem implementação, nem um que devolve nulo e deixa quem chama adivinhar. A instância é a submissão de outro documento; submetê-la seria submeter a submissão. A fila de submissão diferida chama esta pergunta sem saber o que tem do outro lado, e uma resposta ausente é exatamente o tipo de coisa que ela invocaria por engano no dia em que alguém anexasse um parecer a uma instância cujo anexo ainda está em Scanning.

O OpenApprovalOf da instância é a própria instância

Novo em 09/09/2026. Para ownerType = ApprovalRequest, o ownerId já é o approvalRequestId — a resposta é reflexiva e não custa consulta nenhuma: devolve o próprio ownerId se a instância estiver aberta, e nulo se estiver concluída. Está escrito porque a alternativa é alguém implementar "procure a instância aberta deste dono" com o dono sendo uma instância, e descobrir a recursão em produção, no dia em que um anexo de parecer for revogado no meio de uma rodada.

Por que cada cópia cria a sua própria referência

Seria mais econômico manter uma referência só. Seria também errado: a FileReference é o que responde quem ainda precisa deste arquivo, e é o que segura o expurgo. Com uma referência só, descartar a requisição de origem liberaria o arquivo enquanto o pedido ainda o exibe — e o pedido descobriria isso trinta dias depois, recebendo FILE_PURGED_CONFLICT ao abrir um documento fechado. Uma referência por anexo é o que faz a contagem do GrydFiles significar o que ela diz significar.

Por que a herança de visibilidade é a regra, e não a redefinição

A cópia herda a visibility do original. A alternativa — recalcular do defaultVisibility do tipo no destino — trocaria uma decisão que uma pessoa tomou por um padrão de configuração, e o erro possível é justamente o pior: um anexo marcado Internal de propósito na requisição renascendo Supplier no pedido porque o tipo tem esse padrão. Herdar preserva a decisão; o destino pode rebaixar livremente e promover com as quatro portas da seção anterior.

Explícita, mas não trabalhosa

Explícito não significa um clique por arquivo. Ao criar o pedido a partir da requisição, a tela mostra os anexos elegíveis — os de tipo com propagates = true, não revogados, com arquivo Available — já marcados, com a visibilidade de cada um à vista, e o usuário desmarca o que não vai. É uma confirmação, não uma digitação. O que ela impede é o caso em que ninguém olhou.

Anexo em Scanning aparece na lista desmarcado e desabilitado, com o motivo escrito. Propagar um arquivo que ainda pode virar Infected multiplicaria o problema por dois documentos.

A cadeia é rastreável em um passo

copiedFromAttachmentId dá o pai; rootAttachmentId dá a origem sem recursão. A tela de auditoria responde "este PDF entrou no sistema onde?" com uma consulta, e "quem mais tem este arquivo?" com o índice em (tenantId, storedFileId) — sem perguntar nada ao GrydFiles, que aliás não saberia responder em termos de documento.

O que o aprovador vê depois de uma revogação

Anexo revogado não aparece para o aprovador na fila, porque não é mais evidência válida. Aparece na aba de histórico do documento, com quem revogou, quando, o motivo e a marca visual — e é lá que a auditoria olha. A distinção importa: esconder de quem decide agora, mostrar para quem confere depois.

Revogar evidência de documento submetido aciona explicitamente, na mesma transação, a reavaliação do conteúdo relevante pelo motor de aprovação. Se a evidência sustentava uma decisão, essa decisão não permanece válida sem reavaliação. A notificação durável informa os envolvidos e complementa o controle. A versão efetiva de um pedido emitido permanece preservada durante a aprovação da alteração.

Retenção é resolvida por política e pode ser estendida

O Nexio resolve retenção por tipo, empresa e política versionada no upload, e estende a data quando o marco de contagem ou a obrigação exigir. Pedido e nota são documentos distintos, ligados por referências; um não muda de natureza para virar o outro. O padrão de cinco anos é uma configuração inicial a validar, não autorização automática de expurgo. O CTN, arts. 173, 174 e 195, parágrafo único, distingue decadência, prescrição e conservação de documentos; não fornece uma regra universal de cinco anos após o upload. Guardar fundamento, marco e versão da política; litígio ou obrigação ainda vigente impede expurgo.

Estender é possível pela rota de retenção do GrydFiles, e só para frente — encurtar é recusado com FILE_RETENTION_SHORTENED_UNPROCESSABLE. O caminho para reduzir guarda não é a API: é o expurgo manual, com motivo e permissão própria.

O arquivo compartilhado entre anexos, e o que isso muda

Dois anexos podem apontar para o mesmo storedFileId — por propagação ou por dedupe do GrydFiles, que reconhece o mesmo sha256 dentro do tenant. As retenções podem divergir: o mesmo PDF anexado como GENERAL na requisição e como FISCAL_DOCUMENT na nota. Vale a mais longa, e isso é consequência natural do desenho do GrydFiles — retainUntil só anda para frente, e cada declaração de upload a empurra. Não é regra nova; é a regra existente produzindo o resultado certo.

LGPD, e onde ela cai

Pedido de eliminação por titular esbarra em legalHold e em guarda legal, e é assim que deve ser: a LGPD preserva a guarda exigida por obrigação legal ou regulatória. O que o Nexio precisa oferecer é a resposta — quais anexos contêm dado daquele titular, em quais documentos, sob qual base de retenção — e o índice por dono e por fornecedor é o que torna essa consulta possível. A execução do apagamento, quando cabível, é o expurgo manual do GrydFiles, que preserva a lápide.

A regra: anexar durante a verificação é permitido; submeter não

O usuário anexa, continua preenchendo o documento e vê o estado do arquivo na lista. O que ele não pode é enviar o documento para aprovação enquanto qualquer anexo estiver em Pending, Scanning ou Failed. A submissão é recusada com ATTACHMENT_SCAN_PENDING_CONFLICT, e a resposta nomeia quais anexos estão pendentes.

Failed entrou na lista em 09/09/2026, e a razão é a mesma dos outros dois. Arquivo em Failed não tem veredito, e o GrydFiles recusa o download dele — o aprovador receberia na fila um documento cuja prova ele não consegue abrir. Até 08/09 a regra bloqueava só os dois primeiros estados: a fila diferida desistia em Failed, mas a submissão manual passava. As duas portas passam a fechar juntas. A saída não é esperar indefinidamente: o GrydFiles ganhou POST /files/{id}:rescan, e a tela oferece "tentar verificar de novo" no lugar de um anexo que não serve para nada.

A razão é a fila do aprovador: um aprovador não pode receber um documento cujo anexo ainda pode virar Infected. Se virar, ou ele já leu, ou o documento muda de conteúdo debaixo de uma decisão em curso — e as duas saídas são piores que esperar.

O que não vamos fazer, e está escrito para não ser reinventado

Prender o usuário na tela esperando o antivírus é a solução ruim. Ela transforma um detalhe de infraestrutura em tempo de espera do comprador, e piora exatamente quando não deveria — arquivo grande, hora de pico, base de assinaturas recarregando. Um spinner bloqueante de cinco segundos é aceitável; de quarenta, é um defeito de produto. Esta spec registra a recusa para que a implementação não caia nela por ser a mais fácil de escrever.

A saída — fechada em v1.1, e são as duas coisas

Quem tenta submeter e recebe ATTACHMENT_SCAN_PENDING_CONFLICT escolhe entre ser avisado quando o arquivo liberar — nexio.attachment.scan_completed — e deixar a submissão acontecer sozinha, por uma DeferredSubmission que ele pode cancelar enquanto ela espera. As duas escolhas são a mesma fila. Revisto em 09/09/2026: "só avisar" foi escrito como se não criasse nada, mas "registrado para aquele usuário e aquele documento" é estado, e sem linha em lugar nenhum o pedido se perdia no primeiro reinício. A fila ganha um modo — avisar, ou avisar e submeter —, e não uma segunda tabela: o gatilho, a expiração, o cancelamento e o índice de unicidade são idênticos nos dois casos, e a única diferença é o que acontece quando o último anexo libera. A peça de entrega já existia na plataforma: o GrydNotifications tem in-app pronto, com IInAppNotificationSender e UserNotification, além de push e e-mail.

As quatro perguntas que esta seção listava como sem resposta estão respondidas na spec de Notificação. Quem recebe é quem tentou submeter, não quem anexou — o caso de quem anexou já tem dono, que é o aviso obrigatório de Infected. Veredito demorado não ganha tratamento especial: a fila expira em 72 horas, o documento continua em rascunho e o alerta de operador do GrydFiles é que aponta para o problema real. A submissão automática é pedida, e é por isso que ela não precisa de confirmação depois. E ela aparece como uma faixa no próprio documento, com o que falta liberar e um cancelar. Veredito Infected ou Failed faz a fila desistir com motivo e avisar — nunca submeter.

Consequência para esta spec, e é a mudança real da v1.1: a fila não sabe submeter documento nenhum — ela pergunta ao dono. O registro de descritores ganhou por isso a nona pergunta, SubmitPolicyOf, sem a qual o módulo de submissão diferida teria que conhecer requisição, pedido, cotação, recebimento, nota e contrato — exatamente a dependência que o descritor existe para não ter.

O comportamento já especificado que permanece

O suficiente para não travar ninguém e não fechar nenhuma porta: o estado real na lista, sempre visível; a consulta em lote que a tela usa para atualizar sem vinte chamadas; a recusa de submissão com a lista dos anexos pendentes; e a revogação automática com aviso quando o veredito é Infected. Nenhuma dessas quatro coisas mudou com a decisão de mensageria fechada — ela acrescentou o aviso e a fila, e não substituiu o mecanismo.

O escopo vem do dono, e fora dele a resposta é 404

companyId é derivado do dono pelo descritor e denormalizado no anexo, e o filtro por UserCompanyScope roda na consulta, sem join entre contextos. Anexo de documento de outra empresa responde 404, não 403 — os dois casos, "não existe" e "não é seu", respondem igual de propósito, que é a regra do DeliveryLocation. Um 403 confirmaria a existência do documento a quem não deveria saber que ele existe.

E há a terceira resposta, que não é nem "é seu" nem "não é seu": companyId nulo. Novo em 09/09/2026. Anexo de item, de fornecedor e de proposta de alteração bancária não pertence a empresa nenhuma, porque o dono deles é do tenant. O filtro por UserCompanyScope passa a ser "a empresa está no escopo do usuário ou o anexo não tem empresa" — a mesma forma de GLAccountCompany e BudgetPolicy, em que a linha sem empresa vale para todas. Escrever o filtro sem essa segunda metade faz a ata de visita ao fornecedor desaparecer para todos os usuários, e nenhum erro é registrado em lugar nenhum.

Permissão de anexo não substitui permissão no dono

manage:attachments é necessária e não suficiente: quem anexa precisa também poder escrever no documento, e quem responde isso é o CanWrite do descritor. Sem essa delegação, o anexo viraria uma porta lateral para escrever em documento alheio — e teríamos duas regras diferentes sobre quem manda numa requisição, o que sempre termina com as duas divergindo.

A trilha: o Nexio registra o que a plataforma não sabe

O GrydFiles já grava no AuditLog a emissão de cada URL de download. O Nexio não repete isso — repetir daria duas linhas para o mesmo ato, com risco de divergirem. O que ele registra é o que lá não existe: qual documento e qual anexo, porque do lado da plataforma só há um fileId, e um fileId não responde "quem baixou o anexo do pedido PED-2026-00871".

Usa o IAuditLogService.RecordAsync do framework, que é a via de evento de negócio manual — o interceptor de diff pega a mudança de linha, não o ato de ler. Ações registradas: attachment.created, attachment.downloaded, attachment.visibility-changed, attachment.copied, attachment.revoked. Cada uma carrega ownerType, o número legível do documento e o attachmentId.

A convenção que estes cinco nomes propuseram fechou na spec de Notificação: <entidade>.<verbo-no-passado> é a ação da trilha, e o slug do aviso é a mesma cauda com o prefixo do produto. A ação vai em AdditionalData["action"] do RecordAsync, porque o AuditLog do GrydAudit não tem coluna de ação — dar-lhe uma é pendência de plataforma, no molde do GrydFiles, e está registrada no mapa de domínio.