Skip to content

Status Serialization Groups

Jump to bottom
technical-documenter edited this page Aug 31, 2026 · 1 revision

Status — grupos de serialização para recursos aninhados

Objetivo

Documentar como a entidade Status (api-platform-common) expõe campos (id, status, realStatus, color, …) via Symfony Serializer Groups quando é embutida em outros recursos (ex.: InvoiceTax).

Isso evita respostas de listagem com status/color vazios (-) no frontend.

Contexto de negócio

  • CT-e (Conhecimento de Transporte eletrônico) usa o modelo de nota invoiceModel = 57.
  • A listagem de CT-e consome a coleção GET /invoice_taxes?invoiceModel=57 (normalização invoice_tax:read).
  • InvoiceTax (módulo api-platform-accounting) possui relação ManyToOne com Status.
  • O frontend de logística (ui-logistic) exibe o rótulo e a cor do status na grade de CT-e.

Se os campos de Status não carregarem o grupo invoice_tax:read, o serializer omite status, realStatus e color no JSON aninhado → a UI mostra -.

Correção aplicada (#32)

Em src/Entity/Status.php os atributos abaixo passaram a incluir o grupo invoice_tax:read:

Campo Groups (trecho relevante)
id invoice_tax:read, …
status invoice_tax:read, …
realStatus invoice_tax:read, …
color invoice_tax:read, …

Demais campos de controle (visibility, notify, system, context) seguem os grupos já existentes e não foram alterados neste fix.

Commit de referência em master: 3532f0b (fix(status): add invoice_tax:read groups for CTE list serialization).

Contrato de serialização

  • Recurso principal: InvoiceTax
    • normalizationContext.groups = ['invoice_tax:read']
    • Campo status marcado com #[Groups(['invoice_tax:read', 'invoice_tax:write'])]
  • Recurso aninhado: Status
    • Para que propriedades apareçam no JSON de InvoiceTax, elas devem declarar o mesmo grupo invoice_tax:read.

Padrão geral: sempre que um recurso A embute Status (ou outra entidade compartilhada) e usa um grupo de normalização próprio (*:read), os campos de Status que a UI precisa devem listar esse mesmo grupo.

Repositórios envolvidos

Repositório Papel
api-platform-common Entidade Status e groups de serialização
api-platform-accounting Entidade InvoiceTax (modelo 57 = CT-e) e endpoint de listagem
ui-logistic Listagem visual de CT-e (consome o JSON com status/cor)

Visões de app (APP_TYPE)

  • MANAGER / logística: tela de CT-e em ui-logistic (visão operacional de transporte).
  • O módulo api-platform-common não implementa UI; só fornece o contrato de dados compartilhado.
  • api-platform-accounting é o backend fiscal/tributário que materializa InvoiceTax.

Manutenção

Ao adicionar um novo grupo de leitura que embuta Status (ex.: novo foo:read):

  1. Inclua o grupo nos campos de Status que a listagem/detalhe do consumidor precisa (id, status, realStatus, color no mínimo).
  2. Verifique o JSON real da coleção (ou teste de serialização) antes de fechar a task.
  3. Atualize esta página se o caso for relevante para outro fluxo transversal.

Links

Clone this wiki locally