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 confirma no GrydFiles (POST /files/{id}/complete), cria o Attachment e cria a FileReference com ownerScope = "nexio.attachment" e ownerKey = attachment.id. 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 libera download, envio ao fornecedor e submissão para aprovação. Infected é terminal: o anexo é revogado automaticamente, com motivo próprio, e a tela diz o que aconteceu.

Por que o Attachment nasce antes do veredito, e não depois

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 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.

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:attachment; 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:file libera pedir uma URL de download, e é permissão de módulo. 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 supplierId: o portal só devolve anexos cujo supplierId é o do token, mais os anexos Supplier do próprio QuotationRequest, que são para todos por definição. É 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.

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, 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.

Retenção é declarada uma vez, no upload

O Nexio resolve retentionMode, retainUntil e legalHold a partir do AttachmentType e envia no POST /files. Depois disso o GrydFiles executa sozinho, e o Nexio não volta a mexer — exceto em dois casos, ambos declarados. O primeiro é o documento que muda de natureza: um pedido que vira nota fiscal recebe anexos com retenção fiscal no momento em que são anexados àquele documento, e não retroativamente. O segundo, fechado em 08/09/2026, é o fechamento fiscal do documento dono: a data resolvida no upload é só o piso (uploadedAt + retentionYears), e no fechamento o Nexio empurra retainUntil para 31/12 do exercício do fechamento + retentionYears. A razão é aritmética e é fiscal: o prazo decadencial do art. 173, I do CTN começa a correr no primeiro dia do exercício seguinte, de modo que contar do upload deixa o arquivo até dois anos curto quando o processo é longo — e o anexo que falta numa fiscalização não volta. Errar para mais custa armazenamento; errar para menos custa a prova.

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 ou Scanning. A submissão é recusada com ATTACHMENT_SCAN_PENDING_CONFLICT, e a resposta nomeia quais anexos estão pendentes.

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. 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 que a v1.0 já entregava, e continua valendo

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.

supplierId obrigatório, portalUserId opcional

A assimetria é deliberada e vem do mundo real: o fornecedor pode responder a uma RFQ por link de uso único, sem PortalUser cadastrado, e nesse caso não há usuário a registrar — mas sempre há fornecedor, porque o token da RFQ o identifica. supplierId é resolvido do token 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, e não é visível a ninguém no portal — quem lê é o comprador. Marcar como Supplier depois é possível, com as quatro portas da seção de visibilidade, e é o caso raro de um documento que o comprador quer devolver a todos os concorrentes.

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.

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

manage:attachment é 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.