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 e CanWrite, confere que o tipo é aceito naquele dono e os limites, resolve a retenção, reserva o arquivo pela IFileService com o perfil nexio.attachment e grava o anexo em fileReferenceStatus = Reserved, com dono, tipo, retenção e quem reservou. A recusa cara acontece antes de gastar rede. A reserva não aparece na lista; se a gravação falhar depois de reservar, o arquivo vence sozinho no GrydFiles.

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 só aceita o fileId de uma reserva feita pelo mesmo usuário, no mesmo tenant, para o mesmo dono e o mesmo tipo — fora disso, ATTACHMENT_UPLOAD_NOT_RESERVED_CONFLICT (RN-ATT-36). Reconfere o CanWrite do dono, que pode ter mudado desde a reserva — documento que não aceita mais escrita responde ATTACHMENT_OWNER_NOT_WRITABLE_CONFLICT e nada é confirmado. Então confirma pela IFileService, declarando a referência esperada ownerScope = "nexio.attachment" · ownerKey = attachment.id — no processo, nunca por rota HTTP, que não aceita dono —, e grava Expected. Nenhuma FileReference é criada aqui. O anexo passa a aparecer na lista com o estado real; o que ele ainda não é, é referenciável, baixável ou propagável. A resposta volta com o arquivo em Scanning. Repetir a chamada repete a confirmação e devolve o mesmo anexo; reprovação na confirmação — tamanho divergente, reserva vencida — revoga o anexo com FileRejected e repassa o erro do GrydFiles.

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 da referência esperada na própria transação e, depois do commit, entrega o veredito ao Nexio. 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 com rejectionCode) chegam pelo mesmo contrato, sem referência nenhuma para desfazer: o anexo é descartado — revogado com FileInfected ou FileRejected, sem direito a arquivo —, e a tela e o aviso dizem o que aconteceu. Failed não descarta: pede nova verificação ou remoção.

O que a inversão compra. Criar a referência no passo 3, sobre um arquivo em Scanning, tornaria falsa a invariante central do módulo de arquivo — a que diz que nada é referenciável antes do veredito. E as duas saídas negativas ficariam inconsistentes por construção: a reprovação por tipo apagaria um objeto com referência ativa apontando para ele, e Infected deixaria uma referência viva apontando para blob em quarentena.

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. Criar o vínculo cedo é decisão de produto; criar a FileReference cedo seria violar a regra de quem guarda o arquivo. As duas estão separadas: o Attachment aparece 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 deixa de ser uma promessa sobre um arquivo que ainda pode 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

As duas são prova 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 e a planilha que justificam uma suplementação são parte da solicitação de 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 BudgetChangeRequest e são anexadas com o dono em rascunho. A proposta bancária nasce em Draft, recebe o comprovante (BANK_OWNERSHIP_PROOF) e só é submetida quando ele tem veredito Available — sem ele o Fornecedor recusa a submissão, e por baixo vale a decisão 8; na carga inicial, o comprovante é anexado à proposta que o lote criou — em Open, aceitando anexo até a confirmação —, e a confirmação do lote pergunta ao Anexo pelos comprovantes como a submissão pergunta, e o Fornecedor decide: Failed, Infected, revogado ou eliminado é falta de evidência, com o código dele; sem falta, comprovante ainda em varredura (Pending) recusa com ATTACHMENT_SCAN_PENDING_CONFLICT (RN-ATT-19; RN-FOR-31 do Fornecedor). Submetida — ou confirmado o lote —, a proposta não aceita anexo novo nem revogação — nem a confirmação de reserva feita antes (RN-ATT-36): o aprovador decide sobre a prova que o proponente apresentou, e ela não muda debaixo da decisão.

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

A decisão 1 decide, e a spec de Fornecedor diz o mesmo. 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

Quatro donos com spec não têm empresa: Item e Supplier são vocabulário e cadastro do tenant, não da empresa, e SupplierQualification e BankAccountChangeProposal pendem 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 as empresas do escopo — e quem não tem empresa nenhuma no escopo não a vê. 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, orçamento e solicitação de revisão têm empresa; fornecedor, qualificação, proposta bancária e item não têm. O mesmo ownerType devolve Guid nos processos cujo alvo tem empresa e nulo nos outros, e isso é correto — o descritor pergunta ao alvo, não a uma tabela de de-para.

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

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.

Quatro portas, e todas precisam estar abertas

Marcar um anexo como Supplier exige, ao mesmo tempo: o AttachmentType com allowsSupplierVisibility = true; o descritor do dono respondendo que aquele documento pode expor anexo; o usuário com a permissão share-with-supplier:attachments; e o anexo em estado editável. Falhar qualquer uma é 422 ou 409, nunca uma exposição parcial. Quatro portas parece excessivo até a primeira vez que a planilha de custo interno vaza numa RFQ.

O GrydFiles não participa desta decisão — e é bom que não participe

A permissão read:files libera pedir uma URL de download: é permissão da rota HTTP do GrydFiles, que os hosts do Nexio não expõem — em processo a IFileService não confere permissão de módulo e o GrydFiles não define identidade de serviço —, e não vai a papel de tenant — requisito do catálogo de permissões da plataforma, na demanda; o que a asserção 8 da Arquitetura verifica é que os hosts do Nexio não expõem /files/*. Quem decide se este usuário pode ver este documento é o Nexio, antes de chamar o GrydFiles. O módulo de arquivo emitir URL curta para quem já foi autorizado é a fronteira correta: ele não sabe o que é fornecedor, cotação nem concorrente, e ensiná-lo isso seria mover regra de negócio para a camada errada.

A consequência prática é uma frase que vale para todo o produto: uma URL assinada emitida é uma autorização já concedida. O TTL curto do perfil é o que limita o dano de um link repassado, e é por isso que ele é curto.

Rebaixar é livre; promover é decisão

Passar de Supplier para Internal não precisa de permissão especial — reduzir exposição nunca deveria ter atrito. O caminho contrário é o controlado. E há um ponto sem volta: depois que o documento foi enviado ao fornecedor, a visibilidade fica travada (ATTACHMENT_VISIBILITY_LOCKED_CONFLICT). Rebaixar depois do envio seria fingir que o fornecedor não viu; o caminho honesto é revogar, o que retira o anexo da tela do fornecedor daqui para a frente e deixa registrado que ele existiu.

Isolamento entre fornecedores não é visibilidade

Numa cotação com cinco concorrentes, nenhum pode ver o anexo do outro — e isso não se resolve com visibility. Resolve-se com autoria: o portal devolve ao fornecedor autenticado os anexos que ele mesmo subiu nas respostas dele (uploadedByKind = PortalUser e o supplierId dele), em qualquer visibilidade, mais os anexos Supplier do próprio QuotationRequest, que são para todos por definição. O que o comprador acrescentou à resposta de um fornecedor — mesmo com o supplierId preenchido — não volta ao portal, e anexo de resposta nunca vira Supplier. É uma comparação de coluna, não uma regra especial — e foi um dos três ganhos que motivaram a decisão 9.

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.

Entre empresas, só com escopo nas duas

A compra centralizada pode relacionar documentos de empresas diferentes do mesmo tenant; como a demanda de várias empresas se consolida é decisão da spec da Cotação. A propagação acompanha: o destino pode ser de outra empresa quando quem propaga lê a origem (escopo e CanRead do dono de origem) e escreve no destino (escopo e CanWrite do dono de destino), e o ownerType do destino está no PropagatesTo da origem. Faltando qualquer um, o documento responde 404, como todo documento fora de escopo. A cópia grava o companyId do destino e herda a visibilidade; a tela mostra, antes da confirmação, que o arquivo passa a outra empresa (RN-ATT-14).

Não é rateio. Cada documento continua de uma empresa só, e cada cópia responde ao escopo da empresa dela: quem enxerga só a empresa de destino vê a cópia, e não a origem.

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 anexo de documento já submetido e ainda em aprovação é permitido quando o CanWrite do dono deixa — a proposta bancária submetida não deixa —, com motivo, e notifica os aprovadores pendentes. Não invalida a aprovação — invalidar por conta própria seria o módulo de anexo tomando uma decisão do motor de aprovação. O que ele faz é avisar quem precisa saber.

A guarda: piso no upload, fim contado do fechamento do dono

Na reserva do upload o Nexio resolve retentionMode e retainUntil do AttachmentType, envia ao GrydFiles pela IFileService e congela no anexo o modo e os anos. A data enviada é só o piso: o GrydFiles não expurga arquivo com referência ativa nem com retainUntil no futuro, e a referência é do Nexio.

O fim da guarda conta do fechamento do dono (RN-ATT-31). Quando o dono vai a Closed — o occurredAt do evento que o dono publica (RN-ATT-28) —, cada anexo dele com referência mantida, ativo ou revogado, e o que o re-scan tornou infectado depois de liberado, ganha guardUntil = 31/12 do ano do fechamento + retentionYears, e o retainUntil do arquivo é estendido até essa data no GrydFiles, depois do commit (RN-ATT-35) — e só anda para frente. A razão é aritmética e é fiscal: o prazo decadencial do art. 173, I do CTN começa no primeiro dia do exercício seguinte, e contar do upload deixaria o arquivo até dois anos curto num processo longo. O job diário attachment-guard-release libera a referência dos anexos cujo guardUntil passou, que não estão sob guarda legal e cujo dono, perguntado na hora, continua fechado; dali em diante o expurgo é regra do GrydFiles. Em UntilReleased — só em tipo do tenant — o fim da guarda é a data do fechamento; em Permanent não existe.

Dono que sai de Closed — a instância aprovada que a reavaliação reabre — zera o guardUntil dos anexos ainda referenciados, e o próximo fechamento recalcula. Dono que nunca fecha — cadastro de fornecedor e de item — mantém os anexos enquanto existir. Errar para mais custa armazenamento; errar para menos custa a prova. Encurtar guarda não é a rota de retenção, que recusa (FILE_RETENTION_SHORTENED_UNPROCESSABLE): é a eliminação a pedido de titular.

O arquivo compartilhado entre anexos, e o que isso muda

Dois anexos podem apontar para o mesmo storedFileId — por propagação. Cada cópia tem a sua referência e o seu guardUntil, contado do fechamento do dono dela, e as guardas podem divergir: o mesmo PDF numa requisição que fechou em 2026 e num pedido que fechou em 2027. Vale a mais longa, sem regra nova: o arquivo vive enquanto alguma referência existir, e retainUntil só anda para frente.

Guarda legal é ato por caso, nunca propriedade do tipo

Litígio, fiscalização e auditoria externa congelam um caso, não um tipo de documento. Guarda legal por tipo transformaria cinco anos em "nunca" para todo documento fiscal de todo cliente, e ninguém conseguiria encerrá-la. Por isso o AttachmentType não tem legalHold: quem tem create:attachment-legal-holds coloca a guarda sobre um anexo, ou sobre todos os anexos de um dono, com a referência do caso e o motivo. Cada colocação é uma linha de AttachmentLegalHold; retirar é outro ato, também com motivo, que encerra só aquela linha. Dois casos sobre o mesmo anexo são duas linhas, e encerrar um não solta o outro (RN-ATT-32). Colocar e retirar tomam a mesma trava do arquivo que a execução da eliminação toma — é o que impede a guarda de nascer no meio de uma eliminação, e a eliminação de correr por cima de uma guarda recém-posta (RN-ATT-39).

O efeito é a referência que não sai — e o legalHold do arquivo ligado. Com guarda ativa, o fim da guarda não libera a referência, a revogação em rascunho não a libera, e a eliminação é recusada (ATTACHMENT_UNDER_LEGAL_HOLD_CONFLICT). A referência mantida não basta sozinha: o re-scan que acha vírus num arquivo liberado libera todas as referências dele, e a quarentena tem prazo próprio. Por isso a primeira guarda ativa sobre qualquer anexo de um arquivo liga também o legalHold do StoredFile, com o caseReference como motivo e quem colocou como autor, e a retirada da última guarda ativa sobre os anexos daquele arquivo pede o desligamento — as duas chamadas depois do commit, idempotentes, com a pendência à vista em fileHoldAppliedAt e fileHoldReleasedAt (RN-ATT-35). O sinal do arquivo é um só; quem conta os casos é o Nexio. Desligar a guarda que o Nexio ligou é pedido do mesmo escopo, com quem retirou a guarda como autor declarado — também na repetição pelo job, que não tem usuário —, e não pede admin:system: é o requisito da RN-GF-27 do GrydFiles, registrado na demanda de plataforma. Enquanto ele não estiver entregue, a pendência fica aberta e o arquivo, preso — o erro possível é para mais. Colocar e retirar são atos de controle: registro isolado por tenant, gravado na transação do ato, e os eventos attachment-legal-hold.placed e attachment-legal-hold.lifted depois do commit. A linha da guarda não traz nome de arquivo nem conteúdo — gerir guarda não dá leitura de anexo —, e colocar, retirar e listar valem só no escopo da empresa do dono, com 404 fora dele.

Eliminação a pedido de titular (LGPD)

A LGPD preserva a guarda exigida por obrigação legal (art. 16) e manda eliminar o dado tratado sem base. O produto entrega as duas coisas. A resposta — quais anexos, em quais documentos, sob qual guarda — sai do índice por dono e por fornecedor. O ato é POST /attachments/{id}/erase, com permissão própria, erase:attachments: registra o pedido do titular e o executa — na hora, ou pela mão de uma segunda pessoa quando o arquivo é prova de controle ou ainda está sob guarda (RN-ATT-38) —, e é o único caminho que libera a referência de documento em curso ou fechado antes do fim da guarda (RN-ATT-33).

O ato exige a referência do pedido do titular, a data-limite de resposta a ele (dueAt) e um comentário com a avaliação de que não há base legal de guarda — a decisão jurídica é de quem tem a permissão, e fica registrada; o motivo é sempre DADO_PESSOAL_INDEVIDO. No registro, e de novo na execução, três condições recusam, e na recusa nada muda: algum dos anexos do tenant que apontam para o mesmo arquivo está sob guarda legal (ATTACHMENT_UNDER_LEGAL_HOLD_CONFLICT); o arquivo tem referência ativa de outro escopo além de nexio.attachment (ATTACHMENT_ERASURE_FILE_REFERENCED_CONFLICT — o documento de cadastro que aproveitou o arquivo é tratado no módulo dele; não há caminho automático entre consumidores, e na v1 o caso não ocorre, porque o Nexio é o único consumidor de escopo de anexo do GrydFiles — RN-GF-25); ou o GrydFiles não aceitaria o expurgo — guarda de qualquer detentor, inclusive a posta pela rota dele, sem escopo; estado do arquivo; e, na execução, em Permanent, dois autores distintos — no registro a consulta roda em modo registro, com um autor só —, conferido pela consulta de pré-condição em processo — que nomeia todos os pares do escopo nexio.attachment daquele arquivo, o original e as cópias — antes de qualquer gravação (RN-ATT-39). Três condições bloqueiam, e nenhuma delas recusa o registro. Duas são do dono: algum desses donos tem aprovação em curso (OpenApprovalOf diferente de nulo) ou decisão de controle pendente fora da instância (PendingControlOf diferente de nulo — lote de carga inicial por confirmar, contato à espera da segunda pessoa, carência, janela de contestação ainda aberta ou contestação sem desfecho, alerta de divergência com o ERP em aberto, devolução à espera de reenvio, correção de identidade em curso), qualquer que seja o CanWrite. A terceira é de alcance: quem registra tem escopo e CanRead no anexo em que agiu — sem isso a rota responde 404 —, mas não em todos os donos dos outros anexos do mesmo arquivo. Nesse caso o pedido também é registrado, bloqueado. Recusar era responder ao exercício de um direito com silêncio: nada gravado, nenhum prazo correndo, ninguém avisado, nenhuma saída declarada. Registrado, o pedido nasce Requested, o dueAt corre desde o registro, e o bloqueio nomeia o alcance que falta — as empresas fora do escopo e os tipos de dono cuja leitura foi negada, nunca o número nem o nome do documento —, para quem for resolver saber o que conceder. O aviso sai a quem registrou e ao titular, e o administrador do tenant é escalado no mesmo ato, porque conceder escopo é dele: enquanto ninguém tiver o alcance inteiro, não há quem execute. A quem registrou a resposta diz apenas que o pedido ficou bloqueado por alcance incompleto — que o arquivo tem anexo fora do alcance dele é o mínimo para ele não repetir o pedido, e é tudo o que ele fica sabendo. Na execução as três recusam: ATTACHMENT_ERASURE_APPROVAL_IN_PROGRESS_CONFLICT, ATTACHMENT_ERASURE_CONTROL_DECISION_PENDING_CONFLICT e ATTACHMENT_ERASURE_SCOPE_INCOMPLETE_FORBIDDEN — quem executa precisa do alcance inteiro, e é aí que a eliminação parcial é impedida: ela não elimina nada, porque o arquivo continuaria preso pela cópia que ficou. Eliminar a prova debaixo de uma decisão aberta tiraria de quem decide o que ele precisa olhar; a eliminação espera a decisão terminar, e o desfecho que depende da prova é recusado do lado do dono — o Fornecedor, para o comprovante bancário. E revogar, trocar o nome e publicar a eliminação de um arquivo que o GrydFiles vai recusar daria o dado por eliminado com os bytes guardados para sempre — por isso a consulta vem antes. Executada, numa transação do Nexio, com o arquivo travado — a mesma trava que a cópia e a guarda legal tomam — e cada dono travado como a submissão dele o trava (RN-ATT-39), todos esses anexos — o original e as cópias — são revogados com revocationSource = Erasure e marcados ReleasePending, originalFileName e description dão lugar a texto neutro — nome de arquivo também é dado pessoal — e o ato de controle é registrado com quem registrou e quem executou. Depois do commit (RN-ATT-35) sai attachment-erasure-request.executed — o ato foi executado, a eliminação não está concluída — e o job de guarda, sem usuário no contexto, libera as referências e pede o expurgo ao GrydFiles como eliminação (RN-GF-25), nomeando todos os pares do escopo nexio.attachment daquele arquivo — o original e as cópias, liberados na transação do expurgo —, com a marcação, o motivo, a referência do pedido e quem registrou e quem executou como autores declarados (RN-GF-27) — a lápide suprime o nome original. O evento attachment.erased só sai quando o GrydFiles grava purgedAt em todos esses pares: até lá o pedido fica Executed, com a pendência à vista no anexo, e só o job repete, com os autores gravados — nunca por usuário, que o GrydFiles recusaria por autor declarado diferente de quem está no contexto. Expurgo recusado — guarda de qualquer detentor, ou referência de outro escopo criada nesse meio-tempo — não vira pendência silenciosa: o pedido vai a PurgeBlocked, com o código — FILE_LEGAL_HOLD_CONFLICT, guarda de algum detentor, ou FILE_STILL_REFERENCED_CONFLICT, referência ativa de outro escopo — e a hora, à vista na fila ao lado do dueAt do titular, e o evento attachment-erasure-request.purge-blocked sai depois do commit dessa transição — nome próprio, que não se confunde com o attachment-erasure-request.blocked do registro bloqueado; o job segue repetindo, o aviso sai a quem registrou e ao titular, e, com o dueAt vencido, também ao administrador do tenant. Expurgo que ainda não voltou não é melhor do que expurgo recusado: pedido Executed com purgedAt nulo e dueAt vencido escala igual — mesmo aviso, mesma fila, mesmo destaque —, porque do lado do titular o prazo venceu do mesmo jeito, e falha transitória que ninguém repara é indistinguível de bloqueio. E pedido parado vence do mesmo jeito: pedido Requested bloqueado — por aprovação, por decisão de controle ou por alcance — com o dueAt vencido escala igual, com o mesmo aviso, a mesma fila e o mesmo destaque dos outros dois, e com o administrador do tenant na audiência. Bloqueio não para o relógio do titular: avisá-lo uma vez, no registro, e deixar o prazo correr em silêncio é a mesma pendência silenciosa do expurgo, um passo antes. E o bloqueio por alcance ganha saída declarada: quem concede escopo no tenant — update:company-scopes, da Empresa — pode encerrar o pedido bloqueado por alcance incompleto, com motivo escrito, pela própria rota de cancelamento: o pedido vai a Cancelled, o titular é avisado como em todo cancelamento, o ato fica registrado com quem encerrou, e o arquivo volta à propagação (RN-ATT-15). Sem essa saída, quem tivesse erase:attachments e um anexo legível registrava um pedido que ninguém pode executar — o alcance nunca fica inteiro por conta própria — e prendia POST /attachments/copy sobre o arquivo inteiro, sem prazo e sem fim. Por que encerramento por gente, e não caducidade por prazo: um relógio que cancela sozinho responde outra vez com silêncio ao exercício de um direito, e ainda por decurso, sem que ninguém tenha decidido nada; assim a conta fica com quem tem o poder de desfazer o bloqueio — conceder o escopo, ou encerrar o pedido dizendo por que não o concede —, e a escolha fica escrita. E o encerramento fecha o laço: enquanto o alcance de quem registra continuar incompleto, pedido novo bloqueado por alcance sobre o mesmo arquivo é recusado (ATTACHMENT_ERASURE_SCOPE_INCOMPLETE_FORBIDDEN) — o caminho é pedir escopo, não repetir o pedido; quem tem o alcance inteiro registra e executa normalmente. Depois do ato, o único instrumento que segura os bytes é a guarda legal: o job relê a guarda antes de cada chamada e não relê OpenApprovalOf nem PendingControlOf — esses são conferidos no registro e relidos sob a trava na execução (RN-ATT-39), não depois. A consequência fica escrita: decisão ou contestação aberta depois do commit do ato não segura o expurgo, e já não teria o que preservar do lado do Nexio — o nome foi neutralizado e as referências, liberadas; quem precisa dos bytes para uma decisão aberta põe guarda legal por caso, que vence o pedido do titular, e o pedido fica PurgeBlocked. Publicar a eliminação de bytes que continuam lá é o erro que não se corrige depois. É ato de controle.

Prova de controle, ou anexo ainda sob guarda: quem registra o pedido não executa

O registro grava um AttachmentErasureRequest e calcula, sobre todos os anexos do arquivo, se a eliminação pede segunda pessoa. Pede quando algum deles é de tipo com isControlEvidence = true — na semente, BANK_OWNERSHIP_PROOF, SIGNED_CONTACT_CHANGE_REQUEST e APPROVAL_EVIDENCE —, ou de tipo com retenção Permanent — SIGNED_CONTRACT, na semente —, qualquer que seja a marca, ou está dentro da guarda: com o dono fora de Draft, a referência ainda não liberada, ou guardUntil no futuro — o anexo de documento fechado que o re-scan achou infectado depois de liberado continua sob guarda (RN-ATT-37) —, ou o dono ainda não fechado. Sem segunda pessoa e sem bloqueio, o registro executa, e o pedido nasce Executed com o mesmo usuário nas duas pontas. Com segunda pessoa, ou com bloqueio (RN-ATT-33), o pedido nasce Requested e nada é revogado. Pedido bloqueado continua registrado: o titular tem prazo, e o registro é a prova de que o pedido foi recebido. A fila mostra o bloqueio — calculado na leitura, nunca gravado — e o dueAt; o aviso sai ao titular, pelo e-mail informado no registro, dizendo só que o pedido aguarda a conclusão de uma decisão em curso — sem nome de arquivo, de documento ou de decisão —, e, sem e-mail, a quem registrou, que responde pelo canal do pedido. O aviso de pedido pendente vai a quem pode executar — erase:attachments, escopo e CanRead em todos os donos, menos quem registrou quando o pedido pede segunda pessoa; sem ninguém assim, ao administrador do tenant, e o pedido fica parado. Executa POST /attachments/erasure-requests/{requestId}/execute — com segunda pessoa, por usuário diferente de quem registrou (ATTACHMENT_ERASURE_SAME_PERSON_FORBIDDEN); sem ela, também quem registrou, depois de o bloqueio cair —, com as condições reconferidas na hora e a marca recalculada — o que endureceu entre o registro e a execução vale; o que afrouxou, não. Quem registrou, ou outra pessoa com o mesmo alcance, cancela o pedido pendente com comentário (RN-ATT-38).

A razão é a do núcleo de controle bancário: uma pessoa que pede e executa sozinha a eliminação do comprovante de uma troca de conta fraudulenta já fechada apaga a prova da própria fraude, e o pedido do titular vira a porta; em Permanent, o que se apaga não tem data para deixar de ser prova. Nos demais casos — anexo de rascunho nunca submetido, sem a marca, de tipo com prazo, cuja guarda já terminou — o que está em jogo é o dado pessoal, não a prova, e uma pessoa basta, com o ato registrado.

A segunda pessoa é outro usuário. A comparação é por userId, como nas decisões do motor: sem comparação por CPF e sem regra de conflito de interesse — o proponente, o aprovador, o remetente do lote, o autor do callback ou quem anexou a prova podem registrar ou executar. Risco aceito, e registrado: dois usuários da mesma pessoa, ou o aprovador de uma troca fraudulenta, fazem as duas pontas. O que o mitiga fica: o ato de controle registrado com os dois autores, o aviso ao segundo antes de ele executar e a trilha do ato. Identidade verificada por CPF, como a do núcleo bancário, e regra de conflito de interesse foram consideradas e não entram.

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. O estado vem do GrydFiles na hora da submissão, não do que o contrato de veredito já aplicou: anexo cujo arquivo já está Infected ou reprovado, e ainda não foi revogado, também bloqueia — e também a reserva de upload que ainda pode ser confirmada (Reserved): o arquivo que chegasse depois da submissão entraria num documento que não aceita mais escrita (RN-ATT-19, RN-ATT-36).

Failed bloqueia pela mesma razão 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. A saída não é esperar indefinidamente: o arquivo só chega a Failed depois das tentativas automáticas do GrydFiles, e a tela oferece "verificar de novo", que o Nexio pede ao GrydFiles pela IFileService (POST /attachments/{id}/rescan), ou "remover".

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 — um spinner que bloqueia até o veredito — é 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 na v1: a tela mostra o estado, e a pessoa envia quando libera

Ninguém fica preso: a pessoa continua preenchendo, sai da tela e volta. Quem tenta enviar com anexo sem veredito recebe ATTACHMENT_SCAN_PENDING_CONFLICT, com a lista dos anexos e o estado de cada um. A tela não precisa chegar a essa resposta: ela acompanha o estado pela consulta em lote (GET /attachments/status), mostra ao lado do botão de enviar o que ainda falta liberar e o torna disponível quando o último veredito chega. O 409 é a guarda do servidor — vale para a tela desatualizada, para a integração e para o clique que chega junto com o veredito. Anexo em Failed sai por "verificar de novo" (POST /attachments/{id}/rescan) ou por revogação; anexo em Infected já foi revogado pelo contrato de veredito (RN-ATT-20), e a pessoa anexa outro arquivo.

Nenhum processo em segundo plano submete documento. Submeter abre aprovação e, no desfecho, empenha verba; fazer isso fora da requisição de uma pessoa exigiria restaurar a identidade, as permissões e o escopo dela e registrar que o ato foi feito em nome dela — execução delegada, que a plataforma não oferece. Por isso o registro de descritores não tem pergunta sobre como submeter o dono: o dono submete a si mesmo, na requisição de quem clicou, e pergunta ao anexo se há algo pendente. Submeter sozinho quando o arquivo liberar está em § Fora de escopo, como v2.

supplierId obrigatório, portalUserId opcional

A assimetria é deliberada e vem do mundo real: o fornecedor pode entrar no portal sem PortalUser cadastrado — a forma de acesso é do Portal do Fornecedor —, e nesse caso não há usuário a registrar; mas sempre há fornecedor, porque o acesso do portal o identifica. supplierId é resolvido pelo portal e gravado denormalizado no anexo, nunca lido do contato: contato muda de empresa, é desligado ou apagado, e a autoria tem que ficar congelada. É a regra 1 do mapa de domínio aplicada à autoria.

Nasce Internal, sempre

O defaultVisibility do tipo é ignorado no caminho do portal. A proposta que o fornecedor A enviou não é visível ao fornecedor B nem a nenhum outro no portal — além do próprio A, quem lê é o comprador. Marcar como Supplier depois não existe (ATTACHMENT_SUPPLIER_VISIBILITY_NOT_ALLOWED_UNPROCESSABLE): a proposta de um concorrente ficaria legível aos outros. O documento que o comprador quer mandar a todos, ele anexa ao QuotationRequest. E Internal não tira o anexo do próprio autor: o portal devolve ao fornecedor o que ele mesmo subiu (RN-ATT-12).

Os três ganhos que motivaram a decisão

Trilha legível. "Anexado por Fornecedor X" sem decodificar token nem cruzar tabela de sessão.

Isolamento barato. O que seria uma regra especial de visibilidade vira comparação de supplierId — a mesma coluna, o mesmo índice, nenhum caso particular no código de autorização.

Promoção a SupplierDocument. Uma certidão que chegou anexada numa cotação pode virar documento de cadastro porque já se sabe de quem ela é. Sem supplierId no anexo, essa promoção exigiria alguém digitar o fornecedor de novo — e digitar de novo é onde o dado erra.

Duas identidades, e nenhuma finge ser a outra

O uploadedBy do StoredFile continua sendo identidade do tenant no GrydAuth: o portal não tem GrydAuth, então quem aparece lá é o serviço que fez o upload. A autoria de negócio é do Attachment, em uploadedByKind, portalUserId e supplierId. Tentar forçar a identidade do fornecedor na camada de plataforma criaria usuário de tenant para quem não é do tenant — e é assim que se abre uma porta que ninguém queria abrir.

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. Anexo de item, de fornecedor, de qualificação do 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 as empresas do escopo — e, para quem não tem empresa nenhuma no escopo, para nenhuma. 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

create:attachments e update:attachments são necessárias e não suficientes: 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".

É evento de negócio do Nexio, isolado por tenant — 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, attachment.rescan-requested. Cada uma carrega ownerType, o número legível do documento e o attachmentId. O caminho do framework para gravar a trilha é demanda de plataforma, em correção pelo Gryd.IO (isolamento de tenant, permissão e gravação na transação do ato); esta página fixa o requisito, não o mecanismo.

A convenção dos nomes 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. Nem todo evento tem aviso: attachment.created, attachment.copied, attachment.visibility-changed, attachment.rescan-requested, attachment.quarantined, attachment-legal-hold.placed, attachment-legal-hold.lifted e attachment-erasure-request.executed são eventos de domínio sem linha no catálogo de avisos na v1 — alimentam a trilha e quem quiser consumi-los, e não têm destinatário nem slug. A ausência no catálogo é a declaração de que não há aviso, não esquecimento. O pedido de eliminação segue a mesma regra, com a entidade dele, e cada momento tem um nome só: attachment-erasure-request.registered (nasce livre, à espera da segunda pessoa), attachment-erasure-request.blocked (nasce travado), attachment-erasure-request.executed (ato gravado, expurgo pendente), attachment-erasure-request.purge-blocked (expurgo recusado) e attachment-erasure-request.cancelled; attachment.erased — os bytes saíram — é fato do arquivo. Os avisos são os slugs de mesma cauda na Notificação.