[ArtRiv]

Um pedido dizia userId e mais nada sobre quem comprou, então um back-office
só conseguia mostrar um UUID. customers.read está no catálogo de permissões
sem rota nenhuma atrás, e construir esse diretório agora é uma decisão maior do
que a tela precisa — o comprador daquele pedido é dado do pedido, do mesmo
jeito que o nome numa nota fiscal.

Nasceu de uma lacuna real: o painel administrativo da AVESSO tem coluna
Cliente na lista e um card com nome e e-mail no detalhe, e não havia como
preenchê-los. Caminho upstream em vez de contorno no front-end, conforme
docs/upstream-first.md.

O que muda no contrato

// OrderBuyerResponse
{ id: string; name: string | null; email: string }

// em OrderResponse — obrigatório e anulável
buyer: OrderBuyerResponse | null

42 operações, as mesmas de antes. Nenhuma rota nova: é um campo numa
resposta que já existia, e é por isso que o painel não ganha chamada nenhuma.

• buyer vem preenchido só para quem carrega orders.read, e null para
  todo mundo mais — o próprio comprador incluído. null em vez de ausente
  para que o campo esteja sempre no contrato e um cliente tipado não tenha que
  tratar undefined além de null.
• name é anulável porque User.name é String?: uma conta criada pelo
  Google nunca passou por RegisterDto. Quem exibe decide o fallback.

Como o vazamento fica fechado

Três colunas escolhidas pelo nome ({ id: true, name: true, email: true }) e
copiadas uma a uma para a resposta. Nunca spread, nunca include: { user: true }
— a forma genérica é exatamente como uma listagem de back-office distribui
todo hash de senha do banco, e é o item 2 de docs/admin-api.md.

Dois testes seguram isso:

• um unitário afirma que o select são aqueles três e nenhum a mais
  (toEqual, não toMatchObject — coluna acrescentada é a regressão);
• um e2e serializa o corpo inteiro e compara com o hash bcrypt real do
  comprador — o valor, não o nome do campo. Um vazamento que chegasse por
  outra relação, ou sob outra grafia, ainda falha.

Conferido no documento gerado: passwordHash, googleId, emailVerifiedAt e
roleId não aparecem.

Uma decisão que merece revisão

As quatro transições de back-office (mark-paid, ship, deliver, refund)
passaram a receber o chamador, para que as respostas delas obedeçam à mesma
regra — o painel re-renderiza o detalhe a partir delas, e o card do cliente
esvaziaria a cada transição. O webhook mantém a assinatura e recebe null:
ele não tem chamador, e não é uma pessoa.

Consequência real: um operador com orders.update_status e sem
orders.read envia o pedido e recebe buyer: null. É o comportamento certo —
uma regra só, sem exceção por rota — e está registrado nos edge cases da spec.

A permissão é orders.read e não customers.read de propósito: quem lê o
pedido de qualquer pessoa já lê o endereço de entrega dela, que identifica
mais do que um nome. customers.read continua reservada para o diretório de
clientes, que lista gente sem pedido nenhum e é outra superfície.

Verificação

porta	resultado
unitários	502 (492 + 10 novos)
e2e	210 em 8 suítes (204 + 6 novos)
lint:check	limpo
typecheck	limpo
build	limpo
openapi:generate	42 operações, +47 linhas

payments-live não rodou: depende de rede até a Stripe, não toca em nada que
esta mudança altera, e a própria docstring dele manda rodar sob demanda.

Spec: docs/specs/order-buyer.md.